99 lines
4.2 KiB
Markdown
99 lines
4.2 KiB
Markdown
# Actions
|
|
|
|
> Source: `src/content/docs/actors/actions.mdx`
|
|
> Canonical URL: https://rivet.dev/docs/actors/actions
|
|
> Description: Actions are how your backend, frontend, or other actors can communicate with actors.
|
|
|
|
---
|
|
Actions are very lightweight. They can be called thousands of times per second safely. Actions are executed via HTTP requests or via WebSockets if [using `.connect()`](/docs/actors/connections).
|
|
|
|
For advanced use cases that require direct access to HTTP requests or WebSocket connections, see [raw HTTP and WebSocket handling](/docs/actors/fetch-and-websocket-handler).
|
|
|
|
By default, actions run in parallel. If you need advanced control over concurrency, use [queues](/docs/actors/queues).
|
|
|
|
## Writing Actions
|
|
|
|
Actions are defined in the `actions` object when creating an actor:
|
|
|
|
Each action receives a context object (commonly named `c`) as its first parameter, which provides access to state, connections, and other utilities. Additional parameters follow after that.
|
|
|
|
## Calling Actions
|
|
|
|
Actions can be called in different ways depending on your use case:
|
|
|
|
### Frontend (createClient)
|
|
|
|
Learn more about [communicating with actors from the frontend](/docs/actors/communicating-between-actors).
|
|
|
|
### Backend (registry.handler)
|
|
|
|
Learn more about [communicating with actors from the backend](/docs/actors/communicating-between-actors).
|
|
|
|
### Actor-to-Actor (c.client())
|
|
|
|
Learn more about [communicating between actors](/docs/actors/communicating-between-actors).
|
|
|
|
Calling actions from the client are async and require an `await`, even if the action itself is not async.
|
|
|
|
### Type Safety
|
|
|
|
The actor client includes type safety out of the box. When you use `createClient<typeof registry>()`, TypeScript automatically infers action parameter and return types:
|
|
|
|
## Error Handling
|
|
|
|
Actors provide robust error handling out of the box for actions.
|
|
|
|
### User Errors
|
|
|
|
`UserError` can be used to return rich error data to the client. You can provide:
|
|
|
|
- A human-readable message
|
|
- A machine-readable code that's useful for matching errors in a try-catch (optional)
|
|
- A metadata object for providing richer error context (optional)
|
|
|
|
For example:
|
|
|
|
### Internal Errors
|
|
|
|
All other errors will return an error with the code `internal_error` to the client. This helps keep your application secure, as errors can sometimes expose sensitive information.
|
|
|
|
## Schema Validation
|
|
|
|
If passing data to an actor from the frontend, use a library like [Zod](https://zod.dev/) to validate input data.
|
|
|
|
For example, to validate action parameters:
|
|
|
|
## Streaming Data
|
|
|
|
Actions have a single return value. To stream realtime data in response to an action, use [events](/docs/actors/events).
|
|
|
|
## Canceling Long-Running Actions
|
|
|
|
For operations that should be cancelable on-demand, create your own `AbortController`. Chain it with `c.abortSignal` so actor shutdown also cancels the operation.
|
|
|
|
See [Actor Shutdown Abort Signal](/docs/actors/lifecycle#actor-shutdown-abort-signal) for automatically canceling operations when the actor stops.
|
|
|
|
## Using `ActionContext` Externally
|
|
|
|
When writing complex logic for actions, you may want to extract parts of your implementation into separate helper functions. When doing this, you'll need a way to properly type the context parameter.
|
|
|
|
Rivet provides the `ActionContextOf` utility type for exactly this purpose:
|
|
|
|
See [types](/docs/actors/types) for more details on using `ActionContextOf` and other utility types.
|
|
|
|
## Debugging
|
|
|
|
- `GET /inspector/rpcs` lists all available actions on an actor.
|
|
- `POST /inspector/action/:name` executes an action with JSON args and returns output.
|
|
- In non-dev mode, inspector endpoints require authorization.
|
|
|
|
## API Reference
|
|
|
|
- [`Actions`](/typedoc/interfaces/rivetkit.mod.Actions.html) - Interface for defining actions
|
|
- [`ActionContext`](/typedoc/interfaces/rivetkit.mod.ActionContext.html) - Context available in action handlers
|
|
- [`ActorDefinition`](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html) - Interface for defining actors with actions
|
|
- [`ActorHandle`](/typedoc/types/rivetkit.client_mod.ActorHandle.html) - Handle for calling actions from client
|
|
- [`ActorActionFunction`](/typedoc/types/rivetkit.client_mod.ActorActionFunction.html) - Type for action functions
|
|
|
|
_Source doc path: /docs/actors/actions_
|