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.
Constructors
Signature
declare const make: (
options: Omit<Runners["Service"], "sendLocal" | "notifyLocal">,
) => Effect.Effect<
Runners["Service"],
never,
MessageStorage.MessageStorage | Snowflake.Generator | ShardingConfig | Scope
>;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
>;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
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
Layer that provides the no-op Runners service, using the default snowflake generator.
Signature
declare const layerNoop: Layer.Layer<
Runners,
never,
ShardingConfig | MessageStorage.MessageStorage
>;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
Client interface generated from the runner RPC group.
Signature
interface RpcClient extends FromGroup<typeof Rpcs, RpcClientError> {}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
Service that creates an RPC client protocol for communicating with a runner at a given address.
Signature
declare class RpcClientProtocol extends Shape<"effect/cluster/Runners/RpcClientProtocol", (address: RunnerAddress) => Effect<{
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);
}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, PersistenceError>;
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);
}
Builds the
Runnersservice 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
Runnersservice around remoteping,send,notify, andonRunnerUnavailablecallbacks, with standard local persistence and reply recovery behavior.Details
makeuses the supplied remote callbacks for runner communication and derivessendLocalandnotifyLocal. Local sends can optionally simulate remote serialization, persisted notifications are saved throughMessageStorage, duplicate requests are resumed from stored replies when possible, and pending replies are polled according toShardingConfig.entityReplyPollInterval.Gotchas
notifyandnotifyLocalonly support RPCs annotated as persisted; calling either path with a non-persisted message dies instead of returning a typed error.See
makeRpcfor the RPC-backed implementation built on top of this constructormakeNoopfor a no-op implementation when remote runner communication is not needed