@qlever-llc/trellis 0.7.0-rc.5 → 0.7.0

package/esm/transfer.js

@@ -0,0 +1,353 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _BaseTransferHandle_nc, _BaseTransferHandle_auth, _BaseTransferHandle_timeoutMs, _UploadTransferHandle_grant, _DownloadTransferHandle_grant;
+import { AsyncResult, isErr, Result } from "@qlever-llc/result";
+import { createInbox, headers as natsHeaders } from "@nats-io/nats-core";
+import Type from "typebox";
+import { verifyProof } from "./auth/proof.js";
+import { base64urlEncode, sha256 } from "./auth/utils.js";
+import { TransferError } from "./errors/TransferError.js";
+const TRANSFER_SEQUENCE_HEADER = "trellis-transfer-seq";
+const TRANSFER_EOF_HEADER = "trellis-transfer-eof";
+export const FileInfoSchema = Type.Object({
+    key: Type.String({ minLength: 1 }),
+    size: Type.Integer({ minimum: 0 }),
+    updatedAt: Type.String({ minLength: 1 }),
+    digest: Type.Optional(Type.String({ minLength: 1 })),
+    contentType: Type.Optional(Type.String({ minLength: 1 })),
+    metadata: Type.Record(Type.String({ minLength: 1 }), Type.String()),
+}, { additionalProperties: false });
+const TransferGrantBaseSchema = Type.Object({
+    type: Type.Literal("TransferGrant"),
+    service: Type.String({ minLength: 1 }),
+    sessionKey: Type.String({ minLength: 1 }),
+    transferId: Type.String({ minLength: 1 }),
+    subject: Type.String({ minLength: 1 }),
+    expiresAt: Type.String({ minLength: 1 }),
+    chunkBytes: Type.Integer({ minimum: 1 }),
+}, { additionalProperties: false });
+export const UploadTransferGrantSchema = Type.Object({
+    ...TransferGrantBaseSchema.properties,
+    kind: Type.Literal("upload"),
+    maxBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+    contentType: Type.Optional(Type.String({ minLength: 1 })),
+    metadata: Type.Optional(Type.Record(Type.String({ minLength: 1 }), Type.String())),
+}, { additionalProperties: false });
+export const DownloadTransferGrantSchema = Type.Object({
+    ...TransferGrantBaseSchema.properties,
+    kind: Type.Literal("download"),
+    info: FileInfoSchema,
+}, { additionalProperties: false });
+export const TransferGrantSchema = Type.Union([
+    UploadTransferGrantSchema,
+    DownloadTransferGrantSchema,
+]);
+async function createTransferProof(auth, subject, payload) {
+    const payloadHash = await sha256(payload);
+    const proofOk = await auth.sign(await sha256(buildTransferProofInput(auth.sessionKey, subject, payloadHash)));
+    return base64urlEncode(proofOk);
+}
+function buildTransferProofInput(sessionKey, subject, payloadHash) {
+    const enc = new TextEncoder();
+    const sessionKeyBytes = enc.encode(sessionKey);
+    const subjectBytes = enc.encode(subject);
+    const buf = new Uint8Array(4 + sessionKeyBytes.length + 4 + subjectBytes.length + 4 + payloadHash.length);
+    const view = new DataView(buf.buffer);
+    let offset = 0;
+    view.setUint32(offset, sessionKeyBytes.length);
+    offset += 4;
+    buf.set(sessionKeyBytes, offset);
+    offset += sessionKeyBytes.length;
+    view.setUint32(offset, subjectBytes.length);
+    offset += 4;
+    buf.set(subjectBytes, offset);
+    offset += subjectBytes.length;
+    view.setUint32(offset, payloadHash.length);
+    offset += 4;
+    buf.set(payloadHash, offset);
+    return buf;
+}
+function expired(expiresAt) {
+    return Date.now() >= Date.parse(expiresAt);
+}
+function asUint8Array(body) {
+    return body instanceof Uint8Array ? body : new Uint8Array(body);
+}
+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 streamFromBody(body) {
+    if (body instanceof Uint8Array || body instanceof ArrayBuffer) {
+        const bytes = asUint8Array(body);
+        return new ReadableStream({
+            start(controller) {
+                controller.enqueue(bytes);
+                controller.close();
+            },
+        });
+    }
+    return body instanceof ReadableStream ? body : streamFromAsyncIterable(body);
+}
+async function* chunkBody(body, chunkBytes) {
+    const reader = streamFromBody(body).getReader();
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done) {
+                return;
+            }
+            let offset = 0;
+            while (offset < next.value.length) {
+                const end = Math.min(offset + chunkBytes, next.value.length);
+                yield next.value.slice(offset, end);
+                offset = end;
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function parseTransferAck(msg, operation) {
+    if (msg.headers?.get("status") === "error") {
+        return Result.err(deserializeTransferError(msg, operation));
+    }
+    try {
+        const value = JSON.parse(msg.string());
+        return Result.ok(value);
+    }
+    catch (cause) {
+        return Result.err(new TransferError({ operation, cause }));
+    }
+}
+function deserializeTransferError(msg, operation) {
+    try {
+        const value = JSON.parse(msg.string());
+        return new TransferError({
+            operation: value.operation ?? operation,
+            context: value.context,
+            cause: value.message ? new Error(value.message) : undefined,
+        });
+    }
+    catch (cause) {
+        return new TransferError({ operation, cause });
+    }
+}
+async function collectDownload(nc, inbox, timeoutMs) {
+    const sub = nc.subscribe(inbox);
+    const iterator = sub[Symbol.asyncIterator]();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const next = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    clearTimeout(timer);
+                    reject(new TransferError({ operation: "get", context: { reason: "timeout" } }));
+                }, timeoutMs);
+                iterator.next().then((value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                }, (error) => {
+                    clearTimeout(timer);
+                    reject(error);
+                });
+            });
+            if (next.done) {
+                return Result.err(new TransferError({ operation: "get", context: { reason: "stream_closed" } }));
+            }
+            const msg = next.value;
+            if (msg.headers?.get("status") === "error") {
+                return Result.err(deserializeTransferError(msg, "get"));
+            }
+            if (msg.data.length > 0) {
+                chunks.push(msg.data);
+                total += msg.data.length;
+            }
+            if (msg.headers?.get(TRANSFER_EOF_HEADER) === "true") {
+                const merged = new Uint8Array(total);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    merged.set(chunk, offset);
+                    offset += chunk.length;
+                }
+                return Result.ok(merged);
+            }
+        }
+    }
+    catch (cause) {
+        return Result.err(cause instanceof TransferError ? cause : new TransferError({ operation: "get", cause }));
+    }
+    finally {
+        sub.unsubscribe();
+    }
+}
+class BaseTransferHandle {
+    constructor(nc, auth, timeoutMs) {
+        _BaseTransferHandle_nc.set(this, void 0);
+        _BaseTransferHandle_auth.set(this, void 0);
+        _BaseTransferHandle_timeoutMs.set(this, void 0);
+        __classPrivateFieldSet(this, _BaseTransferHandle_nc, nc, "f");
+        __classPrivateFieldSet(this, _BaseTransferHandle_auth, auth, "f");
+        __classPrivateFieldSet(this, _BaseTransferHandle_timeoutMs, timeoutMs, "f");
+    }
+    get nc() {
+        return __classPrivateFieldGet(this, _BaseTransferHandle_nc, "f");
+    }
+    get auth() {
+        return __classPrivateFieldGet(this, _BaseTransferHandle_auth, "f");
+    }
+    get timeoutMs() {
+        return __classPrivateFieldGet(this, _BaseTransferHandle_timeoutMs, "f");
+    }
+    validateGrant(grant, operation) {
+        if (expired(grant.expiresAt)) {
+            return Result.err(new TransferError({ operation, context: { reason: "expired", transferId: grant.transferId } }));
+        }
+        if (grant.sessionKey !== __classPrivateFieldGet(this, _BaseTransferHandle_auth, "f").sessionKey) {
+            return Result.err(new TransferError({
+                operation,
+                context: {
+                    reason: "session_mismatch",
+                    expectedSessionKey: grant.sessionKey,
+                    actualSessionKey: __classPrivateFieldGet(this, _BaseTransferHandle_auth, "f").sessionKey,
+                },
+            }));
+        }
+        return Result.ok(undefined);
+    }
+    async buildHeaders(subject, payload, seq, eof) {
+        const headers = natsHeaders();
+        headers.set("session-key", __classPrivateFieldGet(this, _BaseTransferHandle_auth, "f").sessionKey);
+        headers.set("proof", await createTransferProof(__classPrivateFieldGet(this, _BaseTransferHandle_auth, "f"), subject, payload));
+        if (seq !== undefined) {
+            headers.set(TRANSFER_SEQUENCE_HEADER, String(seq));
+        }
+        if (eof) {
+            headers.set(TRANSFER_EOF_HEADER, "true");
+        }
+        return headers;
+    }
+}
+_BaseTransferHandle_nc = new WeakMap(), _BaseTransferHandle_auth = new WeakMap(), _BaseTransferHandle_timeoutMs = new WeakMap();
+export class UploadTransferHandle extends BaseTransferHandle {
+    constructor(nc, auth, timeoutMs, grant) {
+        super(nc, auth, timeoutMs);
+        _UploadTransferHandle_grant.set(this, void 0);
+        __classPrivateFieldSet(this, _UploadTransferHandle_grant, grant, "f");
+    }
+    async put(body) {
+        const valid = this.validateGrant(__classPrivateFieldGet(this, _UploadTransferHandle_grant, "f"), "put").take();
+        if (isErr(valid)) {
+            return Result.err(valid.error);
+        }
+        let sentBytes = 0;
+        let seq = 0;
+        let completed = null;
+        for await (const chunk of chunkBody(body, __classPrivateFieldGet(this, _UploadTransferHandle_grant, "f").chunkBytes)) {
+            sentBytes += chunk.length;
+            if (__classPrivateFieldGet(this, _UploadTransferHandle_grant, "f").maxBytes !== undefined && sentBytes > __classPrivateFieldGet(this, _UploadTransferHandle_grant, "f").maxBytes) {
+                return Result.err(new TransferError({
+                    operation: "put",
+                    context: {
+                        reason: "max_bytes_exceeded",
+                        maxBytes: __classPrivateFieldGet(this, _UploadTransferHandle_grant, "f").maxBytes,
+                        attemptedBytes: sentBytes,
+                    },
+                }));
+            }
+            const headers = await this.buildHeaders(__classPrivateFieldGet(this, _UploadTransferHandle_grant, "f").subject, chunk, seq, false);
+            const response = await AsyncResult.try(() => this.nc.request(__classPrivateFieldGet(this, _UploadTransferHandle_grant, "f").subject, chunk, { timeout: this.timeoutMs, headers })).take();
+            if (isErr(response)) {
+                return Result.err(new TransferError({ operation: "put", cause: response.error }));
+            }
+            const ack = parseTransferAck(response, "put").take();
+            if (isErr(ack)) {
+                return Result.err(ack.error);
+            }
+            if (ack.status === "complete") {
+                completed = ack.info;
+            }
+            seq += 1;
+        }
+        const finalHeaders = await this.buildHeaders(__classPrivateFieldGet(this, _UploadTransferHandle_grant, "f").subject, new Uint8Array(), seq, true);
+        const finalResponse = await AsyncResult.try(() => this.nc.request(__classPrivateFieldGet(this, _UploadTransferHandle_grant, "f").subject, new Uint8Array(), {
+            timeout: this.timeoutMs,
+            headers: finalHeaders,
+        })).take();
+        if (isErr(finalResponse)) {
+            return Result.err(new TransferError({ operation: "put", cause: finalResponse.error }));
+        }
+        const finalAck = parseTransferAck(finalResponse, "put").take();
+        if (isErr(finalAck)) {
+            return Result.err(finalAck.error);
+        }
+        if (finalAck.status !== "complete") {
+            return Result.err(new TransferError({ operation: "put", context: { reason: "missing_completion" } }));
+        }
+        return Result.ok(finalAck.info ?? completed);
+    }
+}
+_UploadTransferHandle_grant = new WeakMap();
+export class DownloadTransferHandle extends BaseTransferHandle {
+    constructor(nc, auth, timeoutMs, grant) {
+        super(nc, auth, timeoutMs);
+        _DownloadTransferHandle_grant.set(this, void 0);
+        __classPrivateFieldSet(this, _DownloadTransferHandle_grant, grant, "f");
+    }
+    async getBytes() {
+        const valid = this.validateGrant(__classPrivateFieldGet(this, _DownloadTransferHandle_grant, "f"), "get").take();
+        if (isErr(valid)) {
+            return Result.err(valid.error);
+        }
+        const inbox = createInbox(`_INBOX.${this.auth.sessionKey.slice(0, 16)}`);
+        const payload = new Uint8Array();
+        const headers = await this.buildHeaders(__classPrivateFieldGet(this, _DownloadTransferHandle_grant, "f").subject, payload);
+        try {
+            this.nc.publish(__classPrivateFieldGet(this, _DownloadTransferHandle_grant, "f").subject, payload, { headers, reply: inbox });
+            await this.nc.flush();
+        }
+        catch (cause) {
+            return Result.err(new TransferError({ operation: "get", cause }));
+        }
+        return await collectDownload(this.nc, inbox, this.timeoutMs);
+    }
+}
+_DownloadTransferHandle_grant = new WeakMap();
+export function createTransferHandle(nc, auth, timeoutMs, grant) {
+    return grant.kind === "upload"
+        ? new UploadTransferHandle(nc, auth, timeoutMs, grant)
+        : new DownloadTransferHandle(nc, auth, timeoutMs, grant);
+}
+export async function verifyTransferMessage(args) {
+    if (!args.proof || !args.sessionKey || args.sessionKey !== args.expectedSessionKey) {
+        return false;
+    }
+    return await verifyProof(args.expectedSessionKey, {
+        sessionKey: args.sessionKey,
+        subject: args.subject,
+        payloadHash: await sha256(args.payload),
+    }, args.proof);
+}

package/esm/trellis.d.ts

@@ -0,0 +1,314 @@
+import { type JetStreamClient } from "@nats-io/jetstream";
+import { type Msg, type NatsConnection } from "@nats-io/nats-core";
+import type { EventDesc, InferSchemaType, TrellisAPI } from "./contracts.js";
+import type { StaticDecode } from "typebox";
+import { AuthValidateRequestResponseSchema, AuthValidateRequestSchema } from "./auth/protocol.js";
+import { AsyncResult, BaseError, type MaybeAsync, Result } from "@qlever-llc/result";
+import { Type } from "typebox";
+import { type JsonValue } from "./codec.js";
+import { TransferError, AuthError, type TrellisErrorInstance, type TrellisErrorMap, type TrellisErrorName, UnexpectedError, ValidationError } from "./errors/index.js";
+import { RemoteError } from "./errors/RemoteError.js";
+import { type LoggerLike } from "./globals.js";
+import { TypedKV } from "./kv.js";
+import { OperationInvoker, type OperationRefData } from "./operations.js";
+import { type FileInfo, type UploadTransferGrant } from "./transfer.js";
+type InferRuntimeRpcError<T> = T extends {
+    fromSerializable(data: unknown): infer TError;
+} ? TError : never;
+export type AuthValidateRequestResponse = StaticDecode<typeof AuthValidateRequestResponseSchema>;
+export type AuthValidateRequestInput = StaticDecode<typeof AuthValidateRequestSchema>;
+export type SessionCaller = AuthValidateRequestResponse["caller"];
+/**
+ * Safely extract JSON from a NATS message.
+ * The .json() method can throw if the message data is not valid JSON.
+ */
+export declare function safeJson(msg: Msg): Result<JsonValue, UnexpectedError>;
+export declare function base64urlEncode(data: Uint8Array): string;
+export declare function base64urlDecode(s: string): Uint8Array;
+export declare function toArrayBuffer(data: Uint8Array): ArrayBuffer;
+export declare function sha256(data: Uint8Array): Promise<Uint8Array>;
+export declare function buildProofInput(sessionKey: string, subject: string, payloadHash: Uint8Array): Uint8Array;
+export type TrellisSigner = (data: Uint8Array) => Promise<Uint8Array> | Uint8Array;
+export type TrellisAuth = {
+    sessionKey: string;
+    sign: TrellisSigner;
+};
+export type AnyTrellisAPI = TrellisAPI;
+export type TrellisMode = "client" | "server";
+type NonNever<T> = [T] extends [never] ? string : T;
+type OwnedApiFor<TContract> = TContract extends {
+    API: {
+        owned: infer TOwnedApi;
+    };
+} ? TOwnedApi extends AnyTrellisAPI ? TOwnedApi : never : never;
+type TrellisApiFor<TContract> = TContract extends {
+    API: {
+        trellis: infer TTrellisApi;
+    };
+} ? TTrellisApi extends AnyTrellisAPI ? TTrellisApi : OwnedApiFor<TContract> : OwnedApiFor<TContract>;
+export type MethodsOf<TA extends AnyTrellisAPI> = NonNever<keyof TA["rpc"] & string>;
+export type RpcMethodNameOf<TA extends AnyTrellisAPI> = MethodsOf<TA>;
+export type OperationsOf<TA extends AnyTrellisAPI> = NonNever<keyof TA["operations"] & string>;
+type EventsOf<TA extends AnyTrellisAPI> = NonNever<keyof TA["events"] & string>;
+type MethodInputOf<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> = TA["rpc"][M] extends {
+    input: infer TInput;
+} ? InferSchemaType<TInput> : never;
+export type RpcInputOf<TA extends AnyTrellisAPI, M extends RpcMethodNameOf<TA>> = MethodInputOf<TA, M>;
+type MethodOutputOf<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> = TA["rpc"][M] extends {
+    output: infer TOutput;
+} ? InferSchemaType<TOutput> : never;
+export type RpcOutputOf<TA extends AnyTrellisAPI, M extends RpcMethodNameOf<TA>> = MethodOutputOf<TA, M>;
+type RpcDescriptorOf<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> = TA["rpc"][M] extends {
+    input: infer TInput;
+    output: infer TOutput;
+    errors?: infer TErrors;
+    runtimeErrors?: infer TRuntimeErrors;
+    declaredErrorTypes?: infer TDeclaredErrorTypes;
+} ? {
+    input: TInput;
+    output: TOutput;
+    errors?: TErrors;
+    runtimeErrors?: TRuntimeErrors;
+    declaredErrorTypes?: TDeclaredErrorTypes;
+} & TA["rpc"][M] : never;
+type DeclaredBuiltinErrorOf<TNames> = TNames extends readonly (infer TName)[] ? TName extends TrellisErrorName ? TrellisErrorMap[TName] : never : never;
+type DeclaredRuntimeErrorOf<TRuntimeErrors> = TRuntimeErrors extends readonly (infer TRuntimeError)[] ? InferRuntimeRpcError<TRuntimeError> : never;
+type MethodDeclaredErrorOf<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> = RpcDescriptorOf<TA, M> extends {
+    errors?: infer TErrors;
+    runtimeErrors?: infer TRuntimeErrors;
+} ? DeclaredBuiltinErrorOf<TErrors> | DeclaredRuntimeErrorOf<TRuntimeErrors> : never;
+type RequestErrorOf<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> = MethodDeclaredErrorOf<TA, M> | RemoteError | ValidationError | UnexpectedError;
+type HandlerErrorOf<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> = MethodDeclaredErrorOf<TA, M> | TrellisErrorInstance;
+type EventOf<TA extends AnyTrellisAPI, E extends EventsOf<TA>> = TA["events"][E] extends EventDesc<infer TEvent> ? InferSchemaType<TEvent> : never;
+type EventPayloadOf<TA extends AnyTrellisAPI, E extends EventsOf<TA>> = Omit<EventOf<TA, E>, "header">;
+export type OperationInputOf<TA extends AnyTrellisAPI, O extends OperationsOf<TA>> = TA["operations"][O] extends {
+    input: infer TInput;
+} ? InferSchemaType<TInput> : never;
+export type OperationProgressOf<TA extends AnyTrellisAPI, O extends OperationsOf<TA>> = TA["operations"][O] extends {
+    progress: infer TProgress;
+} ? TProgress extends undefined ? unknown : InferSchemaType<NonNullable<TProgress>> : unknown;
+export type OperationOutputOf<TA extends AnyTrellisAPI, O extends OperationsOf<TA>> = TA["operations"][O] extends {
+    output: infer TOutput;
+} ? TOutput extends undefined ? unknown : InferSchemaType<NonNullable<TOutput>> : unknown;
+export type OperationRuntimeHandle<TProgress = unknown, TOutput = unknown> = {
+    id: string;
+    started(): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+    progress(value: TProgress): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+    complete(value: TOutput): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+    fail(error: BaseError): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+    cancel(): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+    attach(job: {
+        wait(): Promise<Result<unknown, BaseError>>;
+    }): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+};
+export type AcceptedOperation<TProgress = unknown, TOutput = unknown> = OperationRuntimeHandle<TProgress, TOutput> & {
+    ref: OperationRefData;
+    snapshot: RuntimeOperationSnapshot & {
+        progress?: TProgress;
+        output?: TOutput;
+    };
+};
+export type OperationTransferHandle = {
+    updates(): AsyncIterable<RuntimeOperationTransferProgress>;
+    completed(): Promise<Result<FileInfo, TransferError>>;
+};
+export type OperationHandlerContext<TInput, TProgress = unknown, TOutput = unknown, TTransfer = undefined> = {
+    input: TInput;
+    op: OperationRuntimeHandle<TProgress, TOutput>;
+    caller: SessionCaller;
+} & (TTransfer extends undefined ? {} : {
+    transfer: TTransfer;
+});
+export type OperationRegistration<TInput, TProgress = unknown, TOutput = unknown, TTransfer = undefined> = {
+    accept(args: {
+        sessionKey: string;
+    }): Promise<Result<AcceptedOperation<TProgress, TOutput>, UnexpectedError>>;
+    handle(handler: (context: OperationHandlerContext<TInput, TProgress, TOutput, TTransfer>) => unknown | Promise<unknown>): Promise<void>;
+};
+export type OperationTransferContextOf<TA extends AnyTrellisAPI, O extends OperationsOf<TA>> = TA["operations"][O] extends {
+    transfer: infer TTransfer;
+} ? TTransfer extends undefined ? undefined : OperationTransferHandle : undefined;
+export type OperationSurface<TA extends AnyTrellisAPI, TMode extends TrellisMode, O extends OperationsOf<TA>> = TMode extends "server" ? OperationRegistration<OperationInputOf<TA, O>, OperationProgressOf<TA, O>, OperationOutputOf<TA, O>, OperationTransferContextOf<TA, O>> : OperationInvoker<TA["operations"][O] & RuntimeOperationDesc>;
+export declare function isResultLike(value: unknown): value is Result<unknown, BaseError>;
+export type RuntimeOperationDesc = {
+    subject: string;
+    input: unknown;
+    progress?: unknown;
+    output?: unknown;
+    transfer?: {
+        store: string;
+        key: `/${string}`;
+        contentType?: `/${string}`;
+        metadata?: `/${string}`;
+        expiresInMs?: number;
+        maxBytes?: number;
+    };
+    cancel?: boolean;
+};
+export type RuntimeOperationTransferProgress = {
+    chunkIndex: number;
+    chunkBytes: number;
+    transferredBytes: number;
+};
+export type RuntimeOperationState = "pending" | "running" | "completed" | "failed" | "cancelled";
+export type RuntimeOperationSnapshot = {
+    id: string;
+    service: string;
+    operation: string;
+    revision: number;
+    state: RuntimeOperationState;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    progress?: unknown;
+    transfer?: RuntimeOperationTransferProgress;
+    output?: unknown;
+    error?: {
+        type: string;
+        message: string;
+    };
+};
+export type RuntimeOperationRecord = {
+    id: string;
+    service: string;
+    operation: string;
+    ownerSessionKey: string;
+    snapshot: RuntimeOperationSnapshot;
+    sequence: number;
+    terminal: boolean;
+    watchers: Set<string>;
+    waiters: Set<string>;
+};
+export type DurableOperationRecord = {
+    ownerSessionKey: string;
+    sequence: number;
+    snapshot: RuntimeOperationSnapshot;
+};
+export declare const DurableOperationRecordSchema: Type.TObject<{
+    ownerSessionKey: Type.TString;
+    sequence: Type.TNumber;
+    snapshot: Type.TObject<{
+        id: Type.TString;
+        service: Type.TString;
+        operation: Type.TString;
+        revision: Type.TNumber;
+        state: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"running">, Type.TLiteral<"completed">, Type.TLiteral<"failed">, Type.TLiteral<"cancelled">]>;
+        createdAt: Type.TString;
+        updatedAt: Type.TString;
+        completedAt: Type.TOptional<Type.TString>;
+        progress: Type.TOptional<Type.TAny>;
+        transfer: Type.TOptional<Type.TObject<{
+            chunkIndex: Type.TNumber;
+            chunkBytes: Type.TNumber;
+            transferredBytes: Type.TNumber;
+        }>>;
+        output: Type.TOptional<Type.TAny>;
+        error: Type.TOptional<Type.TObject<{
+            type: Type.TString;
+            message: Type.TString;
+        }>>;
+    }>;
+}>;
+export type RuntimeOperationAcceptedEnvelope = {
+    kind: "accepted";
+    ref: OperationRefData;
+    snapshot: RuntimeOperationSnapshot;
+    transfer?: UploadTransferGrant;
+};
+export type RuntimeOperationControlRequest = {
+    action: "get" | "wait" | "watch" | "cancel";
+    operationId: string;
+};
+export type RuntimeOperationController = {
+    get(operationId: string): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+    started(operationId: string): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+    progress(operationId: string, progress: unknown): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+    complete(operationId: string, output: unknown): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+    fail(operationId: string, error: BaseError): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+    cancel(operationId: string): Promise<Result<RuntimeOperationSnapshot, UnexpectedError>>;
+};
+export declare function buildRuntimeOperationSnapshot(runtime: Pick<RuntimeOperationRecord, "id" | "service" | "operation" | "snapshot">, state: RuntimeOperationState, patch?: Partial<RuntimeOperationSnapshot>): RuntimeOperationSnapshot;
+export declare function isTerminalRuntimeOperationSnapshot(value: unknown): value is RuntimeOperationSnapshot;
+type NoResponderRetryOpts = {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+};
+export type TrellisOpts<TA extends AnyTrellisAPI> = {
+    log?: LoggerLike;
+    timeout?: number;
+    stream?: string;
+    noResponderRetry?: NoResponderRetryOpts;
+    api?: TA;
+    authBypassMethods?: string[];
+};
+export type RequestOpts = {
+    timeout?: number;
+};
+export type EventOpts = {
+    mode?: "durable" | "ephemeral";
+    replay?: "all" | "new";
+    durableName?: string;
+    signal?: AbortSignal;
+};
+type MaybePromise<T> = T | Promise<T>;
+export type RpcHandlerContext = {
+    caller: SessionCaller;
+    sessionKey: string;
+};
+export type HandlerTrellis<TA extends AnyTrellisAPI> = {
+    request<M extends MethodsOf<TA>>(method: M, input: MethodInputOf<TA, M>, opts?: RequestOpts): Promise<Result<MethodOutputOf<TA, M>, RequestErrorOf<TA, M>>>;
+    requestOrThrow<M extends MethodsOf<TA>>(method: M, input: MethodInputOf<TA, M>, opts?: RequestOpts): Promise<MethodOutputOf<TA, M>>;
+    publish<E extends EventsOf<TA>>(event: E, data: EventPayloadOf<TA, E>): Promise<Result<void, ValidationError | UnexpectedError>>;
+    event<E extends EventsOf<TA>>(event: E, subjectData: Record<string, unknown>, fn: (message: EventOf<TA, E>) => MaybeAsync<void, BaseError>, opts?: EventOpts): Promise<Result<void, ValidationError | UnexpectedError>>;
+    operation<O extends OperationsOf<TA>>(operation: O): OperationSurface<TA, TrellisMode, O>;
+};
+export type HandlerFn<TMountApi extends AnyTrellisAPI, M extends MethodsOf<TMountApi>, TOutboundApi extends AnyTrellisAPI = TMountApi> = (m: MethodInputOf<TMountApi, M>, context: RpcHandlerContext, trellis: HandlerTrellis<TOutboundApi>) => MaybePromise<Result<MethodOutputOf<TMountApi, M>, HandlerErrorOf<TMountApi, M>>>;
+export type RpcHandlerFn<TA extends AnyTrellisAPI, M extends RpcMethodNameOf<TA>> = HandlerFn<TA, M, TA>;
+export type TrellisFor<TContract> = HandlerTrellis<TrellisApiFor<TContract>>;
+export type RpcName<TContract> = RpcMethodNameOf<OwnedApiFor<TContract>>;
+export type RpcInput<TContract, M extends RpcName<TContract>> = RpcInputOf<OwnedApiFor<TContract>, M>;
+export type RpcOutput<TContract, M extends RpcName<TContract>> = RpcOutputOf<OwnedApiFor<TContract>, M>;
+export type RpcRequestErrorOf<TA extends AnyTrellisAPI, M extends RpcMethodNameOf<TA>> = RequestErrorOf<TA, M>;
+export type RpcHandlerErrorOf<TA extends AnyTrellisAPI, M extends RpcMethodNameOf<TA>> = HandlerErrorOf<TA, M>;
+export type RpcHandler<TContract, M extends RpcName<TContract>> = HandlerFn<OwnedApiFor<TContract>, M, TrellisApiFor<TContract>>;
+export type EventName<TContract> = EventsOf<OwnedApiFor<TContract>>;
+export type EventType<TContract, E extends EventName<TContract>> = EventOf<OwnedApiFor<TContract>, E>;
+export type EventPayload<TContract, E extends EventName<TContract>> = EventPayloadOf<OwnedApiFor<TContract>, E>;
+export type EventHandler<TContract, E extends EventName<TContract>> = (event: EventType<TContract, E>) => MaybeAsync<void, BaseError>;
+export declare class Trellis<TA extends AnyTrellisAPI = TrellisAPI, TMode extends TrellisMode = "client"> {
+    #private;
+    readonly name: string;
+    readonly timeout: number;
+    readonly stream: string;
+    protected nats: NatsConnection;
+    protected js: JetStreamClient;
+    protected auth: TrellisAuth;
+    readonly api: TA;
+    constructor(name: string, // Must be unique for a service
+    nats: NatsConnection, auth: TrellisAuth, opts?: TrellisOpts<TA>);
+    /**
+     * Returns the underlying NATS connection.
+     */
+    get natsConnection(): NatsConnection;
+    operationStoreHandle(): Promise<TypedKV<typeof DurableOperationRecordSchema>>;
+    loadOperationRecord(operationId: string): Promise<DurableOperationRecord | null>;
+    saveOperationRecord(runtime: RuntimeOperationRecord): Promise<void>;
+    operation<O extends OperationsOf<TA>>(operation: O): OperationSurface<TA, TMode, O>;
+    mount(method: string, fn: (input: unknown, context: RpcHandlerContext, trellis: HandlerTrellis<TA>) => MaybePromise<Result<unknown, BaseError>>): Promise<void>;
+    respondWithError(msg: Msg, error: Error | BaseError): void;
+    publish(event: string, data: Record<string, unknown>): Promise<Result<void, ValidationError | UnexpectedError>>;
+    event(event: string, subjectData: Record<string, unknown>, fn: (message: unknown) => MaybeAsync<void, BaseError>, opts?: EventOpts): Promise<Result<void, ValidationError | UnexpectedError>>;
+    wait(): AsyncResult<void, BaseError>;
+    template(subject: string, data: unknown, allowWildcards?: boolean): Result<string, ValidationError>;
+    protected requestAuthValidate(input: AuthValidateRequestInput): Promise<Result<AuthValidateRequestResponse, AuthError | RemoteError | ValidationError | UnexpectedError>>;
+}
+export interface Trellis<TA extends AnyTrellisAPI = TrellisAPI, TMode extends TrellisMode = "client"> {
+    request<M extends MethodsOf<TA>>(method: M, input: MethodInputOf<TA, M>, opts?: RequestOpts): Promise<Result<MethodOutputOf<TA, M>, RequestErrorOf<TA, M>>>;
+    requestOrThrow<M extends MethodsOf<TA>>(method: M, input: MethodInputOf<TA, M>, opts?: RequestOpts): Promise<MethodOutputOf<TA, M>>;
+}
+export interface Trellis<TA extends AnyTrellisAPI = TrellisAPI, TMode extends TrellisMode = "client"> {
+    request<M extends MethodsOf<TA>>(method: M, input: MethodInputOf<TA, M>, opts?: RequestOpts): Promise<Result<MethodOutputOf<TA, M>, RequestErrorOf<TA, M>>>;
+    requestOrThrow<M extends MethodsOf<TA>>(method: M, input: MethodInputOf<TA, M>, opts?: RequestOpts): Promise<MethodOutputOf<TA, M>>;
+}
+export {};
+//# sourceMappingURL=trellis.d.ts.map