tarsk 0.1.0__tar.gz

tarsk-0.1.0/.github/workflows/bench.yml

@@ -0,0 +1,64 @@
+name: bench
+
+# Manual only. A benchmark on a shared runner is worth running when you want it,
+# not on every push: it takes about twenty minutes and its absolute numbers are
+# not comparable between runs on different machines.
+on:
+  workflow_dispatch:
+    inputs:
+      scenarios:
+        description: "scenarios to run, space separated (empty = all)"
+        required: false
+        default: ""
+
+jobs:
+  bench:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Report the machine
+        # Every absolute number below depends on these. A run with a different
+        # core count is a different experiment, not a later data point.
+        run: |
+          echo "cores: $(nproc)"
+          free -m | sed -n 2p
+          lscpu | grep -E "Model name|MHz" || true
+
+      - name: Install Redis
+        # Only Redis: no bench scenario touches Postgres, and the tests that do
+        # are not what this workflow runs. The harness starts its own instance
+        # on its own port, so the one apt starts is stopped to keep it out of
+        # the way.
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq redis-server
+          sudo systemctl stop redis-server || true
+
+      - name: Allow a memory-limited scope
+        # The runner is started from a service and has no user session bus, so
+        # `systemd-run --user` fails. The harness falls back to `sudo -n`, which
+        # is available here; this step only proves it before twenty minutes of
+        # work rather than after.
+        run: |
+          sudo -n systemd-run --scope -q -p MemoryMax=64M -p MemorySwapMax=0 -- true
+          echo "memory-limited scopes work"
+
+      - name: Build the extension
+        run: |
+          python -m venv .venv
+          .venv/bin/pip install -q maturin celery taskiq taskiq-redis redis
+          .venv/bin/maturin develop --release
+
+      - name: Run the benchmark
+        run: .venv/bin/python bench/run.py ${{ inputs.scenarios }} | tee bench-output.md
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: bench-${{ github.sha }}
+          path: bench-output.md

tarsk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,148 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.14t from day one (spec §7). It is not the default path — the memory
+        # guarantee comes from processes, not threads — but a free-threading
+        # break should show up here rather than in someone's deploy.
+        python: ["3.11", "3.13", "3.14", "3.14t"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      # The broker tests start their own servers on free ports; these are just
+      # the binaries. Postgres ships with the runner image.
+      - run: sudo apt-get update && sudo apt-get install -y redis-server
+
+      # A venv so `maturin develop` puts the extension in the source tree,
+      # which is where the tests add ROOT to sys.path expects to find it.
+      - run: python -m venv .venv
+      - run: .venv/bin/pip install --upgrade pip maturin msgpack
+      - run: .venv/bin/maturin develop --release
+
+      - run: .venv/bin/python tests/test_ipc.py
+      - run: .venv/bin/python tests/test_recycle.py
+      - run: .venv/bin/python tests/test_brokers.py
+
+      # The definition of done, at a length CI can afford. Exits non-zero if a
+      # single task went missing.
+      - run: .venv/bin/python demo/run.py --minutes 1 --ceiling 150MB --rate 30
+
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo fmt --check
+      - run: cargo clippy --all-targets -- -D warnings
+      - run: cargo test --lib
+
+  test-macos:
+    # The wheel has been built for macOS since the first CI commit and nothing
+    # had ever run there, so "Linux and macOS" in pyproject.toml was a guess.
+    # Everything platform-specific here is a candidate: RSS accounting through
+    # sysinfo, ru_maxrss being bytes rather than kilobytes, and the spawn and
+    # socket paths.
+    runs-on: macos-14
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install Redis and Postgres
+        run: |
+          brew install -q redis postgresql@16
+          # The harness starts its own instances and finds initdb by globbing
+          # Homebrew's opt directory, so nothing needs to be on PATH or running.
+          brew services stop redis 2>/dev/null || true
+      - name: Build and test
+        run: |
+          python -m venv .venv
+          .venv/bin/pip install -q maturin msgpack
+          .venv/bin/maturin develop --release
+          .venv/bin/python tests/rss_probe.py
+          .venv/bin/python tests/test_ipc.py
+          .venv/bin/python tests/test_recycle.py
+          .venv/bin/python tests/test_brokers.py
+
+  test-windows:
+    # No Redis and no Postgres: neither ships for Windows, so this runs the two
+    # suites that use the in-process memory broker. That still exercises the
+    # part that is actually different — spawning a child, the named pipe, the
+    # protocol, RSS accounting and the recycling ceiling.
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Build and test
+        run: |
+          python -m venv .venv
+          .venv\Scripts\pip install -q maturin msgpack
+          .venv\Scripts\maturin develop --release
+          .venv\Scripts\python tests/rss_probe.py
+          .venv\Scripts\python tests/test_ipc.py
+          .venv\Scripts\python tests/test_recycle.py
+
+  wheels:
+    # Proves the matrix builds; publishing is a separate, deliberate step.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-24.04, target: x86_64 }
+          # aarch64 cross-compiles through zig rather than the manylinux
+          # container's toolchain. rustls pulls in ring, whose ARM assembly the
+          # container's assembler rejects with `#error "ARM assembler must
+          # define __ARM_ARCH"`. zig cc gets the target flags right; verified by
+          # building this wheel on an x86_64 host before it was written here.
+          - { os: ubuntu-24.04, target: aarch64, zig: true }
+          - { os: macos-14, target: universal2-apple-darwin }
+          - { os: windows-latest, target: x64 }
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Provide zig
+        if: matrix.zig
+        # maturin looks for a `zig` binary on PATH; the pip package is a Python
+        # module, so it needs a shim.
+        run: |
+          python -m pip install --quiet ziglang
+          mkdir -p "$HOME/.local/bin"
+          printf '#!/bin/sh\nexec %s -m ziglang "$@"\n' "$(which python)" > "$HOME/.local/bin/zig"
+          chmod +x "$HOME/.local/bin/zig"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist ${{ matrix.zig && '--zig' || '' }}
+          # zig cross-compiles on the host and tags the wheel manylinux itself,
+          # so the container would only get in the way of finding it.
+          container: ${{ matrix.zig && 'off' || 'auto' }}
+          manylinux: auto
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.target }}
+          path: dist

tarsk-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,50 @@
+name: pages
+
+# The docs are the README's long half, moved out so the README can be read in
+# under a minute. Built from `site/` rather than `docs/`, which this repository
+# keeps out of git.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "site/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# One deploy at a time, and let a newer push win rather than queueing behind an
+# older one that is about to be replaced anyway.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      # Pages has never been switched on for this repository, and this
+      # turns it on rather than failing the first run with a setting
+      # somebody has to find in the web UI.
+      - uses: actions/configure-pages@v6
+        with:
+          enablement: true
+      - uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./site
+          destination: ./_site
+      - uses: actions/upload-pages-artifact@v5
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@v5

tarsk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,158 @@
+name: release
+
+# Started from `maturin generate-ci github --platform all`, then cut down. What
+# changed from the generated file, and why, is in the comments below — the
+# generator does not know what this project links against or what it needs at
+# runtime, and two of its defaults would have shipped wheels that cannot work.
+#
+# Tags only. `ci.yml` already builds a four-target smoke matrix on every push;
+# this one is the full set and the publish, and both are wasted on a branch.
+on:
+  push:
+    # Both spellings. The first tag written for this project was `0.1.0`, the
+    # trigger only listened for `v*`, and the push went nowhere — a release
+    # that silently does not happen is a worse failure than one that stops
+    # with a message.
+    tags: ["v[0-9]*", "[0-9]*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    # Before ten wheels are built and before anything can reach PyPI, because
+    # PyPI does not allow a version to be uploaded twice: publishing 0.1.0
+    # under a tag that says something else cannot be taken back.
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - name: The tag must match the version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          declared=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          tagged=${GITHUB_REF_NAME#v}
+          echo "pyproject says $declared, tag says $tagged"
+          if [ "$declared" != "$tagged" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match version $declared in pyproject.toml"
+            exit 1
+          fi
+
+  build:
+    needs: check
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-24.04, target: x86_64, manylinux: auto }
+          # aarch64 cross-compiles through zig rather than the manylinux
+          # container's toolchain. rustls pulls in ring, whose ARM assembly the
+          # container's assembler rejects with `#error "ARM assembler must
+          # define __ARM_ARCH"`.
+          #
+          # `maturin generate-ci --zig` does exist and adds the flag, but it
+          # leaves the container on; only `container: off` is the form this
+          # repository has actually built an aarch64 wheel with. Whether the
+          # generated combination also works here is untested, which is the
+          # only reason it is not used.
+          - { os: ubuntu-24.04, target: aarch64, manylinux: auto, zig: true }
+          - { os: ubuntu-24.04, target: x86_64, manylinux: musllinux_1_2, musl: true }
+          - { os: macos-14, target: universal2-apple-darwin }
+          - { os: windows-latest, target: x64 }
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Provide zig
+        if: matrix.zig
+        # maturin looks for a `zig` binary on PATH; the pip package is a Python
+        # module, so it needs a shim.
+        run: |
+          python -m pip install --quiet ziglang
+          mkdir -p "$HOME/.local/bin"
+          printf '#!/bin/sh\nexec %s -m ziglang "$@"\n' "$(which python)" > "$HOME/.local/bin/zig"
+          chmod +x "$HOME/.local/bin/zig"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist ${{ matrix.zig && '--zig' || '' }}
+          # zig cross-compiles on the host and tags the wheel manylinux itself,
+          # so the container would only get in the way of finding it.
+          container: ${{ matrix.zig && 'off' || 'auto' }}
+          manylinux: ${{ matrix.manylinux }}
+          sccache: true
+      - name: Build the free-threaded wheel
+        # abi3 stops at the GIL: a free-threaded build cannot use the stable
+        # ABI, so 3.14t needs a wheel of its own or its users compile from the
+        # sdist. CI has tested 3.14t since the first commit, and shipping
+        # without this would have been a supported version with no wheel.
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist -i python3.14t ${{ matrix.zig && '--zig' || '' }}
+          container: ${{ matrix.zig && 'off' || 'auto' }}
+          manylinux: ${{ matrix.manylinux }}
+          sccache: true
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.target }}${{ matrix.musl && '-musl' || '' }}
+          path: dist
+
+  sdist:
+    needs: check
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-sdist
+          path: dist
+
+  publish:
+    needs: [build, sdist]
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tarsk
+    permissions:
+      # Trusted publishing, so there is no API token in this repository to
+      # rotate or leak. PyPI has to know about this workflow first: add a
+      # pending publisher for `tarsk` naming this repository, `release.yml`
+      # and the `pypi` environment. Renaming this file breaks that link.
+      id-token: write
+      # For the artifact attestation and the GitHub release.
+      attestations: write
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: wheels-*
+          merge-multiple: true
+          path: dist
+      - uses: actions/attest-build-provenance@v4
+        with:
+          subject-path: "dist/*"
+      # Pinned to the full version: setup-uv stopped publishing a moving
+      # major tag after v7, so @v10 does not resolve.
+      - uses: astral-sh/setup-uv@v10.0.1
+      - name: Publish to PyPI
+        # Only a tag publishes. A manual run builds every wheel and attests
+        # them, which is the rehearsal worth having before the first release.
+        if: startsWith(github.ref, 'refs/tags/')
+        # `always` rather than the `automatic` default: automatic falls back
+        # to looking for a token and would fail with a credentials error
+        # instead of saying the publisher is not configured.
+        run: uv publish --trusted-publishing always dist/*
+      - uses: softprops/action-gh-release@v3
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          files: dist/*
+          generate_release_notes: true
+          prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}

tarsk-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+/docs/
+/target/
+/.venv/
+__pycache__/
+*.py[cod]
+*.so
+/demo/out*/