microsandbox-rb 0.5.11 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2d0013cf55f89aa21492847859554937ff838d5d38d4f5f34d0e8da473c9554
-  data.tar.gz: 95bd9d994905567facd356597a8fee6e7f25715a485edbbc48bf98bb09f90eb3
+  metadata.gz: abfe8d0fedb192bc5efa95a741ae971475a2a5cc441879c092108bc8bdf9eed5
+  data.tar.gz: ffeb9bda17817cc1c58bfe5cc9c7d58543cde155eead9d2e5eb3844c8a48b4dd
 SHA512:
-  metadata.gz: 337de8ed90dfea5b44d959579a16dafdd736e33fbfff7e10ed8ad4678184f84bdf417f33d85a7a8f11ab69a4785a91c381ea719600769b804d9a71c1c048adb1
-  data.tar.gz: 672d7c7945e3a5561ad9934bc682b5f9764d1873d4235105e33ca1494a0079d11e574d520ed0e1f90bb66049264cdc783180448d2f456c78185024d9f18b186d
+  metadata.gz: 73379d82644123c717cd7db9391cab9bf72c16b5cf398ea104fb51d2b608353ed9cd6783db55e1490d941ae67728f1c69fe0bd2dcec37c7ad541c56996afea9f
+  data.tar.gz: b20914b13315697e89ec8a72e7620592a9c00d1e8fa908117ef24d64aea9755b431a2298b85d58ed00ca664065f0b626510c7f11fbb919860d3f839c93268a28

data/CHANGELOG.md

@@ -1,11 +1,48 @@
 # Changelog
 
 All notable changes to this gem are documented here. The format is based on
-[Keep a Changelog](https://keepachangelog.com/), and the version tracks the
-upstream microsandbox runtime.
+[Keep a Changelog](https://keepachangelog.com/). The gem follows its own
+[semantic version](https://semver.org/), **independent of** the upstream
+microsandbox runtime it embeds; each release notes the upstream runtime tag it
+wraps, and the README's Versioning section keeps the full gem→runtime map.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-23
+
+This release puts the gem on its **own semantic version**, decoupled from the
+upstream microsandbox runtime tag it embeds (which stays at `v0.5.8`). The
+`0.5.x` lineage had stopped tracking upstream 1:1 — gem-only revisions and a
+bundled breaking change (the `0.5.9 → 0.5.10` lifecycle split) had already
+diverged the two numbers. `0.6.0` makes the split explicit; the gem version no
+longer mirrors the upstream tag. See the README's **Versioning** section for the
+gem→runtime map and the go-forward policy. No runtime change and no breaking API
+change in this release.
+
+### Added
+
+- **`Microsandbox.runtime_version`** and the `Microsandbox::RUNTIME_VERSION`
+  constant — report the upstream microsandbox runtime tag this gem build embeds
+  (e.g. `"v0.5.8"`). The gem now versions itself independently of that tag, so
+  this is the supported way to learn which runtime is wrapped.
+  `spec/unit/version_spec.rb` pins the constant to the Cargo git tag so it can't
+  drift.
+
+## [0.5.12] - 2026-06-23
+
+### Fixed
+
+- **fork-safe tokio runtime.** The process-wide multi-threaded runtime is now
+  tagged with the pid it was built under and rebuilt automatically after a
+  `fork(2)`. A forking host (Solid Queue / Resque job servers, clustered Puma)
+  used to inherit a runtime whose worker + I/O-driver threads do not survive the
+  fork — `block_on` could still drive the calling thread, but background I/O (e.g.
+  the agent-relay connection that streams `exec_stream` output) never ran, so
+  long-lived operations stalled or the connection dropped mid-stream in the child.
+  `runtime()` now detects the pid change and builds a fresh runtime for the child
+  (the stale one is leaked, never dropped — dropping a runtime whose threads
+  vanished across fork can hang on the shutdown join). No API change.
+
 ## [0.5.11] - 2026-06-23
 
 ### Added
@@ -254,6 +291,7 @@ microsandbox runtime, aligned with the official Python/Node/Go SDKs.
   core crate has Apple-native deps). Until precompiled gems are published,
   installing from source requires a Rust toolchain (stable >= 1.91).
 
-[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.8...HEAD
+[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.12...v0.6.0
 [0.5.8]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.5.7...v0.5.8
 [0.5.7]: https://github.com/superradcompany/microsandbox/releases/tag/v0.5.7

data/Cargo.lock

@@ -3249,7 +3249,7 @@ dependencies = [
 
 [[package]]
 name = "microsandbox_rb"
-version = "0.5.11"
+version = "0.6.0"
 dependencies = [
  "chrono",
  "futures",

data/README.md

@@ -374,6 +374,43 @@ Resolution order when no backend is set programmatically: `MSB_BACKEND`
 operations (create/start/stop/remove/get/list, one-shot exec, follow log
 streaming); unsupported operations raise `Microsandbox::UnsupportedError`.
 
+## Versioning
+
+The gem follows its **own** [semantic version](https://semver.org/), **independent
+of** the upstream `microsandbox` runtime it embeds. Early releases (`0.5.7`–`0.5.9`)
+happened to share the upstream tag, but gem-only revisions and a bundled breaking
+change diverged the two numbers — the gem version is **not** a reliable indicator
+of the embedded runtime version. To learn which runtime a build wraps, ask it:
+
+```ruby
+Microsandbox::VERSION          # => "0.6.0"  (the gem's own version)
+Microsandbox.runtime_version   # => "v0.5.8"  (the embedded upstream runtime tag)
+```
+
+| Gem version | Upstream runtime | Notes |
+|-------------|------------------|-------|
+| `0.5.7`  | `v0.5.7` | initial release |
+| `0.5.8`  | `v0.5.7` | gem-only revision |
+| `0.5.9`  | `v0.5.7` | gem-only revision |
+| `0.5.10` | `v0.5.8` | adopts upstream `v0.5.8`; **breaking** lifecycle split |
+| `0.5.11` | `v0.5.8` | gem-only revision |
+| `0.5.12` | `v0.5.8` | gem-only revision |
+| `0.6.0`  | `v0.5.8` | gem version decoupled from the upstream tag; adds `runtime_version` |
+
+**Going forward** — the gem version moves on its own semver track and no longer
+mirrors the upstream tag:
+
+- A **gem-only** change (new bindings, fixes, refactors over the *same* runtime)
+  bumps the gem version by itself.
+- **Adopting a new upstream runtime** bumps the gem version too and updates the
+  pinned git tag, `Microsandbox::RUNTIME_VERSION`, and the table above together.
+- While the gem is `0.x`, a breaking API change bumps the **minor** (`0.5 → 0.6`),
+  not the patch — the `0.5.9 → 0.5.10` lifecycle split predates this policy and is
+  the reason for it.
+
+Every release records its embedded runtime in `CHANGELOG.md`, and
+`Microsandbox.runtime_version` reports it at runtime.
+
 ## Development
 
 ```bash
@@ -406,9 +443,13 @@ or credential setup is needed.
 
 **Each release:**
 
-1. Bump `Microsandbox::VERSION` (and the `tag = "vX.Y.Z"` on the core-crate
-   dependency in `ext/microsandbox/Cargo.toml`) to match the upstream runtime,
-   update `CHANGELOG.md`.
+1. Bump the gem's **own** version — `Microsandbox::VERSION` and the matching
+   `[package] version` in `ext/microsandbox/Cargo.toml` (they must stay equal) —
+   on its independent semver track (see [Versioning](#versioning)); **don't** pick
+   the number to mirror the upstream tag. If the release also adopts a new upstream
+   runtime, bump the `tag = "vX.Y.Z"` on **both** the `microsandbox` and
+   `microsandbox-network` git deps, update `Microsandbox::RUNTIME_VERSION` to match,
+   and add a row to the Versioning table. Update `CHANGELOG.md`.
 2. Push a `vX.Y.Z` tag. CI builds the **source gem** and pushes it to RubyGems
    via `rubygems/configure-rubygems-credentials` (OIDC, `id-token: write`) — no
    `RUBYGEMS_API_KEY` secret required.

data/ext/microsandbox/Cargo.toml

@@ -7,7 +7,7 @@ description = "Ruby SDK native extension for microsandbox — secure, fast micro
 # Must equal Microsandbox::VERSION (lib/microsandbox/version.rb) — Native.version
 # returns this via env!("CARGO_PKG_VERSION") and version_spec.rb asserts equality.
 # The core-crate dependency below stays pinned at its own tag (v0.5.8).
-version = "0.5.11"
+version = "0.6.0"
 authors = ["Super Rad Company <development@superrad.company>"]
 repository = "https://github.com/superradcompany/microsandbox"
 license = "Apache-2.0"

data/ext/microsandbox/src/runtime.rs

@@ -9,7 +9,8 @@
 use std::ffi::c_void;
 use std::future::Future;
 use std::panic::{catch_unwind, AssertUnwindSafe};
-use std::sync::OnceLock;
+use std::sync::atomic::{AtomicPtr, AtomicU32, Ordering};
+use std::sync::Mutex;
 
 use magnus::Ruby;
 use tokio::runtime::Runtime;
@@ -21,17 +22,60 @@ pub fn ruby() -> Ruby {
     Ruby::get().expect("microsandbox: not on a Ruby thread")
 }
 
-static RUNTIME: OnceLock<Runtime> = OnceLock::new();
+// The process-wide tokio runtime, guarded by the pid it was built under. A
+// multi-threaded runtime owns worker + I/O-driver threads, and `fork(2)` copies
+// ONLY the calling thread — so a child that inherits this runtime has a runtime
+// whose threads are gone: `block_on` can still drive the current thread, but the
+// background I/O that keeps e.g. the agent-relay connection alive never runs, so
+// connections stall/drop mid-use. This is hit in practice by forking job servers
+// (Solid Queue, Resque) and clustered web servers (Puma workers).
+//
+// Fix: store the runtime behind a leaked raw pointer tagged with the building
+// pid. If `runtime()` is called in a process whose pid differs (we forked), build
+// a FRESH runtime for this process and swap the pointer. The stale runtime is
+// LEAKED, never dropped — dropping a tokio runtime whose worker threads vanished
+// across fork can hang on the shutdown thread-join. One runtime is leaked per
+// process that uses the SDK (bounded; equivalent to the old set-once behavior in
+// the common no-fork case).
+static RUNTIME_PTR: AtomicPtr<Runtime> = AtomicPtr::new(std::ptr::null_mut());
+static RUNTIME_PID: AtomicU32 = AtomicU32::new(0);
+static RUNTIME_LOCK: Mutex<()> = Mutex::new(());
 
-/// The process-wide multi-threaded tokio runtime, built on first use.
+fn build_runtime() -> Runtime {
+    tokio::runtime::Builder::new_multi_thread()
+        .enable_all()
+        .thread_name("microsandbox-rb")
+        .build()
+        .expect("microsandbox: failed to build tokio runtime")
+}
+
+/// The multi-threaded tokio runtime for THIS process, built on first use and
+/// rebuilt after a `fork(2)` (fork-safe — see the note above).
 pub fn runtime() -> &'static Runtime {
-    RUNTIME.get_or_init(|| {
-        tokio::runtime::Builder::new_multi_thread()
-            .enable_all()
-            .thread_name("microsandbox-rb")
-            .build()
-            .expect("microsandbox: failed to build tokio runtime")
-    })
+    let cur = std::process::id();
+    let ptr = RUNTIME_PTR.load(Ordering::Acquire);
+    if !ptr.is_null() && RUNTIME_PID.load(Ordering::Acquire) == cur {
+        // SAFETY: ptr was produced by Box::leak (valid for 'static) and matches
+        // this process's pid, so its runtime threads are live in this process.
+        return unsafe { &*ptr };
+    }
+
+    let _guard = RUNTIME_LOCK
+        .lock()
+        .expect("microsandbox: runtime lock poisoned");
+    // Re-check under the lock (another thread may have just built it).
+    let ptr = RUNTIME_PTR.load(Ordering::Acquire);
+    if !ptr.is_null() && RUNTIME_PID.load(Ordering::Acquire) == cur {
+        return unsafe { &*ptr };
+    }
+
+    // Build a fresh runtime for this process and publish it. The previous pointer
+    // (if any) belonged to a parent process and is intentionally leaked, not
+    // dropped (its threads are gone post-fork; Drop would block on join).
+    let rt: &'static Runtime = Box::leak(Box::new(build_runtime()));
+    RUNTIME_PTR.store(rt as *const Runtime as *mut Runtime, Ordering::Release);
+    RUNTIME_PID.store(cur, Ordering::Release);
+    rt
 }
 
 /// Run `f` with the Ruby GVL released.

data/lib/microsandbox/version.rb

@@ -1,9 +1,19 @@
 # frozen_string_literal: true
 
 module Microsandbox
-  # Gem version. Tracks the upstream microsandbox runtime (currently `v0.5.8`,
-  # the pinned core-crate tag); the patch segment advances for gem-only revisions
-  # that add bindings atop the same core. Must equal the native ext's Cargo crate
-  # version (`Native.version`), enforced by spec/unit/version_spec.rb.
-  VERSION = "0.5.11"
+  # Gem version. Versioned independently of the upstream microsandbox runtime it
+  # embeds: the gem follows its own semver (while 0.x, breaking changes bump the
+  # minor and fixes bump the patch), so the number does NOT track the upstream tag
+  # one-to-one. Consult {RUNTIME_VERSION} for the wrapped runtime, and the
+  # Versioning section of the README for the full gem-to-runtime map. Must equal
+  # the native ext's Cargo crate version (`Native.version`), enforced by
+  # spec/unit/version_spec.rb.
+  VERSION = "0.6.0"
+
+  # The upstream microsandbox runtime release this gem build embeds — the `tag`
+  # pinned on the `microsandbox`/`microsandbox-network` git deps in
+  # ext/microsandbox/Cargo.toml. Exposed at runtime as
+  # {Microsandbox.runtime_version}. spec/unit/version_spec.rb asserts it stays in
+  # sync with the Cargo tag so it can't silently drift out of date.
+  RUNTIME_VERSION = "v0.5.8"
 end

data/lib/microsandbox.rb

@@ -45,6 +45,15 @@ module Microsandbox
       VERSION
     end
 
+    # The upstream microsandbox runtime release this gem build embeds (the git
+    # `tag` pinned in ext/microsandbox/Cargo.toml). The gem's own {version} is
+    # versioned independently of this, so consult this to learn which runtime is
+    # wrapped. See the Versioning section of the README for the full map.
+    # @return [String] e.g. "v0.5.8"
+    def runtime_version
+      RUNTIME_VERSION
+    end
+
     # Download and install the `msb` runtime + `libkrunfw` into
     # `~/.microsandbox` (idempotent).
     #

data/sig/microsandbox.rbs

@@ -2,8 +2,10 @@
 
 module Microsandbox
   VERSION: String
+  RUNTIME_VERSION: String
 
   def self.version: () -> String
+  def self.runtime_version: () -> String
   def self.install: () -> nil
   def self.installed?: () -> bool
   def self.ensure_runtime!: () -> nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: microsandbox-rb
 version: !ruby/object:Gem::Version
-  version: 0.5.11
+  version: 0.6.0
 platform: ruby
 authors:
 - ya-luotao