Skip to content
Effect Days 2026 Get your ticket

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 SchemaBinary, 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?: "binary" | "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>