Blocklet Restore
This section details how to use the RestoreBlockletCommand in the DID Spaces SDK to restore your Blocklet data from a previously created backup stored in DID Spaces. This command orchestrates the entire restoration process, ensuring your Blocklet is returned to a desired previous state.
For information on creating backups, please refer to the Blocklet Backup section. To understand the underlying synchronization mechanism, see Sync Pull.
How it Works#
The RestoreBlockletCommand facilitates the restoration of a Blocklet by coordinating several internal operations. The process involves initiating a restore session with the DID Space, pulling the backed-up data, and then updating the restore status based on the operation's outcome. The command automatically sets the appropriate source path for the backup data within the DID Space, abstracting away the complexities of folder management.
The overall flow is depicted in the following sequence diagram:
Parameters#
The RestoreBlockletCommandInput extends SyncFolderBaseCommandInput (excluding the source field, which is internally determined), and includes additional properties for identifying the Blocklet and the restore context.
Name | Type | Description | Required |
|---|---|---|---|
|
| The permanent | Yes |
|
| The DID of the Blocklet to be restored. | Yes |
|
| The DID of the user initiating the restore. | Yes |
|
| The URL of the page from which the restore operation was initiated. This must be a valid HTTP/HTTPS URI. | Yes |
|
| The DID address pointing to the server where the Blocklet resides. Defaults to an empty string if not provided. | No |
|
| The local directory path where the Blocklet data will be restored. | Yes |
|
| Optional. An array of glob patterns for files or directories to ignore during the restore. | No |
|
| Optional. If | No |
|
| Optional. If | No |
|
| Optional. The number of concurrent file operations during the pull. | No |
|
| Optional. Callback function to receive overall synchronization progress updates. | No |
|
| Optional. Callback function to receive progress updates for individual files. | No |
|
| Optional. Callback function to receive informational messages during the sync process. | No |
Output#
The RestoreBlockletCommandOutput extends SyncFolderBaseCommandOutput, providing details about the restore operation's success or failure, including file transfer statistics.
Name | Type | Description |
|---|---|---|
|
| The HTTP status code of the operation. |
|
| A human-readable message describing the status of the operation. |
|
| Optional. The error stack trace if an error occurred. |
|
| The number of errors encountered during the data pull. |
|
| The total number of files processed during the data pull. |
|
| The total duration of the data pull in milliseconds. |
|
| The total size of data transferred in bytes. |
Usage Example#
The following example demonstrates how to restore a Blocklet with a specific appPid to a local directory, providing the necessary user and server DIDs, and a referrer URL.
import { SpaceClient } from '@blocklet/did-spaces-client';
import { join } from 'path';
async function restoreMyBlocklet() {
const client = new SpaceClient({
endpoint: 'https://your-space-service-url.com', // Replace with your DID Space service endpoint
wallet: yourDIDWalletInstance, // Your authenticated DID Wallet instance
});
const appPidToRestore = 'z8k...'; // Replace with the appPid of the Blocklet to restore
const appDidToRestore = 'did:abt:z8k...'; // Replace with the appDid of the Blocklet to restore
const userDid = 'did:abt:z1f...'; // Replace with the user's DID
const referrerUrl = 'https://my-blocklet-dashboard.com/restore'; // The page where the restore was initiated
const restoreTargetDir = join(process.cwd(), 'restored-blocklet-data');
try {
console.log(`Attempting to restore Blocklet ${appPidToRestore} to ${restoreTargetDir}...`);
const result = await client.send('restoreBlocklet', {
appPid: appPidToRestore,
appDid: appDidToRestore,
userDid: userDid,
referrer: referrerUrl,
target: restoreTargetDir,
// Optional: Add other sync options if needed, e.g., overwrite: true
});
if (result.statusCode === 200) {
console.log('Blocklet restoration completed successfully!');
console.log(`Files restored: ${result.data.count}`);
console.log(`Total size: ${result.data.size} bytes`);
} else {
console.error(`Blocklet restoration failed with status ${result.statusCode}: ${result.statusMessage}`);
if (result.stack) {
console.error('Stack trace:', result.stack);
}
console.error(`Error count: ${result.data.errorCount}`);
}
} catch (error) {
console.error('An unexpected error occurred during Blocklet restoration:', error);
}
}
restoreMyBlocklet();This example demonstrates a typical scenario for initiating a Blocklet restore operation. It specifies the unique identifiers for the Blocklet and the user, along with the local target directory.
Conclusion#
The RestoreBlockletCommand provides a robust and streamlined way to recover your Blocklet data from DID Spaces backups. By understanding its parameters and workflow, you can effectively manage the lifecycle of your Blocklets' data. For more commands related to Blocklet management, explore the Backup Blocklet command.