feat(rivetkit): add runner config admin helper

[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

• feat(rivetkit): add runner config admin helper #4790 👈 (View in Graphite)
• fix(serverless): split metadata protocol errors #4789 : 1 other dependent PR (#4791 )
• chore(sqlite): add open close lifecycle for envoy actors #4788
• fix(rivetkit): share lifecycle shutdown grace #4810
• fix(pegboard): move sqlite v1 migration into actor workflow #4787 : 1 other dependent PR (#4797 )
• test(rivetkit): cover c.db access from onWake/onSleep/onDestroy #4786
• fix(rivetkit-napi): run onMigrate before createState/onCreate/createVars #4785
• refactor(rivetkit-core): merge ready+started into lifecycle_started, drop redundant napi calls #4784
• fix(rivetkit): drain native sleep side tasks reliably #4782 : 1 other dependent PR (#4783 )
• fix(rivetkit): route raw request fetches to actors #4781
• fix(pegboard): refresh runner config after envoy connect #4778 : 2 other dependent PRs (#4779 , #4798 )
• chore(kitchen-sink): configurable endpoint #4766 : 2 other dependent PRs (#4754 , #4777 )
• refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs #4765
• chore(envoy-client): log command and event payloads #4751
• fix(rivetkit): minor sleep-cleanup follow-ups #4761
• docs(rivetkit): clean up stale setPreventSleep references in docs and JSDoc #4760
• docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors #4759
• test(engine): force overdue branch in alarm-during-sleep test with negative offset #4758
• fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown #4757
• test(rivetkit): remove sleepWithPreventSleep fixture and tests #4756
• test(engine): add regression test for alarm-during-sleep-transition race #4755
• test(rivetkit-core): cover sleep/destroy guards and prevent_sleep no-op #4750
• docs: add keepAwake vs waitUntil table and internal sleep-sequence invariants #4749
• feat(rivetkit): expose c.keepAwake(promise) through native path #4748
• refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript #4747
• fix(rivetkit-core): enumerate non-drained counters in grace deadline warn log #4746
• fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses #4745
• fix(rivetkit-core): error on sleep/destroy before startup or already-requested #4743
• fix(rivetkit-core): cap SerializeState shutdown timeout at 15s #4742
• refactor(rivetkit-core): remove prevent_sleep field and deprecate set_prevent_sleep to no-op #4741
• fix(api-public): remove orphan import_export actors module #4764
• main

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

[claude]

PR Review: feat(rivetkit): add runner config admin helper

Overview

This PR refactors the runner configuration admin helper by moving logic from pure TypeScript HTTP calls into Rust core and exposing it via NAPI bindings. It introduces EngineAdminConfig, publicizes several types/functions from runner_config.rs, adds upsert_runner_config_for_all_datacenters as a convenience helper, and eliminates the now-redundant TS-side getDatacenters/updateRunnerConfig implementations in api-endpoints.ts.

---

Correctness

• config.headers access is valid. RegistryConfig schema includes headers: z.record(z.string(), z.string()).optional().default({}), so the access in runner-config.ts is safe.
• NapiInvalidArgument usage is correct. It is defined in lib.rs and follows the pattern already established across database.rs, kv.rs, queue.rs, etc.
• upsert_runner_config_for_all_datacenters atomicity. The function fetches datacenters and then issues a second request, so the set of datacenters can change between the two calls. This matches the old TS behavior, but a comment acknowledging the non-atomic nature would be useful if called in high-churn environments.

---

Issues

Missing newline at EOF

rivetkit-rust/engine/artifacts/errors/engine.request_failed.json is missing a trailing newline. Should be a quick fix.

normal and metadata typed as any in the generated .d.ts

The TypeScript interface in runner-config.ts correctly types these as Record<string, unknown>, but the generated NAPI declaration falls back to any because serde_json::Value does not map to a richer JS type. Since the .d.ts is hand-maintained, these could be tightened to Record<string, unknown> directly in the declaration file for better downstream type safety.

Plain Error thrown for missing endpoint

// runner-config.ts
if (!config.endpoint) {
    throw new Error("endpoint is required for runner config updates");
}

CLAUDE.md requires RivetError at all TS boundaries. This path is TS-only and does not cross into core, so it is technically in-bounds, but for consistency with the rest of the codebase a structured error would be preferable.

build_client() called on every invocation

get_datacenters and update_runner_config both call build_client().await which invokes rivet_pools::reqwest::client() each time. Fine for the current infrequent admin-helper use case, but worth noting if this path is called more frequently in the future.

---

Code Quality

• Clean refactor. Moving the two-step fetch-then-update logic from TS into Rust core follows the layering rules ("all load-bearing logic must live in rivetkit-core").
• Structured errors. Transitioning from anyhow::bail! to #[derive(RivetError)] types with the artifact file is correct and follows the error system conventions.
• From/TryFrom conversions. The explicit conversion impls in registry.rs are clean and the json_object_field runtime validation with json_value_kind gives actionable errors.
• All match arms are explicit. The json_value_kind function enumerates all serde_json::Value variants without a _ fallthrough.
• apply_headers mutating loop could use .fold() for concision, but the current form is readable — not a blocker.

---

Tests

The checklist items are all unchecked and there are no tests for the new public get_datacenters, update_runner_config, or upsert_runner_config_for_all_datacenters NAPI exports. Given this is a DRAFT PR the omission is understandable, but tests should be added before merge.

---

Summary

Correctness	No functional regressions found
Layering	Logic correctly moved to Rust core via NAPI
Error handling	Structured errors; one minor plain Error instead of RivetError
Style	Follows project conventions
Action needed	Missing EOF newline in artifact JSON; any types in .d.ts; no tests

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4790

All packages published as 0.0.0-pr.4790.a926470 with tag pr-4790.

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-a926470
docker pull rivetdev/engine:full-a926470

Individual packages

npm install rivetkit@pr-4790
npm install @rivetkit/react@pr-4790
npm install @rivetkit/rivetkit-napi@pr-4790
npm install @rivetkit/workflow-engine@pr-4790