Interface MessageBus

public interface MessageBus
Async pub/sub message bus for inter-script communication over named channels.

On sender: the bus a running script receives is bound to that script's identity, and the runtime stamps it on every outbound message. The sender argument you pass is therefore advisory — what subscribers observe is the script's registered name, not the string supplied at the call site. Do not rely on being able to send under another name.

  • Method Details

    • subscribe

      void subscribe(String channel, Consumer<ScriptMessage> handler)
      Subscribes a handler to receive messages on the given channel.

      The bus holds a bounded number of channels, and each channel a bounded number of handlers. A subscription past either bound is refused with a warning in the host log and the handler never fires — reaching a bound is a bug in the subscriber, not a state to design around.

      Parameters:
      channel - the channel name to subscribe to
      handler - the callback invoked for each message on the channel

    • unsubscribe

      void unsubscribe(String channel, Consumer<ScriptMessage> handler)
      Removes a previously registered handler from the given channel.
      Parameters:
      channel - the channel name
      handler - the handler to remove

    • publish

      void publish(String channel, String sender, Object payload)
      Publishes a message to all subscribers of the given channel. Delivery is asynchronous; the caller never blocks.

      Delivery is best-effort: the bus bounds how many handler invocations it will have running at once, and drops deliveries beyond that rather than spawning threads without limit. A script publishing at a sane rate never meets the bound, but do not treat delivery as guaranteed.

      Parameters:
      channel - the channel to publish on
      sender - identifier of the sending script
      payload - the message payload

    • request

      CompletableFuture<ScriptMessage> request(String channel, String sender, Object payload, long timeoutMs)
      Sends a request and waits for a response on the given channel.

      timeoutMs is clamped to a range in which the timeout actually expires — a request always either completes or times out, so asking to wait forever is not an option. The returned future also fails immediately when too many requests are already outstanding.

      Parameters:
      channel - the channel to send the request on
      sender - identifier of the requesting script
      payload - the request payload
      timeoutMs - maximum time to wait for a response in milliseconds
      Returns:
      a future that completes with the response message

    • respond

      void respond(String requestId, String channel, String sender, Object payload)
      Sends a response to a previous request.
      Parameters:
      requestId - the correlation ID from the original request
      channel - the channel to respond on
      sender - identifier of the responding script
      payload - the response payload