Used to check for browser translation.
用于检测浏览器翻译。
ブラウザの翻訳を検出する
Commands Reference

Pull

The Pull command in the DID Spaces SDK allows you to synchronize data from your DID Space to a local folder, ensuring your local content is updated with the latest versions from the remote. This command focuses on retrieving new or modified files from the DID Space and writing them to your local file system.

For information on pushing local changes to your DID Space, see Push. To understand the foundational concepts of synchronization, refer to Sync.

Usage#

To pull content from your DID Space, you utilize the SyncFolderPullCommand class. Instantiate it with the necessary input parameters and then call its request() method.

Parameters#

The SyncFolderPullCommandInput interface extends SyncFolderBaseCommandInput and defines the required and optional parameters for a pull operation.

Name

Type

Description

source

string

Required. The remote path in your DID Space to pull data from. This should be a folder path and typically ends with a /.

target

string

Required. The local folder path where the data will be pulled to. This folder will be created if it does not exist, and its content will be updated.

concurrency

number

Optional. The maximum number of concurrent file operations (downloads). Defaults to 4.

retryCount

number

Optional. The number of times to retry a failed file operation. Defaults to 3.

filter

(object: Object) => boolean

Optional. A function that filters remote objects before synchronization. Only objects for which this function returns true will be considered for pulling.

debug

boolean

Optional. If true, enables verbose debug logging during the synchronization process. Defaults to false.

strictSync

boolean

Optional. Note: For pull operations, this parameter is currently ignored. The Pull command will only add or update local files; it does not delete local files that are no longer present remotely. Defaults to false.

tmpDir

string

Optional. A temporary directory used for intermediate file operations. Defaults to a system-defined temporary directory.

onProgress

(params: OnProgressInput) => Promise<void>

Optional. A callback function invoked periodically to report the progress of the sync operation.

onAfterUpload

(params: OnAfterUploadInput) => Promise<void>

Optional. A callback function invoked after each individual object has been successfully pulled (downloaded).

onFailed

(error: Error) => Promise<void>

Optional. A callback function invoked if the entire sync operation fails after all retries are exhausted.

Returns#

The request() method of SyncFolderPullCommand returns a Promise that resolves to a SyncFolderPullCommandOutput object, which provides details about the completed operation.

Name

Type

Description

statusCode

number

The HTTP status code of the overall operation.

statusMessage

string

A descriptive message for the operation's status.

stack

string

The error stack trace if an error occurred.

data.errorCount

number

The total number of files that failed to sync.

data.count

number

The total number of files processed for synchronization (pulled or determined to be up-to-date).

data.duration

number

The total duration of the sync operation in seconds.

data.size

number

The total size (in bytes) of all objects successfully pulled.

Example Output

{
"statusCode": 200,
"statusMessage": "OK",
"data": {
"errorCount": 0,
"count": 50,
"duration": 15.3,
"size": 1024000
}
}

Example#

The following example demonstrates how to pull all content from a specific remote folder in your DID Space to a local directory, with progress reporting.

import { SpaceClient } from '@arcblock/did-spaces-client';
import { SyncFolderPullCommand } from '@arcblock/did-spaces-client/commands/sync/sync-folder-pull';

async function pullSpaceContent() {
const client = new SpaceClient({
endpoint: 'https://your-did-space-node.com',
// Add your DID authentication context here (e.g., wallet, signer)
});

const sourceRemotePath = '/my-space-folder/'; // Must end with a slash
const targetLocalPath = './local-data/';

try {
const command = new SyncFolderPullCommand(
{
source: sourceRemotePath,
target: targetLocalPath,
concurrency: 5,
debug: true,
onProgress: async (params) => {
console.log(`Pulling progress: ${params.completed}/${params.total} files completed. Current file: ${params.key}`);
},
onAfterUpload: async (params) => {
console.log(`Successfully pulled: ${params.key}`);
},
onFailed: async (error) => {
console.error('Pull operation failed:', error.message);
}
},
client.context
);

console.log(`Starting pull from ${sourceRemotePath} to ${targetLocalPath}...`);
const result = await command.request();

if (result.statusCode === 200) {
console.log('Pull operation completed successfully!');
console.log(`Total files pulled: ${result.data.count}`);
console.log(`Total data size: ${result.data.size} bytes`);
console.log(`Duration: ${result.data.duration} seconds`);
} else {
console.error(`Pull operation failed: ${result.statusMessage}`);
console.error(result.stack);
}
} catch (error) {
console.error('An unexpected error occurred during pull:', error);
}
}

pullSpaceContent();

This example initializes SpaceClient and then creates and executes a SyncFolderPullCommand. It configures a progress callback to log the status of the pull and an onAfterUpload callback to confirm each file's completion.

How It Works#

The SyncFolderPullCommand orchestrates a multi-step process to ensure efficient and reliable data synchronization:

Local File SystemDID SpaceSpaceClientUserLocal File SystemDID SpaceSpaceClientUseralt[Remote object exists, Local doesn't or is different (size/hash/lastModified)][Remote object deleted, Local exists]Call SyncFolderPullCommand.request()ListObjectsCommand (Get remote objects metadata)Remote Objects MapFileHound.create().findSync() (Get local files metadata)Local Objects MapCompare Remote & Local Maps (getWaitSyncObjects)GetObjectCommand (Request object stream)Object Stream & HeaderscreateWriteStream (Prepare local file)Stream.pipe (Write object to local file)Verify object hash (if x-hash header present)Trigger onProgress/onAfterUpload hooksSkip deletion (current implementation only pulls/updates)SyncFolderPullCommandOutput

  1. Retrieve Remote Objects: The command first fetches a comprehensive map of all objects and their metadata (key, size, last modified, hash) from the specified source path in your DID Space using the ListObjectsCommand.
  2. Retrieve Local Objects: Simultaneously, it scans the target local folder to create a similar map of local files and their metadata.
  3. Determine Sync Actions: It then compares the remote and local object maps. For each object, it determines if it needs to be pulled (remote exists, local doesn't; or remote is newer/different in size/hash).
  4. Execute Pulls: For each object marked for pulling, the command initiates a download from the DID Space using GetObjectCommand, streams the content to the corresponding local file, and verifies its integrity if a hash is provided by the server. The process is optimized with a concurrency queue.
  5. Report Progress: Throughout the operation, registered onProgress and onAfterUpload callbacks are triggered to provide real-time updates on the synchronization status.

It's important to note that the SyncFolderPullCommand is designed to only pull new or updated files. It will not delete local files that are no longer present in the remote DID Space. If you require bidirectional synchronization or deletion of local files that mirror remote deletions, you would need to implement additional logic or use a different sync strategy.

Conclusion#

The SyncFolderPullCommand is a robust tool for keeping your local data synchronized with your DID Space. By understanding its parameters and operational flow, you can effectively manage the integrity and currency of your local file system.

For more advanced synchronization scenarios, explore the Incremental Sync documentation.

previous
Push
next
Incremental Sync