Skip to content

docs(serverless): document timeout tuning #5018

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
NathanFlurry wants to merge 1 commit into
base: counter-latency/kitchen-sink-load-harness
Choose a base branch
from
+11 −1
Draft

docs(serverless): document timeout tuning #5018

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .agent/notes/driver-test-progress.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,11 @@ Scope: DB driver tests only
- 2026-05-08 16:52 PDT raw-websocket [native/local/bare]: PASS (16 passed, 14.0s). Covers raw websocket callback tracking.
- 2026-05-08 16:52 PDT actor-conn-state [native/local/bare]: PASS (11 passed, 10.9s). Covers connection lifecycle and disconnect accounting through the work registry.
- 2026-05-08 16:52 PDT actor-sleep-db [native/local/bare]: PASS (26 passed, 70.9s). Covers DB close timing during sleep shutdown and waitUntil state persistence.
- 2026-05-09 04:48 PDT DB TESTS RERUN STARTED [native only] - validating async websocket close handler behavior.
- 2026-05-09 04:48 PDT actor-db rerun [native]: PASS (13 passed, 104 skipped, 18.3s).
- 2026-05-09 04:48 PDT actor-db-raw rerun [native]: PASS (5 passed, 40 skipped, 4.9s).
- 2026-05-09 04:48 PDT actor-db-pragma-migration rerun [native]: PASS (4 passed, 32 skipped, 4.3s).
- 2026-05-09 04:48 PDT actor-sleep-db rerun [native]: PASS (26 passed, 208 skipped, 63.8s). Includes `async websocket close handler can use c.db before sleep completes` and `async websocket addEventListener close handler can use c.db before sleep completes`.
- 2026-05-09 04:48 PDT actor-db-stress rerun [native]: PASS (5 passed, 40 skipped, 31.3s).
- 2026-05-09 04:48 PDT actor-db-init-order rerun [native]: PASS (6 passed, 48 skipped, 6.3s).
- 2026-05-09 04:48 PDT DB TESTS RERUN COMPLETE [native only] - 6/6 DB file groups passed. Async close handler tests included.
4 changes: 3 additions & 1 deletion website/src/content/docs/general/production-checklist.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,9 @@ We recommend passing this page to your coding agent to verify your configuration
- **Verify `/api/rivet/start` body size limits.** Serverless actor starts carry actor config and preloaded KV or SQLite startup data in the request body. Keep `serverless.maxStartPayloadBytes` and your platform or proxy body limit at **16 MiB or higher**, or lower the preload budget if your platform cannot accept that size. See [Limits](/docs/actors/limits#kv-preloading).
- **Configure max runners.** Go to Settings > Providers > Edit Provider > Max Runners to set the limit. The default is 100,000 runners. This is effectively your max actor count.
- **Verify your platform rate limit accommodates your actor create and wake frequency.** Actor start requests are sent from Rivet's servers, so they all originate from the same IP. Per-IP rate limits will throttle the engine well before they would throttle real end-user traffic. Size your platform's rate limit to your peak actor create and wake rate, not your end-user request rate.
- **Configure platform max concurrency if available.** Some platforms (e.g. GCP Cloud Run, AWS Lambda) let you cap the number of concurrent instances. Set this to match your expected concurrent actor count so the platform admits enough instances to host your actors.
- **Set the per-instance max concurrent actor limit.** Each serverless instance hosts one actor per in-flight `/api/rivet/start` request, so your platform's per-instance concurrency (e.g. GCP Cloud Run `--concurrency`, AWS Lambda reserved concurrency, Vercel `maxDuration` + concurrency) directly caps actors per instance. Pick a value based on per-actor memory and CPU; the platform autoscales out additional instances once existing ones hit the cap.
- **Tune `requestLifespan` to your platform's hard request timeout.** `requestLifespan` (default `3600`, 60 minutes) is the total lifespan of each serverless request before actors migrate to a fresh instance. Set it just below your platform's hard timeout (e.g. `295` for Vercel Hobby, `3595` for Vercel Pro, `840` for Cloud Run's 15-min cap). Configure via [`configurePool`](/docs/general/registry-configuration). See [Timeouts](/docs/general/runtime-modes#timeouts).
- **Tune `drainGracePeriod` to cover graceful actor shutdown.** Time reserved at the end of `requestLifespan` for actors to stop gracefully before the request is forcibly closed. Default is 30 minutes from the engine; lower it for short-lived stateless actors, raise it if your actors do non-trivial cleanup or final SQLite writes. Configure via [`configurePool`](/docs/general/registry-configuration). See [Limits](/docs/actors/limits).

### Runner

Expand Down
Loading