@oatscenter/trellis 0.100.0-rc.1

package/store.d.ts

@@ -0,0 +1,71 @@
+import type { NatsConnection } from "@nats-io/nats-core/internal";
+import { AsyncResult } from "@oatscenter/result";
+import { StoreError } from "./errors/index.ts";
+import { TypedStoreEntry } from "./store_entry.ts";
+export { TypedStoreEntry } from "./store_entry.ts";
+export type StoreBody = Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+export type StoreWaitOptions = {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+};
+export type StoreOpenOptions = {
+    ttlMs?: number;
+    maxObjectBytes?: number;
+    maxTotalBytes?: number;
+    bindOnly?: boolean;
+    isCurrent?: () => boolean;
+};
+export type StorePutOptions = {
+    contentType?: string;
+    metadata?: Record<string, string>;
+};
+/** Explicit bounded query for listing object metadata in a typed store. */
+export type StoreListOptions = {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+};
+/** One key-sorted page of object metadata and its opaque continuation. */
+export type StoreListPage = {
+    entries: StoreInfo[];
+    nextCursor?: string;
+};
+export type StoreInfo = {
+    key: string;
+    size: number;
+    updatedAt: string;
+    digest?: string;
+    contentType?: string;
+    metadata: Record<string, string>;
+};
+export type StoreStatus = {
+    size: number;
+    sealed: boolean;
+    ttlMs: number;
+    maxObjectBytes?: number;
+    maxTotalBytes?: number;
+};
+type ExistingStoreStatus = {
+    ttl: number;
+};
+/** Verifies that an existing physical store matches its effective binding. */
+export declare function ensureExistingStoreOptions(store: {
+    status(): Promise<ExistingStoreStatus>;
+}, name: string, options: StoreOpenOptions): Promise<void>;
+export declare class TypedStore {
+    #private;
+    private constructor();
+    static open(nats: NatsConnection, name: string, options?: StoreOpenOptions): AsyncResult<TypedStore, StoreError>;
+    create(key: string, body: StoreBody, options?: StorePutOptions): AsyncResult<void, StoreError>;
+    put(key: string, body: StoreBody, options?: StorePutOptions): AsyncResult<void, StoreError>;
+    get(key: string): AsyncResult<TypedStoreEntry, StoreError>;
+    /**
+     * Waits for an object key to appear in the store and returns the resulting entry.
+     */
+    waitFor(key: string, options?: StoreWaitOptions): AsyncResult<TypedStoreEntry, StoreError>;
+    delete(key: string): AsyncResult<void, StoreError>;
+    list(opts?: StoreListOptions): AsyncResult<StoreListPage, StoreError>;
+    status(): AsyncResult<StoreStatus, StoreError>;
+}
+export declare function bytesFromStoreStream(stream: ReadableStream<Uint8Array>): Promise<Uint8Array>;

package/store.js

@@ -0,0 +1,412 @@
+import { Objm, } from "@nats-io/obj";
+import { AsyncResult, Result, } from "@oatscenter/result";
+import { StoreError } from "./errors/index.js";
+import { decodePaginationCursor, encodePaginationCursor, paginationQueryDigest, } from "./auth/protocol_wasm.js";
+import { TypedStoreEntry } from "./store_entry.js";
+export { TypedStoreEntry } from "./store_entry.js";
+const INTERNAL_CONTENT_TYPE_METADATA_KEY = "__trellis_content_type";
+const DEFAULT_STORE_WAIT_POLL_INTERVAL_MS = 250;
+const MAX_STORE_LIST_LIMIT = 500;
+const DEFAULT_STORE_LIST_LIMIT = 100;
+const STORE_LIST_CURSOR_ENDPOINT = "trellis.store.list";
+function metadataWithContentType(options) {
+    if (!options?.metadata && !options?.contentType) {
+        return undefined;
+    }
+    return {
+        ...(options?.metadata ?? {}),
+        ...(options?.contentType
+            ? { [INTERNAL_CONTENT_TYPE_METADATA_KEY]: options.contentType }
+            : {}),
+    };
+}
+function storeInfoFromObjectInfo(info) {
+    const { [INTERNAL_CONTENT_TYPE_METADATA_KEY]: contentType, ...metadata } = info.metadata ?? {};
+    return {
+        key: info.name,
+        size: info.size,
+        updatedAt: info.mtime,
+        ...(info.digest ? { digest: info.digest } : {}),
+        ...(contentType ? { contentType } : {}),
+        metadata,
+    };
+}
+function compareStoreKeys(left, right) {
+    const leftBytes = new TextEncoder().encode(left);
+    const rightBytes = new TextEncoder().encode(right);
+    for (let index = 0; index < Math.min(leftBytes.length, rightBytes.length); index++) {
+        if (leftBytes[index] !== rightBytes[index]) {
+            return leftBytes[index] - rightBytes[index];
+        }
+    }
+    return leftBytes.length - rightBytes.length;
+}
+function streamFromAsyncIterable(iterable) {
+    const iterator = iterable[Symbol.asyncIterator]();
+    return new ReadableStream({
+        async pull(controller) {
+            const next = await iterator.next();
+            if (next.done) {
+                controller.close();
+                return;
+            }
+            controller.enqueue(next.value);
+        },
+        async cancel(reason) {
+            await iterator.return?.(reason);
+        },
+    });
+}
+function validateStoreListOptions(opts = {}) {
+    const limit = opts.limit ?? DEFAULT_STORE_LIST_LIMIT;
+    if (!Number.isInteger(limit) || limit <= 0) {
+        return Result.err(new StoreError({
+            operation: "list",
+            context: { reason: "invalid_limit", limit },
+        }));
+    }
+    if (limit > MAX_STORE_LIST_LIMIT) {
+        return Result.err(new StoreError({
+            operation: "list",
+            context: {
+                reason: "limit_exceeded",
+                limit,
+                maxLimit: MAX_STORE_LIST_LIMIT,
+            },
+        }));
+    }
+    const cursor = opts.cursor ?? "";
+    if (opts.cursor !== undefined && cursor.length === 0) {
+        return Result.err(new StoreError({
+            operation: "list",
+            context: { reason: "invalid_cursor" },
+        }));
+    }
+    return Result.ok({ prefix: opts.prefix ?? "", cursor, limit });
+}
+function enforceMaxObjectBytes(stream, maxObjectBytes) {
+    if (maxObjectBytes === undefined) {
+        return stream;
+    }
+    const reader = stream.getReader();
+    let totalBytes = 0;
+    return new ReadableStream({
+        async pull(controller) {
+            const next = await reader.read();
+            if (next.done) {
+                controller.close();
+                return;
+            }
+            totalBytes += next.value.length;
+            if (totalBytes > maxObjectBytes) {
+                controller.error(new StoreError({
+                    operation: "put",
+                    context: {
+                        reason: "max_object_bytes_exceeded",
+                        maxObjectBytes,
+                        attemptedBytes: totalBytes,
+                    },
+                }));
+                await reader.cancel();
+                return;
+            }
+            controller.enqueue(next.value);
+        },
+        async cancel(reason) {
+            await reader.cancel(reason);
+        },
+    });
+}
+async function bytesFromStream(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let totalLength = 0;
+    while (true) {
+        const next = await reader.read();
+        if (next.done) {
+            break;
+        }
+        chunks.push(next.value);
+        totalLength += next.value.length;
+    }
+    const merged = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return merged;
+}
+function isNotFoundStoreError(error) {
+    return error.getContext().reason === "not_found";
+}
+function abortedStoreError(key, cause) {
+    return new StoreError({
+        operation: "waitFor",
+        cause,
+        context: { key, reason: "aborted" },
+    });
+}
+async function sleepWithSignal(ms, signal) {
+    if (signal?.aborted) {
+        throw signal.reason ??
+            new DOMException("The operation was aborted", "AbortError");
+    }
+    await new Promise((resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            cleanup();
+            reject(signal?.reason ??
+                new DOMException("The operation was aborted", "AbortError"));
+        };
+        const cleanup = () => {
+            clearTimeout(timeoutId);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function streamFromBody(body) {
+    return body instanceof ReadableStream ? body : streamFromAsyncIterable(body);
+}
+async function unwrapObjectInfo(store, key) {
+    try {
+        const info = await store.info(key);
+        if (info === null || info.deleted) {
+            return Result.err(new StoreError({
+                operation: "get",
+                context: { key, reason: "not_found" },
+            }));
+        }
+        return Result.ok(info);
+    }
+    catch (cause) {
+        return Result.err(new StoreError({ operation: "get", cause, context: { key } }));
+    }
+}
+/** Verifies that an existing physical store matches its effective binding. */
+export async function ensureExistingStoreOptions(store, name, options) {
+    const status = await store.status();
+    const actualTtlMs = status.ttl > 0 ? Math.floor(status.ttl / 1_000_000) : 0;
+    if (actualTtlMs !== (options.ttlMs ?? 0)) {
+        throw new Error(`Store '${name}' TTL does not match its binding`);
+    }
+}
+export class TypedStore {
+    #store;
+    #options;
+    constructor(store, options) {
+        this.#store = store;
+        this.#options = {
+            ttlMs: options.ttlMs ?? 0,
+            ...(options.maxObjectBytes !== undefined
+                ? { maxObjectBytes: options.maxObjectBytes }
+                : {}),
+            ...(options.maxTotalBytes !== undefined
+                ? { maxTotalBytes: options.maxTotalBytes }
+                : {}),
+            ...(options.bindOnly !== undefined ? { bindOnly: options.bindOnly } : {}),
+        };
+    }
+    static open(nats, name, options = {}) {
+        return AsyncResult.from((async () => {
+            try {
+                const objm = new Objm(nats);
+                const store = options.bindOnly
+                    ? await objm.open(name)
+                    : await objm.create(name, {
+                        ...(options.ttlMs && options.ttlMs > 0
+                            ? { ttl: options.ttlMs * 1_000_000 }
+                            : {}),
+                        ...(options.maxTotalBytes !== undefined
+                            ? { max_bytes: options.maxTotalBytes }
+                            : {}),
+                    });
+                await ensureExistingStoreOptions(store, name, options);
+                return Result.ok(new TypedStore(store, options));
+            }
+            catch (cause) {
+                return Result.err(new StoreError({ operation: "open", cause, context: { name } }));
+            }
+        })());
+    }
+    create(key, body, options) {
+        return AsyncResult.from(this.#putInternal("create", key, body, options, 0));
+    }
+    put(key, body, options) {
+        return AsyncResult.from(this.#putInternal("put", key, body, options));
+    }
+    get(key) {
+        return AsyncResult.from((async () => {
+            if (!this.#isCurrent())
+                return this.#stale("get", key);
+            const info = await unwrapObjectInfo(this.#store, key);
+            return info.map((objectInfo) => new TypedStoreEntry(this.#store, storeInfoFromObjectInfo(objectInfo)));
+        })());
+    }
+    /**
+     * Waits for an object key to appear in the store and returns the resulting entry.
+     */
+    waitFor(key, options = {}) {
+        return AsyncResult.from((async () => {
+            const startedAt = Date.now();
+            const pollIntervalMs = options.pollIntervalMs ??
+                DEFAULT_STORE_WAIT_POLL_INTERVAL_MS;
+            while (true) {
+                if (options.signal?.aborted) {
+                    return Result.err(abortedStoreError(key, options.signal.reason));
+                }
+                const entry = await this.get(key);
+                if (entry.isOk()) {
+                    return entry;
+                }
+                if (!isNotFoundStoreError(entry.error)) {
+                    return entry;
+                }
+                const remainingTimeoutMs = options.timeoutMs === undefined
+                    ? undefined
+                    : options.timeoutMs - (Date.now() - startedAt);
+                if (remainingTimeoutMs !== undefined && remainingTimeoutMs <= 0) {
+                    return Result.err(new StoreError({
+                        operation: "waitFor",
+                        context: { key, reason: "timeout", timeoutMs: options.timeoutMs },
+                    }));
+                }
+                try {
+                    await sleepWithSignal(remainingTimeoutMs === undefined
+                        ? pollIntervalMs
+                        : Math.min(pollIntervalMs, remainingTimeoutMs), options.signal);
+                }
+                catch (cause) {
+                    return Result.err(abortedStoreError(key, cause));
+                }
+            }
+        })());
+    }
+    delete(key) {
+        return AsyncResult.from((async () => {
+            if (!this.#isCurrent())
+                return this.#stale("delete", key);
+            try {
+                await this.#store.delete(key);
+                return Result.ok(undefined);
+            }
+            catch (cause) {
+                return Result.err(new StoreError({ operation: "delete", cause, context: { key } }));
+            }
+        })());
+    }
+    list(opts = {}) {
+        return AsyncResult.from((async () => {
+            if (!this.#isCurrent())
+                return this.#stale("list");
+            const query = validateStoreListOptions(opts);
+            if (query.isErr())
+                return Result.err(query.error);
+            const { prefix, cursor, limit } = query.unwrapOrElse(() => {
+                throw new Error("unreachable");
+            });
+            try {
+                const queryDigest = await paginationQueryDigest(STORE_LIST_CURSOR_ENDPOINT, { prefix });
+                let after = "";
+                if (cursor) {
+                    const decoded = await decodePaginationCursor(cursor, queryDigest);
+                    if (typeof decoded !== "string") {
+                        throw new Error("invalid pagination cursor");
+                    }
+                    after = decoded;
+                }
+                const objects = await this.#store.list();
+                const filtered = objects
+                    .filter((info) => !info.deleted && info.name.startsWith(prefix))
+                    .map(storeInfoFromObjectInfo)
+                    .sort((left, right) => compareStoreKeys(left.key, right.key))
+                    .filter((info) => compareStoreKeys(info.key, after) > 0);
+                const entries = filtered.slice(0, limit);
+                return Result.ok({
+                    entries,
+                    ...(filtered.length > limit
+                        ? {
+                            nextCursor: await encodePaginationCursor(queryDigest, entries.at(-1)?.key),
+                        }
+                        : {}),
+                });
+            }
+            catch (cause) {
+                return Result.err(new StoreError({ operation: "list", cause, context: { prefix } }));
+            }
+        })());
+    }
+    status() {
+        return AsyncResult.from((async () => {
+            if (!this.#isCurrent())
+                return this.#stale("status");
+            try {
+                const status = await this.#store.status();
+                return Result.ok(storeStatusFromObjectStoreStatus(status, this.#options));
+            }
+            catch (cause) {
+                return Result.err(new StoreError({ operation: "status", cause }));
+            }
+        })());
+    }
+    async #putInternal(operation, key, body, options, previousRevision) {
+        try {
+            if (!this.#isCurrent())
+                return this.#stale(operation, key);
+            const metadata = metadataWithContentType(options);
+            if (body instanceof Uint8Array) {
+                if (this.#options.maxObjectBytes !== undefined &&
+                    body.length > this.#options.maxObjectBytes) {
+                    return Result.err(new StoreError({
+                        operation,
+                        context: {
+                            key,
+                            reason: "max_object_bytes_exceeded",
+                            maxObjectBytes: this.#options.maxObjectBytes,
+                            attemptedBytes: body.length,
+                        },
+                    }));
+                }
+                await this.#store.putBlob({ name: key, ...(metadata ? { metadata } : {}) }, body, previousRevision === undefined ? undefined : { previousRevision });
+                return Result.ok(undefined);
+            }
+            const limitedStream = enforceMaxObjectBytes(streamFromBody(body), this.#options.maxObjectBytes);
+            await this.#store.put({ name: key, ...(metadata ? { metadata } : {}) }, limitedStream, previousRevision === undefined ? undefined : { previousRevision });
+            return Result.ok(undefined);
+        }
+        catch (cause) {
+            return Result.err(cause instanceof StoreError
+                ? cause
+                : new StoreError({ operation, cause, context: { key } }));
+        }
+    }
+    #isCurrent() {
+        return this.#options.isCurrent?.() ?? true;
+    }
+    #stale(operation, key) {
+        return Result.err(new StoreError({
+            operation,
+            context: { ...(key ? { key } : {}), reason: "stale_binding" },
+        }));
+    }
+}
+function storeStatusFromObjectStoreStatus(status, options) {
+    return {
+        size: status.size,
+        sealed: status.sealed,
+        ttlMs: status.ttl > 0 ? Math.floor(status.ttl / 1_000_000) : 0,
+        ...(options.maxObjectBytes !== undefined
+            ? { maxObjectBytes: options.maxObjectBytes }
+            : {}),
+        ...(status.streamInfo.config.max_bytes > 0
+            ? { maxTotalBytes: status.streamInfo.config.max_bytes }
+            : {}),
+    };
+}
+export function bytesFromStoreStream(stream) {
+    return bytesFromStream(stream);
+}

package/store_entry.d.ts

@@ -0,0 +1,20 @@
+import { AsyncResult } from "@oatscenter/result";
+import { StoreError } from "./errors/index.ts";
+import type { StoreInfo } from "./store.ts";
+type ObjectResultLike = {
+    data: ReadableStream<Uint8Array>;
+    error: Promise<unknown>;
+};
+type ObjectStoreLike = {
+    get(key: string): Promise<ObjectResultLike | null>;
+    getBlob(key: string): Promise<Uint8Array | null>;
+};
+export declare class TypedStoreEntry {
+    #private;
+    readonly key: string;
+    readonly info: StoreInfo;
+    constructor(store: ObjectStoreLike, info: StoreInfo);
+    stream(): AsyncResult<ReadableStream<Uint8Array>, StoreError>;
+    bytes(): AsyncResult<Uint8Array, StoreError>;
+}
+export {};

package/store_entry.js

@@ -0,0 +1,75 @@
+import { AsyncResult, Result } from "@oatscenter/result";
+import { StoreError } from "./errors/index.js";
+export class TypedStoreEntry {
+    key;
+    info;
+    #store;
+    constructor(store, info) {
+        this.#store = store;
+        this.key = info.key;
+        this.info = info;
+    }
+    stream() {
+        return AsyncResult.from((async () => {
+            try {
+                const result = await this.#store.get(this.key);
+                if (result === null) {
+                    return Result.err(new StoreError({
+                        operation: "stream",
+                        context: { key: this.key, reason: "not_found" },
+                    }));
+                }
+                return Result.ok(streamWithErrorCheck(result));
+            }
+            catch (cause) {
+                return Result.err(new StoreError({
+                    operation: "stream",
+                    cause,
+                    context: { key: this.key },
+                }));
+            }
+        })());
+    }
+    bytes() {
+        return AsyncResult.from((async () => {
+            try {
+                const bytes = await this.#store.getBlob(this.key);
+                if (bytes === null) {
+                    return Result.err(new StoreError({
+                        operation: "bytes",
+                        context: { key: this.key, reason: "not_found" },
+                    }));
+                }
+                return Result.ok(bytes);
+            }
+            catch (cause) {
+                return Result.err(new StoreError({
+                    operation: "bytes",
+                    cause,
+                    context: { key: this.key },
+                }));
+            }
+        })());
+    }
+}
+function streamWithErrorCheck(result) {
+    const reader = result.data.getReader();
+    return new ReadableStream({
+        async pull(controller) {
+            const next = await reader.read();
+            if (next.done) {
+                const error = await result.error;
+                if (error) {
+                    controller.error(error);
+                    return;
+                }
+                controller.close();
+                return;
+            }
+            controller.enqueue(next.value);
+        },
+        async cancel(reason) {
+            await reader.cancel(reason);
+        },
+    });
+}

package/tasks.d.ts

@@ -0,0 +1,10 @@
+import { AsyncResult, type BaseError } from "@oatscenter/result";
+import { type LoggerLike } from "./globals.ts";
+export declare class TrellisTasks {
+    #private;
+    constructor(opts: {
+        log?: LoggerLike;
+    });
+    add<E extends BaseError>(name: string, task: AsyncResult<void, E>): void;
+    wait(): AsyncResult<void, BaseError>;
+}

package/tasks.js

@@ -0,0 +1,28 @@
+import { AsyncResult, Result } from "@oatscenter/result";
+import { logger } from "./globals.js";
+export class TrellisTasks {
+    #tasks = {};
+    #log;
+    constructor(opts) {
+        this.#log = opts.log ?? logger;
+    }
+    /*
+     * Add a task to the task queue
+     */
+    add(name, task) {
+        if (name in this.#tasks) {
+            this.#log.error({ name }, "Task already running?");
+            throw new Error(`Task ${name} already running`);
+        }
+        this.#log.debug({ name }, "Added task");
+        this.#tasks[name] = task.then((r) => {
+            if (Result.isErr(r)) {
+                this.#log.error(r, "Task encountered a runtime error");
+            }
+            return r;
+        });
+    }
+    wait() {
+        return AsyncResult.any(Object.values(this.#tasks));
+    }
+}

package/telemetry/carrier.d.ts

@@ -0,0 +1,8 @@
+import { type Context, type Span } from "@opentelemetry/api";
+export interface HeaderCarrier {
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+}
+export declare function injectTraceContext(carrier: HeaderCarrier, span?: Span): void;
+export declare function extractTraceContext(carrier: HeaderCarrier): Context;
+export declare function createMapCarrier(): HeaderCarrier;

package/telemetry/carrier.js

@@ -0,0 +1,20 @@
+import { context, propagation, trace, } from "@opentelemetry/api";
+export function injectTraceContext(carrier, span) {
+    const ctx = span ? trace.setSpan(context.active(), span) : context.active();
+    propagation.inject(ctx, carrier, {
+        set: (c, k, v) => c.set(k, v),
+    });
+}
+export function extractTraceContext(carrier) {
+    return propagation.extract(context.active(), carrier, {
+        get: (c, k) => c.get(k),
+        keys: () => [],
+    });
+}
+export function createMapCarrier() {
+    const map = new Map();
+    return {
+        get: (key) => map.get(key),
+        set: (key, value) => map.set(key, value),
+    };
+}

package/telemetry/core.d.ts

@@ -0,0 +1,7 @@
+import { type Context, context, type Span, SpanKind, SpanStatusCode, trace, type Tracer } from "@opentelemetry/api";
+export declare function getTracer(scope?: string): Tracer;
+export declare function getActiveSpan(): Span | undefined;
+export declare function withSpan<T>(span: Span, fn: () => T): T;
+export declare function withSpanAsync<T>(span: Span, fn: () => Promise<T>): Promise<T>;
+export { context, SpanKind, SpanStatusCode, trace };
+export type { Context, Span };

package/telemetry/core.js

@@ -0,0 +1,14 @@
+import { context, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+export function getTracer(scope = "@oatscenter/trellis/telemetry") {
+    return trace.getTracer(scope);
+}
+export function getActiveSpan() {
+    return trace.getActiveSpan();
+}
+export function withSpan(span, fn) {
+    return context.with(trace.setSpan(context.active(), span), fn);
+}
+export async function withSpanAsync(span, fn) {
+    return context.with(trace.setSpan(context.active(), span), fn);
+}
+export { context, SpanKind, SpanStatusCode, trace };

package/telemetry/env.d.ts

@@ -0,0 +1,2 @@
+/** Reads an optional native environment variable without loading Node in browsers. */
+export declare function getEnv(key: string): string | undefined;

package/telemetry/env.js

@@ -0,0 +1,10 @@
+/** Reads an optional native environment variable without loading Node in browsers. */
+export function getEnv(key) {
+    const environmentGlobal = globalThis;
+    try {
+        return environmentGlobal.process?.env?.[key];
+    }
+    catch {
+        return undefined;
+    }
+}