Kella Client

JS/TS client library for Kella

Features:

• Supports multiple servers (as in cluster) with automatic retry/failover
• Supports stream up/downloading

Installation

npm install @faulpeltz/kella-client

Usage

Here are some Typescript examples for the most common use cases:

import { KellaClient } from "@faulpeltz/kella-client";
 
 // setup new client
 const kc = new KellaClient({
    clientToken: "<client access token>", // note: use an env var instead of hard coding
    serverUrls: ["https://example1.internal:6010/", "https://example2.internal:6020"],
    caCertificate: "./config/my-ca.crt", // alternatively use self-signed cert (or omit if already in cert chain)
    connectTimeout: 500, // client connection timeout
    keepAliveTimeout: 5000, // keepalive timeout for HTTP connection
    maxConnections: 10, // max connections per server
});

// get basic server info
const info = await kc.serverInfo();

// get namespaces in universe
const namespaces = await kc.namespaces("your-universe");

// upload a blob (returns blob metadata)
const uploadedInfo = await kc.upload({ 
    universe: "your-univ", // universe name - required
    namespace: "ns",  // namespace - required (namespaces are automatically created on the first blob upload)
    friendlyName: "blob1",  // friendly blob name (mus be a valid cross-platform filename)
    blobId: "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD",  // optional: custom blob id (32-alphanumeric), requires permission enabled universe config
    mimeType: "application/foobar", // optional: blob data mimetype, uses header by default
    encrypt: true, // optional if a storage key is configured, encrypts automatically, false turns off
    compress: true, // compresses with gzip for serving to (most) HTTP clients
    data, // data blob (Buffer, Stream, string)
});

// get namespace blob ids
const iteratableBlobIds = await kc.namespaceBlobIds("default", "myns");

// get namespace info (total count and uncompressed, not-deduplicated size)
const namespaceInfo = await kc.namespaceInfo("default", "myns");

// get blob metadata only
const blobInfo = await kc.blobInfo("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD");

// download blob data
 const stream = await kc.download("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD");
 const buffer = await kc.downloadBuffer("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD");

// delete/undelete blob
await kc.deleteBlob("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD");
await kc.undeleteBlob("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD");

// final delete blob (no undelete, still available on backup nodes until cleaned up)
await kc.deleteBlob("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD", true);

// rename namespace (this can be slow and fail if servers are not replicating or very busy)
await kc.renameNamespace("your-univ", "myns", "newns");

// delete namespace (final deletes all blobs in a namespace)
await kc.deleteNamespace("your-univ", "myns");

// pin/unpin server (optional)
kc.selectServer(0); kc.deselectServer();

// handling errors
// will throw a KellaError in most cases
if (err instanceof KellaError && err.code === KellaErrorCode.NamespaceNotFound) { 
    ... 
}

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.

License

(c) faulpeltz MIT