@oatscenter/trellis 0.100.0-rc.1

package/service/runtime/bootstrap.d.ts

@@ -0,0 +1,56 @@
+import type { NatsConnection } from "@nats-io/nats-core";
+import { type TrellisAuth as SessionAuth } from "../../auth.ts";
+import { type AuthorizationContextBundle } from "../../auth/authorization_context.ts";
+import type { RuntimeApi } from "../../participant_runtime/api.ts";
+import type { LoggerLike } from "../../globals.ts";
+import type { TrellisServiceRuntimeDeps } from "./runtime.ts";
+import type { GeneratedServiceParticipant, ResourceBindings } from "./service.ts";
+type ServiceBootstrapConnectInfo = {
+    connectionId: string;
+    participantId: string;
+    participantDigest: string;
+    contractId: string;
+    contractDigest: string;
+    transports: {
+        native?: {
+            natsServers: string[];
+        };
+        websocket?: {
+            natsServers: string[];
+        };
+    };
+    jwt: string;
+    jwtExpiresAt: number;
+    authorizationContext: AuthorizationContextBundle;
+};
+/** Validated bootstrap material used to create a service runtime session. */
+export type ServiceBootstrapResponse = {
+    status: "ready";
+    serverNow: number;
+    serverClockOffsetMs: number;
+    connectInfo: ServiceBootstrapConnectInfo;
+    binding: {
+        contractId: string;
+        digest: string;
+        resources: ResourceBindings;
+        apiBindings: Readonly<Record<string, unknown>>;
+    };
+};
+/** Loads the default transport and telemetry dependencies for service connection. */
+export declare function loadDefaultServiceRuntimeDeps(): Promise<TrellisServiceRuntimeDeps>;
+/** Fetches and validates service bootstrap material, retrying pending states. */
+export declare function fetchServiceBootstrapInfo(args: {
+    trellisUrl: string;
+    serviceName: string;
+    name?: string;
+    contractId: string;
+    contractDigest: string;
+    contract: GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined>;
+    identityAuth: SessionAuth;
+    sessionAuth: SessionAuth;
+    log: LoggerLike;
+    connectionId?: string;
+}): Promise<ServiceBootstrapResponse>;
+/** Closes a NATS connection created by an unsuccessful bootstrap attempt. */
+export declare function closeFailedServiceBootstrapConnection(nc: NatsConnection): Promise<void>;
+export {};

package/service/runtime/bootstrap.js

@@ -0,0 +1,226 @@
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { ulid } from "ulid";
+import { base64urlDecode, base64urlEncode, estimateMidpointClockOffsetMs, sha256, } from "../../auth.js";
+import {} from "../../auth/authorization_context.js";
+import { AuthorizationContextRefreshResponseSchema } from "../../auth/authorization/types.js";
+import { decodeTrellisHttpError, TrellisHttpError, } from "../../auth/http_error.js";
+import { ContractResourceBindingsSchema } from "../../participant.js";
+import { participantEvidence } from "../../participant_runtime/participant.js";
+import { TransportError } from "../../errors/index.js";
+import { loadDefaultRuntimeTransport } from "../../runtime_transport.js";
+import { initTelemetry } from "../../telemetry/init.js";
+const DEFAULT_BOOTSTRAP_UNAVAILABLE_INITIAL_RETRY_MS = 1_000;
+const MAX_BOOTSTRAP_UNAVAILABLE_RETRY_MS = 30_000;
+function getErrorCauseMessage(error) {
+    if (error && typeof error === "object") {
+        const context = error.context;
+        if (typeof context?.causeMessage === "string" &&
+            context.causeMessage.length > 0) {
+            return context.causeMessage;
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function bootstrapUnavailableRetryDelayMs(attempt) {
+    const exponent = Math.min(attempt, 10);
+    return Math.min(DEFAULT_BOOTSTRAP_UNAVAILABLE_INITIAL_RETRY_MS * 2 ** exponent, MAX_BOOTSTRAP_UNAVAILABLE_RETRY_MS);
+}
+class ServiceBootstrapEndpointUnavailableError extends Error {
+    constructor(cause) {
+        super("Service bootstrap endpoint is unavailable.", { cause });
+        this.name = "ServiceBootstrapEndpointUnavailableError";
+    }
+}
+/** Loads the default transport and telemetry dependencies for service connection. */
+export async function loadDefaultServiceRuntimeDeps() {
+    const transport = await loadDefaultRuntimeTransport();
+    return {
+        initTelemetry,
+        connect: ({ servers, token, authenticator, inboxPrefix, ...extraOptions }) => transport.connect({
+            servers,
+            ...extraOptions,
+            ...(token ? { token } : {}),
+            ...(authenticator ? { authenticator: authenticator } : {}),
+            ...(inboxPrefix ? { inboxPrefix } : {}),
+        }),
+    };
+}
+const ServiceBootstrapReadySchema = Type.Object({
+    ...AuthorizationContextRefreshResponseSchema.properties,
+    authorization: Type.Object({
+        participantId: Type.String({ minLength: 1 }),
+        participantDigest: Type.String({ minLength: 1 }),
+        resourceRuntime: ContractResourceBindingsSchema,
+    }),
+});
+async function fetchServiceBootstrapInfoOnce(args) {
+    const requestStartedAtMs = Date.now();
+    const requestId = ulid();
+    const issuedAt = args.identityAuth.currentIat() * 1_000;
+    const provisionedIdentityKeyId = base64urlEncode(await sha256(base64urlDecode(args.identityAuth.sessionKey)));
+    const unsigned = {
+        identityKeyId: provisionedIdentityKeyId,
+        sessionKey: args.sessionAuth.sessionKey,
+        connectionId: args.connectionId,
+        requestId,
+        iat: issuedAt,
+        ...participantEvidence(args.contract),
+        ...(args.name === undefined ? {} : { name: args.name }),
+    };
+    const body = JSON.stringify({
+        ...unsigned,
+        proof: await args.identityAuth.signSessionProof({
+            purpose: "serviceBootstrap",
+            origin: args.bootstrapUrl.origin,
+            unsignedRequest: unsigned,
+        }),
+    });
+    let response;
+    try {
+        response = await fetch(args.bootstrapUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+        });
+    }
+    catch (cause) {
+        throw new ServiceBootstrapEndpointUnavailableError(cause);
+    }
+    const responseReceivedAtMs = Date.now();
+    if (!response.ok)
+        throw await decodeTrellisHttpError(response);
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        payload = undefined;
+    }
+    return {
+        response,
+        payload,
+        requestStartedAtMs,
+        responseReceivedAtMs,
+    };
+}
+/** Fetches and validates service bootstrap material, retrying pending states. */
+export async function fetchServiceBootstrapInfo(args) {
+    const bootstrapUrl = new URL("/bootstrap/service", args.trellisUrl);
+    const connectionId = args.connectionId ?? ulid();
+    let unavailableAttempt = 0;
+    while (true) {
+        let settled;
+        try {
+            settled = await fetchServiceBootstrapInfoOnce({
+                ...args,
+                bootstrapUrl,
+                connectionId,
+            });
+            unavailableAttempt = 0;
+        }
+        catch (cause) {
+            if (cause instanceof TrellisHttpError && cause.code === "resource_pending") {
+                await delay(bootstrapUnavailableRetryDelayMs(unavailableAttempt));
+                unavailableAttempt += 1;
+                continue;
+            }
+            if (!(cause instanceof ServiceBootstrapEndpointUnavailableError)) {
+                throw cause;
+            }
+            const retryDelayMs = bootstrapUnavailableRetryDelayMs(unavailableAttempt);
+            unavailableAttempt += 1;
+            args.log.warn({
+                service: args.serviceName,
+                trellisUrl: args.trellisUrl,
+                contractId: args.contractId,
+                contractDigest: args.contractDigest,
+                attempt: unavailableAttempt,
+                retryDelayMs,
+                causeMessage: getErrorCauseMessage(cause.cause),
+            }, "Service bootstrap endpoint unavailable; retrying");
+            await delay(retryDelayMs);
+            continue;
+        }
+        if (settled.payload === undefined) {
+            throw new TransportError({
+                code: "trellis.bootstrap.invalid_response",
+                message: "Service bootstrap returned invalid JSON.",
+                hint: "Retry the connection. If it keeps happening, check the Trellis deployment.",
+                context: {
+                    trellisUrl: args.trellisUrl,
+                    contractId: args.contractId,
+                    contractDigest: args.contractDigest,
+                },
+            });
+        }
+        const response = Value.Parse(ServiceBootstrapReadySchema, settled.payload);
+        const serverClockOffsetMs = estimateMidpointClockOffsetMs({
+            requestStartedAtMs: settled.requestStartedAtMs,
+            responseReceivedAtMs: settled.responseReceivedAtMs,
+            serverNowSeconds: response.serverNow / 1_000,
+        });
+        args.identityAuth.setServerClockOffsetMs(serverClockOffsetMs);
+        args.sessionAuth.setServerClockOffsetMs(serverClockOffsetMs);
+        const native = response.transports.native;
+        if (!native) {
+            throw new TransportError({
+                code: "trellis.bootstrap.invalid_response",
+                message: "Service bootstrap returned no native NATS transport.",
+                hint: "Configure native NATS endpoints for the Trellis runtime.",
+            });
+        }
+        return {
+            status: "ready",
+            serverNow: response.serverNow / 1_000,
+            serverClockOffsetMs,
+            connectInfo: {
+                connectionId: response.runtime.connectionId,
+                participantId: response.runtime.participantId,
+                participantDigest: response.authorization.participantDigest,
+                contractId: args.contractId,
+                contractDigest: args.contractDigest,
+                transports: { native: { natsServers: native.natsServers } },
+                jwt: response.routing.bootstrapJwt,
+                jwtExpiresAt: response.routing.bootstrapJwtExpiresAt,
+                authorizationContext: response.authorizationContext,
+            },
+            binding: {
+                contractId: args.contractId,
+                digest: response.authorization.participantDigest,
+                apiBindings: response.apiBindings,
+                resources: {
+                    kv: response.authorization.resourceRuntime.kv ?? {},
+                    store: response.authorization.resourceRuntime.store ?? {},
+                    ...(response.authorization.resourceRuntime.jobs === undefined
+                        ? {}
+                        : { jobs: response.authorization.resourceRuntime.jobs }),
+                    ...(response.authorization.resourceRuntime.eventConsumers ===
+                        undefined
+                        ? {}
+                        : {
+                            eventConsumers: response.authorization.resourceRuntime.eventConsumers,
+                        }),
+                },
+            },
+        };
+    }
+}
+/** Closes a NATS connection created by an unsuccessful bootstrap attempt. */
+export async function closeFailedServiceBootstrapConnection(nc) {
+    const closed = nc.closed().catch(() => undefined);
+    if (nc.isClosed()) {
+        await closed;
+        return;
+    }
+    try {
+        await nc.close();
+    }
+    catch {
+        // The connection closure is the lifecycle result, including auth revocation.
+    }
+    await closed;
+}

package/service/runtime/core.d.ts

@@ -0,0 +1,46 @@
+import { type NatsConnection } from "@nats-io/nats-core";
+import { type PermissionAtom, type RuntimeApi } from "../../participant_runtime/api.ts";
+import { AsyncResult, BaseError } from "@oatscenter/result";
+import { TransferError } from "../../errors/index.ts";
+import { type HandlerFn, type MethodsOf, type OperationInputOf, type OperationOutputOf, type OperationProgressOf, type OperationRegistration, type OperationsOf, type OperationTransferContextOf, type OperationTransferHandle, type OperationUpdateOf, type RuntimeOperationController, Trellis, type TrellisAuth, type TrellisMode, type TrellisOpts } from "../../session.ts";
+import { type FileInfo, type SendTransferGrant } from "../../transfer.ts";
+type TrellisServiceRuntimeOpts<TA extends RuntimeApi> = Omit<TrellisOpts<TA>, "api"> & {
+    api: TA;
+    transferSupport?: RuntimeOperationTransferSupport;
+    version?: string;
+    operationDeploymentId?: string;
+    operationConnectionId?: string;
+    feedOwnerId?: string;
+};
+export type TrellisServiceRuntimeFor<TA extends RuntimeApi = RuntimeApi> = Omit<TrellisServiceRuntime, "mount" | "operationHandle"> & {
+    mount<M extends MethodsOf<TA>>(method: M, fn: HandlerFn<TA, M>): Promise<void>;
+    operationHandle<O extends OperationsOf<TA>>(operation: O): OperationRegistration<OperationInputOf<TA, O>, OperationProgressOf<TA, O>, OperationOutputOf<TA, O>, OperationTransferContextOf<TA, O>, BaseError, OperationUpdateOf<TA, O>>;
+};
+type RuntimeOperationTransferSession = {
+    grant: SendTransferGrant;
+    transfer: OperationTransferHandle;
+};
+type RuntimeOperationTransferSupport = {
+    openOperationTransfer(args: {
+        sessionKey: string;
+        permission: PermissionAtom | undefined;
+        requiredCapabilities: readonly string[];
+        store: string;
+        key: string;
+        expiresInMs: number;
+        maxBytes?: number;
+        contentType?: string;
+        metadata?: Record<string, string>;
+        onComplete?: (info: FileInfo) => Promise<void>;
+    }): AsyncResult<RuntimeOperationTransferSession, TransferError>;
+};
+export declare class TrellisServiceRuntime extends Trellis<RuntimeApi, TrellisMode> {
+    #private;
+    readonly operations: RuntimeOperationController;
+    private constructor();
+    mountRuntime(method: string, fn: Parameters<Trellis<RuntimeApi, TrellisMode>["mount"]>[1]): Promise<void>;
+    static create<TA extends RuntimeApi>(name: string, nats: NatsConnection, auth: TrellisAuth, opts: TrellisServiceRuntimeOpts<TA>): TrellisServiceRuntimeFor<TA>;
+    operationHandle(operation: string): OperationRegistration<unknown, unknown, unknown, undefined, BaseError>;
+    stop(): Promise<void>;
+}
+export {};