@oatscenter/trellis 0.100.0-rc.1

package/caller.d.ts

@@ -0,0 +1,111 @@
+import { AsyncResult, type BaseError, type Result } from "@oatscenter/result";
+import type { TrellisConnection } from "./connection.ts";
+import type { TypedKV } from "./kv.ts";
+import type { OperationInvoker } from "./operations.ts";
+import type { TypedStore } from "./store.ts";
+import { type GeneratedParticipant } from "./participant_runtime/participant.ts";
+import type { EventListenerContext, EventOpts, FeedSubscribeOpts, PreparedTrellisEvent, RequestOpts, RuntimeStateStoresForContract, StateFacade, Trellis } from "./session.ts";
+import type { ConnectedActionName, PascalActionName } from "./participant_runtime/surface_names.ts";
+type CodecValue<T> = T extends {
+    decode(value: unknown): infer TValue;
+} ? TValue : never;
+type GeneratedCodec = Readonly<{
+    decode(value: unknown): unknown;
+}>;
+type SelectedActionShape = {
+    kind: "rpc" | "operation" | "event" | "feed";
+    descriptorName: string;
+    direction: unknown;
+    input?: unknown;
+    output?: unknown;
+    event?: unknown;
+    payload?: unknown;
+};
+type SelectedDescriptor<TSelection> = TSelection extends {
+    api: {
+        actions: Readonly<Record<string, unknown>>;
+    };
+    actions: readonly {
+        descriptorName: string;
+        direction: unknown;
+    }[];
+} ? TSelection["actions"][number] extends infer TSelected ? TSelected extends {
+    descriptorName: infer TName extends string;
+} ? TName extends keyof TSelection["api"]["actions"] ? TSelection["api"]["actions"][TName] & {
+    direction: TSelected extends {
+        direction: infer TDirection;
+    } ? TDirection : never;
+} : never : never : never : never;
+type SelectedAction<TContract extends GeneratedParticipant> = TContract["uses"][number] extends infer TSelection ? TSelection extends {
+    api: {
+        identity: string;
+        actions: Readonly<Record<string, unknown>>;
+    };
+    actions: readonly {
+        descriptorName: string;
+        direction: unknown;
+    }[];
+} ? SelectedDescriptor<TSelection> extends infer TAction ? TAction extends SelectedActionShape ? TAction & {
+    generatedName: TContract["actionNames"][`${TSelection["api"]["identity"]}:${TAction["descriptorName"]}`];
+} : never : never : never : never;
+type ActionMethod<TAction extends SelectedActionShape> = TAction["kind"] extends "rpc" ? TAction["input"] extends GeneratedCodec ? TAction["output"] extends GeneratedCodec ? TAction extends {
+    pagination: "cursor";
+} ? CodecValue<TAction["output"]> extends {
+    items: readonly (infer TItem)[];
+    page: {
+        nextCursor?: string;
+    };
+} ? ((input: CodecValue<TAction["input"]>, opts?: RequestOpts) => AsyncResult<CodecValue<TAction["output"]>, BaseError>) & {
+    pages(input?: Omit<CodecValue<TAction["input"]>, "page">, opts?: RequestOpts): AsyncIterable<Result<CodecValue<TAction["output"]>, BaseError>>;
+    items(input?: Omit<CodecValue<TAction["input"]>, "page">, opts?: RequestOpts): AsyncIterable<Result<TItem, BaseError>>;
+} : never : (input: CodecValue<TAction["input"]>, opts?: RequestOpts) => AsyncResult<CodecValue<TAction["output"]>, BaseError> : never : never : TAction["kind"] extends "operation" ? TAction["input"] extends GeneratedCodec ? ((input: CodecValue<TAction["input"]>) => ReturnType<OperationInvoker<never>["input"]>) & {
+    resume: OperationInvoker<never>["resume"];
+} : never : TAction["kind"] extends "feed" ? TAction["input"] extends GeneratedCodec ? TAction["event"] extends GeneratedCodec ? (input: CodecValue<TAction["input"]>, opts?: FeedSubscribeOpts) => AsyncResult<AsyncIterable<CodecValue<TAction["event"]>>, BaseError> : never : never : TAction["kind"] extends "event" ? TAction["payload"] extends GeneratedCodec ? TAction["direction"] extends "publish" ? ((event: CodecValue<TAction["payload"]>) => AsyncResult<void, BaseError>) & {
+    prepare(event: CodecValue<TAction["payload"]>): ReturnType<Trellis["prepare"]>;
+} : (handler: (event: CodecValue<TAction["payload"]>, context: EventListenerContext) => unknown | Promise<unknown>, opts?: EventOpts) => AsyncResult<void, BaseError> : never : never;
+type ActionRecord<TAction> = TAction extends SelectedActionShape & {
+    generatedName: string;
+} ? {
+    readonly [K in TAction["kind"] extends "event" ? TAction["direction"] extends "publish" ? `publish${PascalActionName<TAction["generatedName"]>}` : `on${PascalActionName<TAction["generatedName"]>}` : ConnectedActionName<TAction["generatedName"]>]: ActionMethod<TAction>;
+} : never;
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+type KvFacadeFor<TContract extends GeneratedParticipant> = {
+    readonly [Name in keyof TContract["resources"] as TContract["resources"][Name] extends {
+        kind: "kv";
+    } ? Name : never]: TContract["resources"][Name] extends {
+        codec: infer TCodec;
+    } ? TypedKV<CodecValue<TCodec>> : never;
+};
+type StoreFacadeFor<TContract extends GeneratedParticipant> = {
+    readonly [Name in keyof TContract["resources"] as TContract["resources"][Name] extends {
+        kind: "store";
+    } ? Name : never]: TypedStore;
+};
+/** Minimum participant contract accepted by the public caller connector. */
+export type CallerParticipant = GeneratedParticipant;
+/** Flat caller surface inferred from a generated participant's selected actions. */
+export type CallerRuntime<TContract extends GeneratedParticipant> = UnionToIntersection<ActionRecord<SelectedAction<TContract>>> & {
+    readonly connection: TrellisConnection;
+    availability(): ParticipantAvailability<TContract>;
+    watchAvailability(): AsyncIterable<ParticipantAvailability<TContract>>;
+    readonly state: StateFacade<RuntimeStateStoresForContract<TContract>>;
+    readonly kv: KvFacadeFor<TContract>;
+    readonly store: StoreFacadeFor<TContract>;
+    publishPrepared(event: PreparedTrellisEvent): AsyncResult<void, BaseError>;
+    transfer: Trellis["transfer"];
+    wait(): AsyncResult<void, BaseError>;
+};
+type OptionalCapability<TContract extends GeneratedParticipant> = TContract["uses"][number]["optionalCapabilities"][number];
+type OptionalResource<TContract extends GeneratedParticipant> = {
+    [Name in keyof TContract["resources"]]: TContract["resources"][Name]["availability"] extends "optional" ? Name : never;
+}[keyof TContract["resources"]];
+type ParticipantAvailability<TContract extends GeneratedParticipant> = Readonly<{
+    capabilities: Readonly<Record<OptionalCapability<TContract>, boolean>>;
+    resources: Readonly<Record<OptionalResource<TContract>, boolean>>;
+}>;
+/** Projects a private Trellis session into the selected flat caller vocabulary. */
+export declare function createCallerRuntime<TContract extends GeneratedParticipant>(session: object, contract: TContract, resources?: {
+    kv?: object;
+    store?: object;
+}): CallerRuntime<TContract>;
+export {};

package/caller.js

@@ -0,0 +1,85 @@
+import { AsyncResult, err, ok, } from "@oatscenter/result";
+import { getParticipantRuntime, } from "./participant_runtime/participant.js";
+import { createActionUnavailableError } from "./session.js";
+import { cursorItems, cursorPages } from "./pagination.js";
+/** Projects a private Trellis session into the selected flat caller vocabulary. */
+export function createCallerRuntime(session, contract, resources = {}) {
+    const runtime = session;
+    const caller = {
+        connection: runtime.connection,
+        availability: () => runtime.connection.availability(),
+        watchAvailability: () => runtime.connection.watchAvailability(),
+        state: runtime.state,
+        kv: resources.kv ?? {},
+        store: resources.store ?? {},
+        publishPrepared: runtime.publishPrepared.bind(runtime),
+        transfer: runtime.transfer.bind(runtime),
+        wait: runtime.wait.bind(runtime),
+    };
+    for (const action of getParticipantRuntime(contract).actions) {
+        const unavailable = () => {
+            const current = runtime.connection.availability().capabilities;
+            return action.optionalCapabilities.length > 0 &&
+                !action.optionalCapabilities.every((capability) => current[capability])
+                ? createActionUnavailableError(action.name, action.optionalCapabilities)
+                : undefined;
+        };
+        switch (action.descriptor.kind) {
+            case "rpc":
+                {
+                    const request = (input, opts) => {
+                        const error = unavailable();
+                        return error
+                            ? AsyncResult.from(Promise.resolve(err(error)))
+                            : runtime.request(action.name, input, opts);
+                    };
+                    if (action.descriptor.pagination === "cursor") {
+                        request.pages = (input, opts) => cursorPages(request, input, opts);
+                        request.items = (input, opts) => cursorItems(request, input, opts);
+                    }
+                    caller[action.connectedName] = request;
+                }
+                break;
+            case "operation":
+                {
+                    const operation = runtime.operationHandle(action.name, unavailable);
+                    const invoke = (input) => operation.input(input);
+                    invoke.resume = operation.resume.bind(operation);
+                    caller[action.connectedName] = invoke;
+                }
+                break;
+            case "feed":
+                caller[action.connectedName] = (input, opts) => {
+                    const error = unavailable();
+                    return error
+                        ? AsyncResult.from(Promise.resolve(err(error)))
+                        : runtime.feedHandle(action.name).input(input).subscribe(opts);
+                };
+                break;
+            case "event":
+                if (action.direction === "publish") {
+                    const publish = (event) => {
+                        const error = unavailable();
+                        return error
+                            ? AsyncResult.from(Promise.resolve(err(error)))
+                            : runtime.publish(action.name, event);
+                    };
+                    publish.prepare = (event) => runtime.prepare(action.name, event);
+                    caller[action.connectedName] = publish;
+                }
+                else {
+                    caller[action.connectedName] = (handler, opts) => {
+                        const error = unavailable();
+                        return error
+                            ? AsyncResult.from(Promise.resolve(err(error)))
+                            : runtime.listenEvent(action.name, {}, async (event, context) => {
+                                await handler(event, context);
+                                return ok(undefined);
+                            }, opts);
+                    };
+                }
+                break;
+        }
+    }
+    return caller;
+}

package/client.d.ts

@@ -0,0 +1,14 @@
+import type { LoggerLike } from "./globals.ts";
+type NoResponderRetryOpts = {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+};
+/** Transport options shared by caller connections. */
+export type ClientOpts = {
+    name?: string;
+    log?: LoggerLike;
+    timeout?: number;
+    stream?: string;
+    noResponderRetry?: NoResponderRetryOpts;
+};
+export {};

package/client.js

@@ -0,0 +1 @@
+export {};

package/client_connect.d.ts

@@ -0,0 +1,143 @@
+import { AsyncResult, BaseError, UnexpectedError } from "@oatscenter/result";
+import { type StaticDecode, Type } from "typebox";
+import { type CallerRuntime } from "./caller.ts";
+import type { ClientOpts } from "./client.ts";
+import { type GeneratedParticipant } from "./participant_runtime/participant.ts";
+import type { ContractResourceBindings } from "./participant_runtime/schemas.ts";
+import { TransportError } from "./errors/index.ts";
+import { type ResourceMigrations } from "./kv.ts";
+import { type RuntimeTransport } from "./runtime_transport.ts";
+type ClientContract = GeneratedParticipant;
+type ResourceMigrationsFor<TContract extends ClientContract, TKind extends "state" | "kv"> = Readonly<Partial<{
+    [Name in keyof TContract["resources"] as TContract["resources"][Name] extends {
+        kind: TKind;
+    } ? Name : never]: TContract["resources"][Name] extends {
+        codec: {
+            decode(value: unknown): infer TValue;
+        };
+    } ? ResourceMigrations<TValue> : never;
+}>> & Readonly<Record<string, ResourceMigrations<unknown> | undefined>>;
+/** Direct State and KV migrations supplied by the application at connection time. */
+export type ClientResourceMigrations<TContract extends ClientContract = ClientContract> = Readonly<{
+    state?: ResourceMigrationsFor<TContract, "state">;
+    kv?: ResourceMigrationsFor<TContract, "kv">;
+}>;
+/** Browser caller runtime whose lifecycle owner can revoke and end its session. */
+export type ConnectedTrellisClient<TContract extends ClientContract> = CallerRuntime<TContract> & {
+    logout(): Promise<void>;
+};
+type BrowserClientAuthOptions = {
+    mode?: "browser";
+    provider?: string;
+    redirectTo?: string | (() => string);
+    landingPath?: string;
+    context?: unknown;
+    currentUrl?: URL | string | (() => URL | string);
+    flowId?: string;
+    persistence?: "remembered" | "temporary";
+};
+type SessionKeyClientAuthOptionsBase = {
+    mode: "session_key";
+    sessionKeySeed: string;
+    sessionId?: string;
+    provider?: string;
+    redirectTo: string;
+    currentUrl?: URL | string | (() => URL | string);
+    context?: unknown;
+    flowId?: string;
+};
+type SessionKeyClientAuthOptions = SessionKeyClientAuthOptionsBase;
+export type ClientAuthOptions = BrowserClientAuthOptions | SessionKeyClientAuthOptions;
+export type ClientAuthRequiredContext = {
+    loginUrl: string;
+    sessionKey: string;
+    mode: "browser" | "session_key";
+};
+export type ClientAuthContinuation = {
+    status: "bound";
+    flowId: string;
+} | {
+    status: "handled";
+} | void;
+export type ClientAuthHandledErrorData = {
+    id: string;
+    type: "ClientAuthHandledError";
+    message: string;
+    context?: Record<string, unknown>;
+    traceId?: string;
+};
+/**
+ * Error raised when client authentication was delegated to caller-owned routing.
+ */
+export declare class ClientAuthHandledError extends BaseError<ClientAuthHandledErrorData> {
+    readonly name: "ClientAuthHandledError";
+    constructor();
+    toSerializable(): ClientAuthHandledErrorData;
+}
+type ClientConnectArgsFor<TContract extends ClientContract> = ClientOpts & {
+    trellisUrl: string;
+    participant: TContract;
+    auth?: ClientAuthOptions;
+    resourceMigrations?: ClientResourceMigrations<TContract>;
+    onAuthRequired?: (ctx: ClientAuthRequiredContext) => Promise<ClientAuthContinuation> | ClientAuthContinuation;
+};
+export type TrellisClientConnectArgs<TContract extends ClientContract = ClientContract> = ClientConnectArgsFor<TContract>;
+type ClientConnectDeps = {
+    loadTransport(): Promise<RuntimeTransport>;
+    now(): number;
+    initialBootstrap?: ClientBootstrapReady;
+    runtimeSessionKeySeed?: string;
+};
+declare const ClientBootstrapReadySchema: Type.TObject<{
+    status: Type.TLiteral<"ready">;
+    serverNow: Type.TInteger;
+    connectInfo: Type.TObject<{
+        connectionId: Type.TOptional<Type.TString>;
+        sessionId: Type.TString;
+        participantId: Type.TString;
+        participantDigest: Type.TString;
+        transports: Type.TObject<{
+            native: Type.TOptional<Type.TObject<{
+                natsServers: Type.TArray<Type.TString>;
+            }>>;
+            websocket: Type.TOptional<Type.TObject<{
+                natsServers: Type.TArray<Type.TString>;
+            }>>;
+        }>;
+        transport: Type.TObject<{
+            inboxPrefix: Type.TString;
+            jwt: Type.TString;
+            jwtExpiresAt: Type.TInteger;
+        }>;
+        authorizationContext: Type.TObject<{
+            context: Type.TUnknown;
+            issuer: Type.TObject<{
+                keyId: Type.TString;
+                publicKey: Type.TString;
+                state: Type.TUnion<[Type.TLiteral<"active">, Type.TLiteral<"retired">, Type.TLiteral<"revoked">]>;
+            }>;
+            authorizationRegistry: Type.TObject<{
+                contextBucket: Type.TString;
+            }>;
+            policy: Type.TObject<{
+                allowedClockSkewSeconds: Type.TInteger;
+                maximumContextLifetimeSeconds: Type.TInteger;
+                maximumContextBytes: Type.TInteger;
+                maximumPermissions: Type.TInteger;
+                refreshLeadSeconds: Type.TInteger;
+                refreshJitterSeconds: Type.TInteger;
+            }>;
+        }>;
+    }>;
+}>;
+type ClientBootstrapReady = StaticDecode<typeof ClientBootstrapReadySchema> & {
+    readonly serverClockOffsetMs?: number;
+    readonly apiBindings: Readonly<Record<string, unknown>>;
+    readonly resourceBindings: ContractResourceBindings;
+};
+export declare function connectClientWithDeps<TContract extends ClientContract>(args: ClientConnectArgsFor<TContract>, deps: ClientConnectDeps): Promise<ConnectedTrellisClient<TContract>>;
+/** Connects user-facing participants to the Trellis caller runtime. */
+export declare class TrellisClient {
+    static connect<TContract extends ClientContract>(args: ClientConnectArgsFor<TContract>): AsyncResult<ConnectedTrellisClient<TContract>, TransportError | UnexpectedError | ClientAuthHandledError>;
+}
+export {};