interface IMessageBroker
Since 0.1.0

Message broker for cross-service integration events.

Examples

Example 1

const broker = ctx.services.get<IMessageBroker>(CAPABILITIES.MESSAGING);
await broker.publish('user.created', { userId: user.id });

Methods

connect(): Promise<void>

Opens the broker connection.

disconnect(): Promise<void>

Closes the broker connection.

publish<T>(
topic: string,
message: T
): Promise<void>

Publishes a message to a topic.

subscribe<T>(
topic: string,
handler: MessageHandler<T>,
): Promise<ISubscription>

Subscribes to a topic.

request<TReq, TRes>(
topic: string,
message: TReq,
options?: RequestOptions
): Promise<TRes>

Sends a request to a topic and awaits a single correlated reply, providing brokered request-reply (RPC) over the message broker.

A responder registered with respond on the same topic returns the reply. The call rejects with a RequestTimeoutError when no reply arrives within options.timeoutMs, and with a RemoteHandlerError when the responder throws.

Request traffic rides a channel derived from topic, disjoint from plain publish/subscribe on that same topic — a pub/sub consumer never observes an RPC request, and vice versa.

respond<TReq, TRes>(
topic: string,
handler: RequestHandler<TReq, TRes>,
): Promise<ISubscription>

Registers a responder for a request topic. The handler's resolved value is sent back to the requesting caller, correlated to the originating request.

Pass options.queue to load-balance requests across competing responders.

Since 0.1.0
optional
isHealthy(): Promise<boolean>

Reports whether the broker's backend is reachable right now, for the plugin's health indicator.

Optional: a broker with no meaningful liveness check omits it, and the indicator then reports only the lifecycle state (isReady).

This answers a fact (reachability), not a policy: the indicator that consumes it owns the up/down mapping.

Usage

import { type IMessageBroker } from "common/src/index.ts";