Main reverted G's half merge (#189, reverted by8afc3ebin #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 headf30dee54only 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 atf30dee54) Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
71 lines
2.9 KiB
TypeScript
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);
|
|
}
|