Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

ClusterSchema unstable

The ClusterSchema module collects the annotations that add cluster behavior to RPC protocols and entity definitions. These annotations describe how requests are persisted, handled in transactions, interrupted, traced, and routed to shard groups without changing the request or response schema.

10 exports Since v4.0.0 Source

Predicates

isUninterruptibleForClient

unstable
Since v4.0.0

Returns whether the Uninterruptible annotation applies to client-side request handling for the provided context.

When to use

Use when you need client-side cluster request handling to decide whether to ignore an interrupt.

Details

Returns true when Uninterruptible is true or "client", and false for "server" or the default false.

See

Signature

declare function isUninterruptibleForClient(context: Context<never>): boolean

isUninterruptibleForServer

unstable
Since v4.0.0

Returns whether the Uninterruptible annotation applies to server-side request handling for the provided context.

Details

Returns true only when Uninterruptible is true or "server".

See

Signature

declare function isUninterruptibleForServer(context: Context<never>): boolean

Services

Abandon

unstable
Since v4.0.0

Annotation carried by an interruption when a persisted cluster request is abandoned by its current runner and must continue under another owner.

Signature

declare class Abandon extends Shape<"effect/cluster/ClusterSchema/Abandon", true, this> {
  constructor(_: never);
  static annotation: Context<StackTrace | Abandon>;
}

ClientTracingEnabled

unstable
Since v4.0.0

Annotation that controls whether client-side cluster request tracing is enabled.

Details

The default value is true.

Signature

declare const ClientTracingEnabled: Reference<boolean>

Dynamic

unstable
Since v4.0.0

Context reference for deriving request annotations from a cluster request.

When to use

Use to customize server-side request annotations based on the decoded request value.

Gotchas

This only applies to requests handled by the entity, not to the generated client.

Signature

declare const Dynamic: Reference<(annotations: Context<never>, request: Request<AnyWithProps>) => Context<never>>

InterruptOnTermination

unstable
Since v4.0.0

Annotation that interrupts a cluster request when entity termination starts, rather than waiting for the termination grace period to expire.

Details

The default value is false. Use for long-lived requests that cannot finish on their own. Persisted requests resume under the next owner without saving the interruption as a reply. Non-persisted requests receive an interrupt exit.

Server-side Uninterruptible takes precedence over this annotation.

Signature

declare const InterruptOnTermination: Reference<boolean>

Persisted

unstable
Since v4.0.0

Annotation that marks whether a cluster request should be persisted in mailbox storage.

Details

The default value is false.

Signature

declare const Persisted: Reference<boolean>

ShardGroup

unstable
Since v4.0.0

Annotation that selects the shard group for an entity id.

Details

By default, every entity id is assigned to the "default" shard group.

Signature

declare const ShardGroup: Reference<(entityId: string & Brand<"~effect/cluster/EntityId">) => string>

Uninterruptible

unstable
Since v4.0.0

Annotation that controls whether a cluster request is treated as uninterruptible.

Details

Use true for both client and server handling, "client" for client-side handling only, "server" for server-side handling only, or false to allow interruption.

Signature

declare const Uninterruptible: Reference<boolean | "server" | "client">

WithTransaction

unstable
Since v4.0.0

Annotation that marks whether request handling should be wrapped in the configured message storage transaction.

When to use

Use when you need server-side request handling or storage work wrapped in the storage transaction.

Details

The default value is false. When true, entity handling wraps server writes with the configured storage transaction.

Persisted requests deliver terminal replies and mark requests processed only after commit or clean rollback. Success replies are saved in the transaction; failures are saved after rollback. If commit reports failure, a stored success reply is recovered. Otherwise, commit or rollback failures retry the request without delivering a reply. Handlers must tolerate retries.

Gotchas

This annotation has transactional behavior only when the configured MessageStorage implements it.

Stream chunks are saved and delivered immediately, even if the transaction later rolls back. A handler returning a Deferred commits before its reply is saved. Non-persisted requests save no reply; successes are delivered when the handler exits, and failures after the transaction exits.

Signature

declare const WithTransaction: Reference<boolean>