Blocklet
This section details how to create comprehensive backups of your Blocklet data to DID Spaces, covering both full and incremental backup methods. Leveraging the underlying synchronization commands, the SDK ensures your Blocklet's data is securely stored and can be restored when needed.
For a general understanding of data synchronization within DID Spaces, refer to the Sync section. To learn how to restore your Blocklet from a backup, see Restore Blocklet.
Full Blocklet Backup#
The backup.blocklet command facilitates a full backup of your Blocklet's data to DID Spaces. This command initiates a new backup record and then pushes the entire specified local Blocklet directory to your DID Space, updating the backup status upon completion.
Parameters#
Name | Type | Description |
|---|---|---|
|
| The current DID of the Blocklet to be backed up. |
|
| The DID of the user initiating the backup. |
|
| The URL of the page or application from which the backup was initiated. |
|
| The name of the Blocklet being backed up. |
|
| A description of the Blocklet being backed up. |
|
| The DID address of the server hosting the Blocklet. Defaults to an empty string. |
|
| The latest |
|
| The local file system path to the Blocklet data folder you wish to back up. |
|
| The DID Space service endpoint. Typically configured during |
|
| An instance of |
|
| An object containing delegation details ( |
|
| Encryption key (hex string) for data at rest. |
|
| Initialization vector (hex string) for data at rest encryption. |
|
| If |
|
| If |
|
| If |
|
| If |
|
| Cipher algorithm for encryption. |
|
| Compression algorithm for data transfer. |
|
| The number of concurrent file transfers. Defaults to 5. |
|
| If |
|
| If |
|
| A callback function for tracking transfer progress. |
Returns#
Name | Type | Description |
|---|---|---|
|
| The HTTP status code of the operation. |
|
| A descriptive message about the operation's outcome. |
|
| The error stack trace if an error occurred. |
|
| The number of errors encountered during the data push. -1 if the operation failed before sync. |
|
| The total number of files/objects processed. -1 if the operation failed before sync. |
|
| The duration of the data push operation in milliseconds. -1 if the operation failed before sync. |
|
| The total size of data transferred in bytes. -1 if the operation failed before sync. |
Example#
import { SpaceClient } from '@did-spaces/client';
import { Wallet } from '@arcblock/forge-wallet';
const client = new SpaceClient({
endpoint: 'https://your-space-endpoint.com',
wallet: new Wallet('YOUR_MNEMONIC'), // Replace with your actual wallet setup
});
async function performFullBlockletBackup() {
try {
const result = await client.backup.blocklet({
appDid: 'did:abt:z5QYk516t89uLgG7j2h3k4m6n9p0q2r4s6t8u0v2w4x6y8z0',
userDid: 'did:abt:zUserDidForBackup',
referrer: 'https://my-blocklet-app.com/settings/backup',
appName: 'MyWebAppBlocklet',
appDescription: 'A web application for managing tasks.',
source: './path/to/my-web-app-blocklet-data',
zip: true, // Optional: compress data during transfer
concurrency: 10, // Optional: set concurrent transfers
});
if (result.data.errorCount === 0) {
console.log('Full Blocklet backup completed successfully!');
console.log(`Total files backed up: ${result.data.count}`);
console.log(`Total size: ${result.data.size} bytes`);
} else {
console.error('Full Blocklet backup failed or had errors:', result.statusMessage);
console.error('Error details:', result.stack);
}
} catch (error) {
console.error('An unexpected error occurred during full backup:', error.message);
}
}
performFullBlockletBackup();This example demonstrates how to perform a full backup of a Blocklet by providing its DID, user DID, application details, and the local path to its data. It also shows how to handle the result, checking for successful completion or errors.
Incremental Blocklet Backup#
Similar to full backup, the incrementalBackup.blocklet command is optimized for efficiently backing up large Blocklet datasets. It uses incremental synchronization to only transfer changed or new files, significantly reducing backup time and bandwidth for subsequent backups. This command also ensures temporary space occupied by the backup is cleared upon completion or failure.
Parameters#
Name | Type | Description |
|---|---|---|
|
| The permanent application ID (PID) of the Blocklet. This is crucial for incremental backups to track changes across Blocklet rotations. |
|
| The current DID of the Blocklet to be backed up. |
|
| The DID of the user initiating the backup. |
|
| The URL of the page or application from which the backup was initiated. |
|
| The name of the Blocklet being backed up. |
|
| A description of the Blocklet being backed up. |
|
| The DID address of the server hosting the Blocklet. Defaults to an empty string. |
|
| The latest |
|
| The local file system path to the Blocklet data folder you wish to back up. |
|
| The DID Space service endpoint. Typically configured during |
|
| An instance of |
|
| An object containing delegation details ( |
|
| Encryption key (hex string) for data at rest. |
|
| Initialization vector (hex string) for data at rest encryption. |
|
| If |
|
| If |
|
| If |
|
| If |
|
| Cipher algorithm for encryption. |
|
| Compression algorithm for data transfer. |
|
| The number of concurrent file transfers. Defaults to 5. |
|
| If |
|
| If |
|
| A callback function for tracking transfer progress. |
Returns#
Name | Type | Description |
|---|---|---|
|
| The HTTP status code of the operation. |
|
| A descriptive message about the operation's outcome. |
|
| The error stack trace if an error occurred. |
|
| The number of errors encountered during the data push. -1 if the operation failed before sync. |
|
| The total number of files/objects processed. -1 if the operation failed before sync. |
|
| The duration of the data push operation in milliseconds. -1 if the operation failed before sync. |
|
| The total size of data transferred in bytes. -1 if the operation failed before sync. |
Example#
import { SpaceClient } from '@did-spaces/client';
import { Wallet } from '@arcblock/forge-wallet';
const client = new SpaceClient({
endpoint: 'https://your-space-endpoint.com',
wallet: new Wallet('YOUR_MNEMONIC'), // Replace with your actual wallet setup
});
async function performIncrementalBlockletBackup() {
try {
const result = await client.incrementalBackup.blocklet({
appPid: 'did:abt:zPermanentPIDforMyBlocklet',
appDid: 'did:abt:zCurrentDIDforMyBlocklet',
userDid: 'did:abt:zUserDidForBackup',
referrer: 'https://my-blocklet-app.com/settings/backup',
appName: 'MyDataBlocklet',
appDescription: 'A Blocklet storing large datasets.',
source: './path/to/my-data-blocklet-data',
// Optional sync parameters
zip: true,
concurrency: 5,
});
if (result.data.errorCount === 0) {
console.log('Incremental Blocklet backup completed successfully!');
console.log(`Total files processed: ${result.data.count}`);
console.log(`Total size transferred: ${result.data.size} bytes`);
} else {
console.error('Incremental Blocklet backup failed or had errors:', result.statusMessage);
console.error('Error details:', result.stack);
}
} catch (error) {
console.error('An unexpected error occurred during incremental backup:', error.message);
}
}
performIncrementalBlockletBackup();This example demonstrates an incremental backup, highlighting the use of appPid for efficient tracking of changes. It also showcases proper error handling and logging of the backup results.
Blocklet Backup Workflow#
The following diagram illustrates the typical workflow for both full and incremental Blocklet backups within DID Spaces:
This sequence diagram outlines the steps involved, from initiating the backup and creating a record on DID Spaces, to pushing the data and finally updating the backup status based on the synchronization outcome.
This section provided a detailed guide on how to perform both full and incremental backups of your Blocklet data using the DID Spaces SDK. You are now equipped to secure your Blocklet's data within DID Spaces. For information on restoring your data, proceed to the Restore Blocklet section.