ContextQMD
Back to Rivet

Actor Keys

website/src/content/docs/actors/keys.mdx

2.3.32.5 KB
Original Source

Key Format

Actor keys can be either a string or an array of strings:

<CodeSnippet file="examples/docs/actors-keys/key-format.ts" />

Compound Keys & User Data

Array keys are useful when you need compound keys with user-provided data. Using arrays makes adding user data safe by preventing key injection attacks:

<CodeSnippet file="examples/docs/actors-keys/compound-keys.ts" />

This allows you to create hierarchical addressing schemes and organize actors by multiple dimensions.

<Warning> Don't build keys using string interpolation like `"foo:${userId}:bar"` when `userId` contains user data. If a user provides a value containing the delimiter (`:` in this example), it can break your key structure and cause key injection attacks. </Warning>

Omitting Keys

You can create actors without specifying a key in situations where there is a singleton actor (i.e. only one actor of a given type). For example:

<CodeSnippet file="examples/docs/actors-keys/omitting-keys.ts" />

This pattern should be avoided, since a singleton actor usually means you have a single actor serving all traffic & your application will not scale. See scaling documentation for more information.

Key Uniqueness

Keys are unique within each actor name. Different actor types can use the same key:

<CodeSnippet file="examples/docs/actors-keys/key-uniqueness.ts" />

Accessing Keys in Metadata

Access the actor's key within the actor using the metadata API:

<CodeGroup> <CodeSnippet file="examples/docs/actors-keys/metadata-index.ts" title="index.ts" /> <CodeSnippet file="examples/docs/actors-keys/metadata-client.ts" title="client.ts" /> </CodeGroup>

Configuration Examples

Simple Configuration with Keys

Use keys to provide basic actor configuration:

<CodeGroup> <CodeSnippet file="examples/docs/actors-keys/config-index.ts" title="index.ts" /> <CodeSnippet file="examples/docs/actors-keys/config-client.ts" title="client.ts" /> </CodeGroup>

Complex Configuration with Input

For more complex configuration, use input parameters:

<CodeSnippet file="examples/docs/actors-keys/complex-config.ts" title="client.ts" />

API Reference