Skip to content

feat(runtime): add shutdown() method to gracefully stop all boxes - #155

Merged
DorianZheng merged 5 commits into
mainfrom
feat/runtime-shutdown
Jan 23, 2026
Merged

DorianZheng merged 5 commits into
mainfrom
feat/runtime-shutdown

Conversation

@DorianZheng

Copy link
Copy Markdown
Member

Summary

Implement runtime.shutdown() across all SDKs to gracefully stop all running boxes with configurable timeout.

  • Add boxes_stopped counter to track stopped boxes
  • Implement num_running_boxes() calculation: created - stopped - failed
  • Make box.stop() idempotent (safe to call multiple times)
  • Add shutdown() method to Python, Node.js, and C SDKs

API

# Python
await runtime.shutdown()          # Default 10s timeout
await runtime.shutdown(timeout=5) # Custom timeout
await runtime.shutdown(timeout=-1) # Wait indefinitely
// Node.js
await runtime.shutdown();    // Default 10s timeout
await runtime.shutdown(5);   // Custom timeout
await runtime.shutdown(-1);  // Wait indefinitely
// C
boxlite_runtime_shutdown(runtime, 0, &error);  // Default (0 = 10s)
boxlite_runtime_shutdown(runtime, 5, &error);  // Custom timeout
boxlite_runtime_shutdown(runtime, -1, &error); // Wait indefinitely

Files Changed

Category Files
Core box_impl.rs, runtime_metrics.rs
C SDK boxlite.h, ffi.rs
Node.js SDK runtime.rs
Python SDK runtime.rs, _boxlite.py
Examples shutdown.c, shutdown.js, shutdown_example.py
Tests shutdown.test.ts, test_shutdown.py

Test plan

  • Run Rust unit tests: cargo test -p boxlite --lib
  • Run Python integration tests: pytest sdks/python/tests/test_shutdown.py -v
  • Run Node.js integration tests: cd sdks/node && npm test
  • Run examples manually to verify behavior

Implement runtime.shutdown() across all SDKs (Python, Node.js, C) to
gracefully stop all running boxes with configurable timeout.

Core changes:
- Add boxes_stopped counter to RuntimeMetricsStorage
- Implement num_running_boxes() calculation (created - stopped - failed)
- Make box.stop() idempotent (early exit if already stopped)
- Add unit tests for metrics calculation

SDK bindings:
- Python: async shutdown() + sync API wrapper
- Node.js: async shutdown() via napi-rs
- C: boxlite_runtime_shutdown() FFI function

Examples and tests:
- Add shutdown examples for Python, Node.js, and C
- Add integration tests for Python and Node.js SDKs
The shutdown test requires the native binary and VM environment,
which aren't available in CI unit tests. The Python test uses
pytest.mark.integration to skip in CI; Node.js doesn't have an
equivalent mechanism, so removing the test file.

Integration tests should be run locally during development.
- Remove unused imports (os, Path, Iterator, Generator, boxlite)
- Add TYPE_CHECKING imports for forward references (Boxlite, SyncBox, SyncExecution)
- Add noqa: F401 for re-exported symbols via __all__.extend()
- Fix E712: use `is True/False` instead of `== True/False`
- Remove unused variable `expected_attrs`
@DorianZheng
DorianZheng merged commit bd49271 into main Jan 23, 2026
25 checks passed
@DorianZheng
DorianZheng deleted the feat/runtime-shutdown branch January 23, 2026 07:04
DorianZheng pushed a commit that referenced this pull request Jun 26, 2026
Fix SDK network/secrets integration failures by avoiding the current VMM
seccomp/gvproxy conflict and making MITM TLS validation work inside the
jail.

Test plan:
- Remote e2e runner: Python #155 non-detach failure subset, 25 passed in
116.10s
- Remote e2e runner: Node tests/network-secrets.integration.test.ts, 5
passed
- A/B check without SDK Cargo gvproxy feature changes: Python subset 25
passed, Node network-secrets 5 passed

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Improved secure upstream TLS validation by extending sandbox trust to
include existing system CA bundles and cert files (read-only).
* Prevented syscall filtering from disrupting network-enabled runs by
skipping the VMM syscall filter when networking is active.
* Updated network interception integration coverage to use a new
upstream endpoint, keeping secret-substitution checks stable.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant