.opencode/node_modules/effect/dist/unstable/cluster/Runners.d.ts

/**
 * 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 4.0.0
 */
import * as Context from "../../Context.ts";
import * as Effect from "../../Effect.ts";
import * as Layer from "../../Layer.ts";
import * as Option from "../../Option.ts";
import * as Schema from "../../Schema.ts";
import type { Scope } from "../../Scope.ts";
import * as Rpc from "../rpc/Rpc.ts";
import * as RpcClient_ from "../rpc/RpcClient.ts";
import type { RpcClientError } from "../rpc/RpcClientError.ts";
import * as RpcGroup from "../rpc/RpcGroup.ts";
import * as RpcSchema from "../rpc/RpcSchema.ts";
import type { PersistenceError } from "./ClusterError.ts";
import { AlreadyProcessingMessage, EntityNotAssignedToRunner, MailboxFull, RunnerUnavailable } from "./ClusterError.ts";
import * as Envelope from "./Envelope.ts";
import * as Message from "./Message.ts";
import * as MessageStorage from "./MessageStorage.ts";
import * as Reply from "./Reply.ts";
import type { RunnerAddress } from "./RunnerAddress.ts";
import { ShardingConfig } from "./ShardingConfig.ts";
import * as Snowflake from "./Snowflake.ts";
declare const Runners_base: Context.ServiceClass<Runners, "effect/cluster/Runners", {
    /**
     * Checks whether a Runner is responsive.
     */
    readonly ping: (address: RunnerAddress) => Effect.Effect<void, RunnerUnavailable>;
    /**
     * Send a message locally.
     *
     * This ensures that the message hits storage before being sent to the local
     * entity.
     */
    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>;
    /**
     * Send a message to a Runner.
     */
    readonly send: <R extends Rpc.Any>(options: {
        readonly address: RunnerAddress;
        readonly message: Message.Outgoing<R>;
    }) => Effect.Effect<void, EntityNotAssignedToRunner | RunnerUnavailable | MailboxFull | AlreadyProcessingMessage | PersistenceError>;
    /**
     * Notify a Runner that a message is available, then read replies from storage.
     */
    readonly notify: <R extends Rpc.Any>(options: {
        readonly address: Option.Option<RunnerAddress>;
        readonly message: Message.Outgoing<R>;
        readonly discard: boolean;
    }) => Effect.Effect<void, PersistenceError>;
    /**
     * Notify the current Runner that a message is available, then read replies from
     * storage.
     *
     * This ensures that the message hits storage before being sent to the local
     * entity.
     */
    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>;
    /**
     * Mark a Runner as unavailable.
     */
    readonly onRunnerUnavailable: (address: RunnerAddress) => Effect.Effect<void>;
}>;
/**
 * Service for communicating with cluster runners, including pinging runners,
 * sending and notifying messages, coordinating persisted replies, and marking
 * runners unavailable.
 *
 * @category context
 * @since 4.0.0
 */
export declare class Runners extends Runners_base {
}
/**
 * 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 {@link makeRpc} for the RPC-backed implementation built on top of this constructor
 * @see {@link makeNoop} for a no-op implementation when remote runner communication is not needed
 *
 * @category constructors
 * @since 4.0.0
 */
export 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.
 *
 * @category No-op
 * @since 4.0.0
 */
export declare const makeNoop: Effect.Effect<Runners["Service"], never, MessageStorage.MessageStorage | Snowflake.Generator | ShardingConfig | Scope>;
/**
 * Layer that provides the no-op `Runners` service, using the default snowflake
 * generator.
 *
 * @category layers
 * @since 4.0.0
 */
export declare const layerNoop: Layer.Layer<Runners, never, ShardingConfig | MessageStorage.MessageStorage>;
declare const Rpcs_base: RpcGroup.RpcGroup<Rpc.Rpc<"Ping", Schema.Void, Schema.Void, Schema.Never, never, never> | Rpc.Rpc<"Notify", Schema.Struct<{
    envelope: Schema.Union<readonly [typeof Envelope.PartialRequest, typeof Envelope.AckChunk, typeof Envelope.Interrupt]>;
}>, Schema.Void, Schema.Union<readonly [typeof EntityNotAssignedToRunner, typeof AlreadyProcessingMessage]>, never, never> | Rpc.Rpc<"Effect", Schema.Struct<{
    request: typeof Envelope.PartialRequest;
    persisted: Schema.Boolean;
}>, Schema.Codec<Reply.Encoded, Reply.Encoded, never, never>, Schema.Union<[typeof EntityNotAssignedToRunner, typeof MailboxFull, typeof AlreadyProcessingMessage]>, never, never> | Rpc.Rpc<"Stream", Schema.Struct<{
    request: typeof Envelope.PartialRequest;
    persisted: Schema.Boolean;
}>, RpcSchema.Stream<Schema.Codec<Reply.Encoded, Reply.Encoded, never, never>, Schema.Union<[typeof EntityNotAssignedToRunner, typeof MailboxFull, typeof AlreadyProcessingMessage]>>, Schema.Never, never, never> | Rpc.Rpc<"Envelope", Schema.Struct<{
    envelope: Schema.Union<readonly [typeof Envelope.AckChunk, typeof Envelope.Interrupt]>;
    persisted: Schema.Boolean;
}>, Schema.Void, Schema.Union<[typeof EntityNotAssignedToRunner, typeof MailboxFull, typeof AlreadyProcessingMessage]>, never, never>>;
/**
 * RPC group used for runner-to-runner communication, including ping, notify,
 * effect, stream, and envelope messages.
 *
 * @category Rpcs
 * @since 4.0.0
 */
export declare class Rpcs extends Rpcs_base {
}
/**
 * Client interface generated from the runner RPC group.
 *
 * @category Rpcs
 * @since 4.0.0
 */
export interface RpcClient extends RpcClient_.FromGroup<typeof Rpcs, RpcClientError> {
}
/**
 * Builds a runner RPC client from the current `RpcClient.Protocol`, using the
 * `Runners` span prefix with tracing disabled.
 *
 * @category Rpcs
 * @since 4.0.0
 */
export declare const makeRpcClient: Effect.Effect<RpcClient, never, RpcClient_.Protocol | 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.
 *
 * @category constructors
 * @since 4.0.0
 */
export declare const makeRpc: Effect.Effect<Runners["Service"], never, Scope | RpcClientProtocol | MessageStorage.MessageStorage | Snowflake.Generator | ShardingConfig>;
/**
 * Layer that provides an RPC-backed `Runners` service using `RpcClientProtocol`,
 * message storage, sharding configuration, and the default snowflake generator.
 *
 * @category layers
 * @since 4.0.0
 */
export declare const layerRpc: Layer.Layer<Runners, never, MessageStorage.MessageStorage | RpcClientProtocol | ShardingConfig>;
declare const RpcClientProtocol_base: Context.ServiceClass<RpcClientProtocol, "effect/cluster/Runners/RpcClientProtocol", (address: RunnerAddress) => Effect.Effect<RpcClient_.Protocol["Service"], never, Scope>>;
/**
 * Service that creates an RPC client protocol for communicating with a runner at a
 * given address.
 *
 * @category client
 * @since 4.0.0
 */
export declare class RpcClientProtocol extends RpcClientProtocol_base {
}
export {};
//# sourceMappingURL=Runners.d.ts.map