docs(rivetkit): raise serverless start payload limit

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• fix(rivetkit-core): fail closed sqlite during shutdown #4921
• docs(rivetkit): raise serverless start payload limit #4920 👈 (View in Graphite)
• test(kitchen-sink): add sqlite memory soak harness #4919
• feat(rivetkit): expose runtime diagnostics #4918
• chore(depot-client): migrate to worker thread #4907 : 2 other dependent PRs (#4909 , #4912 )
• test(driver): select matrix cells with vitest filters #4906
• fix(pegboard): restore hibernating requests on serverful start #4904 : 1 other dependent PR (#4905 )
• fix(rivetkit): drain shutdown work before sleep #4902 : 1 other dependent PR (#4903 )
• feat(sqlite): wire remote sqlite execute handlers #4897
• test(serverless): avoid pinning header validation order #4896
• chore(driver-test-runner): add native/wasm runtime matrix to skill #4884 : 3 other dependent PRs (#4892 , #4894 , #4901 )
• chroe: rename rivetkit-sqlite to depot-client #4883
• fix(rivetkit-wasm): fix mem leaks #4880
• chore(rivetkit): wasm support #4860
• feat(sqlite): add cold read benchmarks and simplify optimizations #4857
• feat(sqlite): benchmark cold reads #4848 : 1 other dependent PR (#4864 )
• docs(actors): document manual lifecycle controls #4847
• test(sqlite): expand db stress coverage #4846 : 1 other dependent PR (#4849 )
• test(raw-websocket): add serverless smoke coverage #4845
• feat(serverless): configure drain grace period #4844
• fix(publish): enable frontend build for engine target and use turbo build instead of turbo build:engine #4843
• feat(rivetkit): expose conn handle in onWebSocket context #4842
• fix(rivetkit): normalize waitUntil/keepAwake promises to null to avoid serde undefined error #4841
• fix(rivetkit): remove requirement for token #4839 : 1 other dependent PR (#4840 )
• fix(pegboard-envoy): allow sqlite requests across lifecycle states #4838
• fix(pegboard): route scoped actor key reads by runner dc #4837
• fix(sqlite-storage): let sqlite open take over stale owners #4834
• fix(engine-tests): parallelize multi-DC startup + enable 6 multi-DC tests #4833
• fix(api): honor cursor in actor_ids list path #4832
• fix(api): silently filter invalid IDs from actor_ids query instead of 400 #4831
• fix(api-peer): make actors_delete idempotent for already-destroyed actors #4830
• fix(pegboard): use Iterator streaming mode in list_names so limit param is honored #4829
• chore(engine-tests): convert envoy tests to Sleep crash policy + triage ignored #4828
• feat(engine-tests): wire envoy actor names through prepopulate_actor_names #4827
• chore(depot): fault injection tests #4868
• feat(sqlite): pitr & forking #4859 : 1 other dependent PR (#4863 )
• chore(sqlite): stateless storage refactor #4856
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Code Review

PR: docs(rivetkit): raise serverless start payload limit
Status: Closed

Overview

This PR raises the default maxStartPayloadBytes for serverless mode from 1 MiB to 16 MiB to accommodate KV preloading and SQLite startup page preloads serialized into the /api/rivet/start request body. It also adds glibc memory allocator tuning defaults for the spawned engine subprocess, and updates documentation.

---

Code Quality

Constant extraction (serverless.ts)

• Extracting DEFAULT_SERVERLESS_MAX_START_PAYLOAD_BYTES as a named export and using it in the schema description via template literal is the right call. The description now stays in sync with the actual default automatically.

Memory allocator tuning (engine_process.rs)

• The set_default_allocator_env helper is clean and correctly guards with is_none() so operators can override.
• MALLOC_ARENA_MAX=2 and MALLOC_TRIM_THRESHOLD_=131072 (128 KiB) are standard glibc defaults for memory-constrained or memory-fragmentation-sensitive workloads.

---

Potential Issues

Platform portability of glibc env vars

MALLOC_ARENA_MAX and MALLOC_TRIM_THRESHOLD_ are glibc-specific and only have an effect on Linux with glibc. They are silently ignored on macOS and Windows. This isn't a bug since they're just ignored, but a comment explaining this would prevent future confusion:

// glibc-specific: reduces arena fragmentation on Linux; ignored on other platforms
fn set_default_allocator_env(command: &mut Command) {

dev:serverless script and env var interaction

"dev:serverless": "MALLOC_ARENA_MAX=2 MALLOC_TRIM_THRESHOLD_=131072 RIVET_RUN_ENGINE=1 ..."

Setting these vars in the shell environment means the node server process inherits them. When the engine subprocess is spawned, set_default_allocator_env will find them already set via is_none() and correctly skip re-setting them. This is fine, but the intent (applying them to the node process too) could be worth a comment since it looks redundant next to the Rust-side defaults.

No schema validation bounds on maxStartPayloadBytes

The field has no .min() or .max() constraint. With a 16 MiB default and the operational significance of this value, a minimum floor (e.g., .min(1_048_576)) would prevent silent misconfiguration like maxStartPayloadBytes: 0. This was pre-existing, not introduced here, but the raised default makes it more salient.

---

Documentation

• The limits.mdx addition is accurate and gives the right context (why 16 MiB vs the 1 MiB preload budget).
• The sentence is long — consider splitting after "...alongside the start command." for readability.
• The production checklist addition is practical and actionable. Good inclusion.

---

Summary

The change is straightforward and well-motivated. The constant extraction and the set_default_allocator_env guard are both done correctly. The main gaps are:

1. Missing a comment on glibc-specific env vars (minor).
2. No min/max validation on maxStartPayloadBytes (pre-existing, worth a follow-up).
3. The dev:serverless script applying env vars to the parent node process vs. the subprocess is slightly surprising without a comment.

Overall a clean, low-risk change.