scope

PREVIEW: Returns a ScopedClient that routes all outgoing calls within the given scope.

NOTE: This API is in preview and is not enabled by default. To use it in restate-server 1.7, enable the flow control and protocol v7 experimental features, via RESTATE_EXPERIMENTAL_ENABLE_PROTOCOL_V7=true and RESTATE_EXPERIMENTAL_ENABLE_VQUEUES=true. These can be enabled only on new clusters, for more info check out https://docs.restate.dev/services/flow-control#enabling-flow-control. If these experimental features aren't enabled, the call fails with a retryable error and keeps retrying until they are.

A scope is a sub-grouping of resources (invocations, virtual object instances, workflow instances, concurrency limits) within the Restate cluster. It becomes part of the target identity tuple:

• scope, service, handler, idempotencyKey?
• scope, virtualObject, objectKey, handler, idempotencyKey?
• scope, workflow, workflowKey, handler

Under the hood, the scope contributes to the partition key, so all resources in a scope get co-located by the restate-server.

Omitting the scope (i.e. using the regular service / workflow methods) is equivalent to calling with no scope, which is the existing behavior.

The scope key must consist only of [a-zA-Z0-9_.-] characters, with 1 <= length <= 36 chars.

Client client = Client.connect("http://localhost:8080");

// Route a call into a named scope
client.scope("tenant-123").service(MyService.class).process(payload);

// Idempotency keys are scoped — "req-1" in "tenant-123" is distinct from "req-1" in "tenant-456"
client.scope("tenant-123").serviceHandle(MyService.class)
    .call(MyService::process, payload, InvocationOptions.idempotencyKey("req-1").build());

// Combine with a limit key to enforce per-scope concurrency limits
client.scope("tenant-123").workflowHandle(MyWorkflow.class, "wf-key")
    .call(MyWorkflow::run, input, InvocationOptions.limitKey("api-key/user42").build());

Parameters

See also