fauxbus 0.1.2__tar.gz

fauxbus-0.1.2/.dockerignore

@@ -0,0 +1,13 @@
+# Podman reads this too (falls back to .dockerignore when no
+# .containerignore exists) — one file covers both runtimes.
+.git
+.worktrees
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+dist
+build
+*.egg-info

fauxbus-0.1.2/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+
+# Internal review artifacts — findings land here for triage, not for
+# publication.  A security review is a working document: it names
+# weaknesses before they are fixed, which is precisely the thing not to
+# hand a stranger.  What survives triage becomes a commit, an issue, or
+# a SPEC entry — those are the public record.
+.reviews/

fauxbus-0.1.2/.woodpecker.yml

@@ -0,0 +1,170 @@
+# Fauxbus CI — the conformance tether, mechanized.
+#
+# SPEC.md promises "one test suite, two backends: Fauxbus on every CI run,
+# the real Globus service env-gated before each release."  This file is the
+# first half of that promise.  The second half arrives with the recording
+# session (see RELEASING.md for the honest posture until then).
+#
+# Fauxbus is a library, not a service — no deploy step.  What ships is a
+# wheel and an image, so CI builds and boots both.
+#
+# THE TRUST ARC (a lesson worth keeping): build #1 failed because
+# untrusted repos may not mount `volumes` — correctly, since this config
+# lives in the repo and a config that could mount /var/run/docker.sock
+# would hand the host to anyone who can push a branch.  The refusal was
+# the security model working.  An admin has since marked the repo
+# trusted, which is a statement about who can push here, not about
+# Woodpecker relaxing: the socket mount below is exactly as dangerous as
+# it always was, and belongs only in repos where every committer could
+# already root the host by other means.
+#
+# Pip cache mounted at /opt/cache/pip, per house convention.
+
+# Tags get their own pipeline too: a tag re-verifies the exact tagged
+# commit, and `event: tag` is what the parked publish-pypi step at the
+# bottom will hang on once restored.
+when:
+  - event: push
+  - event: tag
+
+labels:
+  host: xdocker01
+
+matrix:
+  PYTHON:
+    - "3.11"
+    - "3.12"
+    - "3.13"
+
+steps:
+  # `ruff check` only — deliberately no `ruff format --check`.  pyproject
+  # ignores E501 at line-length 100, which is the author saying line breaks
+  # are a human call in this codebase; a formatter gate would overrule that.
+  - name: lint
+    image: python:${PYTHON}-slim
+    commands:
+      - pip install --cache-dir /cache/pip -e ".[dev]"
+      - ruff check src/ tests/
+    volumes:
+      - /opt/cache/pip:/cache/pip
+
+  # FAUXBUS_REQUIRE_CONFORMANCE is the point of this step, not decoration.
+  # tests/test_sdk_conformance.py guards its import with `importorskip` so a
+  # bare checkout still runs; that same guard means a CI image missing
+  # globus-sdk would drop every SDK test and still go green.  The env var
+  # turns that skip into a collection error, so "the SDK is the contract"
+  # stays a fact about this pipeline rather than a claim in a README.
+  - name: test
+    image: python:${PYTHON}-slim
+    environment:
+      FAUXBUS_REQUIRE_CONFORMANCE: "1"
+    commands:
+      - pip install --cache-dir /cache/pip -e ".[dev,conformance]"
+      - python -c "import globus_sdk; print('SDK under test:', globus_sdk.__version__)"
+      - pytest -v --tb=short
+    volumes:
+      - /opt/cache/pip:/cache/pip
+
+  # An editable install never exercises the wheel path, and the wheel is
+  # what the container image and every consumer actually installs.  Build
+  # it here so a packaging break fails CI instead of surfacing at
+  # someone's `pipx install`.
+  - name: build-wheel
+    image: python:${PYTHON}-slim
+    commands:
+      - pip install --cache-dir /cache/pip build
+      - python -m build --wheel
+      - pip install --cache-dir /cache/pip dist/*.whl
+      - fauxbus --help
+    volumes:
+      - /opt/cache/pip:/cache/pip
+    depends_on:
+      - test
+
+  # The image is shipped documentation: examples/compose.yaml tells
+  # consumers to build it, and root-cellar's deploy module actually does.
+  # This step proves the Containerfile builds, boots, and answers the
+  # same unauthenticated /_fauxbus/ probe the HEALTHCHECK uses — the
+  # thing compose's `depends_on: service_healthy` hangs on.  Gated to one
+  # matrix cell: the image pins its own Python, so building it three
+  # times would test Woodpecker, not Fauxbus.
+  #
+  # Names key on CI_PIPELINE_NUMBER, not the commit SHA: a push to main
+  # and a fleet branch can carry the SAME sha and run concurrently, and
+  # two `docker run --name fauxbus-ci-<sha>` would collide.  The
+  # pipeline number is unique by construction.
+  - name: build-image
+    image: docker:cli
+    when:
+      matrix:
+        PYTHON: "3.13"
+    environment:
+      # The Containerfile uses RUN --mount, a BuildKit feature; be
+      # explicit rather than trusting the daemon's default.
+      DOCKER_BUILDKIT: "1"
+    commands:
+      - docker build -f Containerfile -t fauxbus:ci-${CI_PIPELINE_NUMBER} .
+      - docker run -d --name fauxbus-ci-${CI_PIPELINE_NUMBER} fauxbus:ci-${CI_PIPELINE_NUMBER}
+      - |
+        for i in $(seq 1 30); do
+          docker exec fauxbus-ci-${CI_PIPELINE_NUMBER} python -c \
+            "import urllib.request; urllib.request.urlopen('http://127.0.0.1:9800/_fauxbus/', timeout=1)" \
+            && break
+          [ "$i" = "30" ] && { docker logs fauxbus-ci-${CI_PIPELINE_NUMBER}; exit 1; }
+          sleep 1
+        done
+      # The SBOM must ride in the image and name what it claims to name
+      # — an image that lost its bill of materials fails the build, not
+      # a compliance review three months later.
+      - |
+        docker exec fauxbus-ci-${CI_PIPELINE_NUMBER} python -c \
+          "import json; d = json.load(open('/usr/share/fauxbus/sbom.json')); names = sorted(c['name'] for c in d['components']); assert 'fauxbus' in names, names; print('SBOM components:', names)"
+      - docker rm -f fauxbus-ci-${CI_PIPELINE_NUMBER}
+      - docker rmi fauxbus:ci-${CI_PIPELINE_NUMBER} || true
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    depends_on:
+      - test
+
+# ---------------------------------------------------------------------------
+# PARKED PENDING PUBLICATION — the PyPI publish step, written 2026-08-05
+# while we were thinking of it, so tag time never has to improvise.
+# The name is free (checked: fauxbus 404s on PyPI) and the v0.1.0
+# artifacts pass `twine check`; this step is the automation for v0.2
+# onward.  ONE condition left — was two:
+#
+#   1. A project-scoped PyPI token exists as the Woodpecker secret
+#      `pypi_token`.  (PyPI's OIDC trusted publishing doesn't cover
+#      Woodpecker, so token it is.)  Project-scoped implies the first,
+#      manual upload already happened — RELEASING.md has the sequence.
+#   2. DONE 2026-08-07 — pyproject's homepage/issues URLs now point at
+#      github.com/atmarx/fauxbus, which is public with issues enabled.
+#      (Was: a package that tells strangers to file issues behind the
+#      VPN is a bad look.)
+#
+# The `event: tag` this hangs on is already live in the top-level when.
+#
+#  - name: publish-pypi
+#    image: python:${PYTHON}-slim
+#    when:
+#      event: tag
+#      matrix:
+#        PYTHON: "3.13"
+#    environment:
+#      TWINE_USERNAME: __token__
+#      TWINE_PASSWORD:
+#        from_secret: pypi_token
+#    commands:
+#      - pip install --cache-dir /cache/pip build twine
+#      - python -m build
+#      # The tag names the version; the build had better agree.  A tag
+#      # pointing at a .dev0 commit must die here, not on PyPI —
+#      # uploads are burn-once.
+#      - test -f "dist/fauxbus-${CI_COMMIT_TAG#v}.tar.gz" || { echo "tag ${CI_COMMIT_TAG} does not match built version:"; ls dist/; exit 1; }
+#      - twine check dist/*
+#      - twine upload --non-interactive dist/*
+#    volumes:
+#      - /opt/cache/pip:/cache/pip
+#    depends_on:
+#      - test
+# ---------------------------------------------------------------------------

fauxbus-0.1.2/Containerfile

@@ -0,0 +1,58 @@
+# Fauxbus — a wire-level fake of the Globus API.
+#
+# Two stages: build the wheel, install only the wheel.  Fauxbus has zero
+# runtime dependencies, so the final image is the Python base plus one
+# pure-stdlib package — no supply chain rides along into your dev stack.
+#
+# Named Containerfile (the OCI-neutral spelling).  Docker wants
+# `-f Containerfile`, or in compose:
+#   build: { context: ., dockerfile: Containerfile }
+
+FROM python:3.13-slim AS build
+WORKDIR /src
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN pip wheel --no-deps --no-cache-dir --wheel-dir /dist .
+
+# The SBOM is generated from a CLEAN venv holding only the wheel we just
+# built: pointing the generator at its own environment would list the
+# generator and its dependencies, polluting the receipt.  For a
+# zero-dependency package the bill of materials is short on purpose —
+# it is the machine-readable proof of the "no supply chain rides along"
+# claim, license metadata included (CycloneDX reads MIT straight out of
+# the wheel).
+RUN pip install --no-cache-dir cyclonedx-bom \
+    && python -m venv /sbomenv \
+    && /sbomenv/bin/pip install --no-cache-dir /dist/*.whl \
+    && cyclonedx-py environment /sbomenv/bin/python --of json -o /dist/sbom.json
+
+FROM python:3.13-slim
+
+LABEL org.opencontainers.image.title="fauxbus" \
+      org.opencontainers.image.description="A wire-level fake of the Globus API for E2E testing.  Independent test tool, not affiliated with Globus." \
+      org.opencontainers.image.source="https://github.com/atmarx/fauxbus" \
+      org.opencontainers.image.licenses="MIT"
+
+ENV PYTHONUNBUFFERED=1
+
+RUN --mount=type=bind,from=build,source=/dist,target=/dist \
+    pip install --no-cache-dir /dist/*.whl
+
+# The image carries its own bill of materials — transparency travels
+# with the artifact, not with a wiki page about the artifact.
+COPY --from=build /dist/sbom.json /usr/share/fauxbus/sbom.json
+
+# Unprivileged, uid matching the port — memorable, and stable for anyone
+# who needs to reason about mounted-file ownership.
+RUN useradd --system --uid 9800 --no-create-home fauxbus
+COPY --chmod=755 container/entrypoint.sh /usr/local/bin/fauxbus-entrypoint
+USER fauxbus
+
+EXPOSE 9800
+
+# The control-plane index answers without auth — the natural liveness
+# probe, and what makes `depends_on: service_healthy` work in compose.
+HEALTHCHECK --interval=5s --timeout=2s --start-period=2s --retries=3 \
+    CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:9800/_fauxbus/', timeout=1)"]
+
+ENTRYPOINT ["fauxbus-entrypoint"]

fauxbus-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Marx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fauxbus-0.1.2/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: fauxbus
+Version: 0.1.2
+Summary: A wire-level fake of the Globus API for E2E testing
+Project-URL: Homepage, https://github.com/atmarx/fauxbus
+Project-URL: Issues, https://github.com/atmarx/fauxbus/issues
+Author: Andrew Marx
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fake,globus,http,integration-tests,testing
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Provides-Extra: conformance
+Requires-Dist: globus-sdk<5,>=4.8.1; extra == 'conformance'
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Fauxbus
+
+A wire-level fake of the Globus API for E2E testing.
+
+## The problem
+
+Globus is the data fabric of research computing: it moves datasets
+between universities, national labs, and HPC centers, and its API is how
+institutions automate that world — group rosters that gate who can reach
+which collection, permissions, transfer pipelines.  If you run research
+infrastructure, sooner or later you have code calling this API, and that
+code matters more than most: it decides who can touch the data.
+
+Testing that code is where it gets uncomfortable.  Globus has no
+sandbox, no emulator, no local mode.  The SDK ships a testing module,
+but it is in-process canned responses — by its own docs "a best
+approximation of API responses" — which serves unit tests well and
+cannot back a socket.  So an integration test has two options: a real
+tenancy (real credentials in CI, real groups with real people in them,
+rate limits, shared mutable state, network weather), or nothing.  A lot
+of shops choose nothing.  The layer that gates access to research data
+ends up the least-tested code in the pipeline, precisely because it is
+the riskiest thing to point a test at.
+
+Fauxbus is a third option: a standalone HTTP server that imitates the
+Globus API at the wire level.  Point your `globus-sdk` client at
+`http://localhost:9800` instead of the real service and run your
+existing suite — same requests, same response shapes, same status
+codes.  Your code never learns it isn't talking to Globus.  And because
+the whole point of a fake is control, failure is a feature you schedule:
+a 429 on exactly the request where your retry logic needs exercise, an
+identity that is already in the group, a batch action that partially
+fails the way the real service partially fails.
+
+**Status: early but real.**  The complete `GroupsClient` surface of
+globus-sdk 4.8.1 is implemented — all fourteen methods, all eleven
+batch membership verbs — and the conformance suite drives every one of
+the fourteen through the actual globus-sdk, unmodified, including the
+SDK's retry layer recovering through an injected 429.  Response shapes
+not yet backed by a recording are marked `PROVISIONAL` in code and
+tracked as conformance obligations.  Nothing is stable yet — see
+[SPEC.md](SPEC.md) for the full design.
+
+## Fake, not mock
+
+Your code doesn't know Fauxbus is there.  No monkeypatching, no fixture
+dicts shaped like your guess about what Globus returns.  The client
+library you ship is the client library you test against — Fauxbus
+imitates what `globus-sdk` actually sends and expects, pinned to a
+stated SDK version and derived from real recorded responses, never
+guesswork.
+
+If canned responses inside a Python unit test are all you need, use the
+SDK's own `globus_sdk.testing` — that's the in-process layer, and its
+fixtures are Fauxbus's ground truth.  Fauxbus is for the layer it
+architecturally can't reach: a real socket your whole stack can talk
+to, with state behind it (think moto next to botocore's `Stubber`).
+
+## Quick start
+
+```sh
+# not on PyPI yet — install straight from the repo
+pipx install git+https://github.com/atmarx/fauxbus
+fauxbus serve --port 9800
+```
+
+Point `globus_sdk.GroupsClient(...)` at that port instead of the real
+service host and run your existing test suite.  Other Globus clients
+will meet honest `501`s until their surfaces exist — see below.
+
+## In a compose stack
+
+The repo ships a `Containerfile`.  Zero runtime dependencies means the
+image is the Python base plus one stdlib-only wheel — nothing else rides
+along.  Mount a state document at `/seed.json` and the world exists
+before the first test connects:
+
+```yaml
+services:
+  fauxbus:
+    build: { context: ., dockerfile: Containerfile }
+    ports: ["9800:9800"]
+    volumes: ["./seed.json:/seed.json:ro"]
+```
+
+The image ships a healthcheck on the control-plane index, so
+`depends_on: { fauxbus: { condition: service_healthy } }` does the
+waiting for you.  A runnable example — sibling-service pattern, seed
+file included, both round-trip tested in CI — is in
+[`examples/`](examples/).
+
+## The control plane
+
+Everything test-harness-y lives under `/_fauxbus/`, a prefix no Globus
+API will ever claim — the imitated surface stays pure.  `GET
+/_fauxbus/state` dumps everything in the world for assertions; `POST
+/_fauxbus/reset` returns the world to its canonical seed (or to empty)
+between tests — mutate freely, reset comes home.  Full control-plane
+surface is in [SPEC.md](SPEC.md).
+
+It is unauthenticated by design — it imitates a service that answers
+the network, and harnesses are often sibling containers.  Which means
+anyone who can reach the port can rewrite the world and arm forged
+responses; for a fake, the sharpest risk isn't a crash but a lie, since
+tests that trust it would go green when they should go red.  Run it
+where you'd run any test fixture.  On a shared host,
+`--control-loopback-only` refuses `/_fauxbus/` from non-loopback peers
+without touching the imitated surface.  The reasoning, and the two
+things that flag deliberately doesn't solve, are in
+[SPEC.md](SPEC.md#control-plane-reachability).
+
+## Loud 501s, no fiction
+
+Fauxbus only implements endpoints a real consumer needs.  Anything it
+doesn't imitate yet returns a loud `501` with a pointer to file an
+issue — never a silent wrong answer pretending to be Globus.  If you
+hit one, that's the fastest way to get it prioritized.
+
+## The source is meant to be read
+
+Comments narrate the design decisions where they live — why uuid5 and
+never uuid4, why one lock, why 404 instead of 403, why failure
+injection can't touch the control plane — at a depth meant for someone
+learning how to *build* a wire-level fake, not just use one.
+
+## Not affiliated with Globus
+
+Fauxbus is an independent test tool, not affiliated with or endorsed by
+Globus or the University of Chicago.  "Globus" is their trademark; this
+project imitates the API's behavior for local testing only — the name
+is a confession, not an infringement.  It's *faux*.
+
+## License
+
+MIT.  Fauxbus contains no Globus code: it imitates publicly documented
+wire behavior, grounded against the Apache-2.0 `globus-sdk` as a
+test-time dependency only.

fauxbus-0.1.2/README.md

@@ -0,0 +1,137 @@
+# Fauxbus
+
+A wire-level fake of the Globus API for E2E testing.
+
+## The problem
+
+Globus is the data fabric of research computing: it moves datasets
+between universities, national labs, and HPC centers, and its API is how
+institutions automate that world — group rosters that gate who can reach
+which collection, permissions, transfer pipelines.  If you run research
+infrastructure, sooner or later you have code calling this API, and that
+code matters more than most: it decides who can touch the data.
+
+Testing that code is where it gets uncomfortable.  Globus has no
+sandbox, no emulator, no local mode.  The SDK ships a testing module,
+but it is in-process canned responses — by its own docs "a best
+approximation of API responses" — which serves unit tests well and
+cannot back a socket.  So an integration test has two options: a real
+tenancy (real credentials in CI, real groups with real people in them,
+rate limits, shared mutable state, network weather), or nothing.  A lot
+of shops choose nothing.  The layer that gates access to research data
+ends up the least-tested code in the pipeline, precisely because it is
+the riskiest thing to point a test at.
+
+Fauxbus is a third option: a standalone HTTP server that imitates the
+Globus API at the wire level.  Point your `globus-sdk` client at
+`http://localhost:9800` instead of the real service and run your
+existing suite — same requests, same response shapes, same status
+codes.  Your code never learns it isn't talking to Globus.  And because
+the whole point of a fake is control, failure is a feature you schedule:
+a 429 on exactly the request where your retry logic needs exercise, an
+identity that is already in the group, a batch action that partially
+fails the way the real service partially fails.
+
+**Status: early but real.**  The complete `GroupsClient` surface of
+globus-sdk 4.8.1 is implemented — all fourteen methods, all eleven
+batch membership verbs — and the conformance suite drives every one of
+the fourteen through the actual globus-sdk, unmodified, including the
+SDK's retry layer recovering through an injected 429.  Response shapes
+not yet backed by a recording are marked `PROVISIONAL` in code and
+tracked as conformance obligations.  Nothing is stable yet — see
+[SPEC.md](SPEC.md) for the full design.
+
+## Fake, not mock
+
+Your code doesn't know Fauxbus is there.  No monkeypatching, no fixture
+dicts shaped like your guess about what Globus returns.  The client
+library you ship is the client library you test against — Fauxbus
+imitates what `globus-sdk` actually sends and expects, pinned to a
+stated SDK version and derived from real recorded responses, never
+guesswork.
+
+If canned responses inside a Python unit test are all you need, use the
+SDK's own `globus_sdk.testing` — that's the in-process layer, and its
+fixtures are Fauxbus's ground truth.  Fauxbus is for the layer it
+architecturally can't reach: a real socket your whole stack can talk
+to, with state behind it (think moto next to botocore's `Stubber`).
+
+## Quick start
+
+```sh
+# not on PyPI yet — install straight from the repo
+pipx install git+https://github.com/atmarx/fauxbus
+fauxbus serve --port 9800
+```
+
+Point `globus_sdk.GroupsClient(...)` at that port instead of the real
+service host and run your existing test suite.  Other Globus clients
+will meet honest `501`s until their surfaces exist — see below.
+
+## In a compose stack
+
+The repo ships a `Containerfile`.  Zero runtime dependencies means the
+image is the Python base plus one stdlib-only wheel — nothing else rides
+along.  Mount a state document at `/seed.json` and the world exists
+before the first test connects:
+
+```yaml
+services:
+  fauxbus:
+    build: { context: ., dockerfile: Containerfile }
+    ports: ["9800:9800"]
+    volumes: ["./seed.json:/seed.json:ro"]
+```
+
+The image ships a healthcheck on the control-plane index, so
+`depends_on: { fauxbus: { condition: service_healthy } }` does the
+waiting for you.  A runnable example — sibling-service pattern, seed
+file included, both round-trip tested in CI — is in
+[`examples/`](examples/).
+
+## The control plane
+
+Everything test-harness-y lives under `/_fauxbus/`, a prefix no Globus
+API will ever claim — the imitated surface stays pure.  `GET
+/_fauxbus/state` dumps everything in the world for assertions; `POST
+/_fauxbus/reset` returns the world to its canonical seed (or to empty)
+between tests — mutate freely, reset comes home.  Full control-plane
+surface is in [SPEC.md](SPEC.md).
+
+It is unauthenticated by design — it imitates a service that answers
+the network, and harnesses are often sibling containers.  Which means
+anyone who can reach the port can rewrite the world and arm forged
+responses; for a fake, the sharpest risk isn't a crash but a lie, since
+tests that trust it would go green when they should go red.  Run it
+where you'd run any test fixture.  On a shared host,
+`--control-loopback-only` refuses `/_fauxbus/` from non-loopback peers
+without touching the imitated surface.  The reasoning, and the two
+things that flag deliberately doesn't solve, are in
+[SPEC.md](SPEC.md#control-plane-reachability).
+
+## Loud 501s, no fiction
+
+Fauxbus only implements endpoints a real consumer needs.  Anything it
+doesn't imitate yet returns a loud `501` with a pointer to file an
+issue — never a silent wrong answer pretending to be Globus.  If you
+hit one, that's the fastest way to get it prioritized.
+
+## The source is meant to be read
+
+Comments narrate the design decisions where they live — why uuid5 and
+never uuid4, why one lock, why 404 instead of 403, why failure
+injection can't touch the control plane — at a depth meant for someone
+learning how to *build* a wire-level fake, not just use one.
+
+## Not affiliated with Globus
+
+Fauxbus is an independent test tool, not affiliated with or endorsed by
+Globus or the University of Chicago.  "Globus" is their trademark; this
+project imitates the API's behavior for local testing only — the name
+is a confession, not an infringement.  It's *faux*.
+
+## License
+
+MIT.  Fauxbus contains no Globus code: it imitates publicly documented
+wire behavior, grounded against the Apache-2.0 `globus-sdk` as a
+test-time dependency only.

fauxbus-0.1.2/RELEASING.md

@@ -0,0 +1,91 @@
+# Releasing fauxbus
+
+The ritual, written down.  The point of a checklist is that a release
+cut under time pressure walks the same path as one cut with all the
+time in the world.
+
+## 0. The tether posture, stated honestly
+
+SPEC's conformance tether has two legs: Fauxbus on every CI run (live
+since v0.2.5), and the real Globus service, env-gated, before each
+release.  The second leg needs a sacrificial tenancy, and **none
+exists anywhere yet** — dev deliberately has no Globus tenancy (that
+absence is why fauxbus is load-bearing for its first consumer).
+
+So, until the first recording session is possible:
+
+- Every release ships with the **PROVISIONAL inventory** in its release
+  notes.  Generate it: `grep -rn PROVISIONAL src/`.  The batch
+  membership response document is the standing #1.
+- The moment a sacrificial tenancy exists, the recording session
+  becomes **release-blocking for every release after it becomes
+  possible**.  A gate nobody can run is worse than an honest gap —
+  but a gate somebody could run and didn't is just a gap.
+
+## 1. Green, current, coordinated
+
+- [ ] CI green on `main` — lint, conformance-enforced suite, and wheel
+      across 3.11/3.12/3.13, plus the image build-and-boot step.
+- [ ] SPEC.md changelog carries an entry for this version.
+- [ ] **The re-pin handshake.**  Downstream consumers may pin fauxbus
+      in more than one place (the first consumer pins it twice: once
+      as an application dependency, once in its deploy stack).  Hand
+      consumers the new tag so every pin moves **in one commit** —
+      never let pins drift, because a half-repinned consumer tests two
+      different fakes and believes it tested one.
+
+## 2. Version and tag
+
+- [ ] `src/fauxbus/__init__.py`: drop the `.dev0` from `__version__`
+      (e.g. `0.1.0.dev0` → `0.1.0`).  **That one line is the whole
+      bump** — pyproject reads it at build time.  It did not use to be:
+      the version lived in two files, this checklist named only one of
+      them, and v0.1.0 and v0.1.1 both shipped reporting `0.1.0.dev0`
+      to `--version`, the banner, and `GET /_fauxbus/`.  A checklist
+      that names one of two sources of truth is a checklist that walks
+      you confidently past the bug.
+- [ ] Confirm the artifact agrees before you tag: `python -m build`
+      then check `dist/` is named for the version you meant.  (CI's
+      tagged pipeline enforces this too, but after the tag exists.)
+- [ ] Commit `Release vX.Y.Z`, tag `vX.Y.Z`, push commit and tag.
+- [ ] Immediately follow with a bump to the next `.dev0` so `main` is
+      never ambiguous about whether it is a release.
+
+## 3. Artifacts
+
+- The wheel: CI builds it on every push; the tagged pipeline's wheel is
+  the release artifact.
+- The image: built from the tag via the shipped `Containerfile`.  It
+  carries its own CycloneDX SBOM at `/usr/share/fauxbus/sbom.json`,
+  generated at image build from a clean install of the wheel and
+  asserted by CI — for a zero-dependency package, the SBOM is the
+  receipt for the packaging claim.  A bare wheel install can mint the
+  same receipt: `cyclonedx-py environment <venv-python>`.
+- Publication: **PyPI — decided 2026-08-05, not yet armed.**  The name
+  is free and the v0.1.0 artifacts pass `twine check`.  The sequence,
+  in order, none of it improvised at tag time:
+  1. **First upload is manual**, from a clean tag build:
+     `git archive vX.Y.Z | tar -x -C /tmp/rel`, then `python -m build`
+     and `twine upload dist/*` from there.  Manual because the first
+     upload is what creates the PyPI project a token can be scoped to.
+  2. **Scope a token** to the project; store it as the Woodpecker
+     secret `pypi_token`.
+  3. **Restore the parked `publish-pypi` step** at the bottom of
+     `.woodpecker.yml` (restore conditions annotated there).  Tags
+     publish automatically from then on, with a guard that dies if the
+     tag's version disagrees with the built artifacts.
+  4. **Then, and only then, flip the docs**: README's install line
+     becomes the real `pipx install fauxbus`, and the blog draft's
+     "not on PyPI yet" caveat goes.  Docs never promise a package
+     that isn't live.
+
+  Prerequisite for all of it: public homepage/issues URLs in
+  pyproject (the mirror decision).  **Satisfied 2026-08-07** — they
+  point at `github.com/atmarx/fauxbus`, which is public and has issues
+  enabled.  A container registry remains a decision not yet taken.
+
+## 4. Tell the people
+
+- Announce the release where consumers actually look, with the
+  PROVISIONAL inventory and the re-pin pointer.  Consumers learn about
+  releases from the announcement, not from watching the repo.