@tweedegolf/sab-adapter-cubbit-s3

Cubbit S3 Adapter

This adapter provides an abstraction layer over the S3 API of Cubbit cloud storage. It extends AdapterAmazonS3 and overrides some methods because the implementation of Cubbit is not fully compatible.

The adapter is one of the adapters that is meant to be used as a plugin of the Storage Abstraction package. However it can be used standalone as well, see below.

The API of the adapter abstracts away the differences between the API's of cloud storage services. The API only supports the basic, most commonly used cloud service operations such as creating a bucket, storing files and so on.

It is also possible to access all the specific functionality of the cloud service API through the service client of the adapter, see here.

If you are new to the Storage Abstraction library you may want to read this first.

Cubbit also has a native API. You can use this adapter if you want to use the native API.

import { Storage, StorageType } from "@tweedegolf/storage-abstraction";

const configuration = {
  type: StorageType.CUBBIT,
};

const storage = new Storage(configuration);

const result = await storage.listBuckets();

console.log(result);

The Storage class is cloud service agnostic and doesn't know anything about the adapter it uses and adapters are completely interchangeable. It only expects the adapter to have implemented all methods of the IAdapter interface, see the API.

When you create a Storage instance it checks the mandatory type key in the configuration object and then loads the appropriate adapter module automatically from your node_modules folder using require(). For more information please read this.

Configuration

The configuration object that you pass to the Storage constructor is forwarded to the constructor of the adapter.

The Storage constructor is only interested in the type key of the configuration object, all other keys are necessary for configuring the adapter.

The Storage constructor expects the configuration to be of type StorageAdapterConfig.

The adapter expects the configuration to be of type AdapterConfig or a type that extends this type.

export interface AdapterConfig {
  bucketName?: string;
  [id: string]: any; // any mandatory or optional key
}

export interface StorageAdapterConfig extends AdapterConfig {
  type: string;
}

The type of the configuration object for this adapter:

export interface AdapterConfigS3 extends AdapterConfig {
  region?: string; //
  endpoint: string; // mandatory
  credentials?: {
    accessKeyId: string;
    secretAccessKey: string;
  };
  accessKeyId: string;
  secretAccessKey: string;
}

Note that region is mandatory for the AWS SDK S3Client but it will also be picked up as environment variable AWS_REGION; therefor it is not mandatory in the config object.

Also note that accessKeyId, secretAccessKey and endpoint are mandatory!

Examples

Example with configuration object:

Examples with configuration object:

// Cubbit S3 compatible
const s = new Storage({
  type: StorageType.S3,
  accessKeyId: 'your-key-id'
  secretAccessKey: 'your-secret'
  endpoint: "https://s3.cubbit.eu/",
  region: "eu-west-1",
});

const s = new Storage({
  type: StorageType.S3,
  accessKeyId: 'your-key-id'
  secretAccessKey: 'your-secret'
  endpoint: "https://s3.cubbit.eu/",
  region: "eu-west-1",
  bucketName: "the-buck",
});

Example with configuration url:

const s = new Storage(
  "s3://your-key-id:your-access-key?endpoint=https://s3.cubbit.eu/&region=eu-west-1"
);

const s = new Storage(
  "s3://your-key-id:your-access-key@the-buck?endpoint=https://s3.cubbit.eu/&region=eu-west-1"
);

It is mandatory to set a value for region; setting it to "us-east-1" will always work. Other values may work as well but note that Cubbit is a decentralized storage so setting a region doesn't really make a difference.

You can also set the region using the AWS_REGION environment variable.

For more information about configuration urls please read this.

Standalone

You can also use the adapter standalone, without the need to create a Storage instance:

import { AdapterAmazonS3 } from "@tweedegolf/sab-adapter-amazon-s3";

const a = new AdapterAmazonS3();
const r = await a.listBuckets();
console.log(r);

API

For a complete description of the Adapter API see this part documentation of the Storage Abstraction package readme.

Exceptions

The S3 implementation of Cubbit checking if a bucket is public so bucketIsPublic.

const s = new Storage(config);
const {value, error} = s.bucketIsPublic("myBucket");
console.log(error)
// prints: 
// "Cubbit does not support checking if a bucket is public, please use the Cubbit web console"

Also getPublicURL is only supported with {noCheck: true}:

const s = new Storage(config);
const {value, error} = s.getPublicURL("myBucket", "myFile");
console.log(error)
// prints: 
// "Cannot check if bucket 'myBucket' is public. Use the Cubbit web console to check this or pass {noCheck: true}"

const s = new Storage(config);
const {value, error} = s.getPublicURL("myBucket", "myFile", {noCheck: true});
console.log(value)
// prints the public url