feat(engine,rivetkit): align local dev with envoy-mode design

[brittianwarner]

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

[railway-app]

This PR was not deployed automatically as @brittianwarner does not have access to the Railway project.

In order to get automatic PR deploys, please add @brittianwarner to your workspace on Railway.

[brittianwarner]

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

• feat(engine,rivetkit): align local dev with envoy-mode design #4653 👈 (View in Graphite)
• BREAK THIS UP: WIP patches #4650
• chore(engine): publish engine bases in ci #4649 : 2 other dependent PRs (#4652 , #4666 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

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

[claude]

PR Review: feat(engine,rivetkit): align local dev with envoy-mode design

Overview

This PR renames manager* config properties to http* (e.g. serveManager → serveHttp, managerPort → httpPort) and introduces a structured runtime discriminated union (mode: "envoy" | "serverless") to centralize spawn/mode decisions. It also registers the ${poolName}-native-db runner config in both local dev and serverless paths, changes the default HTTP port from 6420 to 8080, and adds child-process signal handlers to avoid orphaned engine processes.

---

Breaking Changes Not Called Out

• Default port changed from 6420 to 8080 without a deprecation notice or migration guide. Any user relying on the old default will silently break.
• Flat config fields renamed (managerPort, serveManager, managerBasePath, managerHost) with no backward-compatibility shim at the schema level. Users with existing configs will silently lose their settings. The PR checklist box for breaking changes is unchecked.

---

Specific Issues

1. Broken inspector URL when httpPort is undefined (runtime/index.ts:155)

When running in envoy mode with no HTTP server, httpPort is undefined, so 0 is passed via this.httpPort ?? 0. If config.inspector.defaultEndpoint and config.endpoint are both unset, getInspectorUrl will produce http://127.0.0.1:0/ui/ which is a non-functional URL. The old code returned undefined and skipped printing the inspector URL entirely. The comment says the URL falls back through getInspectorUrl's own chain, but that fallback to config.endpoint only works when an endpoint is actually configured.

2. Duplicated mode-resolution logic

The resolvedMode / isProduction / hasEndpoint logic is computed independently in both RegistryConfigSchema.transform() (config/index.ts) and Registry.start() (registry/index.ts). If these two copies drift, the PR's own decision matrix comment will become wrong for one of them.

3. Signal-handler accumulation in ensureEngineProcess

If ensureEngineProcess is called multiple times (e.g. in test suites), process.once calls accumulate. Node.js will warn with MaxListenersExceededWarning. The exit handler is also never removed if the child exits normally before the parent does. Consider storing and removing the handlers when the child exits cleanly.

4. Duplicate error for production without endpoint

A Zod ctx.addIssue is added in config/index.ts for the production-without-endpoint case, and a throw new Error() with a nearly identical message is also added in registry/index.ts. A user will see two separate error messages for the same misconfiguration. One authoritative location should handle this.

5. configurePool set to undefined on a non-optional field (config/index.ts)

The serverless branch of the discriminated union defines configurePool: ConfigurePoolSchema without .optional(). Assigning undefined there bypasses Zod validation and may surface confusing runtime errors downstream rather than a clean config error at parse time.

6. Hardcoded -native-db suffix in two places

The suffix is hardcoded in both runtime/index.ts and serverless/configure.ts. If EngineActorDriver ever changes the pool-name convention, both sites will silently diverge. Extracting it to a shared constant would prevent this.

7. start() continues silently after serverless-mode warning

When resolvedMode is "serverless", a warning is logged but execution continues into the engine-spawn path with no explanation of what will actually happen. If calling start() in serverless mode is genuinely wrong, it should throw. If it is allowed, the warning should describe what the code will do so the caller can reason about the outcome.

---

Minor

• Comment style (runtime/index.ts:151-155): the block uses parenthetical notation — per project conventions, prefer full sentences without parenthetical fragments.
• Deno serve function (serve.ts): serveDeno uses config.httpPort directly instead of the already-resolved httpPort parameter, which means the port-collision fallback from findFreePort is not applied in Deno. The node and bun paths correctly use the parameter. Worth fixing while the rename is in progress.
• @vite-ignore addition (websocket.ts): good fix for the Vite bundler warning.
• Child-process cleanup in ensureEngineProcess: the intent is correct and valuable for the tsx --watch use case. The signal-handler accumulation issue above is the main concern to address.
• Test update (tests/registry-constructor.test.ts) correctly mirrors the renamed fields.

---

Summary

The rename from manager to http and the new runtime discriminated union are reasonable design improvements. The main risks are: the silent breaking-change on the httpPort default, the broken inspector-URL fallback when httpPort is 0, duplicated error handling, and signal-handler accumulation. The PR checklist should be updated to indicate this is a breaking change.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4653

All packages published as 0.0.0-pr.4653.7179278 with tag pr-4653.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-7179278
docker pull rivetdev/engine:full-7179278

Individual packages

npm install rivetkit@pr-4653
npm install @rivetkit/react@pr-4653
npm install @rivetkit/rivetkit-native@pr-4653
npm install @rivetkit/workflow-engine@pr-4653