scope

PREVIEW: Returns a KScope 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.

Example usage:

@Handler
suspend fun myHandler(): String {
    // Route a call into a named scope
    val greeter = scope("tenant-123").service<Greeter>()
    val response = greeter.greet("Alice")
    return "Got: $response"
}

Parameters

See also

PREVIEW: The scope key with which this invocation was submitted, if any.