GitHub

cluster_socket

API reference for cluster_socket.

Cluster runners over TCP (Effect's NodeClusterSocket).

layer() is a whole runner: a SocketServer at the configured runner_listen_address (or runner_address), other runners dialed over TCP, runner health by ping (or Kubernetes), messages and shard locks in SQL (storage="sql", the default, needing a SqlClient), in memory ("local") or brought by the caller ("byo"), and settings read from the environment and passed through sharding_config. client_only=True serves nothing and owns no shards.

Messages are SchemaBinary frames, as in Effect; serialization="ndjson" writes ndjson instead. serialization_max_buffer_size limits a frame of either.

Re-exports

Values

AttributeTypeDescription
layer_client_protocolLayer[RpcClientProtocol, Never, RpcSerialization]

Dial other runners over TCP (one second to connect).

layer_socket_serverLayer[SocketServer, SocketServerError, ShardingConfig]

A SocketServer at the runner's listen address.

Functions

layer

layer(*, client_only: Literal[False] = False, storage: Literal['sql'] = 'sql', runner_health: Health = 'ping', runner_health_k8s_namespace: str | None = None, runner_health_k8s_label_selector: str | None = None, serialization: SerializationKind = ..., serialization_max_buffer_size: MaxBufferSize = ..., sharding_config: ShardingConfigUpdate | None = None) -> Layer[_Out, SocketServerError | ConfigError, SqlClient]
layer(*, client_only: Literal[False] = False, storage: Literal['local'], runner_health: Health = 'ping', runner_health_k8s_namespace: str | None = None, runner_health_k8s_label_selector: str | None = None, serialization: SerializationKind = ..., serialization_max_buffer_size: MaxBufferSize = ..., sharding_config: ShardingConfigUpdate | None = None) -> Layer[_Out, SocketServerError | ConfigError]
layer(*, client_only: Literal[False] = False, storage: Literal['byo'], runner_health: Health = 'ping', runner_health_k8s_namespace: str | None = None, runner_health_k8s_label_selector: str | None = None, serialization: SerializationKind = ..., serialization_max_buffer_size: MaxBufferSize = ..., sharding_config: ShardingConfigUpdate | None = None) -> Layer[_Core, SocketServerError | ConfigError, MessageStorage | RunnerStorage]
layer(*, client_only: Literal[True], storage: Literal['sql'] = 'sql', serialization: SerializationKind = ..., serialization_max_buffer_size: MaxBufferSize = ..., sharding_config: ShardingConfigUpdate | None = None) -> Layer[_Out, ConfigError, SqlClient]
layer(*, client_only: Literal[True], storage: Literal['local'], serialization: SerializationKind = ..., serialization_max_buffer_size: MaxBufferSize = ..., sharding_config: ShardingConfigUpdate | None = None) -> Layer[_Out, ConfigError]
layer(*, client_only: Literal[True], storage: Literal['byo'], serialization: SerializationKind = ..., serialization_max_buffer_size: MaxBufferSize = ..., sharding_config: ShardingConfigUpdate | None = None) -> Layer[_Core, ConfigError, MessageStorage | RunnerStorage]

A cluster runner (or, with client_only, a sender) over TCP.

ParameterTypeDescription
client_only= False
storage= 'sql'
runner_health= 'ping'
runner_health_k8s_namespace= None
runner_health_k8s_label_selector= None
serialization= 'binary'
serialization_max_buffer_size= 16 * 1024 * 1024
sharding_config= None
@overload
def layer(
    *,
    client_only: Literal[False] = False,
    storage: Literal["sql"] = "sql",
    runner_health: Health = "ping",
    runner_health_k8s_namespace: str | None = None,
    runner_health_k8s_label_selector: str | None = None,
    serialization: SerializationKind = ...,
    serialization_max_buffer_size: MaxBufferSize = ...,
    sharding_config: ShardingConfigUpdate | None = None,
) -> Layer[_Out, SocketServerError | ConfigError, SqlClient]: ...
@overload
def layer(
    *,
    client_only: Literal[False] = False,
    storage: Literal["local"],
    runner_health: Health = "ping",
    runner_health_k8s_namespace: str | None = None,
    runner_health_k8s_label_selector: str | None = None,
    serialization: SerializationKind = ...,
    serialization_max_buffer_size: MaxBufferSize = ...,
    sharding_config: ShardingConfigUpdate | None = None,
) -> Layer[_Out, SocketServerError | ConfigError]: ...
@overload
def layer(
    *,
    client_only: Literal[False] = False,
    storage: Literal["byo"],
    runner_health: Health = "ping",
    runner_health_k8s_namespace: str | None = None,
    runner_health_k8s_label_selector: str | None = None,
    serialization: SerializationKind = ...,
    serialization_max_buffer_size: MaxBufferSize = ...,
    sharding_config: ShardingConfigUpdate | None = None,
) -> Layer[_Core, SocketServerError | ConfigError, MessageStorage | RunnerStorage]: ...
@overload
def layer(
    *,
    client_only: Literal[True],
    storage: Literal["sql"] = "sql",
    serialization: SerializationKind = ...,
    serialization_max_buffer_size: MaxBufferSize = ...,
    sharding_config: ShardingConfigUpdate | None = None,
) -> Layer[_Out, ConfigError, SqlClient]: ...
@overload
def layer(
    *,
    client_only: Literal[True],
    storage: Literal["local"],
    serialization: SerializationKind = ...,
    serialization_max_buffer_size: MaxBufferSize = ...,
    sharding_config: ShardingConfigUpdate | None = None,
) -> Layer[_Out, ConfigError]: ...
@overload
def layer(
    *,
    client_only: Literal[True],
    storage: Literal["byo"],
    serialization: SerializationKind = ...,
    serialization_max_buffer_size: MaxBufferSize = ...,
    sharding_config: ShardingConfigUpdate | None = None,
) -> Layer[_Core, ConfigError, MessageStorage | RunnerStorage]: ...
def layer(
    *,
    client_only: bool = False,
    storage: Storage = "sql",
    runner_health: Health = "ping",
    runner_health_k8s_namespace: str | None = None,
    runner_health_k8s_label_selector: str | None = None,
    serialization: SerializationKind = "binary",
    serialization_max_buffer_size: MaxBufferSize = 16 * 1024 * 1024,
    sharding_config: ShardingConfigUpdate | None = None,
) -> Layer[Any, Any, Any]:
    """A cluster runner (or, with ``client_only``, a sender) over TCP."""
    transport: Layer[Any, Any, Any] = (
        socket_runner.layer_client_only.pipe(layer_.provide(layer_client_protocol))
        if client_only
        else socket_runner.layer.pipe(
            layer_.provide(layer_.merge(layer_socket_server, layer_client_protocol))
        )
    )
    health = (
        None
        if client_only
        else runner_health_layer(
            client_protocol=layer_client_protocol,
            health=runner_health,
            namespace=runner_health_k8s_namespace,
            label_selector=runner_health_k8s_label_selector,
        )
    )
    return assemble(
        transport,
        health=health,
        storage=storage,
        sharding_config=sharding_config,
        serialization_kind=serialization,
        serialization_max_buffer_size=serialization_max_buffer_size,
    )