Synchronizing Folders

Keeping a local directory in sync with a remote one in your DID Space is a common requirement for applications like static website hosting, data backup, or collaborative asset management. The DID Space Client SDK simplifies this process with two powerful, high-level commands: SyncFolderPushCommand and SyncFolderPullCommand.

This guide will walk you through practical examples of how to use these commands. For a detailed breakdown of all available parameters and options, please refer to the SyncFolderPushCommand and SyncFolderPullCommand API references.

How Synchronization Works#

At its core, the synchronization process intelligently determines which files need to be transferred. When a sync command is executed, it performs a comparison between the source and target directories. A file is marked for synchronization if any of the following conditions are met:

• The file exists in the source but not in the target.
• The file exists in both, but their sizes differ.
• The file exists in both with the same size, but the source file has a more recent modification time.

By default, the sync commands will only add or update files. You can enable strictSync mode to also delete files in the target directory that do not exist in the source, ensuring an exact mirror.

Pushing a Local Folder to DID Space#

Use SyncFolderPushCommand when you want to upload or update the contents of a local directory to a remote directory in your DID Space. This is perfect for deploying a static website or backing up local files.

Step 1: Initialize the Client and Command#

First, set up your SpaceClient and import the SyncFolderPushCommand.

import { SpaceClient, SyncFolderPushCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

// Initialize the wallet and client
const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...', // Use your Space endpoint
  wallet,
});

Step 2: Define Command Inputs#

To push a folder, you need to specify the local source path and the remote target path.

Step 3: Execute the Push Command#

Now, create an instance of the command with your inputs and send it using the client.

async function pushMyWebsite() {
  const command = new SyncFolderPushCommand({
    source: './build/', // Path to your local build folder
    target: '/public/my-website/', // Destination in DID Space
    strictSync: true, // Mirror the local folder exactly
    onProgress: ({ completed, total }) => {
      const percentage = total > 0 ? (completed / total) * 100 : 0;
      console.log(`Upload progress: ${percentage.toFixed(2)}%`);
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Push successful!');
    console.log(`Total files synced: ${output.data.count}`);
    console.log(`Total size: ${output.data.size} bytes`);
    console.log(`Duration: ${output.data.duration} seconds`);
  } else {
    console.error('Push failed:', output.statusMessage);
  }
}

pushMyWebsite();

This example uploads the contents of the local ./build/ directory to /public/my-website/ in your Space. Because strictSync is true, any files in the remote directory that aren't in ./build/ will be removed.

Pulling a Remote Folder from DID Space#

Use SyncFolderPullCommand to download the contents of a remote directory from your DID Space to your local file system. This is useful for restoring a backup or retrieving a shared project.

Step 1: Define Command Inputs#

The inputs for pulling are similar to pushing, but the roles of source and target are reversed.

Step 2: Execute the Pull Command#

Create the SyncFolderPullCommand instance and send it.

import { SpaceClient, SyncFolderPullCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';

const wallet = getWallet();
const client = new SpaceClient({
  endpoint: 'https://www.didspaces.com/app/api/space/...',
  wallet,
});

async function pullMyBackup() {
  const command = new SyncFolderPullCommand({
    source: '/backups/latest/', // Path in your DID Space
    target: './restored-backup/', // Local destination folder
    onProgress: ({ completed, total }) => {
      const percentage = total > 0 ? (completed / total) * 100 : 0;
      console.log(`Download progress: ${percentage.toFixed(2)}%`);
    },
  });

  const output = await client.send(command);

  if (output.statusCode === 200) {
    console.log('Pull successful!');
    console.log(`Total files synced: ${output.data.count}`);
    console.log(`Total size: ${output.data.size} bytes`);

This script downloads files from /backups/latest/ in your Space to the local ./restored-backup/ directory. Note that even if strictSync were enabled, this command will not delete any extra files you might have in the local directory.

Best Practices#

• File Integrity: During a push operation, files are first copied to a temporary directory before uploading. This ensures that even if a file is modified locally during the sync process, a consistent version is uploaded, preventing data corruption.
• Performance: You can adjust the concurrency parameter in either command to control how many files are transferred simultaneously. The default is 4. Increasing this value may improve speed on fast networks, while decreasing it can reduce load on slower connections.
• Filtering: Both commands accept a filter function in their input. You can use this to selectively include or exclude files from the synchronization process based on their properties, such as name or path.

Next Steps#

You now have a solid understanding of how to synchronize folders between your local machine and DID Space. To further enhance your application, you might want to explore how to manage folder appearances.