fix(rivetkit): fix default spawn engine behavior

[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): preserve internal bridge errors #4993
• fix(rivetkit): remove deprecated actor options #4992
• fix(rivetkit): fix default spawn engine behavior #4989 👈 (View in Graphite)
• chore: fix compile warnings #4988
• fix: compile wasm vs native features with custom cfg to prevent dupe features #4982
• chore: remove setPreventSleep #4981
• main

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

[claude]

Code Review: fix(rivetkit): fix default spawn engine behavior

Overview

This PR is a significant refactoring of the RivetKit entrypoint API. Key changes:

• API rename: registry.handler(req) replaced by registry.fetchHandler({ path })(req), registry.serve() removed
• New method: registry.listen(opts) for local server deployments
• Config consolidation: Entrypoint-specific options moved from setup() to per-method options
• Env var renames: RIVET_ENVOY_VERSION to RIVET_VERSION, RIVET_POOL_NAME to RIVET_POOL, RIVET_RUNNER_TOKEN to RIVET_TOKEN
• Pool config migrated to Rust: configureServerlessPool TypeScript replaced by ensure_local_serverless_runner_config in rivetkit-core
• Default dev behavior: Engine auto-starts for envoy mode in non-production without needing startEngine: true

Strengths

• Excellent error messages for removed fields and renamed env vars
• EnvoyConfigSchema now validates-and-rejects old fields instead of silently ignoring them
• Moving configureServerlessPool to Rust aligns with the layer architecture constraints
• New runtime-mode-config.test.ts is thorough and covers all edge cases
• claimEntrypoint guard preventing double-initialization is a good defensive pattern
• Improved error context in runner_config.rs (includes engine endpoint in error messages)

Issues

Potential silent failure in listen()

startHttpServer is async but its promise is stored without an error handler. If port binding fails, the error is only surfaced in the shutdown handler. Consider adding a .catch immediately after the assignment to log startup failures.

staticDirFromConfig(undefined) returns "public"

When listen() is called without the static option, parsed.static is undefined, and staticDirFromConfig(undefined) returns "public". Static file serving is silently enabled if a public/ directory exists even when the user did not ask for it. Consider only enabling static serving when static is explicitly provided.

isDev behavioral asymmetry

isDevelopmentEnv() in registry/index.ts strictly requires NODE_ENV === "development". When NODE_ENV is unset, listen() automatic dev mode does not fire. But config.ts treats missing NODE_ENV as non-production (isProduction = getNodeEnv() === "production"), so the engine still auto-starts. This asymmetry can confuse users who do not explicitly set NODE_ENV.

version fallback is dead code in production

When version is missing in production, a Zod issue is added but the transform still returns version: version ?? 1. The ?? 1 is unreachable since parse() throws on issues. A brief comment clarifying this would help future readers.

entrypoint not blocked at runtime in setup()

entrypoint is excluded from RegistryConfigInput at the TypeScript type level, but it is not in the removedSetupFields runtime check. Adding it there would make the guard complete for plain-JS callers.

Manual mode implicit in Rust runner config

In runner_config.rs, ensure_local_serverless_runner_config returns early when dev_serverless_url is None, implicitly handling dev_serverless_manual. A comment explaining that manual mode bypasses this function would clarify the intent.

parseNumberEnv can return NaN

parseNumberEnv in env-vars.ts uses Number(value) which returns NaN for non-numeric strings. The downstream parseEnvNumber in config/index.ts catches this. Consider adding an explicit NaN check in parseNumberEnv itself so each layer owns its own validation.

Minor Notes

• wasm-runtime.test.ts has an indentation inconsistency introduced by this PR (spaces mixed with surrounding tabs)
• runtime/index.ts renames startEnvoy() to start() -- verify all internal call sites are updated
• The TODO comment about Add sane defaults for NODE_ENV=development is removed -- confirm this was intentionally resolved

Summary

This is a well-structured cleanup that simplifies the entrypoint API and moves configuration to the right layer. The main items worth addressing before merge are the silent HTTP server failure in listen() and the staticDirFromConfig default behavior.