Files
mesh-sdk/src/messaging/index.ts
T
jschoubben 5fa64be894 Revert the revert of G's mesh-sdk merge (#191): G's sdk stands again over reader release 3
Main reverted G's half merge (#189, reverted by 8afc3eb in #191) and then took the reader release's S1-S5, which
copied G's code. G's form holds where they differ (process_bus.go, seats.go, state.go and their tests); the
release's kept names stay so main's callers keep building: SeatViewPrefix beside SeatReadPrefix, and QueueInvoke's
empty strings on not-ok (with its test TestQueueInvoke). The tree differs from G's head f30dee54 only by those and
the release's two tests (objects cap option, seat states and stream kinds).

Builds: design 47 G (the milestone's sdk part, as at f30dee54)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-13 12:49:56 +01:00

71 lines
2.9 KiB
TypeScript

// The broker and event framework a module's code uses to talk to the mesh. The transport is the
// mesh's one broker (novox/hq ADR 0001); this is the typed surface over it. The concrete broker
// binding is provided by the runtime that hosts a module's code — the sdk defines the contract so
// module code, the tool runtime and provisioners all speak it the same way.
import type { Envelope, EventHeaders } from "../contracts/index.js";
export type { Envelope, EventHeaders };
/** How a publish is asked of the runtime. */
export interface PublishOptions {
/** Resolve once the bus acknowledged the message (the runtime's `mesh/publish` takes `ack: true`). */
readonly ack?: boolean;
}
/** How a subscription is asked of the runtime. */
export interface SubscribeOptions {
/** `new`: only messages published after the subscription (the runtime's `mesh/subscribe` takes `deliver: new`). */
readonly deliver?: "new";
}
/** A request/reply call and a publish/subscribe surface over the mesh broker. */
export interface Broker {
/** Ask one question and await one answer — the client side; the shape mesh-controller's command
* API is reached by. */
request<Req, Res>(key: string, body: Req): Promise<Res>;
/** Answer a question — the server side of request/reply. A tool runtime serves invocations this
* way. Returns an unregister. */
handle<Req, Res>(key: string, handler: (body: Req) => Promise<Res>): Promise<() => void>;
/**
* Emit an event onto the mesh. With `ack: true` a bundle's publish resolves only once the bus acknowledged it and
* rejects with the reason where it did not (design 47 G §559).
*/
publish<T>(env: Envelope<T>, options?: PublishOptions): Promise<void>;
/**
* React to events matching a routing-key pattern. Returns an unsubscribe. With `deliver: "new"` the handler is given
* only the messages published after the subscription is made (design 47 G §559).
*/
subscribe<T>(pattern: string, handler: (env: Envelope<T>) => Promise<void>, options?: SubscribeOptions): Promise<() => void>;
close(): Promise<void>;
}
/**
* How a module obtains its broker. The hosting runtime sets this once; module code calls broker()
* without knowing the concrete binding. Keeping the binding out of the sdk is deliberate — the sdk
* carries the contract, not a specific broker client build.
*/
let binding: (() => Broker) | undefined;
export function useBroker(factory: () => Broker): void {
binding = factory;
}
export function broker(): Broker {
if (!binding) {
throw new Error(
"no broker is bound — the tool runtime or provisioner host must call useBroker() before " +
"module code reaches the mesh",
);
}
return binding();
}
/** A convenience for the common case: consume one event stream until stopped. */
export async function consume<T>(
pattern: string,
handler: (env: Envelope<T>) => Promise<void>,
): Promise<() => void> {
return broker().subscribe<T>(pattern, handler);
}