skills and photots

2026-07-22 00:21:04 +05:30
parent 677a355397
commit 070c6c0a91
337 changed files with 46087 additions and 0 deletions
--- a/.agents/skills/multiplayer-game/reference/actors/debugging.md
+++ b/.agents/skills/multiplayer-game/reference/actors/debugging.md
@@ -0,0 +1,644 @@
+# Debugging
+
+> Source: `src/content/docs/actors/debugging.mdx`
+> Canonical URL: https://rivet.dev/docs/actors/debugging
+> Description: Inspect and debug running Rivet Actors, runners, and provider configs using management, runner, and actor inspector HTTP APIs.
+
+---
+## Connecting to Rivet
+
+All debugging endpoints in this guide are available both locally and in production. In local development, the base URL is `http://localhost:6420` with no authentication. In production (Rivet Cloud or self-hosted), you connect to your Rivet Engine endpoint with a token.
+
+### Setup
+
+All examples in this guide use these shell variables. Extract them from your `RIVET_ENDPOINT` (`https://<namespace>:<token>@<host>`):
+
+```bash
+# From RIVET_ENDPOINT=https://my-namespace:sk_abc123@api.rivet.dev
+export RIVET_API="https://api.rivet.dev"
+export RIVET_NAMESPACE="my-namespace"
+export RIVET_TOKEN="sk_abc123"
+
+# For local development:
+# export RIVET_API="http://localhost:6420"
+```
+
+Rivet Cloud issues two token types: `sk_` (secret key, server-side only) and `pk_` (public key, client-safe). For debugging, always use `sk_`. See [Endpoints](/docs/general/endpoints) for more details.
+
+## Management API
+
+The management API runs on the manager base path (default root path) and is used to list, create, and look up actors.
+
+### Authentication
+
+| Environment | Authentication |
+|---|---|
+| **Local development** | No authentication required. All endpoints are accessible without tokens. |
+| **Self-hosted engine** | Set `RIVET_TOKEN` to enable authenticated access to restricted endpoints like KV. |
+| **Rivet Cloud** | Authentication is enforced by your deployment entrypoint. For manager KV access, use the bearer token header below when enabled. |
+
+Restricted endpoints (like KV reads) require the `Authorization: Bearer` header when `RIVET_TOKEN` is configured:
+
+```bash
+curl "$RIVET_API/actors/{actor_id}/kv/keys/{base64_key}" \
+  -H "Authorization: Bearer $RIVET_TOKEN"
+```
+
+### List Actors
+
+```bash
+# List all actors with a given name
+curl "$RIVET_API/actors?name=my-actor&namespace=$RIVET_NAMESPACE" \
+  -H "Authorization: Bearer $RIVET_TOKEN"
+
+# Look up one actor by key (name is required when key is provided)
+curl "$RIVET_API/actors?name=my-actor&key=%5B%22my-key%22%5D&namespace=$RIVET_NAMESPACE" \
+  -H "Authorization: Bearer $RIVET_TOKEN"
+
+# List actors by IDs (comma-separated)
+curl "$RIVET_API/actors?actor_ids=id1,id2&namespace=$RIVET_NAMESPACE" \
+  -H "Authorization: Bearer $RIVET_TOKEN"
+```
+
+Rules:
+
+- `key` requires `name`.
+- `actor_ids` cannot be combined with `name` or `key`.
+
+Returns:
+
+```json
+{
+  "actors": [
+    {
+      "actor_id": "abc123",
+      "name": "my-actor",
+      "key": "[\"default\"]",
+      "namespace_id": "default",
+      "create_ts": 1706000000000
+    }
+  ]
+}
+```
+
+### Create Actor
+
+`POST /actors` creates a new actor.
+
+```bash
+curl -X POST "$RIVET_API/actors?namespace=$RIVET_NAMESPACE" \
+  -H "Authorization: Bearer $RIVET_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "my-actor",
+    "runner_name_selector": "default",
+    "crash_policy": "restart"
+  }'
+```
+
+### Create or Get Actor
+
+`PUT /actors` creates an actor if it does not exist, otherwise returns the existing one.
+
+```bash
+curl -X PUT "$RIVET_API/actors?namespace=$RIVET_NAMESPACE" \
+  -H "Authorization: Bearer $RIVET_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "my-actor",
+    "key": "[\"default\"]",
+    "runner_name_selector": "default",
+    "crash_policy": "restart"
+  }'
+```
+
+Returns the actor object with its `actor_id`.
+
+### List Actor Names
+
+```bash
+curl "$RIVET_API/actors/names?namespace=$RIVET_NAMESPACE" \
+  -H "Authorization: Bearer $RIVET_TOKEN"
+```
+
+Returns all registered actor names and their metadata.
+
+### Read Actor KV
+
+Requires authentication (see above).
+
+```bash
+curl "$RIVET_API/actors/{actor_id}/kv/keys/{base64_key}" \
+  -H "Authorization: Bearer $RIVET_TOKEN"
+```
+
+Returns the value stored at the given key in the actor KV compatibility snapshot. After an actor has migrated to SQLite-backed runtime storage, this endpoint is stale for user KV and internal runtime records; it continues to expose the frozen pre-migration KV data. The inspector token key is the exception and remains mirrored for dashboard compatibility.
+
+See the [OpenAPI spec](https://github.com/rivet-dev/rivet/tree/main/rivetkit-openapi) for the full schema of all management endpoints.
+
+## Runner API
+
+Use the runner endpoints to debug scheduler capacity and provider configuration (for example serverless URL, headers, and limits) through the Rivet API.
+
+### List Runner Names
+
+```bash
+curl "$RIVET_API/runners/names?namespace=$RIVET_NAMESPACE" \
+  -H "Authorization: Bearer $RIVET_TOKEN"
+```
+
+Returns the runner pools available in the namespace:
+
+```json
+{
+  "names": ["default", "gpu-workers"],
+  "pagination": { "cursor": null }
+}
+```
+
+### List Runners in a Pool
+
+```bash
+curl "$RIVET_API/runners?namespace=$RIVET_NAMESPACE&name=default&include_stopped=true&limit=100" \
+  -H "Authorization: Bearer $RIVET_TOKEN"
+```
+
+Useful fields when debugging:
+
+- `remaining_slots` / `total_slots` for capacity.
+- `drain_ts` and `stop_ts` for shutdown behavior.
+- `last_ping_ts` and `last_connected_ts` for connectivity.
+
+### Inspect Provider Config (Runner Config)
+
+```bash
+curl "$RIVET_API/runner-configs?namespace=$RIVET_NAMESPACE&runner_name=default" \
+  -H "Authorization: Bearer $RIVET_TOKEN"
+```
+
+Returns the configured provider settings per datacenter and the latest pool error (if any):
+
+```json
+{
+  "runner_configs": {
+    "default": {
+      "datacenters": {
+        "dc-1": {
+          "serverless": {
+            "url": "https://your-deployment.example.com/rivet",
+            "headers": { "Authorization": "Bearer token" },
+            "request_lifespan": 55,
+            "slots_per_runner": 1,
+            "max_runners": 10
+          },
+          "runner_pool_error": null
+        }
+      }
+    }
+  },
+  "pagination": { "cursor": null }
+}
+```
+
+`runner_pool_error` mirrors actor scheduling errors such as `serverless_http_error`, `serverless_connection_error`, and `serverless_stream_ended_early`.
+
+### Check Serverless Provider Health
+
+Use this to test whether Rivet can reach your serverless provider URL and read runner metadata:
+
+```bash
+curl -X POST "$RIVET_API/runner-configs/serverless-health-check?namespace=$RIVET_NAMESPACE" \
+  -H "Authorization: Bearer $RIVET_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://your-deployment.example.com/rivet",
+    "headers": {
+      "Authorization": "Bearer token"
+    }
+  }'
+```
+
+Possible responses:
+
+```json
+{ "success": { "version": "1.2.3" } }
+```
+
+```json
+{
+  "failure": {
+    "error": {
+      "message": "non-success status from metadata endpoint",
+      "details": "received status 503"
+    }
+  }
+}
+```
+
+### Refresh Provider Metadata
+
+If you deploy new actor code or routes and metadata has not updated yet, force a refresh:
+
+```bash
+curl -X POST "$RIVET_API/runner-configs/default/refresh-metadata?namespace=$RIVET_NAMESPACE" \
+  -H "Authorization: Bearer $RIVET_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+## Actor API
+
+All actor-level endpoints are accessed through the gateway. The gateway routes requests to the correct actor instance using the actor ID in the URL path:
+
+```
+{RIVET_API}/gateway/{actor_id}/{path}
+```
+
+The gateway only accepts actor IDs, not names. Use `GET /actors?name=...` from the management API to look up actor IDs first.
+
+### Authentication
+
+Standard actor endpoints (health, actions, requests) and inspector endpoints have separate authentication requirements.
+
+#### Standard Endpoints
+
+| Environment | Authentication |
+|---|---|
+| **Local development** | No authentication required. |
+| **Self-hosted engine** | The Rivet Engine handles authentication at the gateway level. |
+| **Rivet Cloud** | Authentication is handled by the Rivet Cloud platform at the gateway level. |
+
+#### Inspector Endpoints
+
+Each actor generates a unique inspector token on first start and persists it in internal SQLite storage. It is also mirrored to legacy KV key `0x03` (base64 `Aw==`) for dashboard compatibility. Pass it as a bearer token in the `Authorization` header.
+
+Inspector endpoints always require the actor's inspector token, including in local development. There is no local-development bypass.
+
+| Environment | Authentication |
+|---|---|
+| **Local development** | Bearer the actor's inspector token in the `Authorization` header. Fetch it through the management KV endpoint (see below). |
+| **Self-hosted engine** | Bearer the actor's inspector token in the `Authorization` header. The Rivet dashboard fetches it automatically; for direct API access, fetch it through the management KV endpoint (see below). |
+| **Rivet Cloud** | Bearer the actor's inspector token in the `Authorization` header. The Rivet dashboard fetches it automatically; for direct API access, fetch it through the management KV endpoint (see below). |
+
+```bash
+curl "$RIVET_API/gateway/{actor_id}/inspector/summary" \
+  -H 'Authorization: Bearer YOUR_INSPECTOR_TOKEN'
+```
+
+#### Retrieving the Inspector Token
+
+Each actor generates a unique inspector token on first start and persists it in internal SQLite storage. The token is also mirrored to the legacy KV key below so the Rivet dashboard can continue to retrieve it through the management KV endpoint. This applies in every environment, including local development.
+
+The inspector token is stored at internal KV key `0x03` (base64: `Aw==`). The response value is also base64-encoded.
+
+```bash
+# Fetch the inspector token for a specific actor
+ACTOR_ID="your-actor-id"
+
+RESPONSE=$(curl -s "$RIVET_API/actors/$ACTOR_ID/kv/keys/Aw==" \
+  -H "Authorization: Bearer $RIVET_TOKEN")
+
+# Extract and decode the base64 value
+INSPECTOR_TOKEN=$(echo "$RESPONSE" | jq -r '.value' | base64 -d)
+
+# Use it to call inspector endpoints
+curl "$RIVET_API/gateway/$ACTOR_ID/inspector/summary" \
+  -H "Authorization: Bearer $INSPECTOR_TOKEN"
+```
+
+### Standard Actor Endpoints
+
+These are the built-in actor endpoints available through the gateway:
+
+```bash
+# Health check
+curl $RIVET_API/gateway/{actor_id}/health
+
+# Metadata
+curl $RIVET_API/gateway/{actor_id}/metadata
+
+# Call an action
+curl -X POST $RIVET_API/gateway/{actor_id}/action/myAction \
+  -H 'Content-Type: application/json' \
+  -d '{"args": [1, 2, 3]}'
+
+# Send queue message (queue name in path)
+curl -X POST $RIVET_API/gateway/{actor_id}/queue/jobs \
+  -H 'Content-Type: application/json' \
+  -d '{"body":{"id":"job-1"}}'
+
+# Send queue message and wait for completion (optional timeout in ms)
+curl -X POST $RIVET_API/gateway/{actor_id}/queue/jobs \
+  -H 'Content-Type: application/json' \
+  -d '{"body":{"id":"job-1"},"wait":true,"timeout":5000}'
+
+# Forward an HTTP request to the actor's onRequest handler
+curl $RIVET_API/gateway/{actor_id}/request/my/custom/path
+```
+
+Queue send responses always include a `status` field:
+
+```json
+{ "status": "completed" }
+```
+
+The `response` field is only present when the queue handler returns a value:
+
+```json
+{ "status": "completed", "response": { "result": "ok" } }
+```
+
+If `wait: true` and the timeout is reached, `status` is `"timedOut"`.
+
+### Inspector Endpoints
+
+The inspector HTTP API exposes JSON endpoints for querying and modifying actor internals at runtime. These are designed for agent-based debugging and tooling.
+
+Every inspector endpoint requires the actor's inspector token as a bearer token, including in local development. The examples below omit the `Authorization` header for brevity, but you must add `-H "Authorization: Bearer $INSPECTOR_TOKEN"` to each request. See [Retrieving the Inspector Token](#retrieving-the-inspector-token) above.
+
+#### Get State
+
+```bash
+curl $RIVET_API/gateway/{actor_id}/inspector/state
+```
+
+Returns the actor's current persisted state:
+
+```json
+{
+  "state": { "count": 42, "users": [] },
+  "isStateEnabled": true
+}
+```
+
+#### Set State
+
+```bash
+curl -X PATCH $RIVET_API/gateway/{actor_id}/inspector/state \
+  -H 'Content-Type: application/json' \
+  -d '{"state": {"count": 0, "users": []}}'
+```
+
+Returns:
+
+```json
+{ "ok": true }
+```
+
+#### Get Connections
+
+```bash
+curl $RIVET_API/gateway/{actor_id}/inspector/connections
+```
+
+Returns all active connections with their params, state, and metadata:
+
+```json
+{
+  "connections": [
+    {
+      "type": "websocket",
+      "id": "conn-id",
+      "details": {
+        "type": "websocket",
+        "params": {},
+        "stateEnabled": true,
+        "state": {},
+        "subscriptions": 2,
+        "isHibernatable": true
+      }
+    }
+  ]
+}
+```
+
+#### Get RPCs
+
+```bash
+curl $RIVET_API/gateway/{actor_id}/inspector/rpcs
+```
+
+Returns a list of available actions:
+
+```json
+{ "rpcs": ["increment", "getCount"] }
+```
+
+#### Execute Action
+
+```bash
+curl -X POST $RIVET_API/gateway/{actor_id}/inspector/action/increment \
+  -H 'Content-Type: application/json' \
+  -d '{"args": [5]}'
+```
+
+Returns:
+
+```json
+{ "output": 47 }
+```
+
+#### Get Queue Status
+
+```bash
+curl $RIVET_API/gateway/{actor_id}/inspector/queue?limit=10
+```
+
+Returns queue status with messages:
+
+```json
+{
+  "size": 3,
+  "maxSize": 1000,
+  "truncated": false,
+  "messages": [
+    { "id": 1, "name": "process", "createdAtMs": 1706000000000 }
+  ]
+}
+```
+
+#### Get Workflow History
+
+```bash
+curl $RIVET_API/gateway/{actor_id}/inspector/workflow-history
+```
+
+Returns:
+
+```json
+{
+  "history": null,
+  "isWorkflowEnabled": false
+}
+```
+
+#### Get Database Schema
+
+```bash
+curl $RIVET_API/gateway/{actor_id}/inspector/database/schema
+```
+
+Returns discovered SQLite tables and views when the actor has `c.db` enabled:
+
+```json
+{
+  "schema": {
+    "tables": [
+      {
+        "table": { "schema": "main", "name": "test_data", "type": "table" },
+        "columns": [
+          { "cid": 0, "name": "id", "type": "", "notnull": 0, "dflt_value": null, "pk": 0 }
+        ],
+        "foreignKeys": [],
+        "records": 2
+      }
+    ]
+  }
+}
+```
+
+#### Get Database Rows
+
+```bash
+curl "$RIVET_API/gateway/{actor_id}/inspector/database/rows?table=test_data&limit=100&offset=0"
+```
+
+Returns paged rows for a specific SQLite table or view:
+
+```json
+{
+  "rows": [
+    {
+      "id": 1,
+      "value": "Alice",
+      "payload": "",
+      "created_at": 1706000000000
+    }
+  ]
+}
+```
+
+#### Execute SQLite
+
+Run manual SQL against an actor's SQLite database. This supports both read-only queries and mutations.
+
+```bash
+curl -X POST http://localhost:6420/gateway/{actor_id}/inspector/database/execute \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "sql": "SELECT id, value FROM test_data WHERE value = ? ORDER BY id DESC",
+    "args": ["alpha"]
+  }'
+```
+
+Returns:
+
+```json
+{
+  "rows": [
+    { "id": 2, "value": "alpha" }
+  ]
+}
+```
+
+You can also use named SQLite bindings through a `properties` object:
+
+```bash
+curl -X POST http://localhost:6420/gateway/{actor_id}/inspector/database/execute \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "sql": "SELECT id, value FROM test_data WHERE value = :value ORDER BY id DESC",
+    "properties": {
+      "value": "alpha"
+    }
+  }'
+```
+
+For mutations, use `RETURNING` if you want rows back. Otherwise the statement still runs and `rows` is empty:
+
+```bash
+curl -X POST http://localhost:6420/gateway/{actor_id}/inspector/database/execute \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "sql": "INSERT INTO test_data (value, created_at) VALUES (?, ?) RETURNING id, value",
+    "args": ["beta", 1706000000000]
+  }'
+```
+
+For workflow-enabled actors, `history` is a JSON object with `nameRegistry`, `entries`, and `entryMetadata`. Step outputs, loop state, and message payloads are decoded from CBOR into normal JSON values.
+
+#### Replay Workflow From Step
+
+Reset a workflow to a specific step and restart execution immediately. Omitting `entryId` replays the workflow from the beginning.
+
+If the workflow is still running when you call replay, the endpoint rejects the request with `409 Conflict` and an `actor/workflow_in_flight` error instead of cancelling the live run for you.
+
+```bash
+curl -X POST http://localhost:6420/gateway/{actor_id}/inspector/workflow/replay \
+  -H 'Content-Type: application/json' \
+  -d '{"entryId":"workflow-step-id"}'
+```
+
+Returns the same JSON shape as `/inspector/workflow-history`:
+
+```json
+{
+  "history": {
+    "nameRegistry": ["step-one", "step-two"],
+    "entries": [],
+    "entryMetadata": {}
+  },
+  "isWorkflowEnabled": true
+}
+```
+
+While a workflow is in flight, the response shape is:
+
+```json
+{
+  "group": "actor",
+  "code": "workflow_in_flight",
+  "message": "Workflow replay is unavailable while the workflow is currently in flight.",
+  "metadata": null
+}
+```
+
+#### Summary
+
+Get a full snapshot of the actor in a single request:
+
+```bash
+curl $RIVET_API/gateway/{actor_id}/inspector/summary
+```
+
+Returns:
+
+```json
+{
+  "state": { "count": 42 },
+  "connections": [],
+  "rpcs": ["increment", "getCount"],
+  "queueSize": 0,
+  "isStateEnabled": true,
+  "isDatabaseEnabled": false,
+  "isWorkflowEnabled": false,
+  "workflowHistory": null
+}
+```
+
+When workflow history is present in `/inspector/summary`, `workflowHistory` is returned as the same decoded JSON shape as `/inspector/workflow-history`.
+
+### Polling
+
+Inspector endpoints are safe to poll. For live monitoring, poll at 1-5 second intervals. The `/inspector/summary` endpoint is useful for periodic snapshots since it returns all data in a single request.
+
+## OpenAPI Spec
+
+An OpenAPI specification covering many of the management and actor endpoints is available:
+
+- In the repository at [`rivetkit-openapi/openapi.json`](https://github.com/rivet-dev/rivet/tree/main/rivetkit-openapi)
+- Served at `/doc` on the manager when running locally
+
+The checked-in spec does not yet list every endpoint documented on this page (for example the actor metadata and queue routes and the inspector database routes), so treat this page as the authoritative reference where they differ.
+
+_Source doc path: /docs/actors/debugging_