From 6f9da1b0235164b595b6bab6dc57ec762de09398 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Mon, 26 Oct 2026 10:23:34 -0700 Subject: [PATCH 01/31] Ship mstar_rust in the Linux wheels on PyPI The release now builds Linux wheels per CPython version (3.12, 3.13) and architecture (x86_64, aarch64) with cibuildwheel, and setup.py compiles rust/ into them, so pip install mstar-ai on Linux gets the extension and MSTAR_RUST_ZMQ/MSTAR_RUST_GRAPH=AUTO pick the Rust paths. The sdist and the pure-Python wheel are unchanged and remain the fallback elsewhere. Only cibuildwheel builds compile rust/: setuptools' editable finder cannot import a top-level extension built in place, and compiling it would slow every pip install -e . and move CPU Core onto the Rust runtime. Checkouts keep building it with maturin. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 33 +++++++++++++++++++++++++++++++++ README.md | 5 +++-- docs/installation.rst | 7 +++++-- pyproject.toml | 2 +- setup.py | 26 +++++++++++++++++++------- 5 files changed, 61 insertions(+), 12 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b7c9a21634..0b7d4f1032 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -12,13 +12,41 @@ name: Publish to PyPI # one release run at a time: publish with the engine's pending publisher, # add the next alias's pending publisher, re-run the failed job, repeat. # Uploads skip files that already exist, so re-runs are safe. +# +# mstar-ai ships an sdist, a pure-Python wheel, and Linux wheels per CPython +# version and architecture that also carry the mstar_rust extension (setup.py +# compiles rust/ only under cibuildwheel). pip prefers the Linux wheel where +# one matches and falls back to the pure one elsewhere, which then runs on the +# Python transport and graph runtime. on: release: types: [published] jobs: + wheels: + strategy: + matrix: + os: [ubuntu-latest, ubuntu-24.04-arm] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - uses: pypa/cibuildwheel@v4.2.1 + env: + # Version-specific rather than abi3, matching the extension that + # `maturin develop` builds and the tests exercise. + CIBW_BUILD: "cp312-manylinux_* cp313-manylinux_*" + CIBW_BEFORE_ALL_LINUX: curl -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal + CIBW_ENVIRONMENT_LINUX: PATH="$HOME/.cargo/bin:$PATH" + with: + output-dir: wheelhouse + - uses: actions/upload-artifact@v4 + with: + name: wheels-${{ matrix.os }} + path: wheelhouse/*.whl + pypi: + needs: wheels runs-on: ubuntu-latest environment: pypi permissions: @@ -39,6 +67,11 @@ jobs: - run: pip install build - name: Build mstar-ai run: python -m build + - uses: actions/download-artifact@v4 + with: + pattern: wheels-* + path: dist + merge-multiple: true - name: Build the alias packages run: | for alias in packaging/aliases/*/; do diff --git a/README.md b/README.md index 911cf78a11..96fa1a022b 100644 --- a/README.md +++ b/README.md @@ -166,8 +166,9 @@ The ZeroMQ control mesh can run over a Rust transport (vendored in [`rust/`](rus pyzmq — wire-compatible, selectable per process with `MSTAR_RUST_ZMQ` (default `AUTO`). Note what AUTO-by-default means: on any machine where the extension is built, the whole mesh switches to the Rust transport with no configuration change — each process logs its -choice at startup (`control mesh transport: ...`), and `MSTAR_RUST_ZMQ=0` pins pyzmq. Build it with -[maturin](https://www.maturin.rs): `uv pip install maturin && maturin develop --release -m rust/Cargo.toml`. +choice at startup (`control mesh transport: ...`), and `MSTAR_RUST_ZMQ=0` pins pyzmq. The Linux +wheels on PyPI (x86_64 and aarch64, CPython 3.12 and 3.13) ship the extension; in a source checkout, +build it with [maturin](https://www.maturin.rs): `uv pip install maturin && maturin develop --release -m rust/Cargo.toml`. See the [installation docs](https://m-star.org/mstar/installation.html) and [environment variables](https://m-star.org/mstar/environment_variables.html). diff --git a/docs/installation.rst b/docs/installation.rst index aa5fc248e4..196e4f175e 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -478,8 +478,11 @@ runs on the pure-Python paths as before. Migrated so far (see wherever that holds, so on a machine with the extension built, installing it is what moves a worker onto the Rust runtime. -Build the extension into your environment with `maturin -`_ (needs a Rust toolchain; ``rustup`` works): +The PyPI wheels for Linux (x86_64 and aarch64, CPython 3.12 and 3.13) already +carry the extension, so ``pip install mstar-ai`` there needs nothing more. Other +platforms get the pure-Python wheel. In a source checkout, build the extension into +your environment with `maturin `_ (needs a Rust toolchain; +``rustup`` works): .. code-block:: bash diff --git a/pyproject.toml b/pyproject.toml index e58ee1662d..5a182731da 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,5 @@ [build-system] -requires = ["setuptools>=78.1.1", "wheel"] +requires = ["setuptools>=78.1.1", "setuptools-rust>=1.11", "wheel"] build-backend = "setuptools.build_meta" [project] diff --git a/setup.py b/setup.py index 2293082ecc..6687610bd8 100644 --- a/setup.py +++ b/setup.py @@ -1,13 +1,14 @@ """Build shim: copy the repo-root configs/ into mstar/default_configs/ so the -default deployment YAMLs ship inside the wheel under the mstar namespace. +default deployment YAMLs ship inside the wheel under the mstar namespace, and +compile the ``mstar_rust`` extension into the published Linux wheels. -Project metadata lives in pyproject.toml; this file exists only to populate -the packaged configs at build time. configs/ stays the single source of truth -(unchanged for checkouts and in-flight model PRs); nothing is duplicated in -git. The sdist carries configs/ via MANIFEST.in so a wheel built from the -sdist also picks them up. +Project metadata lives in pyproject.toml; this file exists only for those two +build steps. configs/ stays the single source of truth (unchanged for checkouts +and in-flight model PRs); nothing is duplicated in git. The sdist carries +configs/ via MANIFEST.in so a wheel built from the sdist also picks them up. """ +import os import shutil from pathlib import Path @@ -34,4 +35,15 @@ def run(self): shutil.copy2(y, dst / y.name) -setup(cmdclass={"build_py": build_py_with_configs}) +# Only the release's cibuildwheel jobs compile rust/; every other build is the +# pure-Python package, and a checkout builds the extension with maturin +# (docs/installation.rst). setuptools' editable finder cannot import a +# top-level extension built in place, and compiling it would slow every +# `pip install -e .`. +rust_extensions = [] +if os.environ.get("CIBUILDWHEEL") == "1": + from setuptools_rust import Binding, RustExtension + + rust_extensions.append(RustExtension("mstar_rust", path="rust/Cargo.toml", binding=Binding.PyO3)) + +setup(cmdclass={"build_py": build_py_with_configs}, rust_extensions=rust_extensions) From 4bbc490759d2c04a566c62866409f27cb2196207 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 00:18:17 -0700 Subject: [PATCH 02/31] release: build the Linux wheels for CPython 3.14 too pyo3 0.23 stops at 3.13; 0.26 is the first release tested against 3.14's release candidates without 0.27's FromPyObject signature change. Its only breakage here is the allow_threads -> detach rename. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 2 +- README.md | 2 +- docs/installation.rst | 2 +- rust/Cargo.lock | 32 ++++++++++++++++++-------------- rust/Cargo.toml | 2 +- rust/server/Cargo.lock | 32 ++++++++++++++++++-------------- rust/src/graph/runtime.rs | 2 +- rust/src/lib.rs | 16 ++++++++-------- rust/src/tensors.rs | 2 +- 9 files changed, 50 insertions(+), 42 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0b7d4f1032..e7beebc355 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -35,7 +35,7 @@ jobs: env: # Version-specific rather than abi3, matching the extension that # `maturin develop` builds and the tests exercise. - CIBW_BUILD: "cp312-manylinux_* cp313-manylinux_*" + CIBW_BUILD: "cp312-manylinux_* cp313-manylinux_* cp314-manylinux_*" CIBW_BEFORE_ALL_LINUX: curl -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal CIBW_ENVIRONMENT_LINUX: PATH="$HOME/.cargo/bin:$PATH" with: diff --git a/README.md b/README.md index 96fa1a022b..3ef5749e0e 100644 --- a/README.md +++ b/README.md @@ -167,7 +167,7 @@ pyzmq — wire-compatible, selectable per process with `MSTAR_RUST_ZMQ` (default Note what AUTO-by-default means: on any machine where the extension is built, the whole mesh switches to the Rust transport with no configuration change — each process logs its choice at startup (`control mesh transport: ...`), and `MSTAR_RUST_ZMQ=0` pins pyzmq. The Linux -wheels on PyPI (x86_64 and aarch64, CPython 3.12 and 3.13) ship the extension; in a source checkout, +wheels on PyPI (x86_64 and aarch64, CPython 3.12 to 3.14) ship the extension; in a source checkout, build it with [maturin](https://www.maturin.rs): `uv pip install maturin && maturin develop --release -m rust/Cargo.toml`. See the [installation docs](https://m-star.org/mstar/installation.html) and [environment variables](https://m-star.org/mstar/environment_variables.html). diff --git a/docs/installation.rst b/docs/installation.rst index 196e4f175e..44bdc87f2b 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -478,7 +478,7 @@ runs on the pure-Python paths as before. Migrated so far (see wherever that holds, so on a machine with the extension built, installing it is what moves a worker onto the Rust runtime. -The PyPI wheels for Linux (x86_64 and aarch64, CPython 3.12 and 3.13) already +The PyPI wheels for Linux (x86_64 and aarch64, CPython 3.12 to 3.14) already carry the extension, so ``pip install mstar-ai`` there needs nothing more. Other platforms get the pure-Python wheel. In a source checkout, build the extension into your environment with `maturin `_ (needs a Rust toolchain; diff --git a/rust/Cargo.lock b/rust/Cargo.lock index 0cac1219d5..c304e26785 100644 --- a/rust/Cargo.lock +++ b/rust/Cargo.lock @@ -33,7 +33,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d067ad48b8650848b989a59a86c6c36a995d02d2bf778d45c3c5d57bc2718f02" dependencies = [ "smallvec", - "target-lexicon", + "target-lexicon 0.12.16", ] [[package]] @@ -279,11 +279,10 @@ dependencies = [ [[package]] name = "pyo3" -version = "0.23.5" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7778bffd85cf38175ac1f545509665d0b9b92a198ca7941f131f85f7a4f9a872" +checksum = "7ba0117f4212101ee6544044dae45abe1083d30ce7b29c4b5cbdfa2354e07383" dependencies = [ - "cfg-if", "indoc", "libc", "memoffset", @@ -297,19 +296,18 @@ dependencies = [ [[package]] name = "pyo3-build-config" -version = "0.23.5" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "94f6cbe86ef3bf18998d9df6e0f3fc1050a8c5efa409bf712e661a4366e010fb" +checksum = "4fc6ddaf24947d12a9aa31ac65431fb1b851b8f4365426e182901eabfb87df5f" dependencies = [ - "once_cell", - "target-lexicon", + "target-lexicon 0.13.5", ] [[package]] name = "pyo3-ffi" -version = "0.23.5" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e9f1b4c431c0bb1c8fb0a338709859eed0d030ff6daa34368d3b152a63dfdd8d" +checksum = "025474d3928738efb38ac36d4744a74a400c901c7596199e20e45d98eb194105" dependencies = [ "libc", "pyo3-build-config", @@ -317,9 +315,9 @@ dependencies = [ [[package]] name = "pyo3-macros" -version = "0.23.5" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fbc2201328f63c4710f68abdf653c89d8dbc2858b88c5d88b0ff38a75288a9da" +checksum = "2e64eb489f22fe1c95911b77c44cc41e7c19f3082fc81cce90f657cdc42ffded" dependencies = [ "proc-macro2", "pyo3-macros-backend", @@ -329,9 +327,9 @@ dependencies = [ [[package]] name = "pyo3-macros-backend" -version = "0.23.5" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fca6726ad0f3da9c9de093d6f116a93c1a38e417ed73bf138472cf4064f72028" +checksum = "100246c0ecf400b475341b8455a9213344569af29a3c841d29270e53102e0fcf" dependencies = [ "heck", "proc-macro2", @@ -505,6 +503,12 @@ version = "0.12.16" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1" +[[package]] +name = "target-lexicon" +version = "0.13.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca" + [[package]] name = "thiserror" version = "2.0.18" diff --git a/rust/Cargo.toml b/rust/Cargo.toml index 4b8471efc5..8aa7c56772 100644 --- a/rust/Cargo.toml +++ b/rust/Cargo.toml @@ -21,7 +21,7 @@ rmp-serde = "1.3" rustc-hash = "2" thiserror = "2" zmq = "0.10" -pyo3 = { version = "0.23" } +pyo3 = { version = "0.26" } rmpv = "1.3.1" # Direct msgpack writing. rmpv builds a Value tree first, which allocates a # String for every map KEY -- ~13 per tensor descriptor -- and then copies the diff --git a/rust/server/Cargo.lock b/rust/server/Cargo.lock index 85fefaf292..071a2e3ef9 100644 --- a/rust/server/Cargo.lock +++ b/rust/server/Cargo.lock @@ -145,7 +145,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d067ad48b8650848b989a59a86c6c36a995d02d2bf778d45c3c5d57bc2718f02" dependencies = [ "smallvec", - "target-lexicon", + "target-lexicon 0.12.16", ] [[package]] @@ -1017,11 +1017,10 @@ dependencies = [ [[package]] name = "pyo3" -version = "0.23.5" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7778bffd85cf38175ac1f545509665d0b9b92a198ca7941f131f85f7a4f9a872" +checksum = "7ba0117f4212101ee6544044dae45abe1083d30ce7b29c4b5cbdfa2354e07383" dependencies = [ - "cfg-if", "indoc", "libc", "memoffset", @@ -1035,19 +1034,18 @@ dependencies = [ [[package]] name = "pyo3-build-config" -version = "0.23.5" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "94f6cbe86ef3bf18998d9df6e0f3fc1050a8c5efa409bf712e661a4366e010fb" +checksum = "4fc6ddaf24947d12a9aa31ac65431fb1b851b8f4365426e182901eabfb87df5f" dependencies = [ - "once_cell", - "target-lexicon", + "target-lexicon 0.13.5", ] [[package]] name = "pyo3-ffi" -version = "0.23.5" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e9f1b4c431c0bb1c8fb0a338709859eed0d030ff6daa34368d3b152a63dfdd8d" +checksum = "025474d3928738efb38ac36d4744a74a400c901c7596199e20e45d98eb194105" dependencies = [ "libc", "pyo3-build-config", @@ -1055,9 +1053,9 @@ dependencies = [ [[package]] name = "pyo3-macros" -version = "0.23.5" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fbc2201328f63c4710f68abdf653c89d8dbc2858b88c5d88b0ff38a75288a9da" +checksum = "2e64eb489f22fe1c95911b77c44cc41e7c19f3082fc81cce90f657cdc42ffded" dependencies = [ "proc-macro2", "pyo3-macros-backend", @@ -1067,9 +1065,9 @@ dependencies = [ [[package]] name = "pyo3-macros-backend" -version = "0.23.5" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fca6726ad0f3da9c9de093d6f116a93c1a38e417ed73bf138472cf4064f72028" +checksum = "100246c0ecf400b475341b8455a9213344569af29a3c841d29270e53102e0fcf" dependencies = [ "heck", "proc-macro2", @@ -1493,6 +1491,12 @@ version = "0.12.16" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1" +[[package]] +name = "target-lexicon" +version = "0.13.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca" + [[package]] name = "thiserror" version = "1.0.69" diff --git a/rust/src/graph/runtime.rs b/rust/src/graph/runtime.rs index 8dc5193385..7b36904971 100644 --- a/rust/src/graph/runtime.rs +++ b/rust/src/graph/runtime.rs @@ -307,7 +307,7 @@ pub struct GraphRuntime { return Ok(()); } let comm = comm.clone(); - py.allow_threads(move || -> Result<(), crate::communicator::CommError> { + py.detach(move || -> Result<(), crate::communicator::CommError> { for (peer, bytes) in &rest { comm.send(peer, bytes)?; } diff --git a/rust/src/lib.rs b/rust/src/lib.rs index 781cf5108e..fa34d53775 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -86,7 +86,7 @@ impl PyZmqCommunicator { /// high-water mark, and blocking with the GIL held would freeze every /// Python thread in the process (pyzmq releases it here too). fn send(&self, py: Python<'_>, peer_id: &str, data: &[u8]) -> PyResult<()> { - py.allow_threads(|| self.inner.send(peer_id, data)) + py.detach(|| self.inner.send(peer_id, data)) .map_err(|e| PyRuntimeError::new_err(e.to_string())) } @@ -97,12 +97,12 @@ impl PyZmqCommunicator { /// Drain all currently-queued frames in one call — one GIL round-trip /// per batch instead of one `try_recv` per message. fn drain<'py>(&self, py: Python<'py>) -> Vec> { - let frames = py.allow_threads(|| self.inner.drain()); + let frames = py.detach(|| self.inner.drain()); frames.iter().map(|b| PyBytes::new(py, b)).collect() } fn recv_timeout<'py>(&self, py: Python<'py>, timeout_ms: u64) -> Option> { - py.allow_threads(|| self.inner.recv_timeout(Duration::from_millis(timeout_ms))) + py.detach(|| self.inner.recv_timeout(Duration::from_millis(timeout_ms))) .map(|b| PyBytes::new(py, &b)) } @@ -114,7 +114,7 @@ impl PyZmqCommunicator { py: Python<'py>, timeout_ms: u64, ) -> PyResult<(&'static str, Option>)> { - let ev = py.allow_threads(|| self.inner.recv_or_wake(Duration::from_millis(timeout_ms))); + let ev = py.detach(|| self.inner.recv_or_wake(Duration::from_millis(timeout_ms))); Ok(match ev { RecvEvent::Message(b) => ("msg", Some(PyBytes::new(py, &b))), RecvEvent::Wake => ("wake", None), @@ -277,7 +277,7 @@ impl PySegmentedShmArena { /// which must not stall other Python threads (the serve loop, stream /// relays). fn reserve(&self, py: Python<'_>, nbytes: usize) -> PyResult<(usize, usize)> { - py.allow_threads(|| self.arena.reserve(nbytes)) + py.detach(|| self.arena.reserve(nbytes)) .map_err(|e| PyRuntimeError::new_err(e.to_string())) } @@ -285,12 +285,12 @@ impl PySegmentedShmArena { /// across an mmap for milliseconds; blocking on that mutex with the /// GIL held would freeze every Python thread for the duration. fn free(&self, py: Python<'_>, segment: usize, offset: usize) -> bool { - py.allow_threads(|| self.arena.free(segment, offset)) + py.detach(|| self.arena.free(segment, offset)) } #[getter] fn num_segments(&self, py: Python<'_>) -> usize { - py.allow_threads(|| self.arena.num_segments()) + py.detach(|| self.arena.num_segments()) } /// `(total_bytes, free_bytes, largest_free_block)` across all segments. @@ -298,7 +298,7 @@ impl PySegmentedShmArena { /// fragmentation signature (allocations fail / segments grow despite /// healthy total free space). fn stats(&self, py: Python<'_>) -> (usize, usize, usize) { - py.allow_threads(|| self.arena.stats()) + py.detach(|| self.arena.stats()) } fn segment_name(&self, i: usize) -> String { diff --git a/rust/src/tensors.rs b/rust/src/tensors.rs index 4e370fa920..8c8c33808c 100644 --- a/rust/src/tensors.rs +++ b/rust/src/tensors.rs @@ -1,7 +1,7 @@ //! Port of `TensorBookkeeping`: per-uuid reference state and descriptors. //! //! Never sees a tensor. `TensorStore` stays Python because freeing a record -//! inside a `py.allow_threads` section would drop a `Py` without the +//! inside a `py.detach` section would drop a `Py` without the //! GIL; everything here is integers and interned strings, so it can be held //! across one. //! From c920649df787d5e15c4a18bdd410782a27e05eb2 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 00:18:46 -0700 Subject: [PATCH 03/31] rust: pin the compiler to 1.99.1 in rust-toolchain.toml CI took whatever stable was that day and the release wheels whatever rustup installed. One file now sets the version for CI, the wheels and local builds; 1.99.1 is what CI resolved stable to on main today. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 3 ++- .github/workflows/release.yml | 4 +++- docs/installation.rst | 5 +++-- rust-toolchain.toml | 5 +++++ 4 files changed, 13 insertions(+), 4 deletions(-) create mode 100644 rust-toolchain.toml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bd060423f3..55ebce56ee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -139,7 +139,8 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable + - name: Install the pinned Rust toolchain (rust-toolchain.toml) + run: rustup toolchain install - uses: Swatinem/rust-cache@v2 with: workspaces: | diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e7beebc355..6f8b8d4910 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -36,7 +36,9 @@ jobs: # Version-specific rather than abi3, matching the extension that # `maturin develop` builds and the tests exercise. CIBW_BUILD: "cp312-manylinux_* cp313-manylinux_* cp314-manylinux_*" - CIBW_BEFORE_ALL_LINUX: curl -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal + CIBW_BEFORE_ALL_LINUX: >- + curl -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain none && + cd {project} && $HOME/.cargo/bin/rustup toolchain install CIBW_ENVIRONMENT_LINUX: PATH="$HOME/.cargo/bin:$PATH" with: output-dir: wheelhouse diff --git a/docs/installation.rst b/docs/installation.rst index 44bdc87f2b..b728d50c98 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -481,8 +481,9 @@ runs on the pure-Python paths as before. Migrated so far (see The PyPI wheels for Linux (x86_64 and aarch64, CPython 3.12 to 3.14) already carry the extension, so ``pip install mstar-ai`` there needs nothing more. Other platforms get the pure-Python wheel. In a source checkout, build the extension into -your environment with `maturin `_ (needs a Rust toolchain; -``rustup`` works): +your environment with `maturin `_ (needs `rustup +`_, which installs the compiler version pinned in +``rust-toolchain.toml``): .. code-block:: bash diff --git a/rust-toolchain.toml b/rust-toolchain.toml new file mode 100644 index 0000000000..067ebd4408 --- /dev/null +++ b/rust-toolchain.toml @@ -0,0 +1,5 @@ +# The Rust compiler for rust/ and rust/server: CI, the release wheels and +# local builds all resolve it from here. +[toolchain] +channel = "1.99.1" +profile = "minimal" From ca89297467def07c2c3173f3d32a84b6c9407004 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 00:20:23 -0700 Subject: [PATCH 04/31] release: ship the mstar-server frontend binary in the Linux wheels setuptools-rust's RustBin installs it into the environment's scripts directory, which find_server_binary now checks after $PATH, so --rust-frontend finds it without an activated venv. mstar-server --help prints usage instead of starting a mock server on port 8000. Co-Authored-By: Claude Opus 5.5 --- README.md | 3 ++- docs/environment_variables.rst | 3 ++- docs/installation.rst | 8 +++++--- mstar/api_server/entrypoint.py | 3 ++- mstar/api_server/rust_frontend.py | 12 ++++++++---- mstar/cli/main.py | 3 ++- rust/server/src/main.rs | 10 +++++++--- setup.py | 16 +++++++++++----- 8 files changed, 39 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 3ef5749e0e..3d984e5b12 100644 --- a/README.md +++ b/README.md @@ -167,7 +167,8 @@ pyzmq — wire-compatible, selectable per process with `MSTAR_RUST_ZMQ` (default Note what AUTO-by-default means: on any machine where the extension is built, the whole mesh switches to the Rust transport with no configuration change — each process logs its choice at startup (`control mesh transport: ...`), and `MSTAR_RUST_ZMQ=0` pins pyzmq. The Linux -wheels on PyPI (x86_64 and aarch64, CPython 3.12 to 3.14) ship the extension; in a source checkout, +wheels on PyPI (x86_64 and aarch64, CPython 3.12 to 3.14) ship the extension and the +`mstar-server` HTTP frontend; in a source checkout, build it with [maturin](https://www.maturin.rs): `uv pip install maturin && maturin develop --release -m rust/Cargo.toml`. See the [installation docs](https://m-star.org/mstar/installation.html) and [environment variables](https://m-star.org/mstar/environment_variables.html). diff --git a/docs/environment_variables.rst b/docs/environment_variables.rst index a31a0d489c..bb3be8403c 100644 --- a/docs/environment_variables.rst +++ b/docs/environment_variables.rst @@ -303,7 +303,8 @@ Read by the ``mstar-server`` binary and its bridge * - ``MSTAR_SERVER_BIN`` - unset - Path to the ``mstar-server`` binary. Fallback order: - ``--rust-frontend-bin``, this variable, ``$PATH``, then the in-repo + ``--rust-frontend-bin``, this variable, ``$PATH``, the environment's + scripts directory (where the Linux wheels install it), then the in-repo ``rust/server/target/release`` build. * - ``MSTAR_API_KEY`` - unset diff --git a/docs/installation.rst b/docs/installation.rst index b728d50c98..b0c748c15e 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -519,16 +519,18 @@ Optional: the Rust HTTP frontend ``mstar-server`` (``rust/server/``) serves the HTTP surface — routes, OpenAI translation, SSE streaming, uploads — from Rust, with the Python process -keeping preprocessing and the conductor protocol. Build and opt in: +keeping preprocessing and the conductor protocol. The Linux wheels on PyPI +install the binary next to ``mstar-serve``; in a source checkout, build it. +Then opt in: .. code-block:: bash - cargo build --release --manifest-path rust/server/Cargo.toml + cargo build --release --manifest-path rust/server/Cargo.toml # checkout only mstar serve qwen3_omni --rust-frontend # or, with an explicit config: mstar-serve --config --rust-frontend The binary is resolved via ``--rust-frontend-bin`` / ``MSTAR_SERVER_BIN`` / -``$PATH`` / the in-repo build. Its knobs are listed in +``$PATH`` / the environment's scripts directory / the in-repo build. Its knobs are listed in :doc:`environment_variables`. The OpenAI routes take the model's adapter from the same registry as the Python diff --git a/mstar/api_server/entrypoint.py b/mstar/api_server/entrypoint.py index e3079dfdb3..7cbdfeed4d 100644 --- a/mstar/api_server/entrypoint.py +++ b/mstar/api_server/entrypoint.py @@ -2051,7 +2051,8 @@ def main(argv: list[str] | None = None): parser.add_argument( "--rust-frontend-bin", type=str, default=None, help="Path to the mstar-server binary (default: MSTAR_SERVER_BIN, " - "$PATH, then rust/server/target/release)", + "$PATH, the environment's scripts dir, then " + "rust/server/target/release)", ) args = parser.parse_args(argv) if args.enable_metrics and MISSING_DEPENDENCY is not None: diff --git a/mstar/api_server/rust_frontend.py b/mstar/api_server/rust_frontend.py index 75914644ad..f5c950dcbf 100644 --- a/mstar/api_server/rust_frontend.py +++ b/mstar/api_server/rust_frontend.py @@ -51,6 +51,7 @@ import os import shutil import subprocess +import sysconfig from pathlib import Path from mstar.api_server.auth import API_KEY_ENV @@ -86,20 +87,23 @@ def openai_adapter_class(model_name: str) -> str: def find_server_binary(explicit: str | None = None) -> str: """Resolve the ``mstar-server`` binary: explicit arg, ``MSTAR_SERVER_BIN``, - ``$PATH``, then the in-repo release build.""" + ``$PATH``, the environment's scripts directory (where a Linux wheel + installs it, also when the venv is not activated), then the in-repo + release build.""" for candidate in ( explicit, os.getenv("MSTAR_SERVER_BIN"), shutil.which("mstar-server"), + str(Path(sysconfig.get_path("scripts")) / "mstar-server"), str(Path(__file__).resolve().parents[2] / "rust" / "server" / "target" / "release" / "mstar-server"), ): if candidate and Path(candidate).is_file(): return candidate raise FileNotFoundError( - "mstar-server binary not found: build it with " - "`cargo build --release` in rust/server/, put it on $PATH, or set " - "MSTAR_SERVER_BIN") + "mstar-server binary not found: the Linux wheels on PyPI ship it; " + "otherwise build it with `cargo build --release` in rust/server/, " + "put it on $PATH, or set MSTAR_SERVER_BIN") def launch_rust_server(binary: str, model_name: str, port: int, diff --git a/mstar/cli/main.py b/mstar/cli/main.py index 1346e39e15..52674f8b26 100644 --- a/mstar/cli/main.py +++ b/mstar/cli/main.py @@ -318,7 +318,8 @@ def build_parser() -> argparse.ArgumentParser: serve.add_argument( "--rust-frontend-bin", default=None, help="path to the mstar-server binary (default: MSTAR_SERVER_BIN, " - "$PATH, then rust/server/target/release)", + "$PATH, the environment's scripts dir, then " + "rust/server/target/release)", ) serve.set_defaults(func=_serve) return parser diff --git a/rust/server/src/main.rs b/rust/server/src/main.rs index dfe8baaca2..423a980717 100644 --- a/rust/server/src/main.rs +++ b/rust/server/src/main.rs @@ -66,9 +66,13 @@ use serving::{ #[tokio::main] async fn main() { - let model_name = std::env::args() - .nth(1) - .expect("usage: mstar-server [port] [conductor_socket_dir] [upload_dir]"); + const USAGE: &str = + "usage: mstar-server [port] [conductor_socket_dir] [upload_dir]"; + let model_name = std::env::args().nth(1).expect(USAGE); + if model_name == "-h" || model_name == "--help" { + println!("{USAGE}"); + return; + } let port: u16 = std::env::args() .nth(2) .and_then(|p| p.parse().ok()) diff --git a/setup.py b/setup.py index 6687610bd8..5841290e53 100644 --- a/setup.py +++ b/setup.py @@ -1,6 +1,7 @@ """Build shim: copy the repo-root configs/ into mstar/default_configs/ so the default deployment YAMLs ship inside the wheel under the mstar namespace, and -compile the ``mstar_rust`` extension into the published Linux wheels. +compile the ``mstar_rust`` extension and the ``mstar-server`` binary into the +published Linux wheels. Project metadata lives in pyproject.toml; this file exists only for those two build steps. configs/ stays the single source of truth (unchanged for checkouts @@ -35,15 +36,20 @@ def run(self): shutil.copy2(y, dst / y.name) -# Only the release's cibuildwheel jobs compile rust/; every other build is the -# pure-Python package, and a checkout builds the extension with maturin +# Only the release's cibuildwheel jobs compile rust/: the mstar_rust extension +# and the mstar-server binary (--rust-frontend), which installs into the +# environment's scripts directory. Every other build is the pure-Python +# package, and a checkout builds both with cargo/maturin # (docs/installation.rst). setuptools' editable finder cannot import a # top-level extension built in place, and compiling it would slow every # `pip install -e .`. rust_extensions = [] if os.environ.get("CIBUILDWHEEL") == "1": - from setuptools_rust import Binding, RustExtension + from setuptools_rust import Binding, RustBin, RustExtension - rust_extensions.append(RustExtension("mstar_rust", path="rust/Cargo.toml", binding=Binding.PyO3)) + rust_extensions += [ + RustExtension("mstar_rust", path="rust/Cargo.toml", binding=Binding.PyO3), + RustBin("mstar-server", path="rust/server/Cargo.toml"), + ] setup(cmdclass={"build_py": build_py_with_configs}, rust_extensions=rust_extensions) From 9616a635823d46a1ee63e15f6bb347ea894a539c Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 00:20:57 -0700 Subject: [PATCH 05/31] release: collect the Rust third-party licenses into the wheels cargo-about writes the notices for every crate, and the C/C++ that zeromq-src, onig_sys and esaxx-rs vendor, into LICENSES-THIRD-PARTY.txt, which setuptools ships in dist-info/licenses. A license not in rust/about.toml's accepted list fails the build. libzmq's LGPL-3.0 (with its static-linking exception) is not accepted yet and needs a decision. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 12 ++++++ .gitignore | 3 ++ rust/about.hbs | 13 +++++++ rust/about.toml | 71 +++++++++++++++++++++++++++++++++++ 4 files changed, 99 insertions(+) create mode 100644 rust/about.hbs create mode 100644 rust/about.toml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6f8b8d4910..d7c5aab6d2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -31,6 +31,18 @@ jobs: runs-on: ${{ matrix.os }} steps: - uses: actions/checkout@v4 + - name: Install the pinned Rust toolchain (rust-toolchain.toml) + run: rustup toolchain install + - uses: taiki-e/install-action@v2 + with: + tool: cargo-about@0.9.2 + # The licenses of the crates and vendored C/C++ compiled into the wheel, + # shipped in its dist-info/licenses (setuptools' default LICEN[CS]E* + # glob). Fails on any license rust/about.toml does not accept. + - name: Collect third-party licenses + run: >- + cargo about generate --locked -c rust/about.toml + -m rust/server/Cargo.toml rust/about.hbs -o LICENSES-THIRD-PARTY.txt - uses: pypa/cibuildwheel@v4.2.1 env: # Version-specific rather than abi3, matching the extension that diff --git a/.gitignore b/.gitignore index dde80cf985..f7f66a7845 100644 --- a/.gitignore +++ b/.gitignore @@ -36,3 +36,6 @@ CLAUDE.md # Optional local CI reports .ci-results/ + +# generated by the release workflow (rust/about.toml) +LICENSES-THIRD-PARTY.txt diff --git a/rust/about.hbs b/rust/about.hbs new file mode 100644 index 0000000000..06e295c41c --- /dev/null +++ b/rust/about.hbs @@ -0,0 +1,13 @@ +Third-party software compiled into the mstar_rust extension and the +mstar-server binary in this wheel. mstar itself is under LICENSE. +{{#each licenses}} + +================================================================================ +{{{name}}} +Used by: +{{#each used_by}} + - {{crate.name}} {{crate.version}} +{{/each}} +-------------------------------------------------------------------------------- +{{{text}}} +{{/each}} diff --git a/rust/about.toml b/rust/about.toml new file mode 100644 index 0000000000..62e23d3051 --- /dev/null +++ b/rust/about.toml @@ -0,0 +1,71 @@ +# cargo-about config for LICENSES-THIRD-PARTY.txt, the notices for the Rust +# crates (and the C/C++ they vendor) compiled into the Linux wheels. The release +# workflow runs it on rust/server, whose dependency tree contains rust/'s. +# A crate under any license not listed here fails the wheel build. +accepted = [ + "Apache-2.0", + "Apache-2.0 WITH LLVM-exception", + "BSD-2-Clause", + "BSD-3-Clause", + "BSL-1.0", + "CDLA-Permissive-2.0", + "ISC", + "MIT", + "Unicode-3.0", + "Unlicense", + "Zlib", +] +targets = ["x86_64-unknown-linux-gnu", "aarch64-unknown-linux-gnu"] +ignore-build-dependencies = false +ignore-dev-dependencies = true +# mstar-rust and mstar-server are this project, covered by LICENSE. +private = { ignore = true } +workarounds = ["ring"] + +# The crate fields below cover only the Rust wrappers; these add the vendored +# C/C++ sources that are compiled into the binaries. + +# libzmq 4.3.4: LGPL-3.0 plus a static-linking exception (appended to +# COPYING.LESSER), and the BSD-3-Clause SHA-1 it compiles. LGPL-3.0-or-later +# is left out of `accepted` on purpose, so the wheels do not ship until a +# maintainer signs off on distributing libzmq under that exception. +[zeromq-src.clarify] +license = "(MIT OR Apache-2.0) AND LGPL-3.0-or-later AND BSD-3-Clause" +[[zeromq-src.clarify.files]] +path = "LICENSE-MIT" +license = "MIT" +checksum = "23f18e03dc49df91622fe2a76176497404e46ced8a715d9d2b67a7446571cca3" +[[zeromq-src.clarify.files]] +path = "vendor/COPYING.LESSER" +license = "LGPL-3.0-or-later" +checksum = "83f32abe61ee58ffb1b007412c08415168c052501dbf56d7a47aaaac52b03ef6" +[[zeromq-src.clarify.files]] +path = "vendor/external/sha1/sha1.c" +license = "BSD-3-Clause" +checksum = "dfe129c5f0d705988c2d07cde42ce44772182e342773c76a0c386beaeeb0097e" +end = "SUCH DAMAGE." + +# Oniguruma (BSD-2-Clause), the regex engine the tokenizers crate binds. +[onig_sys.clarify] +license = "MIT AND BSD-2-Clause" +[[onig_sys.clarify.files]] +path = "LICENSE.md" +license = "MIT" +checksum = "71f321038b088358004bee991635ac09e4c703bec467d3c30c06992c0595f189" +[[onig_sys.clarify.files]] +path = "oniguruma/COPYING" +license = "BSD-2-Clause" +checksum = "70ba5469ea0bab6e18a32d7009068f996503168d27be57747e08da34337ff26f" + +# esaxx (MIT), the C++ suffix-array code esaxx-rs compiles. +[esaxx-rs.clarify] +license = "Apache-2.0 AND MIT" +[[esaxx-rs.clarify.files]] +path = "LICENSE" +license = "Apache-2.0" +checksum = "c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4" +[[esaxx-rs.clarify.files]] +path = "src/esa.hxx" +license = "MIT" +checksum = "cdb4a78fc2d2738d8dd4af2e3b08531d858833822e2a2e968c353d3f40bdfe2d" +end = "OTHER DEALINGS IN THE SOFTWARE." From 4d9ed9c33c2589415cc57b5ef0afe2ad8e281f76 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 00:21:35 -0700 Subject: [PATCH 06/31] release: check each built wheel in a clean venv The release had no check that the Linux wheels carry what they claim: each one is now installed without dependencies, outside the build container, and must import mstar_rust, run mstar-server --help from the scripts directory, and list the third-party licenses, or the release publishes nothing. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d7c5aab6d2..65c1b5309d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -54,6 +54,33 @@ jobs: CIBW_ENVIRONMENT_LINUX: PATH="$HOME/.cargo/bin:$PATH" with: output-dir: wheelhouse + - uses: actions/setup-python@v5 + with: + python-version: | + 3.12 + 3.13 + 3.14 + # Outside the build container, with no dependencies installed: the + # extension imports, the frontend binary runs from the scripts directory + # find_server_binary looks in, and the licenses are in the metadata. + - name: Check each wheel in a clean venv + shell: python + run: | + import glob, re, subprocess, tempfile + check = ( + "import importlib.metadata as md, mstar_rust, pathlib, subprocess, sysconfig\n" + "assert 'LICENSES-THIRD-PARTY.txt' in {f.name for f in md.files('mstar-ai')}\n" + "subprocess.run([pathlib.Path(sysconfig.get_path('scripts')) / 'mstar-server', '--help'], check=True)\n" + ) + wheels = sorted(glob.glob("wheelhouse/*.whl")) + assert len(wheels) == 3, wheels + for whl in wheels: + py = "python3." + re.search(r"-cp3(\d+)-", whl).group(1) + venv = tempfile.mkdtemp() + subprocess.run([py, "-m", "venv", venv], check=True) + subprocess.run([f"{venv}/bin/pip", "install", "-q", "--no-deps", whl], check=True) + subprocess.run([f"{venv}/bin/python", "-c", check], check=True) + print("ok", whl) - uses: actions/upload-artifact@v4 with: name: wheels-${{ matrix.os }} From b00d056274a37aa1c8345ec853d21c93a05c522a Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 00:31:34 -0700 Subject: [PATCH 07/31] docs: describe the Rust wheels in PACKAGING.md Co-Authored-By: Claude Opus 5.5 --- PACKAGING.md | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/PACKAGING.md b/PACKAGING.md index 0387ff1ad2..3213ab51bb 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -31,6 +31,34 @@ sdist so a wheel built from the sdist copies them too. Nothing is duplicated in git. The CLI resolves via `importlib.resources.files("mstar.default_configs")` for a pip install and falls back to the repo `configs/` for checkouts. +## Rust extension and frontend in the Linux wheels + +Besides the sdist and a pure-Python `py3-none-any` wheel, each release builds +a manylinux wheel per CPython version (3.12, 3.13, 3.14) and architecture +(x86_64, aarch64) with cibuildwheel. Those wheels also carry the `mstar_rust` +extension (`rust/`) and the `mstar-server` HTTP frontend binary +(`rust/server/`, installed into the environment's `bin/`). `setup.py` compiles +both with setuptools-rust only when `CIBUILDWHEEL=1`; every other build, +including `pip install -e .`, is pure Python, and a checkout builds the Rust +parts with maturin and cargo (docs/installation.rst). pip picks the matching +manylinux wheel and falls back to the pure one elsewhere, which runs on the +Python transport and graph runtime. + +- **Compiler.** `rust-toolchain.toml` at the repo root pins the Rust version + for CI, the release wheels and local builds. Bump it there. +- **Third-party licenses.** Before building, the workflow runs + [cargo-about](https://github.com/EmbarkStudios/cargo-about) with + `rust/about.toml` over `rust/server` (whose dependency tree contains + `rust/`'s) and writes `LICENSES-THIRD-PARTY.txt`, which ships in each Rust + wheel's `dist-info/licenses/`. A crate under a license not in `accepted` + fails the release. The C/C++ that crates vendor is declared there by hand + (libzmq via zeromq-src, Oniguruma via onig_sys, esaxx via esaxx-rs); check + those entries when bumping those crates. +- **Checks.** Each wheel is installed without dependencies into a clean venv + outside the build container and must import `mstar_rust`, run + `mstar-server --help` and list the license file. A failure there stops the + release before anything is published. + ## Cutting a release Version lives in `pyproject.toml` (`[project] version`), and the alias @@ -40,8 +68,8 @@ release: 1. Bump the version in all three pyproject files and land it on `main`. 2. Publish a GitHub Release with a matching tag (e.g. `v0.2.1`). The workflow refuses a tag that does not match the version. -3. The `Publish to PyPI` workflow builds the engine and the alias packages and - uploads them over Trusted Publishing (OIDC, no token stored in the repo). +3. The `Publish to PyPI` workflow builds the engine (including the Linux Rust + wheels above) and the alias packages and uploads them over Trusted Publishing (OIDC, no token stored in the repo). The `pypi` environment asks one of its reviewers to approve the run first. One-time PyPI setup: each project needs a pending Trusted Publisher (owner @@ -67,3 +95,7 @@ twine upload --repository testpypi dist/* # optional TestPyPI dry r The alias packages are published by the release workflow together with the engine, so they need no separate upload. + +`python -m build` makes only the pure-Python wheel. The Linux Rust wheels need +cibuildwheel (Docker) with the workflow's `CIBW_*` settings; to try the +workflow without publishing, run its `wheels` job on a fork branch. From 53e3b4e8b9cd9007592464ee45a5f7df14319aa5 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:32:12 -0700 Subject: [PATCH 08/31] release: publish the Rust wheels in their own job, after the pure dists libzmq 4.3.4's exception is its own Classpath-style text, not SPDX's LGPL-3.0-linking-exception, so it cannot be accepted as that id. With LGPL-3.0-or-later unaccepted, the license step fails every release; pypi needing wheels meant the sdist, pure wheel and aliases never published either. pypi now runs on its own (and checks the tag before the wheel matrix finishes), and pypi-wheels uploads the Linux wheels once both pass. Docs and the frontend error no longer say PyPI ships the extension. Findings: R1.1, R1.16, R1.13 (PACKAGING step 3, README line break) Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 29 ++++++++++++++++++++++------- PACKAGING.md | 23 +++++++++++++++-------- README.md | 8 ++++---- docs/installation.rst | 20 ++++++++++---------- mstar/api_server/rust_frontend.py | 6 +++--- rust/about.toml | 11 +++++++---- 6 files changed, 61 insertions(+), 36 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 65c1b5309d..706f9c9adb 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -17,7 +17,9 @@ name: Publish to PyPI # version and architecture that also carry the mstar_rust extension (setup.py # compiles rust/ only under cibuildwheel). pip prefers the Linux wheel where # one matches and falls back to the pure one elsewhere, which then runs on the -# Python transport and graph runtime. +# Python transport and graph runtime. The Linux wheels publish in their own +# job, so a failure in `wheels` (the license check fails until libzmq is +# accepted in rust/about.toml) holds back only them. on: release: @@ -87,7 +89,6 @@ jobs: path: wheelhouse/*.whl pypi: - needs: wheels runs-on: ubuntu-latest environment: pypi permissions: @@ -108,11 +109,6 @@ jobs: - run: pip install build - name: Build mstar-ai run: python -m build - - uses: actions/download-artifact@v4 - with: - pattern: wheels-* - path: dist - merge-multiple: true - name: Build the alias packages run: | for alias in packaging/aliases/*/; do @@ -132,3 +128,22 @@ jobs: with: packages-dir: dist-mstar-serve skip-existing: true + + # After pypi, which checked the tag, so these upload only for a release whose + # sdist and pure wheel went up. + pypi-wheels: + needs: [wheels, pypi] + runs-on: ubuntu-latest + environment: pypi + permissions: + id-token: write + steps: + - uses: actions/download-artifact@v4 + with: + pattern: wheels-* + path: dist + merge-multiple: true + - name: Publish the mstar-ai Linux wheels + uses: pypa/gh-action-pypi-publish@release/v1 + with: + skip-existing: true diff --git a/PACKAGING.md b/PACKAGING.md index 3213ab51bb..69007a83c2 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -51,13 +51,19 @@ Python transport and graph runtime. `rust/about.toml` over `rust/server` (whose dependency tree contains `rust/`'s) and writes `LICENSES-THIRD-PARTY.txt`, which ships in each Rust wheel's `dist-info/licenses/`. A crate under a license not in `accepted` - fails the release. The C/C++ that crates vendor is declared there by hand - (libzmq via zeromq-src, Oniguruma via onig_sys, esaxx via esaxx-rs); check - those entries when bumping those crates. + fails the `wheels` job. The C/C++ that crates vendor is declared there by + hand (libzmq via zeromq-src, Oniguruma via onig_sys, esaxx via esaxx-rs); + check those entries when bumping those crates. +- **Not published yet.** libzmq 4.3.4 (vendored by zeromq-src, statically + linked into both binaries) is LGPL-3.0-or-later with its own static-linking + exception, and that license is not in `accepted` until a maintainer signs off + on distributing it. Until then the license step fails, so `wheels` fails and + `pypi-wheels` is skipped; `pypi` still publishes the sdist, the pure wheel + and the aliases. - **Checks.** Each wheel is installed without dependencies into a clean venv outside the build container and must import `mstar_rust`, run - `mstar-server --help` and list the license file. A failure there stops the - release before anything is published. + `mstar-server --help` and list the license file. A failure there keeps the + Rust wheels off PyPI. ## Cutting a release @@ -68,9 +74,10 @@ release: 1. Bump the version in all three pyproject files and land it on `main`. 2. Publish a GitHub Release with a matching tag (e.g. `v0.2.1`). The workflow refuses a tag that does not match the version. -3. The `Publish to PyPI` workflow builds the engine (including the Linux Rust - wheels above) and the alias packages and uploads them over Trusted Publishing (OIDC, no token stored in the repo). - The `pypi` environment asks one of its reviewers to approve the run first. +3. The `Publish to PyPI` workflow builds the engine and the alias packages + and uploads them over Trusted Publishing (OIDC, no token stored in the + repo); the Linux Rust wheels above go up in a job of their own. The `pypi` + environment asks one of its reviewers to approve each publishing job first. One-time PyPI setup: each project needs a pending Trusted Publisher (owner `mstar-project`, repo `mstar`, workflow `release.yml`, environment `pypi`). diff --git a/README.md b/README.md index 3d984e5b12..b5da9a1209 100644 --- a/README.md +++ b/README.md @@ -166,10 +166,10 @@ The ZeroMQ control mesh can run over a Rust transport (vendored in [`rust/`](rus pyzmq — wire-compatible, selectable per process with `MSTAR_RUST_ZMQ` (default `AUTO`). Note what AUTO-by-default means: on any machine where the extension is built, the whole mesh switches to the Rust transport with no configuration change — each process logs its -choice at startup (`control mesh transport: ...`), and `MSTAR_RUST_ZMQ=0` pins pyzmq. The Linux -wheels on PyPI (x86_64 and aarch64, CPython 3.12 to 3.14) ship the extension and the -`mstar-server` HTTP frontend; in a source checkout, -build it with [maturin](https://www.maturin.rs): `uv pip install maturin && maturin develop --release -m rust/Cargo.toml`. +choice at startup (`control mesh transport: ...`), and `MSTAR_RUST_ZMQ=0` pins pyzmq. Build it +with [maturin](https://www.maturin.rs): `uv pip install maturin && maturin develop --release -m rust/Cargo.toml`. +The release workflow also builds Linux wheels that carry it; they are not on PyPI yet +([PACKAGING.md](PACKAGING.md) says why). See the [installation docs](https://m-star.org/mstar/installation.html) and [environment variables](https://m-star.org/mstar/environment_variables.html). diff --git a/docs/installation.rst b/docs/installation.rst index b25d9e7909..4189b9ee0b 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -486,12 +486,12 @@ runs on the pure-Python paths as before. Migrated so far (see wherever that holds, so on a machine with the extension built, installing it is what moves a worker onto the Rust runtime. -The PyPI wheels for Linux (x86_64 and aarch64, CPython 3.12 to 3.14) already -carry the extension, so ``pip install mstar-ai`` there needs nothing more. Other -platforms get the pure-Python wheel. In a source checkout, build the extension into -your environment with `maturin `_ (needs `rustup -`_, which installs the compiler version pinned in -``rust-toolchain.toml``): +The release workflow also builds Linux wheels of ``mstar-ai`` (x86_64 and +aarch64, CPython 3.12 to 3.14) that carry the extension, but they are not on +PyPI yet (``PACKAGING.md`` says why), so ``pip install mstar-ai`` gets the +pure-Python wheel. Build the extension into your environment with `maturin +`_ (needs `rustup `_, which installs +the compiler version pinned in ``rust-toolchain.toml``): .. code-block:: bash @@ -527,13 +527,13 @@ Optional: the Rust HTTP frontend ``mstar-server`` (``rust/server/``) serves the HTTP surface — routes, OpenAI translation, SSE streaming, uploads — from Rust, with the Python process -keeping preprocessing and the conductor protocol. The Linux wheels on PyPI -install the binary next to ``mstar-serve``; in a source checkout, build it. -Then opt in: +keeping preprocessing and the conductor protocol. A Linux wheel that carries +the extension also installs the binary next to ``mstar-serve``; otherwise build +it. Then opt in: .. code-block:: bash - cargo build --release --manifest-path rust/server/Cargo.toml # checkout only + cargo build --release --manifest-path rust/server/Cargo.toml mstar serve qwen3_omni --rust-frontend # or, with an explicit config: mstar-serve --config --rust-frontend diff --git a/mstar/api_server/rust_frontend.py b/mstar/api_server/rust_frontend.py index 80528a795e..e959309cf3 100644 --- a/mstar/api_server/rust_frontend.py +++ b/mstar/api_server/rust_frontend.py @@ -102,9 +102,9 @@ def find_server_binary(explicit: str | None = None) -> str: if candidate and Path(candidate).is_file(): return candidate raise FileNotFoundError( - "mstar-server binary not found: the Linux wheels on PyPI ship it; " - "otherwise build it with `cargo build --release` in rust/server/, " - "put it on $PATH, or set MSTAR_SERVER_BIN") + "mstar-server binary not found: build it with " + "`cargo build --release` in rust/server/, put it on $PATH, or set " + "MSTAR_SERVER_BIN") def launch_rust_server(binary: str, model_name: str, port: int, diff --git a/rust/about.toml b/rust/about.toml index 62e23d3051..6d67b6e39d 100644 --- a/rust/about.toml +++ b/rust/about.toml @@ -25,10 +25,13 @@ workarounds = ["ring"] # The crate fields below cover only the Rust wrappers; these add the vendored # C/C++ sources that are compiled into the binaries. -# libzmq 4.3.4: LGPL-3.0 plus a static-linking exception (appended to -# COPYING.LESSER), and the BSD-3-Clause SHA-1 it compiles. LGPL-3.0-or-later -# is left out of `accepted` on purpose, so the wheels do not ship until a -# maintainer signs off on distributing libzmq under that exception. +# libzmq 4.3.4: LGPL-3.0 plus a static-linking exception appended to +# COPYING.LESSER, and the BSD-3-Clause SHA-1 it compiles. The exception is +# libzmq's own Classpath-style text, which matches no SPDX exception id +# (LGPL-3.0-linking-exception is different text). LGPL-3.0-or-later is left out +# of `accepted` on purpose: until a maintainer signs off on distributing libzmq +# under it, this step fails and the release publishes no Rust wheels (the sdist +# and pure wheel still go up). [zeromq-src.clarify] license = "(MIT OR Apache-2.0) AND LGPL-3.0-or-later AND BSD-3-Clause" [[zeromq-src.clarify.files]] From 65292a1dbf97980324fe8608d7e1d875b7613eed Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:37:07 -0700 Subject: [PATCH 09/31] api_server: look for mstar-server in the running env before $PATH An unactivated venv's python found an older mstar-server elsewhere on $PATH first and launched it against its own bridge code, which has no version handshake with the frontend. Findings: R1.7 Co-Authored-By: Claude Opus 5.5 --- docs/environment_variables.rst | 6 +++--- docs/installation.rst | 4 ++-- mstar/api_server/entrypoint.py | 2 +- mstar/api_server/rust_frontend.py | 9 +++++---- mstar/cli/main.py | 2 +- test/rust/test_rust_frontend.py | 14 ++++++++++++++ 6 files changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/environment_variables.rst b/docs/environment_variables.rst index a06bbd9384..e380ff0de5 100644 --- a/docs/environment_variables.rst +++ b/docs/environment_variables.rst @@ -332,9 +332,9 @@ Read by the ``mstar-server`` binary and its bridge * - ``MSTAR_SERVER_BIN`` - unset - Path to the ``mstar-server`` binary. Fallback order: - ``--rust-frontend-bin``, this variable, ``$PATH``, the environment's - scripts directory (where the Linux wheels install it), then the in-repo - ``rust/server/target/release`` build. + ``--rust-frontend-bin``, this variable, the running environment's + scripts directory (where the Linux wheels install it), ``$PATH``, then + the in-repo ``rust/server/target/release`` build. * - ``MSTAR_API_KEY`` - unset - Same rule as the Python server (``rust/server/src/auth.rs``, read diff --git a/docs/installation.rst b/docs/installation.rst index 4189b9ee0b..47f99b6204 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -538,8 +538,8 @@ it. Then opt in: # or, with an explicit config: mstar-serve --config --rust-frontend The binary is resolved via ``--rust-frontend-bin`` / ``MSTAR_SERVER_BIN`` / -``$PATH`` / the environment's scripts directory / the in-repo build. Its knobs are listed in -:doc:`environment_variables`. +the environment's scripts directory / ``$PATH`` / the in-repo build. Its knobs +are listed in :doc:`environment_variables`. The OpenAI routes take the model's adapter from the same registry as the Python frontend (``ADAPTER_REGISTRY`` in ``mstar/api_server/openai/adapters.py``): diff --git a/mstar/api_server/entrypoint.py b/mstar/api_server/entrypoint.py index c660fb7ced..dfbfff9d3e 100644 --- a/mstar/api_server/entrypoint.py +++ b/mstar/api_server/entrypoint.py @@ -2482,7 +2482,7 @@ def main(argv: list[str] | None = None): parser.add_argument( "--rust-frontend-bin", type=str, default=None, help="Path to the mstar-server binary (default: MSTAR_SERVER_BIN, " - "$PATH, the environment's scripts dir, then " + "the environment's scripts dir, $PATH, then " "rust/server/target/release)", ) args = parser.parse_args(argv) diff --git a/mstar/api_server/rust_frontend.py b/mstar/api_server/rust_frontend.py index e959309cf3..bee545c14a 100644 --- a/mstar/api_server/rust_frontend.py +++ b/mstar/api_server/rust_frontend.py @@ -88,14 +88,15 @@ def openai_adapter_class(model_name: str) -> str: def find_server_binary(explicit: str | None = None) -> str: """Resolve the ``mstar-server`` binary: explicit arg, ``MSTAR_SERVER_BIN``, - ``$PATH``, the environment's scripts directory (where a Linux wheel - installs it, also when the venv is not activated), then the in-repo - release build.""" + the running environment's scripts directory (where a Linux wheel installs + it, also when the venv is not activated), ``$PATH``, then the in-repo + release build. The scripts directory goes before ``$PATH`` so another + environment's older binary never serves this one's bridge.""" for candidate in ( explicit, os.getenv("MSTAR_SERVER_BIN"), - shutil.which("mstar-server"), str(Path(sysconfig.get_path("scripts")) / "mstar-server"), + shutil.which("mstar-server"), str(Path(__file__).resolve().parents[2] / "rust" / "server" / "target" / "release" / "mstar-server"), ): diff --git a/mstar/cli/main.py b/mstar/cli/main.py index 8cc7db4970..28aff93704 100644 --- a/mstar/cli/main.py +++ b/mstar/cli/main.py @@ -333,7 +333,7 @@ def build_parser() -> argparse.ArgumentParser: serve.add_argument( "--rust-frontend-bin", default=None, help="path to the mstar-server binary (default: MSTAR_SERVER_BIN, " - "$PATH, the environment's scripts dir, then " + "the environment's scripts dir, $PATH, then " "rust/server/target/release)", ) serve.set_defaults(func=_serve) diff --git a/test/rust/test_rust_frontend.py b/test/rust/test_rust_frontend.py index 347b67fdb6..15f4bea354 100644 --- a/test/rust/test_rust_frontend.py +++ b/test/rust/test_rust_frontend.py @@ -7,6 +7,7 @@ import contextlib import json import socket +import sysconfig import tempfile import threading import time @@ -1058,3 +1059,16 @@ def test_images_n_cap_follows_the_env(): out = _post_json(port, "/v1/images/generations", {"model": "cosmos3", "prompt": "x", "n": 2}) assert len(out["data"]) == 2 + + +def test_the_running_environment_s_binary_wins_over_one_on_path(tmp_path, monkeypatch): + # An unactivated venv's python must not launch an older mstar-server that + # happens to be on $PATH against its own bridge code. + scripts, elsewhere = tmp_path / "venv-bin", tmp_path / "on-path" + for d in (scripts, elsewhere): + d.mkdir() + (d / "mstar-server").touch(mode=0o755) + monkeypatch.delenv("MSTAR_SERVER_BIN", raising=False) + monkeypatch.setenv("PATH", str(elsewhere)) + monkeypatch.setattr(sysconfig, "get_path", lambda name: str(scripts)) + assert find_server_binary() == str(scripts / "mstar-server") From 8603aa03c52a0d26017f89f0554a8e3ed43342f5 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:38:06 -0700 Subject: [PATCH 10/31] communication: say which mstar_rust loaded, and how to fix a stale one A Linux wheel's top-level mstar_rust module and a maturin-built mstar-rust package can both sit in one environment; the package directory wins, and both report the same crate version. The startup line now names the loaded file, the version warning gives the fix for a checkout and for a pip install, and PACKAGING.md / installation.rst state the precedence and that uninstalling one never deletes the other's files (Kirill's question). Findings: R1.4 Co-Authored-By: Claude Opus 5.5 --- PACKAGING.md | 9 +++++++++ docs/installation.rst | 6 +++++- mstar/communication/communicator.py | 16 ++++++++++------ test/modular/test_outbox_communicator.py | 3 ++- 4 files changed, 26 insertions(+), 8 deletions(-) diff --git a/PACKAGING.md b/PACKAGING.md index 69007a83c2..922bc0c8c8 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -60,6 +60,15 @@ Python transport and graph runtime. on distributing it. Until then the license step fails, so `wheels` fails and `pypi-wheels` is skipped; `pypi` still publishes the sdist, the pure wheel and the aliases. +- **Two copies of `mstar_rust`.** `maturin develop` (or `pip install ./rust`) + installs `rust/` as a separate `mstar-rust` distribution, a `mstar_rust/` + package directory. In an environment that also has a Rust wheel's top-level + `mstar_rust.*.so`, the package directory wins (Python's path finder takes a + package directory over a same-named module), so the maturin build is what + loads; the startup line `control mesh transport: rust from + ` names it. The two own different files, so uninstalling one never + deletes the other's: `pip uninstall mstar-rust` goes back to the wheel's + copy. - **Checks.** Each wheel is installed without dependencies into a clean venv outside the build container and must import `mstar_rust`, run `mstar-server --help` and list the license file. A failure there keeps the diff --git a/docs/installation.rst b/docs/installation.rst index 47f99b6204..0198f410df 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -499,7 +499,11 @@ the compiler version pinned in ``rust-toolchain.toml``): maturin develop --release -m rust/Cargo.toml Build with ``--release`` — an unoptimized debug build (maturin's default) -costs real latency on the hot receive path. Verify with: +costs real latency on the hot receive path. If ``mstar-ai`` came from a Linux +wheel that carries the extension, this build (a separate ``mstar-rust`` +distribution) takes precedence over the wheel's copy in the same environment; +``pip uninstall mstar-rust`` goes back to the wheel's, and neither uninstall +removes the other's files. Verify with: .. code-block:: bash diff --git a/mstar/communication/communicator.py b/mstar/communication/communicator.py index 34b938ccb6..a21e6ef52c 100644 --- a/mstar/communication/communicator.py +++ b/mstar/communication/communicator.py @@ -285,16 +285,20 @@ def make_communicator(*args, nonblocking_send: bool = False, **kwargs) -> BaseCo # A support bundle must be able to tell what a mesh was running, # and an old wheel left in an env must not silently take over # the whole mesh under AUTO after an upgrade. + # The path says which copy loaded: a maturin-built mstar-rust + # package shadows the module an mstar-ai Linux wheel ships. version = getattr(mstar_rust, "__version__", "") logger.info( - "control mesh transport: rust %s (MSTAR_RUST_ZMQ=%s)", - version, choice) + "control mesh transport: rust %s from %s (MSTAR_RUST_ZMQ=%s)", + version, mstar_rust.__file__, choice) if version != EXPECTED_MSTAR_RUST_VERSION: logger.warning( - "mstar_rust version %s does not match this tree's " - "expected %s — a stale wheel may be shadowing the " - "vendored rust/ build (rebuild with `maturin develop " - "--release`)", version, EXPECTED_MSTAR_RUST_VERSION) + "mstar_rust version %s at %s does not match the expected " + "%s: in a checkout, rebuild it with `maturin develop " + "--release -m rust/Cargo.toml`; in a pip install, upgrade " + "mstar-ai and `pip uninstall mstar-rust` if a leftover " + "build is shadowing the wheel's copy", + version, mstar_rust.__file__, EXPECTED_MSTAR_RUST_VERSION) if not nonblocking_send or hasattr(mstar_rust.ZmqCommunicator, "try_send"): return RustZMQCommunicator(*args, **kwargs) # built before try_send: every send the outbox makes would fail. diff --git a/test/modular/test_outbox_communicator.py b/test/modular/test_outbox_communicator.py index af3f87938e..0d8e405f0b 100644 --- a/test/modular/test_outbox_communicator.py +++ b/test/modular/test_outbox_communicator.py @@ -232,7 +232,8 @@ def send(self, peer_id, data): if has_try_send: _Zmq.try_send = lambda self, peer_id, data: True version = communicator.EXPECTED_MSTAR_RUST_VERSION if has_try_send else "0.1.0" - monkeypatch.setitem(sys.modules, "mstar_rust", SimpleNamespace(ZmqCommunicator=_Zmq, __version__=version)) + monkeypatch.setitem(sys.modules, "mstar_rust", SimpleNamespace( + ZmqCommunicator=_Zmq, __version__=version, __file__="mstar_rust.so")) monkeypatch.setattr(rust_communicator, "RustZMQCommunicator", lambda *args, **kwargs: "rust") monkeypatch.setattr(communicator, "ZMQCommunicator", lambda *args, **kwargs: "pyzmq") monkeypatch.setenv("MSTAR_RUST_ZMQ", choice) From d9ff325d5486c88343c56343aa08e4914b0cd3ac Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:38:38 -0700 Subject: [PATCH 11/31] rust: put pyo3 behind a `python` feature so mstar-server links no Python rust/server built mstar-rust without extension-module, so pyo3-ffi linked libpython into the frontend, which uses only the transport. In manylinux that means no shared libpython to link against, and where it links, a binary tied to one interpreter; the wheel check could not see it because setup-python puts its libdir on LD_LIBRARY_PATH. Now the bindings, graph and tensors build only with `python` (extension-module implies it, the default stays extension-module), the server takes no features, and the wheel check asserts no libpython in the binary's NEEDED and runs it with LD_LIBRARY_PATH unset. cargo test takes --features python where it used to take only --no-default-features. Findings: R1.2 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 12 ++-- .github/workflows/release.yml | 18 ++++-- AGENTS.md | 2 +- docs/installation.rst | 11 ++-- rust/Cargo.toml | 15 +++-- rust/server/Cargo.lock | 100 +--------------------------------- rust/server/Cargo.toml | 5 +- rust/src/lib.rs | 24 +++++++- scripts/ci/check.sh | 2 +- 9 files changed, 61 insertions(+), 128 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b53783e38f..1412962a08 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -155,13 +155,13 @@ jobs: run: sudo apt-get update && sudo apt-get install -y libzmq3-dev - name: Cargo tests (transport + arena semantics) working-directory: rust - # Off with extension-module (see rust/Cargo.toml): the test binary is an - # executable, so it links libpython rather than resolving CPython - # symbols at import time. setup-python's interpreter is --enable-shared, - # so point the loader at its libdir for the run. + # The bindings without extension-module (see rust/Cargo.toml): the test + # binary is an executable, so it links libpython rather than resolving + # CPython symbols at import time. setup-python's interpreter is + # --enable-shared, so point the loader at its libdir for the run. env: LD_LIBRARY_PATH: ${{ env.pythonLocation }}/lib - run: cargo test --release --no-default-features + run: cargo test --release --no-default-features --features python - run: cargo test --release --manifest-path rust/server/Cargo.toml - name: Build the Rust frontend (mstar-server) working-directory: rust/server @@ -173,8 +173,6 @@ jobs: maturin build --release pip install target/wheels/*.whl - name: Interop tests (transport + arena + frontend) - env: - LD_LIBRARY_PATH: ${{ env.pythonLocation }}/lib run: | # pyyaml: the runtime tests reach mstar.model.base, which imports it; # prometheus-client: the frontend's /metrics test renders a real registry; diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 706f9c9adb..877a2c566f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -64,16 +64,22 @@ jobs: 3.14 # Outside the build container, with no dependencies installed: the # extension imports, the frontend binary runs from the scripts directory - # find_server_binary looks in, and the licenses are in the metadata. + # find_server_binary looks in without any libpython (setup-python puts + # its libdir on LD_LIBRARY_PATH, which would hide a link to one), and + # the licenses are in the metadata. - name: Check each wheel in a clean venv shell: python run: | import glob, re, subprocess, tempfile - check = ( - "import importlib.metadata as md, mstar_rust, pathlib, subprocess, sysconfig\n" - "assert 'LICENSES-THIRD-PARTY.txt' in {f.name for f in md.files('mstar-ai')}\n" - "subprocess.run([pathlib.Path(sysconfig.get_path('scripts')) / 'mstar-server', '--help'], check=True)\n" - ) + check = """ + import importlib.metadata as md, mstar_rust, os, pathlib, subprocess, sysconfig + assert 'LICENSES-THIRD-PARTY.txt' in {f.name for f in md.files('mstar-ai')} + server = pathlib.Path(sysconfig.get_path('scripts')) / 'mstar-server' + needed = subprocess.run(['readelf', '-d', server], capture_output=True, text=True, check=True).stdout + assert 'libpython' not in needed, needed + env = {k: v for k, v in os.environ.items() if k != 'LD_LIBRARY_PATH'} + subprocess.run([server, '--help'], env=env, check=True) + """ wheels = sorted(glob.glob("wheelhouse/*.whl")) assert len(wheels) == 3, wheels for whl in wheels: diff --git a/AGENTS.md b/AGENTS.md index db455312a4..1f935c3cc8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -191,7 +191,7 @@ python -m pytest test/modular test/distributed test/chatterbox test/kokoro \ test/omnivoice test/sampling_test mstar/model/*/tests benchmark/worker_phases # the CPU Core CI job (CI adds -p xdist -n 4), no GPU or weights pytest test/integration/ # needs GPU + weights -cd rust && cargo test --release --no-default-features && pytest ../test/rust/ +cd rust && cargo test --release --no-default-features --features python && pytest ../test/rust/ ``` The CPU Core job runs every test module under the directories in `CPU_TEST_PATHS` ([scripts/ci/select_cpu_tests.py](scripts/ci/select_cpu_tests.py)), including `test/modular/`, `test/distributed/` and `mstar/model/*/tests/`; there is no list of test files to add to. A new module there runs in CI as soon as it exists, so it must pass or skip on a CPU-only machine: guard CUDA, weights and optional packages with a `skipif` or `pytest.importorskip("")` (import names: `flashinfer`, `misaki`, `qwen_tts`, `mstar_rust`), and give a test that is broken on `main` an in-file `pytest.mark.skip` whose reason says why and names the fixing PR or issue when one exists. A test module outside those directories goes in `NOT_CPU_CORE` there with where it runs instead; `test/ci/test_cpu_selection.py` fails on one in neither, and on two selected modules outside a package with the same basename. A guard on a reference package named like an mstar model (`kokoro`, `chatterbox`, `omnivoice`) imports a submodule only the reference has: once pytest puts `mstar/model` on `sys.path` for `mstar/model/*/tests`, the bare name finds mstar's own package (see [CONTRIBUTING.md](CONTRIBUTING.md)). diff --git a/docs/installation.rst b/docs/installation.rst index 0198f410df..97c26f8d8e 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -513,18 +513,19 @@ removes the other's files. Verify with: ``test/rust`` is skipped wholesale when the extension is not importable, so a green run there without the build above proves nothing. -The Rust-side tests need one extra flag. The crate's default features turn on -``pyo3/extension-module``, which tells pyo3 *not* to link libpython — right +The Rust-side tests need different features. The crate's default features turn +on ``pyo3/extension-module``, which tells pyo3 *not* to link libpython — right for the cdylib, which resolves CPython symbols from the interpreter that imports it, wrong for ``cargo test``, which is an executable and has to link -it itself. Without this the link fails on ``undefined symbol: -PyEval_RestoreThread``: +it itself. Without ``--no-default-features`` the link fails on ``undefined +symbol: PyEval_RestoreThread``; ``--features python`` keeps the bindings and +the graph runtime, whose tests need them: .. code-block:: bash export LD_LIBRARY_PATH="$(python -c 'import sysconfig print(sysconfig.get_config_var("LIBDIR"))')" - cargo test --release --no-default-features --manifest-path rust/Cargo.toml + cargo test --release --no-default-features --features python --manifest-path rust/Cargo.toml Optional: the Rust HTTP frontend -------------------------------- diff --git a/rust/Cargo.toml b/rust/Cargo.toml index 4d2f555971..30cfe22348 100644 --- a/rust/Cargo.toml +++ b/rust/Cargo.toml @@ -21,7 +21,7 @@ rmp-serde = "1.3" rustc-hash = "2" thiserror = "2" zmq = "0.10" -pyo3 = { version = "0.26" } +pyo3 = { version = "0.26", optional = true } rmpv = "1.3.1" # Direct msgpack writing. rmpv builds a Value tree first, which allocates a # String for every map KEY -- ~13 per tensor descriptor -- and then copies the @@ -30,12 +30,15 @@ rmpv = "1.3.1" rmp = "0.8" [features] -# On for the cdylib: a Python extension resolves the CPython symbols at import -# time and must NOT link libpython. Off for `cargo test`, whose binary is an -# executable and therefore has to link it -- hence -# `cargo test --no-default-features`. +# `python`: the PyO3 bindings and the modules built on them (graph runtime, +# tensor bookkeeping). `extension-module` adds the cdylib's rule that a Python +# extension resolves the CPython symbols at import time and must NOT link +# libpython. `cargo test` builds an executable, which has to link it -- hence +# `cargo test --no-default-features --features python`. rust/server takes +# neither, so it links no Python at all. default = ["extension-module"] -extension-module = ["pyo3/extension-module"] +python = ["dep:pyo3"] +extension-module = ["python", "pyo3/extension-module"] [profile.release] opt-level = 3 diff --git a/rust/server/Cargo.lock b/rust/server/Cargo.lock index a616dd1d63..62f7aa6bde 100644 --- a/rust/server/Cargo.lock +++ b/rust/server/Cargo.lock @@ -145,7 +145,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d067ad48b8650848b989a59a86c6c36a995d02d2bf778d45c3c5d57bc2718f02" dependencies = [ "smallvec", - "target-lexicon 0.12.16", + "target-lexicon", ] [[package]] @@ -677,15 +677,6 @@ dependencies = [ "hashbrown", ] -[[package]] -name = "indoc" -version = "2.0.7" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706" -dependencies = [ - "rustversion", -] - [[package]] name = "itertools" version = "0.11.0" @@ -802,15 +793,6 @@ dependencies = [ "libc", ] -[[package]] -name = "memoffset" -version = "0.9.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a" -dependencies = [ - "autocfg", -] - [[package]] name = "mime" version = "0.3.17" @@ -862,7 +844,6 @@ version = "0.1.1" dependencies = [ "libc", "memmap2", - "pyo3", "rmp", "rmp-serde", "rmpv", @@ -982,12 +963,6 @@ version = "0.3.33" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e" -[[package]] -name = "portable-atomic" -version = "1.13.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49" - [[package]] name = "potential_utf" version = "0.1.5" @@ -1015,67 +990,6 @@ dependencies = [ "unicode-ident", ] -[[package]] -name = "pyo3" -version = "0.26.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7ba0117f4212101ee6544044dae45abe1083d30ce7b29c4b5cbdfa2354e07383" -dependencies = [ - "indoc", - "libc", - "memoffset", - "once_cell", - "portable-atomic", - "pyo3-build-config", - "pyo3-ffi", - "pyo3-macros", - "unindent", -] - -[[package]] -name = "pyo3-build-config" -version = "0.26.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4fc6ddaf24947d12a9aa31ac65431fb1b851b8f4365426e182901eabfb87df5f" -dependencies = [ - "target-lexicon 0.13.5", -] - -[[package]] -name = "pyo3-ffi" -version = "0.26.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "025474d3928738efb38ac36d4744a74a400c901c7596199e20e45d98eb194105" -dependencies = [ - "libc", - "pyo3-build-config", -] - -[[package]] -name = "pyo3-macros" -version = "0.26.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2e64eb489f22fe1c95911b77c44cc41e7c19f3082fc81cce90f657cdc42ffded" -dependencies = [ - "proc-macro2", - "pyo3-macros-backend", - "quote", - "syn", -] - -[[package]] -name = "pyo3-macros-backend" -version = "0.26.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "100246c0ecf400b475341b8455a9213344569af29a3c841d29270e53102e0fcf" -dependencies = [ - "heck", - "proc-macro2", - "pyo3-build-config", - "quote", - "syn", -] - [[package]] name = "quote" version = "1.0.46" @@ -1491,12 +1405,6 @@ version = "0.12.16" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1" -[[package]] -name = "target-lexicon" -version = "0.13.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca" - [[package]] name = "thiserror" version = "1.0.69" @@ -1729,12 +1637,6 @@ version = "0.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "39ec24b3121d976906ece63c9daad25b85969647682eee313cb5779fdd69e14e" -[[package]] -name = "unindent" -version = "0.2.4" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3" - [[package]] name = "untrusted" version = "0.9.0" diff --git a/rust/server/Cargo.toml b/rust/server/Cargo.toml index 78fa41caa8..34d277210e 100644 --- a/rust/server/Cargo.toml +++ b/rust/server/Cargo.toml @@ -9,8 +9,9 @@ name = "mstar-server" path = "src/main.rs" [dependencies] -# The vendored transport/arena library crate (rust/) — rlib target. -# Executables must link libpython; extension-module suppresses that linkage. +# The vendored transport/arena library crate (rust/) — rlib target. No default +# features: the server uses only the transport, so it builds without `python` +# and links no libpython. mstar-rust = { path = "..", package = "mstar-rust", default-features = false } axum = { version = "0.7", features = ["multipart"] } tokio = { version = "1", features = ["rt-multi-thread", "macros", "time", "signal", "sync"] } diff --git a/rust/src/lib.rs b/rust/src/lib.rs index ab7d362002..38a1861f2a 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -4,28 +4,41 @@ //! ZMQ PUSH/PULL control mesh, as a transport + codec split) and `shm.rs` //! (the shared-memory tensor arena). The crate is not limited to these — //! new components land as new modules with their own bindings. Also -//! usable as a plain Rust library (rlib) by Rust-side consumers. +//! usable as a plain Rust library (rlib) by Rust-side consumers; without the +//! `python` feature (rust/server) it builds only the transport and arena and +//! links no Python, since the bindings, `graph` and `tensors` need pyo3. //! Build: `maturin develop --release` in rust/. pub mod communicator; +#[cfg(feature = "python")] pub mod graph; pub mod shm; +#[cfg(feature = "python")] pub mod tensors; +#[cfg(feature = "python")] use std::os::raw::{c_int, c_void}; +#[cfg(feature = "python")] use std::time::Duration; +#[cfg(feature = "python")] use pyo3::exceptions::{PyRuntimeError, PyValueError}; +#[cfg(feature = "python")] use pyo3::ffi; +#[cfg(feature = "python")] use pyo3::prelude::*; +#[cfg(feature = "python")] use pyo3::types::PyBytes; +#[cfg(feature = "python")] use communicator::{RawZmqCommunicator, RecvEvent}; +#[cfg(feature = "python")] use shm::{SegmentedShmArena, ShmArena}; /// Opaque byte frames over ZMQ PUSH/PULL: ipc or tcp endpoints, lazily-cached /// peers, and wakeup-fd polling (an eventfd wakes `recv_or_wake` instantly). /// Encoding is the caller's (pickle today; msgpack by swapping the codec). +#[cfg(feature = "python")] #[pyclass(name = "ZmqCommunicator")] pub struct PyZmqCommunicator { /// Behind an Arc so the graph runtime can hold a share of the SAME @@ -35,12 +48,14 @@ pub struct PyZmqCommunicator { inner: std::sync::Arc, } +#[cfg(feature = "python")] impl PyZmqCommunicator { pub fn share(&self) -> std::sync::Arc { self.inner.clone() } } +#[cfg(feature = "python")] #[pymethods] impl PyZmqCommunicator { /// Bind the PULL inbox at `ipc://{dir}/{my_id}.ipc`. @@ -140,11 +155,13 @@ impl PyZmqCommunicator { /// memoryview(arena)[off:off+n], dtype=..).copy_(cpu_tensor)`; send the /// offset descriptor; `free(off)` on reclaim. Consumer: `open(name)` and /// `torch.frombuffer(memoryview(arena)[off:off+n], ..)` (then H2D). +#[cfg(feature = "python")] #[pyclass(name = "ShmArena")] struct PyShmArena { arena: ShmArena, } +#[cfg(feature = "python")] #[pymethods] impl PyShmArena { #[staticmethod] @@ -219,11 +236,13 @@ impl PyShmArena { /// staging stays zero-copy per segment. The mapping never moves, so a /// memoryview (and a CUDA host-registration of the segment) stays valid for /// the segment's lifetime. +#[cfg(feature = "python")] #[pyclass(name = "ShmSegment")] struct PyShmSegment { seg: std::sync::Arc, } +#[cfg(feature = "python")] #[pymethods] impl PyShmSegment { #[getter] @@ -262,11 +281,13 @@ impl PyShmSegment { /// `reserve(n) -> (segment_idx, offset)`; descriptors carry /// `segment_name(idx)` so consumers keep opening plain `ShmArena`s by name. /// Segments are created once and never move — registration-friendly. +#[cfg(feature = "python")] #[pyclass(name = "SegmentedShmArena")] struct PySegmentedShmArena { arena: SegmentedShmArena, } +#[cfg(feature = "python")] #[pymethods] impl PySegmentedShmArena { #[staticmethod] @@ -321,6 +342,7 @@ impl PySegmentedShmArena { } } +#[cfg(feature = "python")] #[pymodule] fn mstar_rust(m: &Bound<'_, PyModule>) -> PyResult<()> { m.add("__version__", env!("CARGO_PKG_VERSION"))?; diff --git a/scripts/ci/check.sh b/scripts/ci/check.sh index 838a43ebd5..202c7633b4 100755 --- a/scripts/ci/check.sh +++ b/scripts/ci/check.sh @@ -52,7 +52,7 @@ runpy.run_module("pytest", run_name="__main__") # location from the active interpreter, including outside setup-python. python_lib=$(python -c 'import sysconfig; print(sysconfig.get_config_var("LIBDIR"))') export LD_LIBRARY_PATH="$python_lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" - (cd rust && cargo test --release --no-default-features) + (cd rust && cargo test --release --no-default-features --features python) (cd rust/server && cargo build --release) # A fresh wheel directory prevents installing an earlier cached build. From e61580e30d0537e9e9e7314741cdad258cc609fa Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:40:48 -0700 Subject: [PATCH 12/31] release: build and check the wheels on PRs and by hand, publish only on a release The shipped build ran only at release time, so a crate bump that changes a license, a toolchain bump or a setuptools-rust/maturin divergence first surfaced as a failed release. The workflow now also runs on workflow_dispatch and on PRs touching rust/, the build files or itself; both pypi jobs run only for a release. Off a release, the license step's failure does not stop the build, so those runs still check the wheels while libzmq's license awaits sign-off. Findings: R1.3 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 23 ++++++++++++++++++++--- PACKAGING.md | 6 ++++-- 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 877a2c566f..93f9472c2c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -24,6 +24,17 @@ name: Publish to PyPI on: release: types: [published] + # Build and check the Linux wheels without publishing: by hand, or on a PR + # that touches what goes into them. Only a release runs the pypi jobs. + workflow_dispatch: + pull_request: + paths: + - "rust/**" + - rust-toolchain.toml + - setup.py + - pyproject.toml + - MANIFEST.in + - .github/workflows/release.yml jobs: wheels: @@ -40,8 +51,11 @@ jobs: tool: cargo-about@0.9.2 # The licenses of the crates and vendored C/C++ compiled into the wheel, # shipped in its dist-info/licenses (setuptools' default LICEN[CS]E* - # glob). Fails on any license rust/about.toml does not accept. + # glob). Fails on any license rust/about.toml does not accept, which + # stops only a release: PR and manual runs go on to build and check the + # wheels (without the file) while libzmq's license awaits sign-off. - name: Collect third-party licenses + continue-on-error: ${{ github.event_name != 'release' }} run: >- cargo about generate --locked -c rust/about.toml -m rust/server/Cargo.toml rust/about.hbs -o LICENSES-THIRD-PARTY.txt @@ -66,14 +80,15 @@ jobs: # extension imports, the frontend binary runs from the scripts directory # find_server_binary looks in without any libpython (setup-python puts # its libdir on LD_LIBRARY_PATH, which would hide a link to one), and - # the licenses are in the metadata. + # the licenses, where the step above wrote them, are in the metadata. - name: Check each wheel in a clean venv shell: python run: | import glob, re, subprocess, tempfile check = """ import importlib.metadata as md, mstar_rust, os, pathlib, subprocess, sysconfig - assert 'LICENSES-THIRD-PARTY.txt' in {f.name for f in md.files('mstar-ai')} + licenses = 'LICENSES-THIRD-PARTY.txt' + assert not os.path.exists(licenses) or licenses in {f.name for f in md.files('mstar-ai')} server = pathlib.Path(sysconfig.get_path('scripts')) / 'mstar-server' needed = subprocess.run(['readelf', '-d', server], capture_output=True, text=True, check=True).stdout assert 'libpython' not in needed, needed @@ -95,6 +110,7 @@ jobs: path: wheelhouse/*.whl pypi: + if: github.event_name == 'release' runs-on: ubuntu-latest environment: pypi permissions: @@ -139,6 +155,7 @@ jobs: # sdist and pure wheel went up. pypi-wheels: needs: [wheels, pypi] + if: github.event_name == 'release' runs-on: ubuntu-latest environment: pypi permissions: diff --git a/PACKAGING.md b/PACKAGING.md index 922bc0c8c8..ef4ef552ee 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -113,5 +113,7 @@ The alias packages are published by the release workflow together with the engine, so they need no separate upload. `python -m build` makes only the pure-Python wheel. The Linux Rust wheels need -cibuildwheel (Docker) with the workflow's `CIBW_*` settings; to try the -workflow without publishing, run its `wheels` job on a fork branch. +cibuildwheel (Docker) with the workflow's `CIBW_*` settings. The workflow +builds and checks them without publishing on any pull request that touches +`rust/`, the build files or the workflow, and from the Actions tab on any +branch (`Run workflow`); only a published Release runs the publishing jobs. From 50680c12a3611c7d0b534b929d593da1a75c8ce0 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:46:19 -0700 Subject: [PATCH 13/31] release: run test/rust against each built wheel Installing a Linux wheel turns the Rust transport and graph runtime on by default (AUTO), including on CPython 3.13/3.14 and aarch64, where rust-transport never runs; the check only imported the extension. Each wheel now also runs test/rust with its dependencies (CPU torch) from a copy of test/, so mstar and mstar_rust both import from the wheel. Findings: R1.5 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 93f9472c2c..e053e40a6a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -104,6 +104,28 @@ jobs: subprocess.run([f"{venv}/bin/pip", "install", "-q", "--no-deps", whl], check=True) subprocess.run([f"{venv}/bin/python", "-c", check], check=True) print("ok", whl) + # These wheels turn the Rust transport and graph runtime on by default + # (MSTAR_RUST_ZMQ / MSTAR_RUST_GRAPH AUTO) on Python versions and an + # architecture rust-transport never runs, so each one also runs test/rust + # with its dependencies installed (CPU torch). From a copy of test/, so + # `mstar` imports from the wheel rather than the checkout. + - name: Run test/rust against each wheel + shell: python + run: | + import glob, re, shutil, subprocess, tempfile + for whl in sorted(glob.glob("wheelhouse/*.whl")): + py = "python3." + re.search(r"-cp3(\d+)-", whl).group(1) + venv, tests = tempfile.mkdtemp(), tempfile.mkdtemp() + subprocess.run([py, "-m", "venv", venv], check=True) + # triton: the arena tests reach mstar.utils.sampling; the rest + # are what ci.yml's rust-transport job adds for test/rust. + subprocess.run([f"{venv}/bin/pip", "install", "-q", + "--extra-index-url", "https://download.pytorch.org/whl/cpu", + whl, "pytest==9.2.0", "prometheus-client", "httpx", "triton"], + check=True) + for d in ("rust", "modular"): # test/rust imports helpers from test/modular + shutil.copytree(f"test/{d}", f"{tests}/test/{d}") + subprocess.run([f"{venv}/bin/pytest", "-q", "-ra", "test/rust"], cwd=tests, check=True) - uses: actions/upload-artifact@v4 with: name: wheels-${{ matrix.os }} From 4df28aeeb2170f31ed7ba8576d7cb0dba6012b1f Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:46:47 -0700 Subject: [PATCH 14/31] release: check each wheel's mstar_rust is the version mstar expects A wheel whose extension disagreed with EXPECTED_MSTAR_RUST_VERSION would ship and then warn at every startup; the clean-venv check now asserts the version it imports against the constant in the checkout. Findings: R1.12 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e053e40a6a..d2a1f6df80 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -77,7 +77,7 @@ jobs: 3.13 3.14 # Outside the build container, with no dependencies installed: the - # extension imports, the frontend binary runs from the scripts directory + # extension imports at the version mstar expects, the frontend binary runs from the scripts directory # find_server_binary looks in without any libpython (setup-python puts # its libdir on LD_LIBRARY_PATH, which would hide a link to one), and # the licenses, where the step above wrote them, are in the metadata. @@ -85,8 +85,11 @@ jobs: shell: python run: | import glob, re, subprocess, tempfile + expected = re.search(r'^EXPECTED_MSTAR_RUST_VERSION = "(.+)"$', + open("mstar/communication/communicator.py").read(), re.M)[1] check = """ - import importlib.metadata as md, mstar_rust, os, pathlib, subprocess, sysconfig + import importlib.metadata as md, mstar_rust, os, pathlib, subprocess, sys, sysconfig + assert mstar_rust.__version__ == sys.argv[1], mstar_rust.__version__ licenses = 'LICENSES-THIRD-PARTY.txt' assert not os.path.exists(licenses) or licenses in {f.name for f in md.files('mstar-ai')} server = pathlib.Path(sysconfig.get_path('scripts')) / 'mstar-server' @@ -102,7 +105,7 @@ jobs: venv = tempfile.mkdtemp() subprocess.run([py, "-m", "venv", venv], check=True) subprocess.run([f"{venv}/bin/pip", "install", "-q", "--no-deps", whl], check=True) - subprocess.run([f"{venv}/bin/python", "-c", check], check=True) + subprocess.run([f"{venv}/bin/python", "-c", check, expected], check=True) print("ok", whl) # These wheels turn the Rust transport and graph runtime on by default # (MSTAR_RUST_ZMQ / MSTAR_RUST_GRAPH AUTO) on Python versions and an From 701beabe8f90aa21ba6469b6e8a48c4e4bb1b25b Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:47:48 -0700 Subject: [PATCH 15/31] setup.py: build the wheels' Rust with --locked and strip them setuptools-rust passed no --locked, so a wheel could compile versions other than the Cargo.lock the license notices were collected from, and both targets shipped unstripped into six wheels (PyPI's size quota). Done in setup.py rather than [profile.release] so local release builds keep their symbols for profiling. Findings: R1.8, R1.9 Co-Authored-By: Claude Opus 5.5 --- setup.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/setup.py b/setup.py index 5841290e53..f35951ef2f 100644 --- a/setup.py +++ b/setup.py @@ -45,11 +45,15 @@ def run(self): # `pip install -e .`. rust_extensions = [] if os.environ.get("CIBUILDWHEEL") == "1": - from setuptools_rust import Binding, RustBin, RustExtension + from setuptools_rust import Binding, RustBin, RustExtension, Strip + # --locked: the checked-in Cargo.lock versions, not whatever resolves on + # the day (the license notices are collected from rust/server/Cargo.lock). + # Stripped: the symbols are unused at runtime and only bloat six wheels. + wheel_build = {"cargo_manifest_args": ["--locked"], "strip": Strip.All} rust_extensions += [ - RustExtension("mstar_rust", path="rust/Cargo.toml", binding=Binding.PyO3), - RustBin("mstar-server", path="rust/server/Cargo.toml"), + RustExtension("mstar_rust", path="rust/Cargo.toml", binding=Binding.PyO3, **wheel_build), + RustBin("mstar-server", path="rust/server/Cargo.toml", **wheel_build), ] setup(cmdclass={"build_py": build_py_with_configs}, rust_extensions=rust_extensions) From 0c14c5015068c4b9b5dbb9550d0f387a40942ac5 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:48:21 -0700 Subject: [PATCH 16/31] rust-toolchain: pin rustfmt and clippy too, and bake the pin into the images A minimal profile left `cargo fmt` and `cargo clippy` failing on the pinned toolchain. scripts/ci/Dockerfile and docker/Dockerfile.xpu installed stable, so every fresh container downloaded 1.99.1 on first use (and failed offline); they now install no default and then the toolchain rust-toolchain.toml names (mac.sh passes the repo as a named build context so the CI image can copy it). Findings: R1.10 Co-Authored-By: Claude Opus 5.5 --- docker/Dockerfile.xpu | 4 +++- rust-toolchain.toml | 1 + scripts/ci/Dockerfile | 8 ++++++-- scripts/ci/mac.sh | 2 +- 4 files changed, 11 insertions(+), 4 deletions(-) diff --git a/docker/Dockerfile.xpu b/docker/Dockerfile.xpu index 2751adbbfa..d2d80927c1 100644 --- a/docker/Dockerfile.xpu +++ b/docker/Dockerfile.xpu @@ -68,7 +68,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \ RUN curl -LsSf https://astral.sh/uv/install.sh | sh ENV PATH="/root/.local/bin:/root/.cargo/bin:$PATH" RUN curl --proto '=https' --retry 3 --retry-delay 2 --tlsv1.2 -sSf https://sh.rustup.rs \ -| sh -s -- -y --no-modify-path --profile minimal && rustc --version && cargo --version +| sh -s -- -y --no-modify-path --profile minimal --default-toolchain none ENV VIRTUAL_ENV="/opt/venv" ENV UV_PYTHON_INSTALL_DIR=/opt/uv/python RUN uv venv --python ${PYTHON_VERSION} ${VIRTUAL_ENV} @@ -79,6 +79,8 @@ WORKDIR /mstar-workspace ARG MSTAR_REPO=https://github.com/mstar-project/mstar.git ARG MSTAR_REF=main RUN git clone --depth 1 --branch "${MSTAR_REF}" "${MSTAR_REPO}" ./mstar +# The toolchain the checkout pins (rust-toolchain.toml). +RUN cd ./mstar && rustup toolchain install && rustc --version && cargo --version # uv selects the XPU index for PyTorch and TorchCodec in the single install below. # torchaudio's latest XPU wheel is 2.11; the import check below checks this pairing. diff --git a/rust-toolchain.toml b/rust-toolchain.toml index 067ebd4408..91e9e496e4 100644 --- a/rust-toolchain.toml +++ b/rust-toolchain.toml @@ -3,3 +3,4 @@ [toolchain] channel = "1.99.1" profile = "minimal" +components = ["rustfmt", "clippy"] diff --git a/scripts/ci/Dockerfile b/scripts/ci/Dockerfile index 960e704e15..18c4ca3f62 100644 --- a/scripts/ci/Dockerfile +++ b/scripts/ci/Dockerfile @@ -13,6 +13,10 @@ RUN apt-get update \ && rm -rf /var/lib/apt/lists/* ENV CARGO_HOME=/opt/cargo RUSTUP_HOME=/opt/rustup ENV PATH="/opt/cargo/bin:${PATH}" +# The repo's pinned toolchain, installed into the image so a container does not +# download it on first use (mac.sh passes the repo as the `repo` context). +COPY --from=repo rust-toolchain.toml /opt/rust-toolchain/ RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/rustup.sh \ - && sh /tmp/rustup.sh -y --profile minimal --default-toolchain stable \ - && rm /tmp/rustup.sh + && sh /tmp/rustup.sh -y --profile minimal --default-toolchain none \ + && rm /tmp/rustup.sh \ + && cd /opt/rust-toolchain && rustup toolchain install diff --git a/scripts/ci/mac.sh b/scripts/ci/mac.sh index 7a39df07db..80ea9143ea 100755 --- a/scripts/ci/mac.sh +++ b/scripts/ci/mac.sh @@ -97,7 +97,7 @@ for job in "${jobs[@]}"; do echo "=== $job ($platform) ===" started=$SECONDS docker build --platform "$platform" --target "$target" \ - --tag "$image" --file scripts/ci/Dockerfile scripts/ci \ + --tag "$image" --file scripts/ci/Dockerfile --build-context repo=. scripts/ci \ > "$job_reports/image-build.log" 2>&1 & active_pid=$! if ! wait "$active_pid"; then From 05de82239c5f5ed265c5223558b6f2f79717f1d6 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:48:21 -0700 Subject: [PATCH 17/31] pyproject: list CPython 3.13 and 3.14 in the classifiers The release builds wheels for both. Findings: R1.11 Co-Authored-By: Claude Opus 5.5 --- pyproject.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index cf0c0abfe6..c918985146 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,6 +19,8 @@ keywords = ["inference", "multimodal", "llm", "serving", "engine"] classifiers = [ "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", "Operating System :: POSIX :: Linux", "Topic :: Scientific/Engineering :: Artificial Intelligence", "Environment :: GPU :: NVIDIA CUDA", From 50a72ff1220e960076fba2acd3de03cf21aa8166 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:48:54 -0700 Subject: [PATCH 18/31] rust: mark mstar-rust and mstar-server publish = false cargo-about's `private = { ignore = true }` skips only crates that are not publishable, so both were listed as third-party Apache-2.0 code in the notices, contrary to about.toml's comment. Findings: R1.15 Co-Authored-By: Claude Opus 5.5 --- rust/Cargo.toml | 1 + rust/about.toml | 3 ++- rust/server/Cargo.toml | 1 + 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/rust/Cargo.toml b/rust/Cargo.toml index 30cfe22348..210afaccd3 100644 --- a/rust/Cargo.toml +++ b/rust/Cargo.toml @@ -3,6 +3,7 @@ name = "mstar-rust" version = "0.1.1" edition = "2021" license = "Apache-2.0" +publish = false [lib] name = "mstar_rust" diff --git a/rust/about.toml b/rust/about.toml index 6d67b6e39d..cc8191d1c5 100644 --- a/rust/about.toml +++ b/rust/about.toml @@ -18,7 +18,8 @@ accepted = [ targets = ["x86_64-unknown-linux-gnu", "aarch64-unknown-linux-gnu"] ignore-build-dependencies = false ignore-dev-dependencies = true -# mstar-rust and mstar-server are this project, covered by LICENSE. +# mstar-rust and mstar-server are this project, covered by LICENSE; this skips +# them because their Cargo.toml says `publish = false`. private = { ignore = true } workarounds = ["ring"] diff --git a/rust/server/Cargo.toml b/rust/server/Cargo.toml index 34d277210e..6bb9b563da 100644 --- a/rust/server/Cargo.toml +++ b/rust/server/Cargo.toml @@ -3,6 +3,7 @@ name = "mstar-server" version = "0.1.0" edition = "2021" license = "Apache-2.0" +publish = false [[bin]] name = "mstar-server" From a1cd6e84c2d5d15104188cb29092aecdda962d98 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 18:51:14 -0700 Subject: [PATCH 19/31] release, about.toml: tidy two comments Rewrap the wheel check's comment, and say which step fails in about.toml's libzmq note. Findings: R1.12, R1.1 (comment follow-ups) Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 9 +++++---- rust/about.toml | 4 ++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d2a1f6df80..dabde2f12f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -77,10 +77,11 @@ jobs: 3.13 3.14 # Outside the build container, with no dependencies installed: the - # extension imports at the version mstar expects, the frontend binary runs from the scripts directory - # find_server_binary looks in without any libpython (setup-python puts - # its libdir on LD_LIBRARY_PATH, which would hide a link to one), and - # the licenses, where the step above wrote them, are in the metadata. + # extension imports at the version mstar expects, the frontend binary + # runs from the scripts directory find_server_binary looks in without + # any libpython (setup-python puts its libdir on LD_LIBRARY_PATH, which + # would hide a link to one), and the licenses, where the step above + # wrote them, are in the metadata. - name: Check each wheel in a clean venv shell: python run: | diff --git a/rust/about.toml b/rust/about.toml index cc8191d1c5..15960886e2 100644 --- a/rust/about.toml +++ b/rust/about.toml @@ -31,8 +31,8 @@ workarounds = ["ring"] # libzmq's own Classpath-style text, which matches no SPDX exception id # (LGPL-3.0-linking-exception is different text). LGPL-3.0-or-later is left out # of `accepted` on purpose: until a maintainer signs off on distributing libzmq -# under it, this step fails and the release publishes no Rust wheels (the sdist -# and pure wheel still go up). +# under it, cargo-about fails here and the release publishes no Rust wheels +# (the sdist and pure wheel still go up). [zeromq-src.clarify] license = "(MIT OR Apache-2.0) AND LGPL-3.0-or-later AND BSD-3-Clause" [[zeromq-src.clarify.files]] From 1e645099bf365367a14747849523a6c42a07ff8f Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 19:24:43 -0700 Subject: [PATCH 20/31] release: collect license notices for the extension as well as the frontend Since pyo3 moved behind the `python` feature, rust/server's tree no longer contains pyo3 and its helpers, so notices collected from it alone left out crates only the mstar_rust .so links. cargo-about now runs on each manifest (it takes one at a time, and the two lockfiles are separate) into LICENSES-THIRD-PARTY-mstar_rust.txt and -mstar-server.txt; the wheel check requires both. Findings: R2.1 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 13 ++++++++----- .gitignore | 2 +- PACKAGING.md | 7 ++++--- rust/about.hbs | 6 ++++-- rust/about.toml | 8 +++++--- setup.py | 2 +- 6 files changed, 23 insertions(+), 15 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index dabde2f12f..0e1aa6d31f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -56,9 +56,11 @@ jobs: # wheels (without the file) while libzmq's license awaits sign-off. - name: Collect third-party licenses continue-on-error: ${{ github.event_name != 'release' }} - run: >- - cargo about generate --locked -c rust/about.toml - -m rust/server/Cargo.toml rust/about.hbs -o LICENSES-THIRD-PARTY.txt + run: | + cargo about generate --locked -c rust/about.toml -m rust/Cargo.toml \ + rust/about.hbs -o LICENSES-THIRD-PARTY-mstar_rust.txt + cargo about generate --locked -c rust/about.toml -m rust/server/Cargo.toml \ + rust/about.hbs -o LICENSES-THIRD-PARTY-mstar-server.txt - uses: pypa/cibuildwheel@v4.2.1 env: # Version-specific rather than abi3, matching the extension that @@ -91,8 +93,9 @@ jobs: check = """ import importlib.metadata as md, mstar_rust, os, pathlib, subprocess, sys, sysconfig assert mstar_rust.__version__ == sys.argv[1], mstar_rust.__version__ - licenses = 'LICENSES-THIRD-PARTY.txt' - assert not os.path.exists(licenses) or licenses in {f.name for f in md.files('mstar-ai')} + shipped = {f.name for f in md.files('mstar-ai')} + for licenses in ('LICENSES-THIRD-PARTY-mstar_rust.txt', 'LICENSES-THIRD-PARTY-mstar-server.txt'): + assert not os.path.exists(licenses) or licenses in shipped, licenses server = pathlib.Path(sysconfig.get_path('scripts')) / 'mstar-server' needed = subprocess.run(['readelf', '-d', server], capture_output=True, text=True, check=True).stdout assert 'libpython' not in needed, needed diff --git a/.gitignore b/.gitignore index 7b0d5337e9..8ee56276c7 100644 --- a/.gitignore +++ b/.gitignore @@ -40,4 +40,4 @@ CLAUDE.md .ci-results/ # generated by the release workflow (rust/about.toml) -LICENSES-THIRD-PARTY.txt +LICENSES-THIRD-PARTY-*.txt diff --git a/PACKAGING.md b/PACKAGING.md index ef4ef552ee..7def05fdc1 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -48,9 +48,10 @@ Python transport and graph runtime. for CI, the release wheels and local builds. Bump it there. - **Third-party licenses.** Before building, the workflow runs [cargo-about](https://github.com/EmbarkStudios/cargo-about) with - `rust/about.toml` over `rust/server` (whose dependency tree contains - `rust/`'s) and writes `LICENSES-THIRD-PARTY.txt`, which ships in each Rust - wheel's `dist-info/licenses/`. A crate under a license not in `accepted` + `rust/about.toml` over `rust/` and over `rust/server` and writes + `LICENSES-THIRD-PARTY-mstar_rust.txt` and + `LICENSES-THIRD-PARTY-mstar-server.txt`, which ship in each Rust wheel's + `dist-info/licenses/`. A crate under a license not in `accepted` fails the `wheels` job. The C/C++ that crates vendor is declared there by hand (libzmq via zeromq-src, Oniguruma via onig_sys, esaxx via esaxx-rs); check those entries when bumping those crates. diff --git a/rust/about.hbs b/rust/about.hbs index 06e295c41c..f129eed704 100644 --- a/rust/about.hbs +++ b/rust/about.hbs @@ -1,5 +1,7 @@ -Third-party software compiled into the mstar_rust extension and the -mstar-server binary in this wheel. mstar itself is under LICENSE. +Third-party software compiled into one Rust binary in this wheel: +LICENSES-THIRD-PARTY-mstar_rust.txt covers the mstar_rust extension and +LICENSES-THIRD-PARTY-mstar-server.txt the mstar-server frontend. mstar itself +is under LICENSE. {{#each licenses}} ================================================================================ diff --git a/rust/about.toml b/rust/about.toml index 15960886e2..65c34462ce 100644 --- a/rust/about.toml +++ b/rust/about.toml @@ -1,6 +1,7 @@ -# cargo-about config for LICENSES-THIRD-PARTY.txt, the notices for the Rust +# cargo-about config for the LICENSES-THIRD-PARTY-*.txt notices of the Rust # crates (and the C/C++ they vendor) compiled into the Linux wheels. The release -# workflow runs it on rust/server, whose dependency tree contains rust/'s. +# workflow runs it once per binary: on rust/ for the mstar_rust extension and on +# rust/server for mstar-server, which share most crates but not pyo3's. # A crate under any license not listed here fails the wheel build. accepted = [ "Apache-2.0", @@ -24,7 +25,8 @@ private = { ignore = true } workarounds = ["ring"] # The crate fields below cover only the Rust wrappers; these add the vendored -# C/C++ sources that are compiled into the binaries. +# C/C++ sources that are compiled into the binaries. onig_sys and esaxx-rs are +# only in rust/server's tree, so the rust/ run warns that they are absent. # libzmq 4.3.4: LGPL-3.0 plus a static-linking exception appended to # COPYING.LESSER, and the BSD-3-Clause SHA-1 it compiles. The exception is diff --git a/setup.py b/setup.py index f35951ef2f..70cddf2547 100644 --- a/setup.py +++ b/setup.py @@ -48,7 +48,7 @@ def run(self): from setuptools_rust import Binding, RustBin, RustExtension, Strip # --locked: the checked-in Cargo.lock versions, not whatever resolves on - # the day (the license notices are collected from rust/server/Cargo.lock). + # the day; the license notices are collected from the same lockfiles. # Stripped: the symbols are unused at runtime and only bloat six wheels. wheel_build = {"cargo_manifest_args": ["--locked"], "strip": Strip.All} rust_extensions += [ From 32fe0f10f85607bd23fcef3accc0fa4204638e16 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 19:25:49 -0700 Subject: [PATCH 21/31] release: on PR and manual runs, tolerate only libzmq's license continue-on-error on the license step hid every license failure off a release, so a crate bump to an unaccepted license or a changed checksum on a clarified file still showed green. Those runs now generate from a copy of about.toml with LGPL-3.0-or-later accepted and are otherwise strict, so the step needs no continue-on-error and the check requires both notices unconditionally. A release still uses about.toml as is. Findings: R2.2 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 23 ++++++++++++++--------- PACKAGING.md | 7 ++++--- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0e1aa6d31f..4a9f37adf6 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -51,15 +51,20 @@ jobs: tool: cargo-about@0.9.2 # The licenses of the crates and vendored C/C++ compiled into the wheel, # shipped in its dist-info/licenses (setuptools' default LICEN[CS]E* - # glob). Fails on any license rust/about.toml does not accept, which - # stops only a release: PR and manual runs go on to build and check the - # wheels (without the file) while libzmq's license awaits sign-off. + # glob). Fails on any license rust/about.toml does not accept. Until a + # maintainer signs off on libzmq's LGPL-3.0-or-later that includes + # libzmq, so PR and manual runs, which publish nothing, accept that one + # license in a copy of the config and stay strict about every other. - name: Collect third-party licenses - continue-on-error: ${{ github.event_name != 'release' }} run: | - cargo about generate --locked -c rust/about.toml -m rust/Cargo.toml \ + config=rust/about.toml + if [ "$GITHUB_EVENT_NAME" != release ]; then + config="$RUNNER_TEMP/about.toml" + sed '/^accepted = \[$/a "LGPL-3.0-or-later",' rust/about.toml > "$config" + fi + cargo about generate --locked -c "$config" -m rust/Cargo.toml \ rust/about.hbs -o LICENSES-THIRD-PARTY-mstar_rust.txt - cargo about generate --locked -c rust/about.toml -m rust/server/Cargo.toml \ + cargo about generate --locked -c "$config" -m rust/server/Cargo.toml \ rust/about.hbs -o LICENSES-THIRD-PARTY-mstar-server.txt - uses: pypa/cibuildwheel@v4.2.1 env: @@ -82,8 +87,8 @@ jobs: # extension imports at the version mstar expects, the frontend binary # runs from the scripts directory find_server_binary looks in without # any libpython (setup-python puts its libdir on LD_LIBRARY_PATH, which - # would hide a link to one), and the licenses, where the step above - # wrote them, are in the metadata. + # would hide a link to one), and both license notices are in the + # metadata. - name: Check each wheel in a clean venv shell: python run: | @@ -95,7 +100,7 @@ jobs: assert mstar_rust.__version__ == sys.argv[1], mstar_rust.__version__ shipped = {f.name for f in md.files('mstar-ai')} for licenses in ('LICENSES-THIRD-PARTY-mstar_rust.txt', 'LICENSES-THIRD-PARTY-mstar-server.txt'): - assert not os.path.exists(licenses) or licenses in shipped, licenses + assert licenses in shipped, licenses server = pathlib.Path(sysconfig.get_path('scripts')) / 'mstar-server' needed = subprocess.run(['readelf', '-d', server], capture_output=True, text=True, check=True).stdout assert 'libpython' not in needed, needed diff --git a/PACKAGING.md b/PACKAGING.md index 7def05fdc1..10178d1f22 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -58,9 +58,10 @@ Python transport and graph runtime. - **Not published yet.** libzmq 4.3.4 (vendored by zeromq-src, statically linked into both binaries) is LGPL-3.0-or-later with its own static-linking exception, and that license is not in `accepted` until a maintainer signs off - on distributing it. Until then the license step fails, so `wheels` fails and - `pypi-wheels` is skipped; `pypi` still publishes the sdist, the pure wheel - and the aliases. + on distributing it. Until then a release's license step fails, so `wheels` + fails and `pypi-wheels` is skipped; `pypi` still publishes the sdist, the + pure wheel and the aliases. PR and manual runs accept that one license in a + temporary copy of the config, so they still build and check the wheels. - **Two copies of `mstar_rust`.** `maturin develop` (or `pip install ./rust`) installs `rust/` as a separate `mstar-rust` distribution, a `mstar_rust/` package directory. In an environment that also has a Rust wheel's top-level From 8a311660b178e616285ba5ed4f5441cff96f2791 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 19:26:38 -0700 Subject: [PATCH 22/31] release: build one CPython per arch off a release, and cancel superseded runs PR and manual runs built the whole release matrix (three CPythons per arch, each LTO-linked, then a CPU-torch venv per wheel). They now build cp312 only, with CIBW_BUILD at job level so the check counts wheels from the same value, and a newer push cancels a PR or manual run in progress. Findings: R2.3 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 17 ++++++++++++----- PACKAGING.md | 7 ++++--- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4a9f37adf6..686fd581e8 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -36,12 +36,22 @@ on: - MANIFEST.in - .github/workflows/release.yml +# A newer push supersedes a PR or manual run; a release run is never cancelled. +concurrency: + group: release-${{ github.ref }} + cancel-in-progress: ${{ github.event_name != 'release' }} + jobs: wheels: strategy: matrix: os: [ubuntu-latest, ubuntu-24.04-arm] runs-on: ${{ matrix.os }} + env: + # Version-specific rather than abi3, matching the extension that + # `maturin develop` builds and the tests exercise. PR and manual runs + # build one CPython per architecture; the check expects one wheel each. + CIBW_BUILD: ${{ github.event_name == 'release' && 'cp312-manylinux_* cp313-manylinux_* cp314-manylinux_*' || 'cp312-manylinux_*' }} steps: - uses: actions/checkout@v4 - name: Install the pinned Rust toolchain (rust-toolchain.toml) @@ -68,9 +78,6 @@ jobs: rust/about.hbs -o LICENSES-THIRD-PARTY-mstar-server.txt - uses: pypa/cibuildwheel@v4.2.1 env: - # Version-specific rather than abi3, matching the extension that - # `maturin develop` builds and the tests exercise. - CIBW_BUILD: "cp312-manylinux_* cp313-manylinux_* cp314-manylinux_*" CIBW_BEFORE_ALL_LINUX: >- curl -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain none && cd {project} && $HOME/.cargo/bin/rustup toolchain install @@ -92,7 +99,7 @@ jobs: - name: Check each wheel in a clean venv shell: python run: | - import glob, re, subprocess, tempfile + import glob, os, re, subprocess, tempfile expected = re.search(r'^EXPECTED_MSTAR_RUST_VERSION = "(.+)"$', open("mstar/communication/communicator.py").read(), re.M)[1] check = """ @@ -108,7 +115,7 @@ jobs: subprocess.run([server, '--help'], env=env, check=True) """ wheels = sorted(glob.glob("wheelhouse/*.whl")) - assert len(wheels) == 3, wheels + assert len(wheels) == len(os.environ["CIBW_BUILD"].split()), wheels for whl in wheels: py = "python3." + re.search(r"-cp3(\d+)-", whl).group(1) venv = tempfile.mkdtemp() diff --git a/PACKAGING.md b/PACKAGING.md index 10178d1f22..57cc844544 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -116,6 +116,7 @@ engine, so they need no separate upload. `python -m build` makes only the pure-Python wheel. The Linux Rust wheels need cibuildwheel (Docker) with the workflow's `CIBW_*` settings. The workflow -builds and checks them without publishing on any pull request that touches -`rust/`, the build files or the workflow, and from the Actions tab on any -branch (`Run workflow`); only a published Release runs the publishing jobs. +builds and checks them without publishing, for CPython 3.12 only, on any pull +request that touches `rust/`, the build files or the workflow, and from the +Actions tab on any branch (`Run workflow`); only a published Release builds +all three versions and runs the publishing jobs. From 91b7d8a2d463696374b1a308d2a3ddb9847b6ee0 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 19:26:57 -0700 Subject: [PATCH 23/31] docker: make the pinned toolchain the XPU image's default With --default-toolchain none and the install done inside ./mstar, cargo failed anywhere outside the clone, including the image's WORKDIR. The pinned channel, read from rust-toolchain.toml, is now the default too. Findings: R2.4 Co-Authored-By: Claude Opus 5.5 --- docker/Dockerfile.xpu | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docker/Dockerfile.xpu b/docker/Dockerfile.xpu index d2d80927c1..9e5725ed5d 100644 --- a/docker/Dockerfile.xpu +++ b/docker/Dockerfile.xpu @@ -79,8 +79,11 @@ WORKDIR /mstar-workspace ARG MSTAR_REPO=https://github.com/mstar-project/mstar.git ARG MSTAR_REF=main RUN git clone --depth 1 --branch "${MSTAR_REF}" "${MSTAR_REPO}" ./mstar -# The toolchain the checkout pins (rust-toolchain.toml). -RUN cd ./mstar && rustup toolchain install && rustc --version && cargo --version +# The toolchain the checkout pins (rust-toolchain.toml), also as the default so +# cargo works outside the clone. +RUN cd ./mstar && rustup toolchain install \ + && rustup default "$(sed -n 's/^channel = "\(.*\)"$/\1/p' rust-toolchain.toml)" \ + && cd / && rustc --version && cargo --version # uv selects the XPU index for PyTorch and TorchCodec in the single install below. # torchaudio's latest XPU wheel is 2.11; the import check below checks this pairing. From 5c1cf530ae218f6103544af27eeef91cd4a4e1db Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 19:27:07 -0700 Subject: [PATCH 24/31] docs: say who compiles rust/ and what the wheel checks cover setup.py still said only release jobs compile rust/, and PACKAGING.md's Checks bullet left out the version check, the no-libpython check and the test/rust run. Findings: R2.5 Co-Authored-By: Claude Opus 5.5 --- PACKAGING.md | 9 ++++++--- setup.py | 9 +++++---- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/PACKAGING.md b/PACKAGING.md index 57cc844544..6dd16d62c3 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -72,9 +72,12 @@ Python transport and graph runtime. deletes the other's: `pip uninstall mstar-rust` goes back to the wheel's copy. - **Checks.** Each wheel is installed without dependencies into a clean venv - outside the build container and must import `mstar_rust`, run - `mstar-server --help` and list the license file. A failure there keeps the - Rust wheels off PyPI. + outside the build container and must import `mstar_rust` at the version + `EXPECTED_MSTAR_RUST_VERSION` names, list both license notices, and have an + `mstar-server` that links no libpython and runs `--help` without + `LD_LIBRARY_PATH`. Then each is installed with its dependencies (CPU torch) + and runs `test/rust` from a copy of `test/`, so `mstar` imports from the + wheel. A failure in either keeps the Rust wheels off PyPI. ## Cutting a release diff --git a/setup.py b/setup.py index 70cddf2547..3ac779841a 100644 --- a/setup.py +++ b/setup.py @@ -36,10 +36,11 @@ def run(self): shutil.copy2(y, dst / y.name) -# Only the release's cibuildwheel jobs compile rust/: the mstar_rust extension -# and the mstar-server binary (--rust-frontend), which installs into the -# environment's scripts directory. Every other build is the pure-Python -# package, and a checkout builds both with cargo/maturin +# Only the release workflow's cibuildwheel builds (on releases, PRs and manual +# runs alike) compile rust/: the mstar_rust extension and the mstar-server +# binary (--rust-frontend), which installs into the environment's scripts +# directory. Every other build is the pure-Python package, and a checkout +# builds both with cargo/maturin # (docs/installation.rst). setuptools' editable finder cannot import a # top-level extension built in place, and compiling it would slow every # `pip install -e .`. From 23937754ee1fa77a05e2ca11abd2d67118bd92b1 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 19:27:48 -0700 Subject: [PATCH 25/31] rust: move the PyO3 bindings into bindings.rs behind one cfg lib.rs carried 16 separate #[cfg(feature = "python")] attributes, one per use, class, impl and the #[pymodule]. The bindings now live, unchanged apart from their crate:: imports, in a `bindings` module gated once, and lib.rs re-exports PyZmqCommunicator for the graph runtime. Findings: R2.6 Co-Authored-By: Claude Opus 5.5 --- rust/src/bindings.rs | 327 ++++++++++++++++++++++++++++++++++++++++ rust/src/lib.rs | 347 +------------------------------------------ 2 files changed, 331 insertions(+), 343 deletions(-) create mode 100644 rust/src/bindings.rs diff --git a/rust/src/bindings.rs b/rust/src/bindings.rs new file mode 100644 index 0000000000..20c9ff090f --- /dev/null +++ b/rust/src/bindings.rs @@ -0,0 +1,327 @@ +//! The PyO3 surface the Python wrappers drive: the `mstar_rust` module. + +use std::os::raw::{c_int, c_void}; +use std::time::Duration; + +use pyo3::exceptions::{PyRuntimeError, PyValueError}; +use pyo3::ffi; +use pyo3::prelude::*; +use pyo3::types::PyBytes; + +use crate::communicator::{RawZmqCommunicator, RecvEvent}; +use crate::shm::{SegmentedShmArena, ShmArena}; + +/// Opaque byte frames over ZMQ PUSH/PULL: ipc or tcp endpoints, lazily-cached +/// peers, and wakeup-fd polling (an eventfd wakes `recv_or_wake` instantly). +/// Encoding is the caller's (pickle today; msgpack by swapping the codec). +#[pyclass(name = "ZmqCommunicator")] +pub struct PyZmqCommunicator { + /// Behind an Arc so the graph runtime can hold a share of the SAME + /// transport and send from Rust, rather than hopping back into Python for + /// every frame. No extra lock: RawZmqCommunicator::send takes &self and + /// guards its own sockets. + inner: std::sync::Arc, +} + +impl PyZmqCommunicator { + pub fn share(&self) -> std::sync::Arc { + self.inner.clone() + } +} + +#[pymethods] +impl PyZmqCommunicator { + /// Bind the PULL inbox at `ipc://{dir}/{my_id}.ipc`. + #[new] + fn new(my_id: &str, dir: &str) -> PyResult { + Ok(Self { + inner: std::sync::Arc::new( + RawZmqCommunicator::bind(my_id, dir) + .map_err(|e| PyRuntimeError::new_err(e.to_string()))?, + ), + }) + } + + /// Bind at an explicit zmq endpoint (e.g. `tcp://0.0.0.0:5701`). + #[staticmethod] + fn bind_endpoint(my_id: &str, endpoint: &str) -> PyResult { + Ok(Self { + inner: std::sync::Arc::new( + RawZmqCommunicator::bind_endpoint(my_id, endpoint) + .map_err(|e| PyRuntimeError::new_err(e.to_string()))?, + ), + }) + } + + fn last_endpoint(&self) -> PyResult { + self.inner + .last_endpoint() + .map_err(|e| PyRuntimeError::new_err(e.to_string())) + } + + fn register_peer(&self, peer_id: &str, endpoint: &str) { + self.inner.register_peer(peer_id, endpoint); + } + + /// Poll `fd` (an eventfd) alongside the inbox; when readable, + /// `recv_or_wake` returns ("wake", None) immediately. The registrant + /// reads/clears the fd (level-triggered). + fn register_wakeup_fd(&self, fd: i32) { + self.inner.register_wakeup_fd(fd); + } + + /// Released-GIL send: a PUSH send blocks when the peer is at its + /// high-water mark, and blocking with the GIL held would freeze every + /// Python thread in the process (pyzmq releases it here too). + fn send(&self, py: Python<'_>, peer_id: &str, data: &[u8]) -> PyResult<()> { + py.detach(|| self.inner.send(peer_id, data)) + .map_err(|e| PyRuntimeError::new_err(e.to_string())) + } + + /// `send` that never blocks: false when the peer is at its high-water + /// mark, with nothing sent. + fn try_send(&self, peer_id: &str, data: &[u8]) -> PyResult { + self.inner.try_send(peer_id, data) + .map_err(|e| PyRuntimeError::new_err(e.to_string())) + } + + fn try_recv<'py>(&self, py: Python<'py>) -> Option> { + self.inner.try_recv().map(|b| PyBytes::new(py, &b)) + } + + /// Drain all currently-queued frames in one call — one GIL round-trip + /// per batch instead of one `try_recv` per message. + fn drain<'py>(&self, py: Python<'py>) -> Vec> { + let frames = py.detach(|| self.inner.drain()); + frames.iter().map(|b| PyBytes::new(py, b)).collect() + } + + fn recv_timeout<'py>(&self, py: Python<'py>, timeout_ms: u64) -> Option> { + py.detach(|| self.inner.recv_timeout(Duration::from_millis(timeout_ms))) + .map(|b| PyBytes::new(py, &b)) + } + + /// ("msg", bytes) | ("wake", None) | ("timeout", None). Raises if a + /// registered wakeup fd is closed/invalid (the registrant's bug — loud, + /// instead of degrading blocking waits into an instant-timeout spin). + fn recv_or_wake<'py>( + &self, + py: Python<'py>, + timeout_ms: u64, + ) -> PyResult<(&'static str, Option>)> { + let ev = py.detach(|| self.inner.recv_or_wake(Duration::from_millis(timeout_ms))); + Ok(match ev { + RecvEvent::Message(b) => ("msg", Some(PyBytes::new(py, &b))), + RecvEvent::Wake => ("wake", None), + RecvEvent::WakeFdError => { + return Err(PyRuntimeError::new_err( + "a registered wakeup fd is closed/invalid (POLLERR/\ + POLLNVAL): fix the EventWakeup lifetime")); + } + RecvEvent::Timeout => ("timeout", None), + }) + } +} + +/// Shared-memory tensor arena for cross-process transport. Producer: +/// `create(name, size)` -> `reserve(nbytes)` -> `torch.frombuffer( +/// memoryview(arena)[off:off+n], dtype=..).copy_(cpu_tensor)`; send the +/// offset descriptor; `free(off)` on reclaim. Consumer: `open(name)` and +/// `torch.frombuffer(memoryview(arena)[off:off+n], ..)` (then H2D). +#[pyclass(name = "ShmArena")] +struct PyShmArena { + arena: ShmArena, +} + +#[pymethods] +impl PyShmArena { + #[staticmethod] + fn create(name: &str, size: usize) -> PyResult { + Ok(Self { + arena: ShmArena::create(name, size) + .map_err(|e| PyRuntimeError::new_err(e.to_string()))?, + }) + } + + #[staticmethod] + fn open(name: &str) -> PyResult { + Ok(Self { + arena: ShmArena::open(name).map_err(|e| PyRuntimeError::new_err(e.to_string()))?, + }) + } + + fn reserve(&self, nbytes: usize) -> PyResult { + self.arena + .reserve(nbytes) + .map_err(|e| PyRuntimeError::new_err(e.to_string())) + } + + fn free(&self, offset: usize) -> bool { + self.arena.free(offset) + } + + #[getter] + fn size(&self) -> usize { + self.arena.size() + } + + #[getter] + fn bytes_free(&self) -> usize { + self.arena.bytes_free() + } + + /// `(base_ptr, len)` for the pinning hook — `cudaHostRegister` the + /// mapping once (e.g. `torch.cuda.cudart().cudaHostRegister(ptr, len, 0)`). + fn ptr_len(&self) -> (usize, usize) { + (self.arena.as_mut_ptr() as usize, self.arena.size()) + } + + fn close(&mut self) { + self.arena.close(); + } + + /// Whole arena as a writable memoryview -> zero-copy `torch.frombuffer`. + unsafe fn __getbuffer__( + slf: Bound<'_, Self>, + view: *mut ffi::Py_buffer, + flags: c_int, + ) -> PyResult<()> { + if view.is_null() { + return Err(PyValueError::new_err("null buffer view")); + } + let borrow = slf.borrow(); + let ptr = borrow.arena.as_mut_ptr() as *mut c_void; + let len = borrow.arena.size() as ffi::Py_ssize_t; + let ret = ffi::PyBuffer_FillInfo(view, slf.as_ptr(), ptr, len, 0, flags); + if ret != 0 { + Err(PyErr::fetch(slf.py())) + } else { + Ok(()) + } + } + + unsafe fn __releasebuffer__(&self, _view: *mut ffi::Py_buffer) {} +} + +/// One segment of a `SegmentedShmArena`, exposed with the buffer protocol so +/// staging stays zero-copy per segment. The mapping never moves, so a +/// memoryview (and a CUDA host-registration of the segment) stays valid for +/// the segment's lifetime. +#[pyclass(name = "ShmSegment")] +struct PyShmSegment { + seg: std::sync::Arc, +} + +#[pymethods] +impl PyShmSegment { + #[getter] + fn size(&self) -> usize { + self.seg.size() + } + + /// `(base_ptr, len)` for the pinning hook (see `ShmArena::ptr_len`). + fn ptr_len(&self) -> (usize, usize) { + (self.seg.as_mut_ptr() as usize, self.seg.size()) + } + + unsafe fn __getbuffer__( + slf: Bound<'_, Self>, + view: *mut ffi::Py_buffer, + flags: c_int, + ) -> PyResult<()> { + if view.is_null() { + return Err(PyValueError::new_err("null buffer view")); + } + let borrow = slf.borrow(); + let ptr = borrow.seg.as_mut_ptr() as *mut c_void; + let len = borrow.seg.size() as ffi::Py_ssize_t; + let ret = ffi::PyBuffer_FillInfo(view, slf.as_ptr(), ptr, len, 0, flags); + if ret != 0 { + Err(PyErr::fetch(slf.py())) + } else { + Ok(()) + } + } + + unsafe fn __releasebuffer__(&self, _view: *mut ffi::Py_buffer) {} +} + +/// Grow-by-segments producer arena with uuid-grouped reclaim. +/// `reserve(n) -> (segment_idx, offset)`; descriptors carry +/// `segment_name(idx)` so consumers keep opening plain `ShmArena`s by name. +/// Segments are created once and never move — registration-friendly. +#[pyclass(name = "SegmentedShmArena")] +struct PySegmentedShmArena { + arena: SegmentedShmArena, +} + +#[pymethods] +impl PySegmentedShmArena { + #[staticmethod] + fn create(base: &str, segment_size: usize, max_segments: usize) -> PyResult { + Ok(Self { + arena: SegmentedShmArena::create(base, segment_size, max_segments) + .map_err(|e| PyRuntimeError::new_err(e.to_string()))?, + }) + } + + /// -> (segment_idx, offset); grows by one segment when full (dedicated + /// segment for oversized allocations), errors at the max_segments cap. + /// GIL released: the growth path creates + maps a new shm segment + /// (file create, preallocate, mmap: on the order of 0.1 s per 256 MiB), + /// which must not stall other Python threads (the serve loop, stream + /// relays). + fn reserve(&self, py: Python<'_>, nbytes: usize) -> PyResult<(usize, usize)> { + py.detach(|| self.arena.reserve(nbytes)) + .map_err(|e| PyRuntimeError::new_err(e.to_string())) + } + + /// GIL released: growth (in `reserve`) holds the segments mutex + /// across an mmap for milliseconds; blocking on that mutex with the + /// GIL held would freeze every Python thread for the duration. + fn free(&self, py: Python<'_>, segment: usize, offset: usize) -> bool { + py.detach(|| self.arena.free(segment, offset)) + } + + #[getter] + fn num_segments(&self, py: Python<'_>) -> usize { + py.detach(|| self.arena.num_segments()) + } + + /// `(total_bytes, free_bytes, largest_free_block)` across all segments. + /// `largest_free_block` collapsing while `free_bytes` stays high is the + /// fragmentation signature (allocations fail / segments grow despite + /// healthy total free space). + fn stats(&self, py: Python<'_>) -> (usize, usize, usize) { + py.detach(|| self.arena.stats()) + } + + fn segment_name(&self, i: usize) -> String { + self.arena.segment_name(i) + } + + /// Shared buffer-protocol view of segment `i`. + fn segment(&self, i: usize) -> PyResult { + self.arena + .segment(i) + .map(|seg| PyShmSegment { seg }) + .ok_or_else(|| PyValueError::new_err(format!("no segment {i}"))) + } +} + +#[pymodule] +fn mstar_rust(m: &Bound<'_, PyModule>) -> PyResult<()> { + m.add("__version__", env!("CARGO_PKG_VERSION"))?; + m.add_class::()?; + m.add_class::()?; + m.add_class::()?; + m.add_class::()?; + m.add_class::()?; + m.add_class::()?; + m.add_class::()?; + m.add_class::()?; + m.add_class::()?; + m.add_class::()?; + m.add_class::()?; + Ok(()) +} diff --git a/rust/src/lib.rs b/rust/src/lib.rs index 38a1861f2a..2f704573e0 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -1,5 +1,5 @@ //! mstar's Rust components, one crate: each module is an independent -//! capability behind its own opt-in flag, and this file is the PyO3 +//! capability behind its own opt-in flag, and `bindings.rs` is the PyO3 //! surface the Python wrappers drive. Currently: `communicator.rs` (the //! ZMQ PUSH/PULL control mesh, as a transport + codec split) and `shm.rs` //! (the shared-memory tensor arena). The crate is not limited to these — @@ -9,6 +9,8 @@ //! links no Python, since the bindings, `graph` and `tensors` need pyo3. //! Build: `maturin develop --release` in rust/. +#[cfg(feature = "python")] +mod bindings; pub mod communicator; #[cfg(feature = "python")] pub mod graph; @@ -17,345 +19,4 @@ pub mod shm; pub mod tensors; #[cfg(feature = "python")] -use std::os::raw::{c_int, c_void}; -#[cfg(feature = "python")] -use std::time::Duration; - -#[cfg(feature = "python")] -use pyo3::exceptions::{PyRuntimeError, PyValueError}; -#[cfg(feature = "python")] -use pyo3::ffi; -#[cfg(feature = "python")] -use pyo3::prelude::*; -#[cfg(feature = "python")] -use pyo3::types::PyBytes; - -#[cfg(feature = "python")] -use communicator::{RawZmqCommunicator, RecvEvent}; -#[cfg(feature = "python")] -use shm::{SegmentedShmArena, ShmArena}; - -/// Opaque byte frames over ZMQ PUSH/PULL: ipc or tcp endpoints, lazily-cached -/// peers, and wakeup-fd polling (an eventfd wakes `recv_or_wake` instantly). -/// Encoding is the caller's (pickle today; msgpack by swapping the codec). -#[cfg(feature = "python")] -#[pyclass(name = "ZmqCommunicator")] -pub struct PyZmqCommunicator { - /// Behind an Arc so the graph runtime can hold a share of the SAME - /// transport and send from Rust, rather than hopping back into Python for - /// every frame. No extra lock: RawZmqCommunicator::send takes &self and - /// guards its own sockets. - inner: std::sync::Arc, -} - -#[cfg(feature = "python")] -impl PyZmqCommunicator { - pub fn share(&self) -> std::sync::Arc { - self.inner.clone() - } -} - -#[cfg(feature = "python")] -#[pymethods] -impl PyZmqCommunicator { - /// Bind the PULL inbox at `ipc://{dir}/{my_id}.ipc`. - #[new] - fn new(my_id: &str, dir: &str) -> PyResult { - Ok(Self { - inner: std::sync::Arc::new( - RawZmqCommunicator::bind(my_id, dir) - .map_err(|e| PyRuntimeError::new_err(e.to_string()))?, - ), - }) - } - - /// Bind at an explicit zmq endpoint (e.g. `tcp://0.0.0.0:5701`). - #[staticmethod] - fn bind_endpoint(my_id: &str, endpoint: &str) -> PyResult { - Ok(Self { - inner: std::sync::Arc::new( - RawZmqCommunicator::bind_endpoint(my_id, endpoint) - .map_err(|e| PyRuntimeError::new_err(e.to_string()))?, - ), - }) - } - - fn last_endpoint(&self) -> PyResult { - self.inner - .last_endpoint() - .map_err(|e| PyRuntimeError::new_err(e.to_string())) - } - - fn register_peer(&self, peer_id: &str, endpoint: &str) { - self.inner.register_peer(peer_id, endpoint); - } - - /// Poll `fd` (an eventfd) alongside the inbox; when readable, - /// `recv_or_wake` returns ("wake", None) immediately. The registrant - /// reads/clears the fd (level-triggered). - fn register_wakeup_fd(&self, fd: i32) { - self.inner.register_wakeup_fd(fd); - } - - /// Released-GIL send: a PUSH send blocks when the peer is at its - /// high-water mark, and blocking with the GIL held would freeze every - /// Python thread in the process (pyzmq releases it here too). - fn send(&self, py: Python<'_>, peer_id: &str, data: &[u8]) -> PyResult<()> { - py.detach(|| self.inner.send(peer_id, data)) - .map_err(|e| PyRuntimeError::new_err(e.to_string())) - } - - /// `send` that never blocks: false when the peer is at its high-water - /// mark, with nothing sent. - fn try_send(&self, peer_id: &str, data: &[u8]) -> PyResult { - self.inner.try_send(peer_id, data) - .map_err(|e| PyRuntimeError::new_err(e.to_string())) - } - - fn try_recv<'py>(&self, py: Python<'py>) -> Option> { - self.inner.try_recv().map(|b| PyBytes::new(py, &b)) - } - - /// Drain all currently-queued frames in one call — one GIL round-trip - /// per batch instead of one `try_recv` per message. - fn drain<'py>(&self, py: Python<'py>) -> Vec> { - let frames = py.detach(|| self.inner.drain()); - frames.iter().map(|b| PyBytes::new(py, b)).collect() - } - - fn recv_timeout<'py>(&self, py: Python<'py>, timeout_ms: u64) -> Option> { - py.detach(|| self.inner.recv_timeout(Duration::from_millis(timeout_ms))) - .map(|b| PyBytes::new(py, &b)) - } - - /// ("msg", bytes) | ("wake", None) | ("timeout", None). Raises if a - /// registered wakeup fd is closed/invalid (the registrant's bug — loud, - /// instead of degrading blocking waits into an instant-timeout spin). - fn recv_or_wake<'py>( - &self, - py: Python<'py>, - timeout_ms: u64, - ) -> PyResult<(&'static str, Option>)> { - let ev = py.detach(|| self.inner.recv_or_wake(Duration::from_millis(timeout_ms))); - Ok(match ev { - RecvEvent::Message(b) => ("msg", Some(PyBytes::new(py, &b))), - RecvEvent::Wake => ("wake", None), - RecvEvent::WakeFdError => { - return Err(PyRuntimeError::new_err( - "a registered wakeup fd is closed/invalid (POLLERR/\ - POLLNVAL): fix the EventWakeup lifetime")); - } - RecvEvent::Timeout => ("timeout", None), - }) - } -} - -/// Shared-memory tensor arena for cross-process transport. Producer: -/// `create(name, size)` -> `reserve(nbytes)` -> `torch.frombuffer( -/// memoryview(arena)[off:off+n], dtype=..).copy_(cpu_tensor)`; send the -/// offset descriptor; `free(off)` on reclaim. Consumer: `open(name)` and -/// `torch.frombuffer(memoryview(arena)[off:off+n], ..)` (then H2D). -#[cfg(feature = "python")] -#[pyclass(name = "ShmArena")] -struct PyShmArena { - arena: ShmArena, -} - -#[cfg(feature = "python")] -#[pymethods] -impl PyShmArena { - #[staticmethod] - fn create(name: &str, size: usize) -> PyResult { - Ok(Self { - arena: ShmArena::create(name, size) - .map_err(|e| PyRuntimeError::new_err(e.to_string()))?, - }) - } - - #[staticmethod] - fn open(name: &str) -> PyResult { - Ok(Self { - arena: ShmArena::open(name).map_err(|e| PyRuntimeError::new_err(e.to_string()))?, - }) - } - - fn reserve(&self, nbytes: usize) -> PyResult { - self.arena - .reserve(nbytes) - .map_err(|e| PyRuntimeError::new_err(e.to_string())) - } - - fn free(&self, offset: usize) -> bool { - self.arena.free(offset) - } - - #[getter] - fn size(&self) -> usize { - self.arena.size() - } - - #[getter] - fn bytes_free(&self) -> usize { - self.arena.bytes_free() - } - - /// `(base_ptr, len)` for the pinning hook — `cudaHostRegister` the - /// mapping once (e.g. `torch.cuda.cudart().cudaHostRegister(ptr, len, 0)`). - fn ptr_len(&self) -> (usize, usize) { - (self.arena.as_mut_ptr() as usize, self.arena.size()) - } - - fn close(&mut self) { - self.arena.close(); - } - - /// Whole arena as a writable memoryview -> zero-copy `torch.frombuffer`. - unsafe fn __getbuffer__( - slf: Bound<'_, Self>, - view: *mut ffi::Py_buffer, - flags: c_int, - ) -> PyResult<()> { - if view.is_null() { - return Err(PyValueError::new_err("null buffer view")); - } - let borrow = slf.borrow(); - let ptr = borrow.arena.as_mut_ptr() as *mut c_void; - let len = borrow.arena.size() as ffi::Py_ssize_t; - let ret = ffi::PyBuffer_FillInfo(view, slf.as_ptr(), ptr, len, 0, flags); - if ret != 0 { - Err(PyErr::fetch(slf.py())) - } else { - Ok(()) - } - } - - unsafe fn __releasebuffer__(&self, _view: *mut ffi::Py_buffer) {} -} - -/// One segment of a `SegmentedShmArena`, exposed with the buffer protocol so -/// staging stays zero-copy per segment. The mapping never moves, so a -/// memoryview (and a CUDA host-registration of the segment) stays valid for -/// the segment's lifetime. -#[cfg(feature = "python")] -#[pyclass(name = "ShmSegment")] -struct PyShmSegment { - seg: std::sync::Arc, -} - -#[cfg(feature = "python")] -#[pymethods] -impl PyShmSegment { - #[getter] - fn size(&self) -> usize { - self.seg.size() - } - - /// `(base_ptr, len)` for the pinning hook (see `ShmArena::ptr_len`). - fn ptr_len(&self) -> (usize, usize) { - (self.seg.as_mut_ptr() as usize, self.seg.size()) - } - - unsafe fn __getbuffer__( - slf: Bound<'_, Self>, - view: *mut ffi::Py_buffer, - flags: c_int, - ) -> PyResult<()> { - if view.is_null() { - return Err(PyValueError::new_err("null buffer view")); - } - let borrow = slf.borrow(); - let ptr = borrow.seg.as_mut_ptr() as *mut c_void; - let len = borrow.seg.size() as ffi::Py_ssize_t; - let ret = ffi::PyBuffer_FillInfo(view, slf.as_ptr(), ptr, len, 0, flags); - if ret != 0 { - Err(PyErr::fetch(slf.py())) - } else { - Ok(()) - } - } - - unsafe fn __releasebuffer__(&self, _view: *mut ffi::Py_buffer) {} -} - -/// Grow-by-segments producer arena with uuid-grouped reclaim. -/// `reserve(n) -> (segment_idx, offset)`; descriptors carry -/// `segment_name(idx)` so consumers keep opening plain `ShmArena`s by name. -/// Segments are created once and never move — registration-friendly. -#[cfg(feature = "python")] -#[pyclass(name = "SegmentedShmArena")] -struct PySegmentedShmArena { - arena: SegmentedShmArena, -} - -#[cfg(feature = "python")] -#[pymethods] -impl PySegmentedShmArena { - #[staticmethod] - fn create(base: &str, segment_size: usize, max_segments: usize) -> PyResult { - Ok(Self { - arena: SegmentedShmArena::create(base, segment_size, max_segments) - .map_err(|e| PyRuntimeError::new_err(e.to_string()))?, - }) - } - - /// -> (segment_idx, offset); grows by one segment when full (dedicated - /// segment for oversized allocations), errors at the max_segments cap. - /// GIL released: the growth path creates + maps a new shm segment - /// (file create, preallocate, mmap: on the order of 0.1 s per 256 MiB), - /// which must not stall other Python threads (the serve loop, stream - /// relays). - fn reserve(&self, py: Python<'_>, nbytes: usize) -> PyResult<(usize, usize)> { - py.detach(|| self.arena.reserve(nbytes)) - .map_err(|e| PyRuntimeError::new_err(e.to_string())) - } - - /// GIL released: growth (in `reserve`) holds the segments mutex - /// across an mmap for milliseconds; blocking on that mutex with the - /// GIL held would freeze every Python thread for the duration. - fn free(&self, py: Python<'_>, segment: usize, offset: usize) -> bool { - py.detach(|| self.arena.free(segment, offset)) - } - - #[getter] - fn num_segments(&self, py: Python<'_>) -> usize { - py.detach(|| self.arena.num_segments()) - } - - /// `(total_bytes, free_bytes, largest_free_block)` across all segments. - /// `largest_free_block` collapsing while `free_bytes` stays high is the - /// fragmentation signature (allocations fail / segments grow despite - /// healthy total free space). - fn stats(&self, py: Python<'_>) -> (usize, usize, usize) { - py.detach(|| self.arena.stats()) - } - - fn segment_name(&self, i: usize) -> String { - self.arena.segment_name(i) - } - - /// Shared buffer-protocol view of segment `i`. - fn segment(&self, i: usize) -> PyResult { - self.arena - .segment(i) - .map(|seg| PyShmSegment { seg }) - .ok_or_else(|| PyValueError::new_err(format!("no segment {i}"))) - } -} - -#[cfg(feature = "python")] -#[pymodule] -fn mstar_rust(m: &Bound<'_, PyModule>) -> PyResult<()> { - m.add("__version__", env!("CARGO_PKG_VERSION"))?; - m.add_class::()?; - m.add_class::()?; - m.add_class::()?; - m.add_class::()?; - m.add_class::()?; - m.add_class::()?; - m.add_class::()?; - m.add_class::()?; - m.add_class::()?; - m.add_class::()?; - m.add_class::()?; - Ok(()) -} +pub use bindings::PyZmqCommunicator; From 78e45bf42d010f255097805e792c7ad241c7578c Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 19:28:16 -0700 Subject: [PATCH 26/31] MANIFEST.in: ship rust/ and rust-toolchain.toml in the sdist The sdist had only configs/, so `CIBUILDWHEEL=1 pip wheel ` failed on the missing rust/Cargo.toml and a packager building from the sdist could not produce the Rust build. A plain sdist install still builds pure Python; the tracked rust/ sources are about 0.7 MB. Findings: R2.7 Co-Authored-By: Claude Opus 5.5 --- MANIFEST.in | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/MANIFEST.in b/MANIFEST.in index 254f8aa7cf..f8a1d62659 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,10 @@ # Carry the default deployment configs into the sdist so a wheel built from it # can copy them into mstar/default_configs/ (see setup.py). graft configs +# rust/ and the pinned toolchain, so the Rust wheels can be built from the +# sdist too (setup.py compiles them under CIBUILDWHEEL=1). +graft rust +prune rust/target +prune rust/server/target +include rust-toolchain.toml global-exclude __pycache__ *.py[cod] From d34e1783baf5508f1cc783530c79ee432f4ed39a Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 19:28:16 -0700 Subject: [PATCH 27/31] release: read-only token by default, and no credentials left in checkouts The workflow had no top-level permissions, and now that pull_request runs build PR code, the wheels job's checkout kept its token in .git, which cibuildwheel copies into the build container. The default is now contents: read, only the two publish jobs add id-token: write, and both checkouts set persist-credentials: false (nothing later needs git auth). Findings: R2.8 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 686fd581e8..16c06c21a4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -36,6 +36,10 @@ on: - MANIFEST.in - .github/workflows/release.yml +# Read-only by default: PR runs build PR code. The publish jobs add id-token. +permissions: + contents: read + # A newer push supersedes a PR or manual run; a release run is never cancelled. concurrency: group: release-${{ github.ref }} @@ -54,6 +58,8 @@ jobs: CIBW_BUILD: ${{ github.event_name == 'release' && 'cp312-manylinux_* cp313-manylinux_* cp314-manylinux_*' || 'cp312-manylinux_*' }} steps: - uses: actions/checkout@v4 + with: + persist-credentials: false - name: Install the pinned Rust toolchain (rust-toolchain.toml) run: rustup toolchain install - uses: taiki-e/install-action@v2 @@ -155,9 +161,12 @@ jobs: runs-on: ubuntu-latest environment: pypi permissions: + contents: read id-token: write steps: - uses: actions/checkout@v4 + with: + persist-credentials: false - uses: actions/setup-python@v5 with: python-version: "3.12" From 12d03d452e3475e6659d1a8ca0efc3168ec6aca5 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 19:43:24 -0700 Subject: [PATCH 28/31] release: key the concurrency group on the event, and fix two comments With the group keyed only on the ref, a manual run on a release tag joined the release run's group and could cancel it. The group now includes the event name. The concurrency comment no longer says a release run is never superseded (a newer one still replaces a pending one), and the license step's garbled sentence is rewritten. Findings: R3.1, R3.3 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 16c06c21a4..71a6bcea5f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -40,9 +40,11 @@ on: permissions: contents: read -# A newer push supersedes a PR or manual run; a release run is never cancelled. +# A newer PR or manual run on the same ref cancels one in progress. Release +# runs have their own group, so neither of those can cancel one; a release run +# is never cancelled in progress, though a newer one still replaces a pending one. concurrency: - group: release-${{ github.ref }} + group: release-${{ github.event_name }}-${{ github.ref }} cancel-in-progress: ${{ github.event_name != 'release' }} jobs: @@ -67,10 +69,10 @@ jobs: tool: cargo-about@0.9.2 # The licenses of the crates and vendored C/C++ compiled into the wheel, # shipped in its dist-info/licenses (setuptools' default LICEN[CS]E* - # glob). Fails on any license rust/about.toml does not accept. Until a - # maintainer signs off on libzmq's LGPL-3.0-or-later that includes - # libzmq, so PR and manual runs, which publish nothing, accept that one - # license in a copy of the config and stay strict about every other. + # glob). Fails on any license rust/about.toml does not accept, which until + # a maintainer signs off includes libzmq's LGPL-3.0-or-later. PR and + # manual runs, which publish nothing, accept that one license in a copy + # of the config and stay strict about every other. - name: Collect third-party licenses run: | config=rust/about.toml From 5977093e895e8973ee6bf0aaf6fa783f49fa3653 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 19:43:24 -0700 Subject: [PATCH 29/31] setup.py, MANIFEST.in: say what gates the Rust build and what an sdist build needs The gate is CIBUILDWHEEL=1, not the release workflow, now that the sdist carries rust/. The notices are generated only by the wheels job, so a Rust build from the sdist has to run the two cargo about commands first. Findings: R3.2 Co-Authored-By: Claude Opus 5.5 --- MANIFEST.in | 4 +++- setup.py | 15 +++++++-------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/MANIFEST.in b/MANIFEST.in index f8a1d62659..3b14c00b9e 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -2,7 +2,9 @@ # can copy them into mstar/default_configs/ (see setup.py). graft configs # rust/ and the pinned toolchain, so the Rust wheels can be built from the -# sdist too (setup.py compiles them under CIBUILDWHEEL=1). +# sdist too (setup.py compiles them under CIBUILDWHEEL=1). Such a build must +# first run release.yml's two `cargo about generate` commands, or its wheels +# carry no third-party notices. graft rust prune rust/target prune rust/server/target diff --git a/setup.py b/setup.py index 3ac779841a..8422e638e2 100644 --- a/setup.py +++ b/setup.py @@ -36,14 +36,13 @@ def run(self): shutil.copy2(y, dst / y.name) -# Only the release workflow's cibuildwheel builds (on releases, PRs and manual -# runs alike) compile rust/: the mstar_rust extension and the mstar-server -# binary (--rust-frontend), which installs into the environment's scripts -# directory. Every other build is the pure-Python package, and a checkout -# builds both with cargo/maturin -# (docs/installation.rst). setuptools' editable finder cannot import a -# top-level extension built in place, and compiling it would slow every -# `pip install -e .`. +# Only a CIBUILDWHEEL=1 build compiles rust/ (the release workflow's +# cibuildwheel builds, or a build from the sdist): the mstar_rust extension and +# the mstar-server binary (--rust-frontend), which installs into the +# environment's scripts directory. Every other build is the pure-Python +# package, and a checkout builds both with cargo/maturin (docs/installation.rst). +# setuptools' editable finder cannot import a top-level extension built in +# place, and compiling it would slow every `pip install -e .`. rust_extensions = [] if os.environ.get("CIBUILDWHEEL") == "1": from setuptools_rust import Binding, RustBin, RustExtension, Strip From 371f541ea3b002891314a97b4cee66befea0cd69 Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 21:59:25 -0700 Subject: [PATCH 30/31] Build the vendored libzmq with posix_memalign zmq-sys compiles libzmq from zeromq-src, which never defines HAVE_POSIX_MEMALIGN. libzmq then allocates its command queues with malloc (16-byte aligned) although command_t is aligned(64). GCC on GitHub's ubuntu-26.04 runners comes from Ubuntu's amd64v3 builds and targets x86-64-v3 by default, so it copies command_t with vmovdqa ymm stores; the first one into a malloc'd chunk faults, in zmq::mailbox_t::send on the first communicator test. main passes only because its rust-transport cache still holds a libzmq built on ubuntu-24.04; this PR's lockfile change missed that cache. Define what libzmq's own build detects on Linux, through a root .cargo/config.toml so that every cargo run in the repo (rust/, rust/server, setup.py's wheel builds) sees it, and ship that file in the sdist. Co-Authored-By: Claude Opus 5.5 --- .cargo/config.toml | 11 +++++++++++ .github/workflows/release.yml | 1 + MANIFEST.in | 2 ++ 3 files changed, 14 insertions(+) create mode 100644 .cargo/config.toml diff --git a/.cargo/config.toml b/.cargo/config.toml new file mode 100644 index 0000000000..1550338737 --- /dev/null +++ b/.cargo/config.toml @@ -0,0 +1,11 @@ +# zmq-sys compiles libzmq from zeromq-src, which never defines +# HAVE_POSIX_MEMALIGN, so libzmq malloc()s its command queues (16-byte aligned) +# although command_t is declared aligned(64). A compiler that targets AVX2, such +# as GCC on Ubuntu 26.04's amd64v3 builds, then copies command_t with aligned +# 32-byte stores, which segfault on the first message. These are the values +# libzmq's own build detects on Linux. The per-target variables add to any +# CXXFLAGS in the environment instead of being replaced by it. At the repository +# root so that cargo runs from here (setup.py, `--manifest-path rust/...`) see it. +[env] +CXXFLAGS_x86_64_unknown_linux_gnu = "-DHAVE_POSIX_MEMALIGN=1 -DZMQ_CACHELINE_SIZE=64" +CXXFLAGS_aarch64_unknown_linux_gnu = "-DHAVE_POSIX_MEMALIGN=1 -DZMQ_CACHELINE_SIZE=64" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 71a6bcea5f..72ab1cbe82 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -31,6 +31,7 @@ on: paths: - "rust/**" - rust-toolchain.toml + - .cargo/config.toml - setup.py - pyproject.toml - MANIFEST.in diff --git a/MANIFEST.in b/MANIFEST.in index 3b14c00b9e..e463efa762 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -9,4 +9,6 @@ graft rust prune rust/target prune rust/server/target include rust-toolchain.toml +# the cargo [env] that builds the vendored libzmq correctly (see the file) +include .cargo/config.toml global-exclude __pycache__ *.py[cod] From b299afc81978e63b15158a90854adcc4b20a5bed Mon Sep 17 00:00:00 2001 From: Joseph Tan Date: Tue, 27 Oct 2026 22:03:21 -0700 Subject: [PATCH 31/31] Accept libzmq's LGPL so the Linux wheels publish rust/about.toml now accepts libzmq 4.3.4's license, declared as LGPL-3.0-or-later WITH AdditionRef-libzmq-static-linking-exception: no SPDX exception id matches the static-linking exception at the end of its COPYING.LESSER, and the notices carry that whole file, exception included. With it accepted, PR and release runs use the same config, so the temporary copy that tolerated LGPL on PR runs goes, and a release's pypi-wheels job publishes the Linux wheels; it stays a separate job so a failing wheels build still holds back only them. README, installation.rst and PACKAGING.md no longer say the wheels are off PyPI, and say where libzmq's source is: the upstream v4.3.4 release that zeromq-src vendors unmodified. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release.yml | 17 ++++------------- PACKAGING.md | 13 ++++++------- README.md | 4 ++-- docs/installation.rst | 15 +++++++++------ rust/about.toml | 18 +++++++++--------- 5 files changed, 30 insertions(+), 37 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 72ab1cbe82..afd55c527f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -18,8 +18,7 @@ name: Publish to PyPI # compiles rust/ only under cibuildwheel). pip prefers the Linux wheel where # one matches and falls back to the pure one elsewhere, which then runs on the # Python transport and graph runtime. The Linux wheels publish in their own -# job, so a failure in `wheels` (the license check fails until libzmq is -# accepted in rust/about.toml) holds back only them. +# job, so a failure in `wheels` holds back only them. on: release: @@ -70,20 +69,12 @@ jobs: tool: cargo-about@0.9.2 # The licenses of the crates and vendored C/C++ compiled into the wheel, # shipped in its dist-info/licenses (setuptools' default LICEN[CS]E* - # glob). Fails on any license rust/about.toml does not accept, which until - # a maintainer signs off includes libzmq's LGPL-3.0-or-later. PR and - # manual runs, which publish nothing, accept that one license in a copy - # of the config and stay strict about every other. + # glob). Fails on any license rust/about.toml does not accept. - name: Collect third-party licenses run: | - config=rust/about.toml - if [ "$GITHUB_EVENT_NAME" != release ]; then - config="$RUNNER_TEMP/about.toml" - sed '/^accepted = \[$/a "LGPL-3.0-or-later",' rust/about.toml > "$config" - fi - cargo about generate --locked -c "$config" -m rust/Cargo.toml \ + cargo about generate --locked -c rust/about.toml -m rust/Cargo.toml \ rust/about.hbs -o LICENSES-THIRD-PARTY-mstar_rust.txt - cargo about generate --locked -c "$config" -m rust/server/Cargo.toml \ + cargo about generate --locked -c rust/about.toml -m rust/server/Cargo.toml \ rust/about.hbs -o LICENSES-THIRD-PARTY-mstar-server.txt - uses: pypa/cibuildwheel@v4.2.1 env: diff --git a/PACKAGING.md b/PACKAGING.md index 6dd16d62c3..5f4121a0f6 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -55,13 +55,12 @@ Python transport and graph runtime. fails the `wheels` job. The C/C++ that crates vendor is declared there by hand (libzmq via zeromq-src, Oniguruma via onig_sys, esaxx via esaxx-rs); check those entries when bumping those crates. -- **Not published yet.** libzmq 4.3.4 (vendored by zeromq-src, statically - linked into both binaries) is LGPL-3.0-or-later with its own static-linking - exception, and that license is not in `accepted` until a maintainer signs off - on distributing it. Until then a release's license step fails, so `wheels` - fails and `pypi-wheels` is skipped; `pypi` still publishes the sdist, the - pure wheel and the aliases. PR and manual runs accept that one license in a - temporary copy of the config, so they still build and check the wheels. +- **libzmq.** libzmq 4.3.4, statically linked into both binaries, is + LGPL-3.0-or-later with its own static-linking exception (the end of its + `COPYING.LESSER`, which the notices carry in full). Its source is the + unmodified upstream release that the zeromq-src 0.2.6+4.3.4 crate vendors: + . The build only adds + defines (`.cargo/config.toml`). - **Two copies of `mstar_rust`.** `maturin develop` (or `pip install ./rust`) installs `rust/` as a separate `mstar-rust` distribution, a `mstar_rust/` package directory. In an environment that also has a Rust wheel's top-level diff --git a/README.md b/README.md index b5da9a1209..6fb16fd59e 100644 --- a/README.md +++ b/README.md @@ -168,8 +168,8 @@ Note what AUTO-by-default means: on any machine where the extension is built, th mesh switches to the Rust transport with no configuration change — each process logs its choice at startup (`control mesh transport: ...`), and `MSTAR_RUST_ZMQ=0` pins pyzmq. Build it with [maturin](https://www.maturin.rs): `uv pip install maturin && maturin develop --release -m rust/Cargo.toml`. -The release workflow also builds Linux wheels that carry it; they are not on PyPI yet -([PACKAGING.md](PACKAGING.md) says why). +The Linux wheels of `mstar-ai` on PyPI carry it, with libzmq 4.3.4 statically linked under +LGPL-3.0-or-later and its static-linking exception ([PACKAGING.md](PACKAGING.md) has where its source is). See the [installation docs](https://m-star.org/mstar/installation.html) and [environment variables](https://m-star.org/mstar/environment_variables.html). diff --git a/docs/installation.rst b/docs/installation.rst index d2176cb7a7..5a9a3bccae 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -490,12 +490,15 @@ runs on the pure-Python paths as before. Migrated so far (see wherever that holds, so on a machine with the extension built, installing it is what moves a worker onto the Rust runtime. -The release workflow also builds Linux wheels of ``mstar-ai`` (x86_64 and -aarch64, CPython 3.12 to 3.14) that carry the extension, but they are not on -PyPI yet (``PACKAGING.md`` says why), so ``pip install mstar-ai`` gets the -pure-Python wheel. Build the extension into your environment with `maturin -`_ (needs `rustup `_, which installs -the compiler version pinned in ``rust-toolchain.toml``): +The Linux wheels of ``mstar-ai`` on PyPI (x86_64 and aarch64, CPython 3.12 to +3.14) carry the extension, so ``pip install mstar-ai`` there gets it; other +platforms get the pure-Python wheel. The extension statically links libzmq +4.3.4, under LGPL-3.0-or-later with its static-linking exception; its source is +the upstream `v4.3.4 release `_. +Elsewhere, or to build from a checkout, build the extension into your +environment with `maturin `_ (needs `rustup +`_, which installs the compiler version pinned in +``rust-toolchain.toml``): .. code-block:: bash diff --git a/rust/about.toml b/rust/about.toml index 65c34462ce..00299d155a 100644 --- a/rust/about.toml +++ b/rust/about.toml @@ -6,6 +6,7 @@ accepted = [ "Apache-2.0", "Apache-2.0 WITH LLVM-exception", + "LGPL-3.0-or-later WITH AdditionRef-libzmq-static-linking-exception", "BSD-2-Clause", "BSD-3-Clause", "BSL-1.0", @@ -28,22 +29,21 @@ workarounds = ["ring"] # C/C++ sources that are compiled into the binaries. onig_sys and esaxx-rs are # only in rust/server's tree, so the rust/ run warns that they are absent. -# libzmq 4.3.4: LGPL-3.0 plus a static-linking exception appended to -# COPYING.LESSER, and the BSD-3-Clause SHA-1 it compiles. The exception is -# libzmq's own Classpath-style text, which matches no SPDX exception id -# (LGPL-3.0-linking-exception is different text). LGPL-3.0-or-later is left out -# of `accepted` on purpose: until a maintainer signs off on distributing libzmq -# under it, cargo-about fails here and the release publishes no Rust wheels -# (the sdist and pure wheel still go up). +# libzmq 4.3.4: LGPL-3.0-or-later plus the static-linking exception appended to +# its COPYING.LESSER ("SPECIAL EXCEPTION GRANTED BY COPYRIGHT HOLDERS"), and +# the BSD-3-Clause SHA-1 it compiles. The exception is libzmq's own +# Classpath-style text, which matches no SPDX exception id +# (LGPL-3.0-linking-exception is different text), hence the AdditionRef. The +# notice carries the whole COPYING.LESSER, exception included. [zeromq-src.clarify] -license = "(MIT OR Apache-2.0) AND LGPL-3.0-or-later AND BSD-3-Clause" +license = "(MIT OR Apache-2.0) AND (LGPL-3.0-or-later WITH AdditionRef-libzmq-static-linking-exception) AND BSD-3-Clause" [[zeromq-src.clarify.files]] path = "LICENSE-MIT" license = "MIT" checksum = "23f18e03dc49df91622fe2a76176497404e46ced8a715d9d2b67a7446571cca3" [[zeromq-src.clarify.files]] path = "vendor/COPYING.LESSER" -license = "LGPL-3.0-or-later" +license = "LGPL-3.0-or-later WITH AdditionRef-libzmq-static-linking-exception" checksum = "83f32abe61ee58ffb1b007412c08415168c052501dbf56d7a47aaaac52b03ef6" [[zeromq-src.clarify.files]] path = "vendor/external/sha1/sha1.c"