@knowledgefutures/sdk 0.0.0-stage → 0.1.0

package/dist/storage/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The only error project code sees from storage. Every implementation maps
+ * its failures onto these codes — vendor XML, status codes and server quirks
+ * never escape — so a `catch` written against the in-memory store handles
+ * R2 the same way.
+ */
+export type StorageErrorCode = 
+/** No binding: the environment doesn't declare the service (or `public`). */
+'not_configured'
+/** The request itself is wrong: a bad key, metadata name, size or expiry. Fix the call. */
+ | 'invalid'
+/** The credentials were refused, or a signed URL was used past its expiry or not as signed. */
+ | 'forbidden'
+/** Bigger than the backend accepts. */
+ | 'too_large'
+/** The backend is down or unreachable. Safe to retry. */
+ | 'unavailable';
+export declare class StorageError extends Error {
+    readonly code: StorageErrorCode;
+    /** The backend's HTTP status, when there was one. For logs, not for branching. */
+    readonly status?: number | undefined;
+    readonly name = "StorageError";
+    constructor(code: StorageErrorCode, message: string, 
+    /** The backend's HTTP status, when there was one. For logs, not for branching. */
+    status?: number | undefined);
+}
+export declare function isStorageError(e: unknown, code?: StorageErrorCode): e is StorageError;

package/dist/storage/errors.js

@@ -0,0 +1,21 @@
+/**
+ * The only error project code sees from storage. Every implementation maps
+ * its failures onto these codes — vendor XML, status codes and server quirks
+ * never escape — so a `catch` written against the in-memory store handles
+ * R2 the same way.
+ */
+export class StorageError extends Error {
+    code;
+    status;
+    name = 'StorageError';
+    constructor(code, message, 
+    /** The backend's HTTP status, when there was one. For logs, not for branching. */
+    status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export function isStorageError(e, code) {
+    return e instanceof StorageError && (code === undefined || e.code === code);
+}

package/dist/storage/index.d.ts

@@ -0,0 +1,34 @@
+import { PUBLIC_STORAGE_ENV, STORAGE_ENV } from './binding.js';
+import { type S3StoreOptions } from './s3.js';
+import type { Storage } from './types.js';
+/**
+ * `@knowledgefutures/sdk/storage` — files for a project that declares
+ * `kf/storage@1`, with nothing to configure:
+ *
+ *   import { storage } from '@knowledgefutures/sdk/storage'
+ *   await storage.put('covers/1.jpg', bytes, { contentType: 'image/jpeg' })
+ *   const { key } = await storage.public.upload(file, { prefix: 'covers' })
+ *   storage.public.url(key)
+ *
+ * The console writes `KF_STORAGE_URL` (and `KF_STORAGE_PUBLIC_URL` with
+ * `"public": true`) into every environment that declares the service; `kf
+ * dev` writes the same variables pointing at a local RustFS. Code never sees
+ * which backend it has.
+ */
+export type * from './types.js';
+export { StorageError, isStorageError, type StorageErrorCode } from './errors.js';
+export type { S3StoreOptions } from './s3.js';
+type Env = Partial<Record<typeof STORAGE_ENV | typeof PUBLIC_STORAGE_ENV, string | undefined>>;
+/**
+ * A client from an explicit environment: a Worker's `env` (when
+ * `nodejs_compat` is off, `process.env` is empty), a script's, a test's. A
+ * string is the private store's binding alone.
+ */
+export declare function createStorage(env: Env | string, options?: S3StoreOptions): Storage;
+/**
+ * The zero-config client. It reads `process.env` on first use, never at
+ * import, so importing it costs nothing where storage isn't declared and a
+ * missing binding fails at the call that needed it, with the fix in the
+ * message.
+ */
+export declare const storage: Storage;

package/dist/storage/index.js

@@ -0,0 +1,77 @@
+import { parseBinding, PUBLIC_STORAGE_ENV, STORAGE_ENV } from './binding.js';
+import { createBrokeredStore } from './brokered.js';
+import { StorageError } from './errors.js';
+import { createS3Store } from './s3.js';
+export { StorageError, isStorageError } from './errors.js';
+/**
+ * A client from an explicit environment: a Worker's `env` (when
+ * `nodejs_compat` is off, `process.env` is empty), a script's, a test's. A
+ * string is the private store's binding alone.
+ */
+export function createStorage(env, options) {
+    const vars = typeof env === 'string' ? { [STORAGE_ENV]: env } : env;
+    const priv = vars[STORAGE_ENV];
+    if (!priv)
+        throw unconfigured(STORAGE_ENV, 'kf/storage@1');
+    // Either form (binding.ts): `s3+https://…` with fixed credentials (kf dev, tests), or
+    // `https://<instance>:<secret>@<storage service>/`, which exchanges for short-lived ones.
+    const parsed = parseBinding(priv, STORAGE_ENV);
+    const store = parsed.kind === 'static'
+        ? createS3Store(parsed.binding, options)
+        : createBrokeredStore({ ...parsed.binding, store: 'private' }, options);
+    let pub;
+    return {
+        ...store,
+        get public() {
+            if (pub)
+                return pub;
+            const value = vars[PUBLIC_STORAGE_ENV];
+            if (!value)
+                throw unconfigured(PUBLIC_STORAGE_ENV, '"public": true under kf/storage@1');
+            const p = parseBinding(value, PUBLIC_STORAGE_ENV);
+            if (!p.binding.publicBase) {
+                throw new StorageError('not_configured', `${PUBLIC_STORAGE_ENV} has no base URL`);
+            }
+            const publicBase = p.binding.publicBase;
+            pub =
+                p.kind === 'static'
+                    ? createS3Store({ ...p.binding, publicBase }, options)
+                    : createBrokeredStore({ ...p.binding, store: 'public', publicBase }, options);
+            return pub;
+        },
+    };
+}
+/**
+ * The zero-config client. It reads `process.env` on first use, never at
+ * import, so importing it costs nothing where storage isn't declared and a
+ * missing binding fails at the call that needed it, with the fix in the
+ * message.
+ */
+export const storage = (() => {
+    let resolved;
+    const current = () => {
+        if (resolved)
+            return resolved;
+        const env = globalThis.process?.env;
+        if (!env?.[STORAGE_ENV])
+            throw unconfigured(STORAGE_ENV, 'kf/storage@1');
+        resolved = createStorage(env);
+        return resolved;
+    };
+    // async, so a missing binding is a rejected promise like every other failure, not a throw.
+    const methods = {
+        put: async (...a) => current().put(...a),
+        get: async (...a) => current().get(...a),
+        head: async (...a) => current().head(...a),
+        delete: async (...a) => current().delete(...a),
+        list: async (...a) => current().list(...a),
+        signUpload: async (...a) => current().signUpload(...a),
+        signDownload: async (...a) => current().signDownload(...a),
+        upload: async (...a) => current().upload(...a),
+    };
+    return Object.defineProperty(methods, 'public', { get: () => current().public });
+})();
+function unconfigured(name, declare) {
+    return new StorageError('not_configured', `${name} is not set: declare ${declare} in kf.project.jsonc for this environment, ` +
+        `run under \`kf dev\`, or pass the environment to createStorage(env)`);
+}

package/dist/storage/local.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Setting up a LOCAL S3 server — the one `kf dev` runs, or one in a test —
+ * over the plain S3 API: create buckets, and let anyone read the public one.
+ * No vendor CLI, so it works against any server that passes the conformance
+ * suite (RustFS today). The console never uses this: deployed buckets are
+ * provisioned by kf/storage@1's adapter through the provider's own API.
+ */
+export interface LocalServer {
+    /** `http://localhost:<port>` */
+    endpoint: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    region?: string;
+}
+export interface LocalBucket {
+    name: string;
+    /** Anonymous GET on every object: the public store. */
+    publicRead?: boolean;
+}
+export interface EnsureOptions {
+    /** How long to wait for the server to accept connections. Default 30s. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/** Idempotent: buckets that exist are left alone, and the policy is simply set again. */
+export declare function ensureBuckets(server: LocalServer, buckets: LocalBucket[], options?: EnsureOptions): Promise<void>;

package/dist/storage/local.js

@@ -0,0 +1,57 @@
+import { StorageError } from './errors.js';
+import { sha256Hex, signRequest } from './sigv4.js';
+/** Idempotent: buckets that exist are left alone, and the policy is simply set again. */
+export async function ensureBuckets(server, buckets, options = {}) {
+    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    const credentials = {
+        accessKeyId: server.accessKeyId,
+        secretAccessKey: server.secretAccessKey,
+        region: server.region ?? 'us-east-1',
+    };
+    const deadline = Date.now() + (options.timeoutMs ?? 30_000);
+    const put = async (url, body = '') => {
+        for (;;) {
+            const headers = await signRequest({
+                method: 'PUT',
+                url,
+                payloadHash: await sha256Hex(body),
+                credentials,
+            });
+            try {
+                return await doFetch(url, { method: 'PUT', headers, ...(body ? { body } : {}) });
+            }
+            catch (e) {
+                // Not listening yet: the container has started, the server hasn't.
+                if (Date.now() > deadline) {
+                    throw new StorageError('unavailable', `${server.endpoint} never answered: ${e.message}`);
+                }
+                await new Promise((r) => setTimeout(r, 250));
+            }
+        }
+    };
+    for (const b of buckets) {
+        const res = await put(new URL(`${server.endpoint}/${b.name}`));
+        const text = await res.text();
+        if (!res.ok && !/BucketAlreadyOwnedByYou|BucketAlreadyExists/.test(text)) {
+            throw new StorageError('unavailable', `creating bucket ${b.name}: ${res.status} ${text.slice(0, 200)}`);
+        }
+        if (!b.publicRead)
+            continue;
+        const policy = JSON.stringify({
+            Version: '2012-10-17',
+            Statement: [
+                {
+                    Effect: 'Allow',
+                    Principal: { AWS: ['*'] },
+                    Action: ['s3:GetObject'],
+                    Resource: [`arn:aws:s3:::${b.name}/*`],
+                },
+            ],
+        });
+        const set = await put(new URL(`${server.endpoint}/${b.name}?policy=`), policy);
+        if (!set.ok) {
+            throw new StorageError('unavailable', `making ${b.name} publicly readable: ${set.status} ${(await set.text()).slice(0, 200)}`);
+        }
+        await set.body?.cancel();
+    }
+}

package/dist/storage/s3.d.ts

@@ -0,0 +1,22 @@
+import type { StorageBinding } from './binding.js';
+import type { ListResult, PublicStore, Store } from './types.js';
+/**
+ * A store over the S3 API — R2 behind the console, RustFS under `kf dev`.
+ * Path-style URLs (`<endpoint>/<bucket>/<key>`), which both accept, so there
+ * is one code path. Nothing here knows which backend it is talking to.
+ */
+export interface S3StoreOptions {
+    /** For tests. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /** With temporary credentials (brokered.ts): signed into every request and presigned URL. */
+    sessionToken?: string;
+}
+export declare function createS3Store(binding: StorageBinding & {
+    publicBase: string;
+}, options?: S3StoreOptions): PublicStore;
+export declare function createS3Store(binding: StorageBinding, options?: S3StoreOptions): Store;
+/**
+ * ListObjectsV2 by hand: Workers have no DOMParser, and the response is a
+ * flat, well-known shape.
+ */
+export declare function parseList(xml: string): ListResult;

package/dist/storage/s3.js

@@ -0,0 +1,254 @@
+import { StorageError } from './errors.js';
+import { attachment, checkExpiresIn, DOWNLOAD_EXPIRES_IN, UPLOAD_EXPIRES_IN, checkKey, checkMetadata, checkPrefix, checkSignUpload, DEFAULT_CONTENT_TYPE, IMMUTABLE, publicDisposition, SHORT_PUBLIC, toBytes, uploadAsPut, } from './shared.js';
+import { encodeKey, EMPTY_SHA256, presign, sha256Hex, signRequest, } from './sigv4.js';
+export function createS3Store(binding, options = {}) {
+    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    const credentials = {
+        accessKeyId: binding.accessKeyId,
+        secretAccessKey: binding.secretAccessKey,
+        region: binding.region,
+        ...(options.sessionToken ? { sessionToken: options.sessionToken } : {}),
+    };
+    const isPublic = binding.publicBase !== undefined;
+    const objectUrl = (key) => new URL(`${binding.endpoint}/${binding.bucket}/${encodeKey(key)}`);
+    async function send(method, url, o = {}) {
+        const headers = await signRequest({
+            method,
+            url,
+            headers: o.headers ?? {},
+            payloadHash: o.payloadHash ?? EMPTY_SHA256,
+            credentials,
+        });
+        try {
+            return await doFetch(url, {
+                method,
+                headers,
+                ...(o.body ? { body: o.body } : {}),
+            });
+        }
+        catch (e) {
+            throw new StorageError('unavailable', `storage is unreachable: ${e.message}`);
+        }
+    }
+    async function put(key, body, opts = {}) {
+        checkKey(key);
+        const metadata = checkMetadata(opts.metadata);
+        const { bytes, contentType } = await toBytes(body, opts.contentType);
+        const cacheControl = opts.cacheControl ?? (isPublic ? SHORT_PUBLIC : undefined);
+        const disposition = isPublic
+            ? publicDisposition(contentType, opts.contentDisposition)
+            : opts.contentDisposition;
+        const headers = { 'content-type': contentType };
+        if (cacheControl)
+            headers['cache-control'] = cacheControl;
+        if (disposition)
+            headers['content-disposition'] = disposition;
+        for (const [name, value] of Object.entries(metadata))
+            headers[`x-amz-meta-${name}`] = value;
+        const res = await send('PUT', objectUrl(key), {
+            headers,
+            body: bytes,
+            payloadHash: await sha256Hex(bytes),
+        });
+        if (!res.ok)
+            throw await failure(res, `put ${key}`);
+        await res.body?.cancel();
+        const stored = {
+            key,
+            size: bytes.byteLength,
+            etag: unquote(res.headers.get('etag') ?? ''),
+            uploaded: new Date(res.headers.get('date') ?? Date.now()),
+            contentType,
+            metadata,
+        };
+        if (cacheControl)
+            stored.cacheControl = cacheControl;
+        if (disposition)
+            stored.contentDisposition = disposition;
+        return stored;
+    }
+    async function head(key) {
+        checkKey(key);
+        const res = await send('HEAD', objectUrl(key));
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw await failure(res, `head ${key}`);
+        return describe(key, res);
+    }
+    async function get(key) {
+        checkKey(key);
+        const res = await send('GET', objectUrl(key));
+        if (res.status === 404) {
+            await res.body?.cancel();
+            return null;
+        }
+        if (!res.ok)
+            throw await failure(res, `get ${key}`);
+        const meta = describe(key, res);
+        const body = res.body ?? new Response('').body;
+        return {
+            ...meta,
+            body,
+            arrayBuffer: () => new Response(body).arrayBuffer(),
+            text: () => new Response(body).text(),
+        };
+    }
+    async function del(key) {
+        checkKey(key);
+        const res = await send('DELETE', objectUrl(key));
+        // 204 for a delete; 404 from some backends for a key that was never there — both are success.
+        if (!res.ok && res.status !== 404)
+            throw await failure(res, `delete ${key}`);
+        await res.body?.cancel();
+    }
+    async function list(opts = {}) {
+        checkPrefix(opts.prefix);
+        const limit = opts.limit ?? 1000;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+            throw new StorageError('invalid', 'limit is 1–1000');
+        }
+        const url = new URL(`${binding.endpoint}/${binding.bucket}`);
+        url.searchParams.set('list-type', '2');
+        url.searchParams.set('max-keys', String(limit));
+        if (opts.prefix)
+            url.searchParams.set('prefix', opts.prefix);
+        if (opts.cursor)
+            url.searchParams.set('continuation-token', opts.cursor);
+        const res = await send('GET', url);
+        if (!res.ok)
+            throw await failure(res, 'list');
+        return parseList(await res.text());
+    }
+    async function signUpload(key, o) {
+        checkKey(key);
+        checkSignUpload(o);
+        const expiresIn = checkExpiresIn(o.expiresIn, UPLOAD_EXPIRES_IN);
+        const cacheControl = o.cacheControl ?? (isPublic ? SHORT_PUBLIC : undefined);
+        // Sent by the browser. content-length is signed too, but the browser sets
+        // it from the body, so it is not in what the caller must send.
+        const sent = { 'content-type': o.contentType };
+        if (cacheControl)
+            sent['cache-control'] = cacheControl;
+        // Signed, so a browser cannot upload HTML to the public store as inline.
+        const disposition = isPublic ? publicDisposition(o.contentType, undefined) : undefined;
+        if (disposition)
+            sent['content-disposition'] = disposition;
+        const url = await presign({
+            method: 'PUT',
+            url: objectUrl(key),
+            headers: { ...sent, 'content-length': String(o.size) },
+            expiresIn,
+            credentials,
+        });
+        return {
+            key,
+            url,
+            method: 'PUT',
+            headers: sent,
+            expiresAt: new Date(Date.now() + expiresIn * 1000),
+        };
+    }
+    async function signDownload(key, o = {}) {
+        checkKey(key);
+        const expiresIn = checkExpiresIn(o.expiresIn, DOWNLOAD_EXPIRES_IN);
+        const url = objectUrl(key);
+        if (o.filename)
+            url.searchParams.set('response-content-disposition', attachment(o.filename));
+        return presign({ method: 'GET', url, expiresIn, credentials });
+    }
+    const store = {
+        put,
+        get,
+        head,
+        delete: del,
+        list,
+        signUpload,
+        signDownload,
+        upload: async (file, options) => {
+            const p = uploadAsPut(file, options, isPublic ? { cacheControl: IMMUTABLE } : {});
+            return put(p.key, p.body, p.options);
+        },
+    };
+    if (!isPublic)
+        return store;
+    const base = binding.publicBase;
+    return {
+        ...store,
+        url: (key) => {
+            checkKey(key);
+            return `${base}/${encodeKey(key)}`;
+        },
+    };
+}
+/* ------------------------------ responses ------------------------------ */
+function describe(key, res) {
+    const metadata = {};
+    for (const [name, value] of res.headers) {
+        if (name.startsWith('x-amz-meta-'))
+            metadata[name.slice('x-amz-meta-'.length)] = value;
+    }
+    const o = {
+        key,
+        size: Number(res.headers.get('content-length') ?? 0),
+        etag: unquote(res.headers.get('etag') ?? ''),
+        uploaded: new Date(res.headers.get('last-modified') ?? 0),
+        contentType: res.headers.get('content-type') ?? DEFAULT_CONTENT_TYPE,
+        metadata,
+    };
+    const cacheControl = res.headers.get('cache-control');
+    const disposition = res.headers.get('content-disposition');
+    if (cacheControl)
+        o.cacheControl = cacheControl;
+    if (disposition)
+        o.contentDisposition = disposition;
+    return o;
+}
+/** Every backend failure as a StorageError — the vendor's XML never reaches the caller. */
+async function failure(res, what) {
+    const text = res.body ? await res.text().catch(() => '') : '';
+    const code = tag(text, 'Code') ?? '';
+    const message = tag(text, 'Message') ?? res.statusText;
+    const detail = `${what}: ${code || res.status}${message ? ` — ${message}` : ''}`;
+    if (res.status === 413 || code === 'EntityTooLarge') {
+        return new StorageError('too_large', detail, res.status);
+    }
+    if (res.status === 401 || res.status === 403)
+        return new StorageError('forbidden', detail, res.status);
+    if (code === 'NoSuchBucket') {
+        return new StorageError('not_configured', `${detail} (the binding names a bucket that does not exist)`, res.status);
+    }
+    if (res.status === 429 || res.status >= 500)
+        return new StorageError('unavailable', detail, res.status);
+    return new StorageError('invalid', detail, res.status);
+}
+/**
+ * ListObjectsV2 by hand: Workers have no DOMParser, and the response is a
+ * flat, well-known shape.
+ */
+export function parseList(xml) {
+    const objects = [...xml.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g)].map(([, c]) => ({
+        key: tag(c, 'Key') ?? '',
+        size: Number(tag(c, 'Size') ?? 0),
+        etag: unquote(tag(c, 'ETag') ?? ''),
+        uploaded: new Date(tag(c, 'LastModified') ?? 0),
+    }));
+    const truncated = tag(xml, 'IsTruncated') === 'true';
+    const cursor = tag(xml, 'NextContinuationToken');
+    return truncated && cursor ? { objects, cursor } : { objects };
+}
+function tag(xml, name) {
+    const m = new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(xml);
+    return m ? unescapeXml(m[1]) : undefined;
+}
+function unescapeXml(s) {
+    return s.replace(/&(#x[0-9a-fA-F]+|#\d+|amp|lt|gt|quot|apos);/g, (_, e) => {
+        if (e[0] === '#') {
+            return String.fromCodePoint(e[1] === 'x' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10));
+        }
+        return { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" }[e];
+    });
+}
+function unquote(etag) {
+    return etag.replace(/^W\//, '').replace(/^"|"$/g, '');
+}

package/dist/storage/shared.d.ts

@@ -0,0 +1,45 @@
+import type { Body, PutOptions, SignUploadOptions, Upload, UploadOptions } from './types.js';
+export declare const MAX_KEY_BYTES = 1024;
+export declare const MAX_EXPIRES_IN = 604800;
+/** Default lifetimes of a signed upload and a signed download, in seconds. */
+export declare const UPLOAD_EXPIRES_IN = 600;
+export declare const DOWNLOAD_EXPIRES_IN = 300;
+/**
+ * A key is 1–1024 UTF-8 bytes with no leading `/`, no `.` or `..` segment and
+ * no control characters. The segment rule is not S3's: a URL path normalizes
+ * `a/../b` to `b` before it is sent, so such a key would silently name a
+ * different object.
+ */
+export declare function checkKey(key: string): void;
+export declare function checkPrefix(prefix: string | undefined): void;
+export declare function checkMetadata(metadata: Record<string, string> | undefined): Record<string, string>;
+export declare function checkExpiresIn(seconds: number | undefined, fallback: number): number;
+export declare function checkSignUpload(o: SignUploadOptions): void;
+export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/** Bytes and a content type, from anything `put` accepts. */
+export declare function toBytes(body: Body, contentType: string | undefined): Promise<{
+    bytes: Uint8Array;
+    contentType: string;
+}>;
+/** `upload`'s arguments as a `put`: a generated key under the prefix, the file's extension kept. */
+export declare function uploadAsPut(file: Blob | Upload, options: UploadOptions | undefined, defaults: {
+    cacheControl?: string;
+}): {
+    key: string;
+    body: Body;
+    options: PutOptions;
+};
+/** `.jpg` from `Cover Art.JPG`; nothing when there is no sensible extension. */
+export declare function extensionOf(name: string): string;
+/** How the public store caches: generated keys never change, chosen keys might. */
+export declare const IMMUTABLE = "public, max-age=31536000, immutable";
+export declare const SHORT_PUBLIC = "public, max-age=300";
+export declare function rendersInline(contentType: string): boolean;
+/**
+ * The disposition a public object is stored with. A caller's own `attachment;
+ * filename=…` is kept; asking for `inline` on a type outside the list is not
+ * honoured.
+ */
+export declare function publicDisposition(contentType: string, requested: string | undefined): string | undefined;
+/** An attachment disposition, safe for any file name (RFC 6266 + RFC 5987). */
+export declare function attachment(filename: string): string;