microsandbox-rb 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72468dc2fa865510c82ecc783988925460acbd7f7d92025f367964277b98e756
-  data.tar.gz: f4bca46d64a694a76a59b712b8d827e6ddff12ba4cb9708a33951f4969c8fce2
+  metadata.gz: 5347e3ff3b98575cd98ee948fce387efc1bde98da5069fb808ed62e8d065a066
+  data.tar.gz: 4c143ec287857130709632f19d124c56488fd22837215a85e61e7c52da609884
 SHA512:
-  metadata.gz: 31cace38acfb4b535aaeb5f9026acb4c63d5f1376637628c2947e1d5ff9c1492d388cde85f3ba38bd8d462bb0598d12f046467331a6507d6af2cd2720bb57137
-  data.tar.gz: 97e665bd96d8d7ae0719c34d5a7d7f7823966a70f793d251d034a519ad04da70a8925c0e17c01c854ab074de904aa9a1baa88b148f099afba33c751836f97a60
+  metadata.gz: f4d810f63d588b685b0393e93d637fa28554bdbfbf34a09b0b5d0ca45a4962acd9ac9991e0e6bd8157e5ef31b9cf4321d6dd20a703ad7d251099b1d4a951f346
+  data.tar.gz: f89447fa04f1bd6112199a7286101c26e1c2bed28d66d08816d171298f357ee412474207b60782b8592838f5191914657adafa3b89745dec9600552cb0507e1b

data/CHANGELOG.md

@@ -6,6 +6,156 @@ All notable changes to this gem are documented here. The format is based on
 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.
 
+## [0.14.0] - 2026-08-24
+
+Runtime tag unchanged — still upstream **`v0.6.9`**.
+
+### Added
+
+- **Companion gem `microsandbox-rb-binaries`** (source in `binaries/`): the
+  prebuilt `msb` microVM runtime and the `libkrunfw` firmware, shipped as one
+  gem per platform (`arm64-darwin`, `x86_64-linux-gnu`, `aarch64-linux-gnu`;
+  the Linux binaries are glibc-linked, hence `required_rubygems_version >=
+  3.3.11`). Install it alongside `microsandbox-rb` at the same version and your
+  bundle carries the runtime instead of downloading it into `~/.microsandbox`
+  on first use. There is no dependency edge in either direction — RubyGems has
+  no optional dependencies, and cloud-only users should not be made to fetch
+  ~50 MB of binaries. Motivated by upstream
+  [superradcompany/microsandbox#1305](https://github.com/superradcompany/microsandbox/issues/1305).
+- **A new tier in the runtime resolver.** `require "microsandbox"` activates the
+  companion gem (if installed at the same version and built for the same
+  upstream runtime) and hands
+  its `msb` to the core's set-once SDK slot; the firmware is found by the
+  runtime's `../lib` adjacency, exactly as in the Python/Node SDKs. The
+  effective order is now `MSB_PATH` → `microsandbox-rb-binaries` → config file →
+  `~/.microsandbox/bin/msb` → `msb` on `PATH`, and
+  `Microsandbox.runtime_path` reports the winner. Activation never raises: a
+  missing gem is silent, and a gem built for a *different* runtime is reported
+  with a warning and skipped rather than handed to the core.
+- **Lock-step guard for the new gem.** `Microsandbox::Binaries::VERSION` must
+  equal `Microsandbox::VERSION` and `Microsandbox::Binaries::RUNTIME_VERSION`
+  must equal `Microsandbox::RUNTIME_VERSION`; `spec/unit/version_spec.rb`
+  asserts both, so a stale companion can't ship.
+- **Vendoring/build pipeline** for the companion gem:
+  `rake -C binaries vendor[<platform>]` downloads the upstream release bundle and
+  verifies every file against that release's `checksums.sha256` as committed
+  in `binaries/checksums/<tag>.sha256` (fail-closed — a missing entry, a digest
+  mismatch, an unexpected file, or a live release file that disagrees with the
+  committed one aborts), `rake -C binaries build[<platform>]` re-verifies the staged tree
+  against its manifest before packaging, `rake -C binaries verify` runs the
+  vendored `msb` on the host, and `vendor:all` covers every platform from any
+  host. CI builds all three platform gems on every run, and `release.yml`
+  builds and publishes them on each version tag in a separate
+  `publish-binaries` job that runs after the SDK gem is live (a companion-gem
+  failure is its own red job and never blocks the SDK release; re-runs are
+  idempotent). The companion gem has its own RubyGems trusted-publisher entry.
+
+### Changed
+
+- **The SDK gem is now SDK-only: nothing is provisioned at build or install
+  time.** The core crate's default `prebuilt` feature — whose `build.rs`
+  downloaded the *host* runtime into `~/.microsandbox` while compiling the
+  extension — is off (`default-features = false`, features `keyring`, `net`,
+  `ssh`, matching the official SDKs). The *guest* agent `agentd` is still
+  embedded into the extension at build time, via a direct
+  `microsandbox-runtime` dependency with just the `prebuilt` sub-feature that
+  fetches it. Host runtime provisioning is now the companion gem's job, with the
+  first-use download as fallback.
+- **`Microsandbox.runtime_path=` is a no-op when the companion gem is active** —
+  it targets the same set-once slot the gem already claimed at load time. Use
+  the `MSB_PATH` environment variable to override a bundled runtime.
+- **`Microsandbox.ensure_runtime!` skips the installer entirely** when the
+  resolved runtime is the companion gem's `msb`: those binaries are already the
+  matching version, so nothing is downloaded or touched in `~/.microsandbox`.
+  Without the gem, behaviour is unchanged — the version-correcting first-use
+  download into `~/.microsandbox` remains the lowest tier, still opt-out-able
+  with `MICROSANDBOX_NO_AUTO_INSTALL`.
+- `Gemfile` now uses `gemspec glob: "{,*}.gemspec"` so Bundler resolves only the
+  root gemspec; its default glob would also evaluate the nested
+  `binaries/microsandbox-rb-binaries.gemspec` in every `bundle exec` process.
+
+## [0.13.0] - 2026-08-18
+
+Adopts upstream runtime **`v0.6.8` → `v0.6.9`**.
+
+### Breaking
+
+- **A bare `MSB_API_KEY` no longer selects the cloud backend** (upstream
+  backend-selection hardening: "a bare API key is credential material, not
+  backend intent"). Cloud intent must now be explicit: set `MSB_BACKEND=cloud`
+  (with a non-empty `MSB_API_KEY`), select a cloud profile, or call
+  `Microsandbox.set_default_backend(:cloud, ...)`. Code that relied on
+  exporting only `MSB_API_KEY` now silently runs on the **local** backend —
+  audit deployment environments when upgrading.
+- **Invalid cloud configuration fails closed** instead of silently falling
+  back to local execution: `MSB_BACKEND=cloud` without a usable API key or
+  cloud profile raises {Microsandbox::InvalidConfigError} at first use rather
+  than dispatching sandboxes locally.
+- **Snapshot payload integrity is opt-in** (upstream #1346). New snapshots no
+  longer record a content digest unless created with
+  `record_integrity: true` (previously documented as a no-op because schema-1
+  always recorded integrity — that default reversed upstream, as hashing
+  large allocated uppers is expensive). {Microsandbox::Snapshot.verify} on a
+  snapshot without recorded integrity now reports
+  `SnapshotVerifyReport#status == :not_recorded` (with `#algorithm` /
+  `#content_digest` nil, `#verified?` false) instead of always `:verified`.
+
+### Added
+
+`v0.6.9` SDK parity (matching the official Python binding surface):
+
+- **Default-workload execution** — `Sandbox.create` is strictly boot-only, so
+  the image's resolved OCI `ENTRYPOINT`+`CMD` now runs via
+  {Microsandbox::Sandbox#exec_default} (buffered),
+  {Microsandbox::Sandbox#exec_default_stream} (streaming), and
+  {Microsandbox::Sandbox#attach_default} (interactive). New
+  {Microsandbox::NoDefaultCommandError} when the image resolves no executable
+  command. New `cmd:` create keyword overrides the durable image CMD (an
+  explicit `[]` clears it) without executing anything at create time.
+- **Flat OCI root disks** — `RootDisk.flat(size_mib, fstype:, clone:)` boots
+  from a single complete ext4 root disk materialized from the OCI image
+  (skips the overlay stack; content-addressed and cached; `clone:` picks
+  `:auto`/`:copy`/`:reflink` private-disk cloning).
+- **Root-disk resizing** — `modify(root_disk_size:)` grows the managed upper
+  or flat root disk (MiB).
+- **Per-sandbox network rate limits** — `rate_limiter:` create keyword with
+  per-direction (`egress:`/`ingress:`) `bandwidth:`/`ops:` token buckets
+  (`size:`, `refill_time_ms:`, `one_time_burst:`).
+- **Host vsock routes** — `vsock:` create keyword exposes host Unix sockets
+  on guest-to-host vsock ports: `{ "/host/api.sock" => 5000 }` or an Array of
+  `{host_socket:, port:, socket_type: :stream|:dgram}`.
+- **Active backend context** — {Microsandbox.default_backend_info} returns a
+  secret-safe {Microsandbox::BackendInfo} (`kind`, `api_url`, `source`,
+  `profile`; never the API key).
+- **Default volume** — {Microsandbox::Volume.get_default} (cloud backend;
+  local raises {Microsandbox::UnsupportedError}) and
+  `VolumeInfo#default?`. The full `VolumeInfo#fs` surface works against cloud
+  default and managed directory volumes as of `v0.6.9`.
+
+Not exposed, matching the official Python binding at `v0.6.9`:
+`DeploymentProfile`/CPU-placement/THP create options (upstream wires them via
+`config.json`/CLI only so far) and the Rust-only sparse
+`SandboxConfigPatch`/`builder.configure` surface.
+
+### Fixed
+
+- `entrypoint: []` now clears the image's `ENTRYPOINT` (blocking the
+  image-config merge), matching the upstream builder contract and the Python
+  binding. Previously the empty array was silently dropped in the native
+  layer, so the image ENTRYPOINT survived — observable under the new
+  `exec_default`/`attach_default`, which would have run the wrong command.
+  `nil` (the default) still inherits the image value.
+
+### Runtime
+
+- Upstream `v0.6.9` runtime changes carried without further Ruby surface
+  change: NUMA-aware placement profiles, degraded placement under pressure,
+  integrated host performance stack (topology-aware CPU placement, THP
+  policy, bounded block writeback), long-link-target preservation in saved
+  image archives, nested OCI image index loads, backpressured published-port
+  data preservation, DNS network-rule parsing in release builds, and
+  child-process reaping in `agentd`.
+
 ## [0.12.0] - 2026-07-30
 
 Adopts upstream runtime **`v0.6.7` → `v0.6.8`** and mirrors its breaking SDK
@@ -881,7 +1031,8 @@ 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.9.0...HEAD
+[Unreleased]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.13.0...v0.14.0
 [0.9.0]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.8.2...v0.9.0
 [0.8.2]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/ya-luotao/microsandbox-rb/compare/v0.8.0...v0.8.1