Skip to content

BunClusterHttp

Bun HTTP and WebSocket layers for Effect Cluster runners.

layerHttpServer provides the Bun HTTP server used by cluster runners. The main layer builds a sharding layer for HTTP or WebSocket transport, choosing serialization, runner health checks, runner storage, message storage, and optional client-only mode from the supplied options.

3 exports Added in v4.0.0 Source

Layers

layer

Added in v4.0.0 Source

Creates Bun cluster layers for HTTP or WebSocket transport, configuring serialization, storage, runner health, and optional client-only mode.

When to use

Use to install the complete Bun HTTP or WebSocket cluster layer, including client-only cluster access when a process should connect without serving runner RPCs.

Details

serialization defaults to MessagePack, runnerHealth defaults to ping checks, SQL-backed storage is used by default, and shardingConfig is overlaid on environment-loaded sharding configuration. local storage uses no-op message storage plus in-memory runner storage, while byo leaves both message and runner storage for the caller to provide.

Gotchas

clientOnly does not start the HTTP server or receive shard assignments. Non-client-only mode listens with runnerListenAddress when present, falling back to runnerAddress. HTTP and WebSocket runner RPCs use the default HttpRunner route.

See

Signature

declare function layer<ClientOnly extends boolean = false, Storage extends "local" | "sql" | "byo" = never>(options: {
  readonly clientOnly?: ClientOnly;
  readonly runnerHealth?: "ping" | "k8s";
  readonly runnerHealthK8s?: {
    readonly labelSelector?: string;
    readonly namespace?: string;
  };
  readonly serialization?: "msgpack" | "ndjson";
  readonly serializationMaxBufferSize?: number | "unbounded";
  readonly shardingConfig?: Partial<{
    readonly assignedShardGroups: readonly Array<string>;
    readonly availableShardGroups: readonly Array<string>;
    readonly entityMailboxCapacity: number | "unbounded";
    readonly entityMaxIdleTime: Input;
    readonly entityMessagePollInterval: Input;
    readonly entityRegistrationTimeout: Input;
    readonly entityReplyPollInterval: Input;
    readonly entityTerminationTimeout: Input;
    readonly preemptiveShutdown: boolean;
    readonly refreshAssignmentsInterval: Input;
    readonly runnerAddress: Option<RunnerAddress>;
    readonly runnerHealthCheckInterval: Input;
    readonly runnerListenAddress: Option<RunnerAddress>;
    readonly runnerShardWeight: number;
    readonly sendRetryInterval: Input;
    readonly shardLockDisableAdvisory: boolean;
    readonly shardLockExpiration: Input;
    readonly shardLockRefreshInterval: Input;
    readonly shardsPerGroup: number;
    readonly simulateRemoteSerialization: boolean;
  }>;
  readonly storage?: Storage;
  readonly transport: "http" | "websocket";
}): ClientOnly extends true ? Layer<Sharding | Runners | "byo" extends Storage ? never : MessageStorage, ConfigError, "local" extends Storage ? never : "byo" extends Storage ? MessageStorage | RunnerStorage : SqlClient> : Layer<Sharding | Runners | MessageStorage, ServeError | ConfigError, "local" extends Storage ? never : "byo" extends Storage ? MessageStorage | RunnerStorage : SqlClient>

layerHttpServer

Added in v4.0.0 Source

Layer that provides a Bun HTTP server for cluster runners.

Signature

declare const layerHttpServer: Layer.Layer<
  HttpPlatform | Etag.Generator | BunServices | HttpServer,
  ServeError,
  ShardingConfig.ShardingConfig
>;

layerK8sHttpClient

Added in v4.0.0 Source

Layer that provides K8sHttpClient, using the Kubernetes service-account CA certificate when it is available.

Signature

declare const layerK8sHttpClient: Layer.Layer<K8sHttpClient.K8sHttpClient>;