Skip to content
Effect V4 Docs

Runners.ts

Runners.ts overview

Section titled “Runners.ts overview”

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.

Since v4.0.0

Exports Grouped by Category

Section titled “Exports Grouped by Category”

No-op

Section titled “No-op”

makeNoop

Section titled “makeNoop”

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<
  {
    readonly ping: (address: RunnerAddress) => Effect.Effect<void, RunnerUnavailable>
    readonly sendLocal: <R extends Rpc.Any>(options: {
      readonly message: Message.Outgoing<R>
      readonly send: <Rpc extends Rpc.Any>(
        message: Message.IncomingLocal<Rpc>
      ) => Effect.Effect<void, EntityNotAssignedToRunner | MailboxFull | AlreadyProcessingMessage>
      readonly simulateRemoteSerialization: boolean
    }) => Effect.Effect<void, EntityNotAssignedToRunner | MailboxFull | AlreadyProcessingMessage | PersistenceError>
    readonly send: <R extends Rpc.Any>(options: {
      readonly address: RunnerAddress
      readonly message: Message.Outgoing<R>
    }) => Effect.Effect<
      void,
      EntityNotAssignedToRunner | RunnerUnavailable | MailboxFull | AlreadyProcessingMessage | PersistenceError
    >
    readonly notify: <R extends Rpc.Any>(options: {
      readonly address: Option.Option<RunnerAddress>
      readonly message: Message.Outgoing<R>
      readonly discard: boolean
    }) => Effect.Effect<void, PersistenceError>
    readonly notifyLocal: <R extends Rpc.Any>(options: {
      readonly message: Message.Outgoing<R>
      readonly notify: (options: Message.IncomingLocal<any>) => Effect.Effect<void, EntityNotAssignedToRunner>
      readonly discard: boolean
      readonly storageOnly?: boolean | undefined
    }) => Effect.Effect<void, PersistenceError>
    readonly onRunnerUnavailable: (address: RunnerAddress) => Effect.Effect<void>
  },
  never,
  Scope | MessageStorage.MessageStorage | ShardingConfig | Snowflake.Generator
>

Source

Since v4.0.0

Rpcs

Section titled “Rpcs”

RpcClient (interface)

Section titled “RpcClient (interface)”

Client interface generated from the runner RPC group.

Signature

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

Source

Since v4.0.0

Rpcs (class)

Section titled “Rpcs (class)”

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

Signature

declare class Rpcs

Source

Since v4.0.0

makeRpcClient

Section titled “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, Scope | RpcClient_.Protocol>

Source

Since v4.0.0

client

Section titled “client”

RpcClientProtocol (class)

Section titled “RpcClientProtocol (class)”

Service that creates an RPC client protocol for communicating with a runner at a given address.

Signature

declare class RpcClientProtocol

Source

Since v4.0.0

constructors

Section titled “constructors”

make

Section titled “make”

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, persisted notifications are saved through MessageStorage, duplicate requests are resumed from stored replies when possible, and pending replies are polled according to ShardingConfig.entityReplyPollInterval.

Gotchas

notify and notifyLocal only support RPCs annotated as persisted; calling either path with a non-persisted message dies instead of returning a typed error.

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">
) => Effect.Effect<
  Runners["Service"],
  never,
  MessageStorage.MessageStorage | Snowflake.Generator | ShardingConfig | Scope
>

Source

Since v4.0.0

makeRpc

Section titled “makeRpc”

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<
  {
    readonly ping: (address: RunnerAddress) => Effect.Effect<void, RunnerUnavailable>
    readonly sendLocal: <R extends Rpc.Any>(options: {
      readonly message: Message.Outgoing<R>
      readonly send: <Rpc extends Rpc.Any>(
        message: Message.IncomingLocal<Rpc>
      ) => Effect.Effect<void, EntityNotAssignedToRunner | MailboxFull | AlreadyProcessingMessage>
      readonly simulateRemoteSerialization: boolean
    }) => Effect.Effect<void, EntityNotAssignedToRunner | MailboxFull | AlreadyProcessingMessage | PersistenceError>
    readonly send: <R extends Rpc.Any>(options: {
      readonly address: RunnerAddress
      readonly message: Message.Outgoing<R>
    }) => Effect.Effect<
      void,
      EntityNotAssignedToRunner | RunnerUnavailable | MailboxFull | AlreadyProcessingMessage | PersistenceError
    >
    readonly notify: <R extends Rpc.Any>(options: {
      readonly address: Option.Option<RunnerAddress>
      readonly message: Message.Outgoing<R>
      readonly discard: boolean
    }) => Effect.Effect<void, PersistenceError>
    readonly notifyLocal: <R extends Rpc.Any>(options: {
      readonly message: Message.Outgoing<R>
      readonly notify: (options: Message.IncomingLocal<any>) => Effect.Effect<void, EntityNotAssignedToRunner>
      readonly discard: boolean
      readonly storageOnly?: boolean | undefined
    }) => Effect.Effect<void, PersistenceError>
    readonly onRunnerUnavailable: (address: RunnerAddress) => Effect.Effect<void>
  },
  never,
  Scope | MessageStorage.MessageStorage | ShardingConfig | Snowflake.Generator | RpcClientProtocol
>

Source

Since v4.0.0

context

Section titled “context”

Runners (class)

Section titled “Runners (class)”

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

Signature

declare class Runners

Source

Since v4.0.0

layers

Section titled “layers”

layerNoop

Section titled “layerNoop”

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

Signature

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

Source

Since v4.0.0

layerRpc

Section titled “layerRpc”

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 | ShardingConfig | RpcClientProtocol>

Source

Since v4.0.0