cassetta 0.30.0__tar.gz

cassetta-0.30.0/.dockerignore

@@ -0,0 +1,51 @@
+# Build context = the repository root. Only `pyproject.toml`, `uv.lock`, `LICENSE`, `src/` and
+# `scripts/docker-entrypoint.sh` are actually COPYed by the Dockerfile, but keeping the context
+# small speeds every build and keeps a stray `.env` from ever reaching the daemon.
+#
+# `scripts/` is therefore not excluded below, and must not become excluded: the entrypoint is the
+# container's first process.
+
+# Version control
+.git/
+.gitignore
+.github/
+
+# Python build + cache artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Test, lint, and type-check state
+tests/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+
+# Docs — not needed to run the service
+docs/
+
+# Runtime state: never bake a developer's bus contents into an image
+data/
+data.keys/
+
+# Secrets
+.env
+.env.local
+
+# The docker files themselves
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# Editor and OS noise
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db

cassetta-0.30.0/.env.example

@@ -0,0 +1,131 @@
+# Cassetta configuration — copy to `.env` and edit.
+#
+#   cp .env.example .env
+#
+# Every value below is read from the environment at startup. Three are required; the rest show
+# their built-in default, so a line you leave commented out behaves exactly as shown.
+# Full reference: docs/CONFIG.md
+#
+# To change a value later, edit `.env` and run `docker compose up -d` again — no image rebuild.
+
+
+# ---------------------------------------------------------------------------
+# Required
+# ---------------------------------------------------------------------------
+
+# Token for the one-time POST /setup call that mints your first API key.
+# Set this to a long random string before exposing the server to anything.
+# Setting it to "" enables dev mode — NO AUTHENTICATION AT ALL. Local experiments only.
+CASSETTA_SETUP_TOKEN=change-me-to-a-long-random-string
+
+# Absolute base URL that agents can reach. Used to compose the download / upload URLs
+# returned in batch responses, so it must be the externally reachable address — not the
+# internal bind address, when those differ. Scheme is mandatory (http:// or https://).
+CASSETTA_PUBLIC_BASE_URL=http://localhost:16001
+
+# ###########################################################################
+# # DEV ONLY — the key below is a fixed placeholder shipped with this file. #
+# # It decodes to the literal "dev-only-quickstart-key-DO-NOT-USE-IN-PRODUCTION",
+# # so anyone who cloned this repository can mint a valid token against it.  #
+# # REPLACE IT before any deployment beyond localhost:                       #
+# #     openssl rand -base64 32                                              #
+# ###########################################################################
+# Base64-encoded HS256 signing key; must decode to at least 32 bytes.
+CASSETTA_JWT_KEY=ZGV2LW9ubHktcXVpY2tzdGFydC1rZXktRE8tTk9ULVVTRS1JTi1QUk9EVUNUSU9O
+
+
+# ---------------------------------------------------------------------------
+# Signing keys (optional)
+# ---------------------------------------------------------------------------
+
+# Path to a file whose contents are the base64-encoded primary key. Wins over
+# CASSETTA_JWT_KEY when both are set — the managed-secret setup.
+#CASSETTA_JWT_KEY_FILE=
+
+# Verify-only secondary key, used during rotation. Never signs. See docs/CONFIG.md
+# "Key rotation procedure".
+#CASSETTA_JWT_KEY_SECONDARY=
+#CASSETTA_JWT_KEY_SECONDARY_FILE=
+
+# Seconds a just-demoted key stays valid after a SIGHUP rotation, so in-flight tokens
+# keep verifying. Must be >= max(CASSETTA_DOWNLOAD_CLAIM_TTL, CASSETTA_UPLOAD_TOKEN_TTL).
+#CASSETTA_JWT_KEY_OVERLAP_TTL=600
+
+
+# ---------------------------------------------------------------------------
+# Storage
+# ---------------------------------------------------------------------------
+
+# Storage path. /data is the container mount; outside a container the default is ./data.
+CASSETTA_STORAGE_PATH=/data
+
+# API key store. Defaults to a sibling of the storage directory —
+# "<storage>.keys/.cassetta-keys.json" — so key files live outside the storage tree and
+# never appear in a /files/ listing.
+#CASSETTA_KEYS_FILE=
+
+# Default file TTL in seconds. 0 disables expiration.
+#CASSETTA_DEFAULT_TTL=0
+
+# Character class allowed in stored paths.
+#CASSETTA_ALLOWED_PATH_CHARS=a-zA-Z0-9\-_./
+
+
+# ---------------------------------------------------------------------------
+# Limits policy
+# ---------------------------------------------------------------------------
+# For the four caps, an empty value means "no cap" — explicitly, so configuration
+# management that cannot distinguish an absent variable from an empty one can still clear one.
+
+# Maximum bytes for any single file in a bundle. Empty = uncapped.
+#CASSETTA_PER_FILE_MAX=
+
+# Maximum total bytes across a bundle. Empty = uncapped.
+#CASSETTA_PER_BUNDLE_TOTAL_MAX=
+
+# Maximum number of files per bundle. Empty = unlimited.
+#CASSETTA_PER_BUNDLE_FILE_COUNT_MAX=25
+
+# Payloads at or below this size are accepted inline; larger ones require the batch
+# upload flow. 102400 = 100 KiB. Empty = always inline.
+#CASSETTA_MAX_INLINE_SIZE=102400
+
+# TTLs, in seconds. All must be > 0.
+#CASSETTA_UPLOAD_TOKEN_TTL=300
+#CASSETTA_DOWNLOAD_CLAIM_TTL=300
+
+# Passive garbage collection of orphaned bundles.
+#CASSETTA_PASSIVE_GC_MIN_AGE=3600
+#CASSETTA_PASSIVE_GC_INTERVAL=600
+
+
+# ---------------------------------------------------------------------------
+# Rate limiting and fan-out
+# ---------------------------------------------------------------------------
+
+# Shared budget across REST /broadcast and the MCP cassetta_broadcast tool.
+# Format "<int>/<unit>", unit one of sec, second, min, minute, hour, hourly.
+#CASSETTA_RATE_LIMIT_BROADCAST=10/minute
+
+# Fan-out cap. A broadcast above this many recipients is rejected before any write.
+#CASSETTA_BROADCAST_MAX_TARGETS=1000
+
+
+# ---------------------------------------------------------------------------
+# MCP and logging
+# ---------------------------------------------------------------------------
+
+# Comma-separated Host header allowlist for the /mcp endpoint (DNS-rebinding protection).
+# Empty means localhost only — set your external hostname(s) to reach MCP from another machine.
+#CASSETTA_MCP_ALLOWED_HOSTS=
+
+# "text" or "json".
+#CASSETTA_LOG_FORMAT=text
+
+
+# ---------------------------------------------------------------------------
+# Compose only
+# ---------------------------------------------------------------------------
+# Read by docker-compose.yml, never by the server. It selects the host port to publish;
+# the port inside the container is fixed at 16001.
+#CASSETTA_PORT=16001

cassetta-0.30.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+# Continuous integration for every pull request, and for the default branch itself.
+#
+# This workflow carries exactly the gates a contributor already runs locally, and nothing more.
+# It is meant to be cheap enough to require on every merge, so anything that builds an image or
+# starts a stack belongs in the weekly smoke workflow instead — never here.
+
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  # So the default branch carries its own status rather than inheriting the last pull request's.
+  push:
+    branches: [main]
+
+# The run reads this repository and writes nothing back. It needs no secret, no registry and no
+# token beyond the read-only one below.
+permissions:
+  contents: read
+
+# A force-pushed branch should not leave superseded runs burning minutes on a status nobody
+# will read.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Format, lint and types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      # `--extra dev` is load-bearing. The gate tools live in [project.optional-dependencies],
+      # which uv treats as an extra rather than as a default dependency group, so a bare
+      # `uv sync` uninstalls pytest, ruff and mypy and every step below then fails.
+      - run: uv sync --extra dev
+
+      # One step per gate, so a failure is named in the run's step list rather than buried.
+      - run: uv run ruff format --check
+      - run: uv run ruff check
+      - run: uv run mypy
+
+  test:
+    name: Test suite
+    runs-on: ubuntu-latest
+    steps:
+      # Default fetch depth is correct: the one test that shells out to git reads `git ls-files`,
+      # which is the index and needs no history.
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      - run: uv sync --extra dev
+
+      - run: uv run pytest
+
+      # Every test must also pass under a randomised ordering — interdependence between tests is
+      # a defect here, not a quirk.
+      - run: uv run pytest -p randomly

cassetta-0.30.0/.github/workflows/release.yml

@@ -0,0 +1,85 @@
+# Build the distribution for a release, and prove it is the release it claims to be.
+#
+# Reusable on purpose, and reusable *only*. What defines a release here is the tag, and the tag is
+# placed by tag.yml after a merge — so this workflow is called from there, in the same run, with the
+# version that was just tagged. There is nothing this could usefully mean on its own, which is why it
+# carries no other trigger.
+#
+# It builds and checks; it does not publish, and it cannot. A called workflow can narrow the token
+# its caller grants but never widen it, so a job here could not obtain the identity token publishing
+# needs, and the index does not support a reusable workflow as a trusted publisher in any case. The
+# publish job is in tag.yml, after the call to this one, and it hands over the artifact uploaded
+# below. tests/test_workflows.py holds publishing to that one place.
+
+name: Release
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: The version that was just tagged, without the leading `v`.
+        required: true
+        type: string
+
+# It reads the tree and writes nothing back — the tag already exists by the time this runs.
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build the distribution and check it against the tag
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      # No `--extra dev` here: a build needs the build backend, not the gate tools. CI has already
+      # run those against this very commit.
+      - run: uv build
+
+      # The step this whole composition exists for. The version in the built artifact is derived
+      # from src/cassetta/__init__.py by the build backend; the version in the tag was read from the
+      # same file by tag.yml. Asserting they match is what turns "they are both read from one place"
+      # from an argument into an observation.
+      #
+      # The input reaches the script through the environment rather than being interpolated into the
+      # script body. The value comes from this repository's own tree, so nothing hostile can reach
+      # it — but a `run:` block with an expression spliced into it is a shape a reviewer has to stop
+      # and think about, and this one gets exactly one review.
+      - name: The built artifact must carry the version that was tagged
+        env:
+          EXPECTED: ${{ inputs.version }}
+        run: |
+          set -euo pipefail
+
+          wheel="dist/cassetta-${EXPECTED}-py3-none-any.whl"
+          sdist="dist/cassetta-${EXPECTED}.tar.gz"
+
+          missing=false
+          for artifact in "$wheel" "$sdist"; do
+              if [ ! -f "$artifact" ]; then
+                  printf 'expected %s, which was not built\n' "$artifact" >&2
+                  missing=true
+              fi
+          done
+
+          if [ "$missing" = true ]; then
+              printf '\nthe tag says %s; the build produced:\n' "$EXPECTED" >&2
+              ls -1 dist/ >&2
+              printf '\nThe tag and the distribution disagree about what this release is.\n' >&2
+              exit 1
+          fi
+
+          printf 'dist/ carries %s, which is what was tagged\n' "$EXPECTED"
+
+      # What tag.yml's publish job hands to the index, once a reviewer approves the run — these bytes,
+      # which the step above checked against the tag, and never a second build. It downloads them by
+      # this name, so the two are renamed together; tests/test_workflows.py compares them.
+      - uses: actions/upload-artifact@v7
+        with:
+          name: cassetta-${{ inputs.version }}
+          path: dist/
+          if-no-files-found: error

cassetta-0.30.0/.github/workflows/smoke.yml

@@ -0,0 +1,132 @@
+# Weekly proof that the container this repository ships still boots and serves traffic.
+#
+# Deliberately off the merge path. Building an image and starting a stack is far too expensive to
+# run on every pull request; the change flow here is low and history is linear and squash-merged,
+# so a weekly signal is enough to identify which recent merge broke it.
+#
+# The shell lives in scripts/smoke.sh rather than in this file, so a contributor can run exactly
+# what the schedule runs against their own clone.
+#
+# It runs twice, against bind mounts owned two different ways. The second run is the only thing in
+# this repository that exercises the case a hosted runner's own user id conceals; see the comment on
+# that job for why one run was never enough.
+
+name: Smoke
+
+on:
+  schedule:
+    # Mondays, off the hour on purpose: scheduled runs at minute zero are heavily contended on
+    # the platform and get delayed, sometimes substantially.
+    - cron: "17 6 * * 1"
+  # So the first proof that any of this works does not have to wait up to a week.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: smoke-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  changes:
+    name: Anything landed since the last green run?
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # For the Actions API query below.
+      actions: read
+    outputs:
+      should_run: ${{ steps.decide.outputs.should_run }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # The commit count below needs history to count over.
+          fetch-depth: 0
+
+      - id: decide
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          decide() {
+              printf 'should_run=%s — %s\n' "$1" "$2"
+              echo "should_run=$1" >>"$GITHUB_OUTPUT"
+          }
+
+          # Key on the last *successful* run rather than on a calendar window, so a run that
+          # fails and is fixed ten days later still measures from the right place. The run
+          # executing this query cannot match it: it is in_progress, not success.
+          query="repos/${GITHUB_REPOSITORY}/actions/workflows/smoke.yml/runs?status=success&branch=main&per_page=1"
+
+          if baseline="$(gh api "$query" --jq '.workflow_runs[0].head_sha // ""')"; then
+              api_reachable=true
+          else
+              api_reachable=false
+              baseline=""
+          fi
+
+          # Every unknown below resolves to "run". A wrong "run" costs one unnecessary run; a
+          # wrong "skip" is silent and can keep skipping forever, which is the failure nobody
+          # notices.
+          if [ "$api_reachable" = false ]; then
+              decide true "the Actions API could not be queried; running rather than skipping blind"
+          elif [ -z "$baseline" ]; then
+              decide true "no successful run of this workflow exists yet"
+          elif ! git cat-file -e "${baseline}^{commit}" 2>/dev/null; then
+              decide true "baseline ${baseline} is not in the fetched history (rewritten, or older than the checkout)"
+          else
+              landed="$(git rev-list --count "${baseline}..HEAD")"
+              if [ "$landed" -gt 0 ]; then
+                  decide true "${landed} commit(s) landed since ${baseline}"
+              else
+                  decide false "nothing has landed since ${baseline}"
+              fi
+          fi
+
+  smoke:
+    name: Container smoke
+    needs: changes
+    if: needs.changes.outputs.should_run == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      # One step, on purpose. Dumping logs on failure and tearing the stack down live in the
+      # script's own exit trap, so a contributor running it locally gets exactly this behaviour.
+      - run: ./scripts/smoke.sh
+
+  smoke-foreign-uid:
+    name: Container smoke, bind mounts owned by another uid
+    needs: changes
+    if: needs.changes.outputs.should_run == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      # The case the job above is structurally unable to see, and the reason this one is permanent.
+      #
+      # A hosted runner's own user carries uid 1001 — the same id as the account inside the image —
+      # so a bind mount the runner creates is already owned by exactly the right user. The job above
+      # therefore passes for a reason that has nothing to do with the code, and would keep passing
+      # if the container lost the ability to write into a directory it did not create. Handing the
+      # two directories to a different uid first is what reproduces the case an ordinary Linux
+      # contributor meets: the quickstart's `mkdir -p` leaves them owned by whoever ran it.
+      #
+      # 1000 is the first ordinary user id on a Debian or Ubuntu desktop, so it stands in for
+      # precisely that contributor. Creating the directories here rather than letting the script do
+      # it is load-bearing — the script creates them itself when they are absent, and one it creates
+      # belongs to the runner again.
+      #
+      # Both ownership cases are kept because they fail for different reasons. Deleting either loses
+      # a signal, and deleting this one returns the weekly run to passing by coincidence.
+      - name: Hand the bind-mount sources to a uid that is not the runner's
+        run: |
+          set -euo pipefail
+          mkdir -p data data.keys
+          sudo chown 1000:1000 data data.keys
+          printf 'runner uid: %s (the container runs as uid 1001)\n' "$(id -u)"
+          ls -ld data data.keys
+
+      - run: ./scripts/smoke.sh

cassetta-0.30.0/.github/workflows/tag.yml

@@ -0,0 +1,132 @@
+# The release tag, as a consequence of the merge rather than a step somebody remembers.
+#
+# This repository is squash-only. A tag made on the branch before the merge names a commit that is
+# not on `main` — the branch commit and the squash commit can have the identical tree and the
+# identical parent and still different hashes, because the squash rewrites the message and the
+# committer. Reading the version *after* the merge and tagging the commit that landed is the only
+# way to get this right by construction.
+#
+# It runs on every push to `main`, and on almost all of them it does nothing. That is the design: the
+# common case must be a quiet, green no-op, because a mechanism that costs something on the ordinary
+# path is a mechanism somebody eventually deletes.
+#
+# The release workflow is *called*, never triggered. A tag pushed with GITHUB_TOKEN does not start
+# other workflow runs — GitHub's loop prevention — so a release workflow listening on `push: tags:`
+# would never fire, and would look correct in review. tests/test_workflows.py forbids that shape
+# repository-wide.
+#
+# Publishing is the last job here, and it waits for a person. It hands the index the artifact the
+# release workflow built and checked against the tag in this same run, and it starts only once a
+# reviewer approves the run in the `pypi` deployment environment. That approval is the gate, and it is
+# deliberately not in this file. The job lives here rather than in release.yml because a called
+# workflow can narrow the token its caller grants but never widen it, and the index does not support a
+# reusable workflow as a trusted publisher. So this file is the workflow registered with the index.
+
+name: Tag on merge
+
+on:
+  push:
+    branches: [main]
+
+# Read by default; each job that needs more says so for itself.
+permissions:
+  contents: read
+
+jobs:
+  tag:
+    name: Tag the declared version, if it is new
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    # Not keyed on the ref: every run of this workflow is on `main`, and the point is that two merges
+    # landing seconds apart cannot both decide that a tag is missing. Cancelling is wrong here — a
+    # cancelled tag job leaves a release untagged with nothing to report it, which is the failure this
+    # workflow exists to prevent.
+    #
+    # On this job rather than on the workflow, because the run ends in a job that waits for a reviewer.
+    # At workflow level the group would be held for the whole wait, and GitHub keeps one pending run
+    # per group, cancelling it when the next one arrives — so a merge landing during the wait could
+    # lose its tag run to the merge after it. Here the group is released before anything waits on a
+    # person.
+    concurrency:
+      group: tag-on-merge
+      cancel-in-progress: false
+    outputs:
+      version: ${{ steps.tag.outputs.version }}
+      created: ${{ steps.tag.outputs.created }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Brings the tags with it, so the "does this already exist?" question and the tag object
+          # itself are one local repository. It also keeps the push off a shallow clone, which git
+          # can refuse.
+          fetch-depth: 0
+
+      - id: tag
+        run: |
+          set -euo pipefail
+
+          # The same extraction make release-check performs, for the same reason: this is the one
+          # place the version is declared, and reading the file as text needs no environment.
+          version="$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' src/cassetta/__init__.py | head -n 1)"
+
+          if [ -z "$version" ]; then
+              echo "src/cassetta/__init__.py declares no __version__ — nothing to tag" >&2
+              exit 1
+          fi
+
+          echo "version=${version}" >>"$GITHUB_OUTPUT"
+
+          if git rev-parse -q --verify "refs/tags/v${version}" >/dev/null; then
+              echo "created=false" >>"$GITHUB_OUTPUT"
+              printf 'v%s is already tagged — this merge carries no release.\n' "$version"
+              exit 0
+          fi
+
+          # Annotated, with the tag's own name as the message: that is what v0.26.0 through v0.26.5
+          # carry, and a release history where one entry is shaped differently is a question someone
+          # has to answer later.
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "v${version}" -m "v${version}"
+          git push origin "v${version}"
+
+          echo "created=true" >>"$GITHUB_OUTPUT"
+          printf 'tagged %s as v%s\n' "$(git rev-parse --short HEAD)" "$version"
+
+  release:
+    name: Release
+    needs: tag
+    if: needs.tag.outputs.created == 'true'
+    # A call, in this same run — not something the tag push triggers, because it could not be. A job
+    # that carries `uses:` carries no `runs-on` and no `steps` of its own.
+    uses: ./.github/workflows/release.yml
+    with:
+      version: ${{ needs.tag.outputs.version }}
+
+  publish:
+    name: Publish the release, once a reviewer approves
+    # `release` is what makes this the checked build. When the merge carried no new version `release`
+    # is skipped, and this job is skipped with it — the quiet no-op above, not a gate. `tag` is listed
+    # as well because the version is read from its outputs, and the `needs` context carries only the
+    # jobs named here.
+    needs: [tag, release]
+    runs-on: ubuntu-latest
+    # The gate: a reviewer on this environment approves the run before this job starts, and the name
+    # is also what the index checks in the token's claim. There is no `if:`. A false condition would
+    # skip the job and paint the run green, and a release that silently did not happen is the failure
+    # this whole composition is built to rule out.
+    environment: pypi
+    # Only what the OIDC exchange needs, and on this job alone. No token, no secret, no `password:` —
+    # the publish action trades a short-lived identity token for an upload credential on its own.
+    permissions:
+      id-token: write
+    steps:
+      # The bytes release.yml built and checked against the tag, under the name it uploaded them with.
+      # Nothing here checks the repository out, so there is nothing to build a second distribution from.
+      - uses: actions/download-artifact@v8
+        with:
+          name: cassetta-${{ needs.tag.outputs.version }}
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

cassetta-0.30.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Atomic writes: tooling that writes <path>.tmp then renames it into place
+*.tmp
+
+# Testing & Linting
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+
+# Environment
+.env
+.env.local
+
+# Claude Code (may contain credentials)
+.claude/settings.local.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+data/
+data.keys/
+
+# Briefs
+inbox/