@super-protocol/sp-files-addon

SP-Files-Addon

SP-Files-Addon is a Node.js addon that provides functionality for uploading, downloading, and managing encrypted files and directories. It supports various storage types such as filesystem (FS), S3, and Storj.

Installation

npm install @super-protocol/sp-files-addon

Usage

Here's a basic example of how to use the SP-Files-Addon:

import { upload, download, calculateResourceHash, deleteResource, StorageConfig } from '@super-protocol/sp-files-addon';

// Example S3 storage configuration
const s3Storage: StorageConfig = {
  storageType: 'S3',
  endpoint: 'your-s3-endpoint',
  region: 'your-s3-region',
  bucket: 'your-s3-bucket',
  accessKeyId: 'your-access-key', // optional
  secretKey: 'your-secret-key'    // optional
};

// Example resource definition
const resource = {
  storage: s3Storage,
  prefix: 'resource/prefix'
};

// Upload example
const uploadOptions = {
  encryption: true, // or provide EncryptionWithIV object, or false to disable
  hashAlgorithm: 'sha256', // optional
  sourcePath: 'subfolder', // optional
  targetPath: 'destination', // optional
  progressCallback: (args) => {
    console.log(`Processing ${args.key}: ${args.current}/${args.total}`);
  }
};

upload('path/to/source', resource, uploadOptions)
  .then(result => {
    console.log('Upload result:', {
      hash: result.hash,
      encryption: result.encryption, // if encryption was enabled
      resource: result.resource
    });
  })
  .catch(err => console.error('Upload error:', err));

// Download example
const downloadOptions = {
  encryption: {
    key: 'hex-encoded-key',
    iv: 'hex-encoded-iv'
  },
  hashAlgorithm: 'sha256',
  sourcePath: 'source-prefix', // optional
  targetPath: 'target-prefix', // optional
  progressCallback: (args) => {
    console.log(`Downloading ${args.key}: ${args.current}/${args.total}`);
  }
};

download(resource, 'local/path', downloadOptions)
  .then(result => {
    console.log('Download result:', {
      hash: result.hash,
      size: result.size
    });
  })
  .catch(err => console.error('Download error:', err));

// Calculate resource hash
const hashOptions = {
  encryption: {
    key: 'hex-encoded-key',
    iv: 'hex-encoded-iv'
  },
  hashAlgorithm: 'sha256',
  path: 'subfolder', // optional
  progressCallback: (args) => {
    console.log(`Hashing ${args.key}: ${args.current}/${args.total}`);
  }
};

calculateResourceHash(resource, hashOptions)
  .then(hash => console.log('Resource hash:', hash))
  .catch(err => console.error('Hash calculation error:', err));

// Delete resource
deleteResource(resource)
  .then(() => console.log('Resource deleted'))
  .catch(err => console.error('Delete resource error:', err));

API

Storage Configuration

The addon supports three types of storage:

type StorageConfig =
  | { storageType: 'FS', bucket: string }
  | { storageType: 'S3', endpoint: string, accessKeyId?: string, secretKey?: string, region?: string, bucket: string }
  | { storageType: 'STORJ', token: string, bucket: string }

Main Functions

upload(source: ResourceOrPath, target: ResourceOrPath, options?: UploadOptions): Promise<UploadResult>

Clones the contents of a resource to another, encrypting the contents, calculating hash and syncing dirhashes if needed.

download(source: ResourceOrPath, target: ResourceOrPath, options: DownloadOptions): Promise<DownloadResult>

Clones the contents of a resource to another, decrypting the contents, calculating hash and comparing with original resource hash.

calculateResourceHash(resource: ResourceOrPath, options?: HashOptions): Promise<Hash>

Calculates resource hash of a directory or file.

deleteResource(resource: ResourceOrPath): Promise<void>

Deletes a resource and all its contents.

smartServerCopy(source: ResourceOrPath, target: ResourceOrPath): Promise<ServerCopyResult>

Performs an optimized server-side copy when possible.

Constants

• DIRHASH_FILE: Constant defining the dirhash file name

For detailed type definitions and interfaces, please refer to the TypeScript definitions.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Benchmarks

The project includes benchmarks to measure the performance of various operations. To run the benchmarks:

yarn benchmark

For more information about the benchmarks, see the benchmarks README.

License

MIT

Acknowledgements

• NAPI-RS for providing the N-API bindings generator
• Super Protocol