Runners

Handles communication between Effect Cluster runners.

Runners sits between sharding decisions and runner execution. It can ping a runner, send requests or control envelopes, notify a runner that persisted work is available, and record that a runner address is unavailable. This module defines the runner communication service, its RPC protocol, no-op and RPC-backed implementations, local persistence support, reply recovery, and the protocol service used by transport-specific runner layers.

10 exports Added in v4.0.0 Source

Constructors

make

Added in v4.0.0 Source

Builds the Runners service from remote runner callbacks and adds local message persistence, duplicate request handling, optional local serialization simulation, and polling for persisted replies.

When to use

Use when you need a custom Runners service around remote ping, send, notify, and onRunnerUnavailable callbacks, with standard local persistence and reply recovery behavior.

Details

make uses the supplied remote callbacks for runner communication and derives sendLocal and notifyLocal. Local sends can optionally simulate remote serialization with the supplied transport codec, persisted notifications are saved through MessageStorage, duplicate requests are resumed from stored replies when possible, and pending replies are polled according to ShardingConfig.entityReplyPollInterval.

See

makeRpc for the RPC-backed implementation built on top of this constructor
makeNoop for a no-op implementation when remote runner communication is not needed

Signature

declare const make: (options: Omit<Runners["Service"], "sendLocal" | "notifyLocal"> & {
  readonly codecFor: RpcSerialization.CodecFor;
}) => Effect.Effect<Runners["Service"], never, MessageStorage.MessageStorage | Snowflake.Generator | ShardingConfig | Scope>

makeNoop

Added in v4.0.0 Source

Creates a no-op Runners service that rejects sends with EntityNotAssignedToRunner and ignores notifications, pings, and unavailable runner reports.

Signature

declare const makeNoop: Effect.Effect<Runners["Service"], never, MessageStorage.MessageStorage | Snowflake.Generator | ShardingConfig | Scope>

makeRpc

Added in v4.0.0 Source

Builds a Runners service backed by RPC clients, caching a client per runner address and dispatching ping, notify, effect, stream, and envelope messages over the runner protocol.

Signature

declare const makeRpc: Effect.Effect<Runners["Service"], never, Scope | RpcClientProtocol | MessageStorage.MessageStorage | Snowflake.Generator | ShardingConfig>

makeRpcClient

Added in v4.0.0 Source

Builds a runner RPC client from the current RpcClient.Protocol, using the Runners span prefix with tracing disabled.

Signature

declare const makeRpcClient: Effect.Effect<RpcClient, never, RpcClient_.Protocol | Scope>

Layers

layerNoop

Added in v4.0.0 Source

Layer that provides the no-op Runners service, using the default snowflake generator.

Signature

declare const layerNoop: Layer.Layer<Runners, never, ShardingConfig | MessageStorage.MessageStorage>

layerRpc

Added in v4.0.0 Source

Layer that provides an RPC-backed Runners service using RpcClientProtocol, message storage, sharding configuration, and the default snowflake generator.

Signature

declare const layerRpc: Layer.Layer<Runners, never, MessageStorage.MessageStorage | RpcClientProtocol | ShardingConfig>

Models

RpcClient interface

Added in v4.0.0 Source

Client interface generated from the runner RPC group.

Signature

interface RpcClient extends FromGroup<typeof Rpcs, RpcClientError> {}

Rpcs

Added in v4.0.0 Source

RPC group used for runner-to-runner communication, including ping, notify, effect, stream, and envelope messages.

Signature

declare class Rpcs extends {} {
  constructor(_: never);
}

Services

RpcClientProtocol

Added in v4.0.0 Source

Service that creates RPC client protocols for runner addresses and exposes the codec shared by those protocols.

Signature

declare class RpcClientProtocol extends Shape<"effect/cluster/Runners/RpcClientProtocol", {
  readonly codecFor: CodecFor;
  readonly make: (address: RunnerAddress) => Effect<{
    readonly codecFor: CodecFor;
    readonly run: (clientId: number, f: (data: FromServerEncoded) => Effect<void>) => Effect<never>;
    readonly send: (clientId: number, request: FromClientEncoded, transferables?: readonly Array<Transferable>) => Effect<void, RpcClientError>;
    readonly supportsAck: boolean;
    readonly supportsTransferables: boolean;
  }, never, Scope>;
}, this> {
  constructor(_: never);
}

Runners

Added in v4.0.0 Source

Service for communicating with cluster runners, including pinging runners, sending and notifying messages, coordinating persisted replies, and marking runners unavailable.

Signature

declare class Runners extends Shape<"effect/cluster/Runners", {
  readonly notify: <R extends Any>(options: {
    readonly address: Option<RunnerAddress>;
    readonly discard: boolean;
    readonly message: Outgoing<R>;
  }) => Effect<void, EntityNotAssignedToRunner | PersistenceError | RunnerUnavailable | MailboxFull | AlreadyProcessingMessage>;
  readonly notifyLocal: <R extends Any>(options: {
    readonly discard: boolean;
    readonly message: Outgoing<R>;
    readonly notify: (options: IncomingLocal<any>) => Effect<void, EntityNotAssignedToRunner>;
    readonly storageOnly?: boolean;
  }) => Effect<void, PersistenceError>;
  readonly onRunnerUnavailable: (address: RunnerAddress) => Effect<void>;
  readonly ping: (address: RunnerAddress) => Effect<void, RunnerUnavailable>;
  readonly send: <R extends Any>(options: {
    readonly address: RunnerAddress;
    readonly message: Outgoing<R>;
  }) => Effect<void, EntityNotAssignedToRunner | PersistenceError | RunnerUnavailable | MailboxFull | AlreadyProcessingMessage>;
  readonly sendLocal: <R extends Any>(options: {
    readonly message: Outgoing<R>;
    readonly send: <Rpc extends Any>(message: IncomingLocal<Rpc>) => Effect<void, EntityNotAssignedToRunner | MailboxFull | AlreadyProcessingMessage>;
    readonly simulateRemoteSerialization: boolean;
  }) => Effect<void, EntityNotAssignedToRunner | PersistenceError | MailboxFull | AlreadyProcessingMessage>;
}, this> {
  constructor(_: never);
}