From 897e26c7e198425f5220ac8a0a5e32c5f7f21f6c Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Thu, 19 Nov 2026 22:27:28 +0100 Subject: [PATCH 1/2] chore: remove the public demo deployment Delete the tracked deployment shape, its workflows and its verification code. --- .github/workflows/ci.yml | 49 -- .github/workflows/deploy-prod.yml | 304 ------------- .github/workflows/image.yml | 3 +- .github/workflows/release.yml | 46 +- README.md | 1 - compose.yaml | 3 +- deploy/.env.example | 13 - deploy/check-front.sh | 299 ------------ deploy/compose.yaml | 154 ------- deploy/deploy.py | 326 ------------- deploy/deployci.sudoers | 26 -- deploy/install_shape.py | 421 ----------------- deploy/installci.sudoers | 26 -- deploy/proxy/Dockerfile | 57 --- deploy/proxy/conf.d/cloudflare-ips.conf | 39 -- deploy/proxy/conf.d/default.conf | 155 ------- deploy/proxy/nginx.conf | 106 ----- deploy/proxy/www/404.html | 104 ----- deploy/selvage-update.service | 27 -- deploy/selvage-update.timer | 11 - deploy/test_compose_args.py | 278 ----------- deploy/test_deploy.py | 480 ------------------- deploy/test_front_limits.py | 561 ----------------------- deploy/test_install_shape.py | 582 ------------------------ docs/deploying.md | 5 +- docs/operating-the-demo.md | 166 ------- docs/publishing.md | 21 +- flake.nix | 90 ---- lychee.toml | 29 +- scripts/ci-local.sh | 40 +- scripts/release-tags.sh | 3 +- scripts/test_verify_deploy.py | 432 ------------------ scripts/test_wait_for_deploy.py | 445 ------------------ scripts/verify_deploy.py | 466 ------------------- scripts/wait_for_deploy.py | 435 ------------------ 35 files changed, 25 insertions(+), 6178 deletions(-) delete mode 100644 .github/workflows/deploy-prod.yml delete mode 100644 deploy/.env.example delete mode 100755 deploy/check-front.sh delete mode 100644 deploy/compose.yaml delete mode 100755 deploy/deploy.py delete mode 100644 deploy/deployci.sudoers delete mode 100755 deploy/install_shape.py delete mode 100644 deploy/installci.sudoers delete mode 100644 deploy/proxy/Dockerfile delete mode 100644 deploy/proxy/conf.d/cloudflare-ips.conf delete mode 100644 deploy/proxy/conf.d/default.conf delete mode 100644 deploy/proxy/nginx.conf delete mode 100644 deploy/proxy/www/404.html delete mode 100644 deploy/selvage-update.service delete mode 100644 deploy/selvage-update.timer delete mode 100644 deploy/test_compose_args.py delete mode 100644 deploy/test_deploy.py delete mode 100755 deploy/test_front_limits.py delete mode 100644 deploy/test_install_shape.py delete mode 100644 docs/operating-the-demo.md delete mode 100644 scripts/test_verify_deploy.py delete mode 100755 scripts/test_wait_for_deploy.py delete mode 100755 scripts/verify_deploy.py delete mode 100755 scripts/wait_for_deploy.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b14a818..7db56b5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -136,36 +136,6 @@ jobs: - name: evaluate every check run: nix flake check --no-build . - # The guard around the deploy script (`deploy/deploy.py`) and the public - # demo's front under a real nginx (`deploy/test_front_limits.py`): the - # checks here that are not Cargo targets. Stdlib Python and nginx, so the runner - # needs nothing but nix. - - name: the public demo's deploy guard - run: nix build .#checks.x86_64-linux.prod-deploy --no-link --print-build-logs - - # The other root command the CI user on that box may run - # (`deploy/install_shape.py`): the shape arrives on stdin, only `compose.yaml` - # and `proxy/` are accepted, and every other name, link, device and - # traversing path is refused with the box untouched. - - name: the public demo's shape installer - run: nix build .#checks.x86_64-linux.prod-shape --no-link --print-build-logs - - # The public demo's front, under its real configuration and a real nginx, in - # both halves: `test_front_limits.py` measures whether a source is refused and - # whether one metered endpoint can spend another's budget, and `check-front.sh` - # reads the front's own answers back out of the bytes it serves — a missing - # path answered with this instance's not-found page where the page container's - # 404 would otherwise arrive, and a request naming a host this front is not the - # server for closed rather than served. Every one is about a running proxy, and - # none is readable from the configuration. - - name: the public demo's front - run: nix build .#checks.x86_64-linux.prod-front --no-link --print-build-logs - - # The command lines the tracked compose shapes give the server, run against - # the binary: a value it refuses is a container that exits 2 and - # restart-loops. - - name: the deployed command line - run: nix build .#checks.x86_64-linux.deploy-args --no-link --print-build-logs # The command this repository's release workflow runs before it commits a # version (`scripts/bump-version.sh`): a bump word in, the next version on the @@ -174,25 +144,6 @@ jobs: - name: the version bump run: nix build .#checks.x86_64-linux.bump-version --no-link --print-build-logs - # The deploy workflow's verification (`scripts/verify_deploy.py`): the origin, - # read on the box through the front over the SSH path the deploy itself used, - # is the assertion — a version other than the one asked for, or a page that - # stops answering, fails the run — while the public read is only reported, - # because an edge answers a programmatic client on a datacenter address with a - # managed challenge. The suite drives the poll loops with injected reads and - # the `ssh`/`curl`-facing edges against stand-ins on `PATH`, so it needs no - # network, no token and no live deploy. - - name: the deploy workflow's verification - run: nix build .#checks.x86_64-linux.deploy-verify --no-link --print-build-logs - - # The watcher the release's last step runs (`scripts/wait_for_deploy.py`): - # `gh workflow run` prints no run id, so the run to wait on is the newest - # one of the workflow that is not the newest seen before the dispatch, and - # the release fails unless it concludes `success`. The suite drives the poll - # loops with injected reads and the `gh`-facing edges against a stand-in on - # `PATH`, so it needs no network, no token and no real run. - - name: the release's wait for its deploy - run: nix build .#checks.x86_64-linux.deploy-wait --no-link --print-build-logs # The guard around a workflow's `dry_run` input (`scripts/check_dry_run_gating.py`): # a plan step prints what a real run would do, and every step after it has to be diff --git a/.github/workflows/deploy-prod.yml b/.github/workflows/deploy-prod.yml deleted file mode 100644 index 91d4444..0000000 --- a/.github/workflows/deploy-prod.yml +++ /dev/null @@ -1,304 +0,0 @@ -name: deploy-prod - -# The button that redeploys the public demo, `selvage-demo.dontblameme.dev`, from -# what is already published. -# -# **There is no approval gate on it.** The credential below is bound to the -# **ref**, not to an environment. The tailnet's federated identity is constrained -# to exactly -# `repo:selvage-protocol@328844633/reference_server@1368869493:ref:refs/heads/main` — -# the immutable form, with the owner's and the repository's numeric ids, because -# this organisation has ID-based OIDC subject claims enabled, and the plain form is -# rejected with a 403 at the exchange. So this workflow runs on `main` and nowhere -# else, and the *credential* is what enforces it: a dispatch at a tag or another -# branch presents a subject naming the ref it ran at — `…:ref:refs/tags/` or -# `…:ref:refs/heads/` — rather than `refs/heads/main`, and is refused at -# the exchange. A job that **declares an environment** is refused as well, which is -# why no such line is in this file: it would present `…:environment:prod`. -# -# A change **CI initiates** reaches the box with no human in the loop. -# A compromised workflow, a compromised third-party action or a stolen repository -# secret has a credential for the box. What is left is the box's own bound — the -# two argument-free root commands below — and how little this dispatch can express. -# -# The box's update timer is unaffected by any of that, and remains the second way -# production moves. It follows the tags `/srv/selvage/.env` names, and while `.env` -# names `latest`, whatever is published to `latest` reaches production **within one -# five-minute tick**, and a new `selvaged` ends every room. That means any `v*` -# release tag of this repository (`image.yml` keeps a prerelease off `latest`), -# any `v*` tag of `web_client`, prerelease included, since its image workflow -# still moves `latest` for one, and anything else holding `packages: write` on -# the organisation's GHCR, a compromised publish step or action included. -# Pinning a version in `.env` is what makes a release a deliberate change rather -# than a tick. A version tag is mutable too, so a GHCR writer who overwrites -# the pinned tag is still followed; only a digest would close that, and the -# owner chose tags. -# -# How it reaches the box: `tailscale/github-action` joins the tailnet as an -# **ephemeral** node tagged `tag:ci`, using Tailscale workload identity -# federation — a client id and an audience, which Tailscale's own documentation -# says are not secrets, exchanged for a short-lived node together with a -# GitHub-signed OIDC token whose `sub` claim carries this run's ref. The pair -# lives in this repository's secrets, and the ref above is the whole of what the -# exchange checks. -# -# Then Tailscale SSH as `deployci`, a local user on the box with no password, no -# key and two permitted root commands — `/usr/local/sbin/selvage-deploy`, whose -# request names which image tags run, and `/usr/local/sbin/selvage-install-shape`, -# which installs the box's shape from a stream on stdin — each with no argument -# wildcard. Tailscale SSH cannot restrict the command (the -# policy's `ssh` rules have no `cmd` field), so the bound lives on the box and -# is proved there rather than claimed here. -# -# What a run may change, and the whole of what this dispatch can do to production. -# Two halves, and the second is opt-in: -# -# * **which tag of two already-published images `/srv/selvage/.env` names**. The -# request carries one tag reference per image this dispatch names, the box -# rewrites those lines of `.env` and nothing else, and pulls and ups. An input -# this dispatch leaves empty means "leave that line exactly as it is". The -# box's update timer follows whatever tag `.env` names, so a dispatch is how a -# service is pinned to a version, moved back to `latest`, or moved at once. -# * **the box's shape**, and only with `install_shape=true`: `compose.yaml` and -# `proxy/` as this run's own ref carries them, installed by -# `selvage-install-shape` and read back against the tracked files afterwards. -# That is a bigger lever than the request above — `compose.yaml` is where a -# published port, a capability, a mount and a memory limit live — and it is the -# tracked, reviewed pair on `main` or nothing, because the archive is taken -# from the ref this run is on. The release workflow sets this input when a -# release moved `deploy/`, which is the half of a shape change CI can do for -# itself; the two scripts and their sudoers lines stay hand work. -# -# What a run cannot do to a live session: the page container is separate and the -# server's state is memory-only, so this is where that cost is written down — -# **replacing `selvaged` ends every room on the instance.** There is no -# drain and no room count; `/meta` is the only read besides `/session`. That is -# why a dispatch is deliberate rather than a tag push, and why it is the release -# workflow that reaches for it rather than a tag doing it on its own. -# -# `workflow_dispatch` only: no `pull_request` and no `push` event can reach this -# file, so no branch can deploy itself. The deploy workflow that runs is the -# reviewed one on `main` (dispatch it with `--ref main`), and the *images* are -# chosen by the inputs. -# -# Every action is pinned by commit SHA with the version it is in a comment. A -# SHA behind a comment that claims a different version is worse than no pin, so -# each one below was read back from the action's repository when it was written. -# -# `ubuntu-24.04`: this job downloads a Tailscale tarball from -# `pkgs.tailscale.com`, reads `ghcr.io` and speaks to the tailnet. It also has to -# support Node.js 24, which `tailscale/github-action@v4.2.0` declares -# (`runs.using: node24`); the GitHub-hosted image does, and this repository -# already runs `actions/checkout@v7.0.1` — also `node24` — on `ubuntu-24.04` -# today. -on: - workflow_dispatch: - inputs: - server_version: - description: 'selvaged tag to deploy: a version (e.g. 0.4.6) or latest. Empty leaves it alone.' - required: false - default: '' - web_version: - description: 'selvage-web tag to deploy: a version (e.g. 0.4.6) or latest. Empty leaves it alone.' - required: false - default: '' - install_shape: - description: "Install the box's shape (compose.yaml and proxy/) from this run's ref, then deploy" - required: false - default: false - type: boolean - -# Two deploys never interleave, and a queued one is not silently dropped: a run that -# another run cancelled would leave the box wherever it had got to, with no record -# of what it had already changed. -concurrency: - group: deploy-prod - cancel-in-progress: false - -permissions: - contents: read - -jobs: - deploy: - runs-on: ubuntu-24.04 - timeout-minutes: 20 - # `id-token: write` is what mints the OIDC token the Tailscale federated - # identity exchange needs; its `sub` claim names this run's ref, which is the - # subject the console holds. Nothing here needs a write to the repository. - permissions: - contents: read - id-token: write - steps: - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - # The request is built and checked against the box's own grammar here, - # before the tailnet is joined, so a malformed tag fails without touching - # anything. It stays a tag: the box pulls it and its deploy log names the - # digest the tag resolved to there, which is the record of what ran. An - # input that is empty means "leave that line as it is" and is simply absent. - - name: build the request - env: - SERVER_VERSION: ${{ inputs.server_version }} - WEB_VERSION: ${{ inputs.web_version }} - run: | - set -euo pipefail - request="$RUNNER_TEMP/deploy-request" - : >"$request" - if [ -n "$SERVER_VERSION" ]; then - echo "SELVAGED_IMAGE=ghcr.io/selvage-protocol/selvaged:$SERVER_VERSION" >>"$request" - fi - if [ -n "$WEB_VERSION" ]; then - echo "SELVAGE_WEB_IMAGE=ghcr.io/selvage-protocol/selvage-web:$WEB_VERSION" >>"$request" - fi - python3 -B - "$request" <<'EOF' - import sys - sys.path.insert(0, "deploy") - import deploy - try: - deploy.parse_request(open(sys.argv[1], "rb").read()) - except deploy.Refused as refusal: - sys.exit(f"refused: {refusal}") - EOF - cat "$request" - - # `ping` and the loop below are the plan's answer to the tailnet being - # eventually consistent about a peer that came up seconds ago: verify - # reachability, then poll the predicate with a deadline rather than sleep - # and hope. The ephemeral node is logged out again in the action's post - # step, so nothing is left joined between runs. - - uses: tailscale/github-action@064b10558093f38325e838ddea35486bdc6b1d5c # v4.4.0 - with: - oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }} - audience: ${{ secrets.TS_AUDIENCE }} - tags: tag:ci - ping: selvage-protocol-prod - - - name: wait for the box to answer as deployci - run: | - set -euo pipefail - last='' - deadline=$((SECONDS + 150)) - while :; do - if last=$(ssh -o BatchMode=yes -o ConnectTimeout=10 \ - -o StrictHostKeyChecking=accept-new \ - deployci@selvage-protocol-prod true 2>&1); then - echo "deployci@selvage-protocol-prod answers" - break - fi - if [ "$SECONDS" -ge "$deadline" ]; then - echo "deployci@selvage-protocol-prod did not answer within 150s; last: $last" >&2 - exit 1 - fi - sleep 5 - done - - # The box's shape, and only when one is owed — the release workflow sets this - # input when `deploy/` moved since the previous release. `git archive` takes the - # two tracked paths from **this run's ref**, which is `main`, and the stream goes - # in on stdin because the sudoers line permits no argument at all. The installer - # is idempotent, so a stream the box already holds writes nothing and restarts - # nothing, and a bad entry is refused with the box untouched. - - name: install the box's shape from this ref - if: inputs.install_shape - env: - SHAPE_REF: ${{ github.ref_name }} - run: | - set -euo pipefail - git archive --format=tar "$SHAPE_REF:deploy" compose.yaml proxy \ - | ssh -o BatchMode=yes -o ConnectTimeout=10 \ - deployci@selvage-protocol-prod \ - '/usr/bin/sudo /usr/local/sbin/selvage-install-shape' - - # Nothing checks the installed shape against the tracked one — neither the - # deploy nor the timer ever writes it — so this does, the comparison the - # production demo's runbook describes under *Changing the shape*: each file's - # digest here against its digest there. Only the two entries the installer - # owns are compared, because `.env` is the box's and is not installed. - - name: read the installed shape back - if: inputs.install_shape - run: | - set -euo pipefail - box=deployci@selvage-protocol-prod - mapfile -t names < <(git ls-files deploy/compose.yaml deploy/proxy | sed 's|^deploy/||') - paths=() - for name in "${names[@]}"; do - paths+=("/srv/selvage/$name") - done - installed=$(ssh -o BatchMode=yes -o ConnectTimeout=10 "$box" "sha256sum ${paths[*]}") - agreed=1 - for name in "${names[@]}"; do - tracked=$(sha256sum "deploy/$name" | cut -d' ' -f1) - there=$(printf '%s\n' "$installed" | awk -v p="/srv/selvage/$name" '$2 == p { print $1 }') - if [ "$tracked" = "$there" ]; then - echo "same: $name" - else - agreed=0 - echo "differs: $name (tracked $tracked, installed ${there:-unreadable})" >&2 - fi - done - if [ "$agreed" != 1 ]; then - echo "the installed shape is not the tracked one; a proxy/ left half-installed goes on serving the configuration from before" >&2 - exit 1 - fi - echo "the installed shape agrees with $GITHUB_REF_NAME for ${#names[@]} files" - - # The other privileged thing this job does, and it is one argument-free - # command line: `deployci` may run nothing else as root. The request goes - # in on stdin because the sudoers rule deliberately has no argument - # wildcard, and the script refuses every value that is not a tag of one of - # the two images. - - name: deploy - run: | - set -euo pipefail - ssh -o BatchMode=yes -o ConnectTimeout=10 \ - deployci@selvage-protocol-prod \ - '/usr/bin/sudo /usr/local/sbin/selvage-deploy' \ - <"$RUNNER_TEMP/deploy-request" - - # A deploy that goes green because `docker compose` exited zero is a deploy - # nobody checked, so this asserts what is actually serving: the origin, read - # on the box through the front over the SSH path step 5 already opened — - # `https://127.0.0.1/meta` and the page, both naming the demo's own `Host`, - # because the front is the server for that name and closes the connection - # for any other one — and the run fails unless it reports the version this - # dispatch asked for. `/meta` reports the Cargo version, so a commit-stamped - # tag (`0.4.6-97ff967`) is compared by its version and a prerelease - # (`1.0.0-rc.1`) as it is. A tag that names no version (`latest`) has none - # to compare, so `/meta` is read and not compared, as it is for a page-only - # dispatch. - # - # The *public* URL is read in three shapes, and only one of them decides the - # run. Cloudflare serves a managed challenge to a programmatic client on a - # datacenter address — this runner, and the box itself — and an edge is not - # something a deploy can fix, so a challenge, an unreadable read, and any - # other answer that is not a version are reports: each says in plain words - # what came back, a challenge ends the attempt at the first challenge - # response instead of polling a deadline it cannot pass, and none of them - # turns a healthy deploy red. A read that answers 200 reporting a version - # *other* than the one this dispatch named is red — there the origin above is - # right and the edge is serving something this deploy did not put behind it, - # a stale cache or a route pointing elsewhere, which is what this step exists - # to catch and what the origin read cannot see. A read reporting the version - # deployed is green, so where the edge does let a client like this one through - # the check comes back on its own. - # - # `scripts/verify_deploy.py` is both reads. Each read polls a real - # predicate with its own 60 s deadline and reports what it last observed, - # so a step that cannot pass says so in about a minute instead of looking - # hung. - - name: verify the origin serves what was deployed - env: - SERVER_VERSION: ${{ inputs.server_version }} - run: | - set -euo pipefail - args=(--ssh-target deployci@selvage-protocol-prod) - expected=$SERVER_VERSION - if [[ $expected =~ ^(.+)-[0-9a-f]{7,40}$ ]]; then - expected=${BASH_REMATCH[1]} - fi - if [[ $expected =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then - args+=(--expect-version "$expected") - fi - scripts/verify_deploy.py "${args[@]}" diff --git a/.github/workflows/image.yml b/.github/workflows/image.yml index 7fc53b7..07db1c4 100644 --- a/.github/workflows/image.yml +++ b/.github/workflows/image.yml @@ -354,8 +354,7 @@ jobs: context: . platforms: linux/amd64,linux/arm64 push: true - # A prerelease never moves `latest`: the public demo follows it - # unapproved (`deploy-prod.yml`), and a blank line here is no tag. + # A prerelease never moves `latest`: a blank line here is no tag. tags: | ghcr.io/selvage-protocol/selvaged:${{ steps.tags.outputs.name }} ghcr.io/selvage-protocol/selvaged:${{ steps.tags.outputs.version }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a40aef9..80710da 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,7 +1,7 @@ name: release -# The button that cuts a release: the bump word in, and the version, the tag, the -# image and the public demo's pin out. +# The button that cuts a release: the bump word in, and the version, the tag and the +# image out. # # A manual dispatch takes `patch`, `minor` or `major`, computes the next version # from the one `Cargo.toml` already carries, and **refuses unless that version is @@ -27,15 +27,10 @@ name: release # commit that is about to land, before anything is pushed. # # Every event a workflow creates with that token is invisible to Actions, so the -# tag push starts nothing either and the two dispatches below are explicit: +# tag push starts nothing either, so the dispatch below is explicit: # `gh workflow run image.yml --ref "v"` is the event the loop-prevention -# rule exempts, and `deploy-prod.yml` is asked for by name once the image it names -# actually exists on GHCR. That last dispatch is watched: `gh workflow run` prints -# no run id, so `scripts/wait_for_deploy.py` reads the workflow's runs, dispatches, -# and waits for the run the dispatch created — a release that says the demo moved -# fails unless that run concludes `success`, rather than standing green beside a -# red deploy. `deploy-prod.yml` does its own verification of what the box serves; -# this workflow reads the run's conclusion and does not repeat it. +# rule exempts. The release waits for that image to exist on GHCR before it +# reports success. # # `dry_run` stops before the first write — before the tree is touched, the gate # runs, anything is pushed or anything is dispatched — and prints the whole plan. A @@ -178,8 +173,6 @@ jobs: publish: image.yml dispatched at v$NEXT, then ghcr.io/selvage-protocol/selvaged:$NEXT waited for (an anonymous read, polled with a 45-minute deadline) - deploy: deploy-prod.yml at main with server_version=$NEXT, and install_shape=true - if deploy/ changed since v$CURRENT EOF release: @@ -192,7 +185,7 @@ jobs: # seen this flake, and the image it publishes is waited for afterwards. timeout-minutes: 90 # `contents: write` pushes the bump and the tag; `actions: write` is what lets - # this run dispatch `image.yml` and `deploy-prod.yml` at all. + # this run dispatch `image.yml` at all. permissions: contents: write actions: write @@ -201,8 +194,7 @@ jobs: with: # The token in `.git/config` is what pushes the bump and the tag below. persist-credentials: true - # Every tag, and the whole history: the last step compares `deploy/` - # against the previous release's tag, which has to be a local ref for it. + # Tags and full history are read by the release guards below. fetch-depth: 0 # A release-only retry can reuse a successful plan after remote tags changed. @@ -328,27 +320,3 @@ jobs: sleep 20 done - # The bump is pushed and the image exists; what is left is the public demo. - # `deploy-prod.yml` changes the tag `/srv/selvage/.env` names for `selvaged`, - # and installs the box's shape when this release moved one. `gh workflow run` - # prints no run id, so `scripts/wait_for_deploy.py` reads the workflow's runs, - # dispatches, and waits for the run this dispatch created: this step fails - # unless that run concludes `success`, which is what keeps a green release from - # standing beside a red deploy. The deploy verifies the origin itself, so - # nothing here re-reads `/meta`. - - name: hand the release to the public demo, and fail when the deploy fails - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - VERSION: ${{ needs.plan.outputs.version }} - PREVIOUS: ${{ needs.plan.outputs.current }} - run: | - set -euo pipefail - args=(-f "server_version=$VERSION") - # What changed since the *last release*, not since the bump: the bump - # touches no file of the shape, and `$GITHUB_SHA` is the commit this run - # was dispatched at, which is the one before it. - if [ -n "$(git diff --name-only "v$PREVIOUS" "$GITHUB_SHA" -- deploy/)" ]; then - args+=(-f install_shape=true) - echo "deploy/ changed since v$PREVIOUS; the box's shape is installed as part of the deploy" - fi - scripts/wait_for_deploy.py --dispatch --workflow deploy-prod.yml --ref main "${args[@]}" diff --git a/README.md b/README.md index 6d6ce93..bd25a5d 100644 --- a/README.md +++ b/README.md @@ -111,7 +111,6 @@ with its default. `--version` prints `selvaged/`. - [The server's shape](docs/the-server.md): rooms in memory, the grace period and `/meta`. - [The first room](docs/rooms.md): who mints a room, and which clients host or join. - [Deploying](docs/deploying.md): the addresses a client dials, the bind and TLS. -- [Operating the demo](docs/operating-the-demo.md): provisioning, the CI privilege boundary, verification, and recovery. - [Publishing](docs/publishing.md): version tags, release gates, and partial-release recovery. - [Serving the page](docs/serving-the-page.md): `--serve-page` and the served headers. - [Licence](docs/licence.md): what each path is under, and what the image carries. diff --git a/compose.yaml b/compose.yaml index eb3b4b8..07a1558 100644 --- a/compose.yaml +++ b/compose.yaml @@ -1,6 +1,5 @@ # Self-host for someone evaluating selvage on their own machine: two containers -# on loopback — the server, and the page image relaying to it. The public demo's -# shape is in `deploy/`. +# on loopback — the server, and the page image relaying to it. # # No volumes: the server is memory-only and the page is served from the page # image, so there is nothing to persist and nothing to mount. diff --git a/deploy/.env.example b/deploy/.env.example deleted file mode 100644 index fbca291..0000000 --- a/deploy/.env.example +++ /dev/null @@ -1,13 +0,0 @@ -# Copy to `/srv/selvage/.env` (owner `selvage`, mode 0600). Compose reads it from -# the project directory, so nothing has to be exported. -# -# The images the next `docker compose pull && docker compose up -d` runs, and -# what the update timer follows. `latest` moves with every release; pin a -# service by writing a published version instead (`selvaged:`), and unpin -# it by writing `latest` back. - -# FSL-1.1-MIT. -SELVAGED_IMAGE=ghcr.io/selvage-protocol/selvaged:latest - -# MIT OR Apache-2.0. -SELVAGE_WEB_IMAGE=ghcr.io/selvage-protocol/selvage-web:latest diff --git a/deploy/check-front.sh b/deploy/check-front.sh deleted file mode 100755 index 922730f..0000000 --- a/deploy/check-front.sh +++ /dev/null @@ -1,299 +0,0 @@ -#!/usr/bin/env bash -# -# The front's own answers, read back out of the bytes it serves. -# -# deploy/check-front.sh -# -# The front answers two things itself, and both are asserted here against a -# running nginx rather than against the files that configure it: -# -# - the not-found page, `proxy/www/404.html`, which the `/404.html` location -# serves in place of the page container's own 404; -# - the host guard, which closes a request naming a name this block is not the -# server for. -# -# What matters is not that a string is in a file this repository owns, but that -# a visitor receives it. A missing path the front stops answering with this -# instance's own page, a `root` that moves, or a `www/` the image stops -# installing are all invisible to a grep of the configuration and all fail here. -# -# No Docker: this host has none. The front's real configuration runs under -# nginx from the host, or from nixpkgs when there is no nginx on `PATH`. Two -# substitutions make that possible — the upstream names answered on loopback, -# and TLS off, because a location answers the same way over either — and each -# one is asserted below, so a change to the front's shape cannot be silently -# masked by the harness. -# -# Everything written stays under `.tmp/` in this checkout — `/tmp` is a -# RAM-backed tmpfs on some hosts, and building there has taken a machine down — -# unless `CHECK_FRONT_WORKDIR` moves it, which a derivation has to do. -set -euo pipefail - -here=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd) -repo=$(cd -- "$here/.." && pwd) -proxy="$here/proxy" - -# The same escape hatch `test_front_limits.py` takes as `FRONT_LIMITS_WORKDIR`, for -# the same reason: `${./deploy}` inside a derivation is a store path, so `$repo` is -# `/nix/store` and the default below cannot be written to. -work=${CHECK_FRONT_WORKDIR:-$repo/.tmp/proxy-check-front} - -server_conf="$proxy/nginx.conf" -default_conf="$proxy/conf.d/default.conf" - -# Which nginx runs the front: a named one, then the host's, then nixpkgs'. The -# override is `NGINX_BIN` — `test_front_limits.py` reads that name for the same -# choice — and never `NGINX`, which is a variable nginx itself owns. -if [ -n "${NGINX_BIN:-}" ]; then - ngx=$NGINX_BIN -elif command -v nginx >/dev/null 2>&1; then - ngx=$(command -v nginx) -elif command -v nix >/dev/null 2>&1; then - ngx=$(nix build --no-link --print-out-paths nixpkgs#nginx)/bin/nginx -else - printf 'no nginx on PATH and no nix to get one; nothing was proved\n' >&2 - exit 2 -fi - -# nginx reads `NGINX` as the list of sockets a socket-activated parent handed it, -# the one environment variable it does not ignore. A value that is not a socket -# number is logged and passed over, but its *presence* is what nginx acts on: it -# takes itself for inherited, skips daemonising, and runs the master in the -# foreground. The start below would then never return, so a front that failed to -# start would hang where it has to exit. An inherited value is dropped here. -unset NGINX - -failures=0 -ok() { printf ' ok %s\n' "$*"; } -bad() { - printf ' FAIL %s\n' "$*" - failures=$((failures + 1)) -} -say() { printf '\n=== %s ===\n' "$*"; } - -# One request, with the Host the front is the server for: the body to `$2`, and -# `status content-type` on stdout. -fetch() { curl -sS --max-time 5 -H "Host: $demo_host" -o "$2" -w '%{http_code} %{content_type}' "$1"; } - -# A free loopback port, asked of the kernel rather than assumed, so a run -# beside another nginx cannot collide or fail for the wrong reason. -free_port() { - local port - for port in $(seq "$1" "$2"); do - if ! (exec 3<>"/dev/tcp/127.0.0.1/$port") 2>/dev/null; then - printf '%s\n' "$port" - return 0 - fi - done - printf 'no free port in %s-%s\n' "$1" "$2" >&2 - return 1 -} - -rm -rf "$work" -mkdir -p "$work/conf.d" "$work/tmp" "$work/prefix" "$work/stub" - -listen_port=$(free_port 18443 18462) -server_port=$(free_port 18463 18482) -page_port=$(free_port 18483 18502) - -stub_pid='' -# The trap runs on the way out of a failed start as much as a good one, so nothing -# in it may block. `kill`'s default TERM is a signal a child may catch or ignore, -# and a `wait` for a child that never dies blocks the trap for good; KILL cannot -# be caught, so the `wait` below cannot outlive it. The stand-in serves a -# directory this script is about to delete; it has nothing to shut down gently. -cleanup() { - "$ngx" -c "$work/nginx.conf" -p "$work/prefix" -e "$work/error.log" -s stop >/dev/null 2>&1 || true - if [ -n "$stub_pid" ]; then - kill -KILL "$stub_pid" 2>/dev/null || true - wait "$stub_pid" 2>/dev/null || true - fi -} -trap cleanup EXIT - -say "the harness" - -# The root the front serves its own not-found page from, read out of the -# configuration rather than repeated here: the Dockerfile below is asserted to -# install it there, so the two cannot drift apart in silence. The `/404.html` -# location is the only one with a `root`, so there is exactly one to read. -www_root=$(sed -n 's/^[[:space:]]*root \(.*\);$/\1/p' "$default_conf" | sort -u) -if [ -z "$www_root" ] || [ "$(printf '%s\n' "$www_root" | wc -l)" != 1 ]; then - printf 'not exactly one root in %s: the harness has nothing to point at\n' "$default_conf" >&2 - exit 2 -fi - -# The one name the front's block is the server for, read out of the configuration -# for the same reason the root is: every request below has to carry it. A request -# for any other Host is closed rather than served (that guard is in the block -# above and `test_front_limits.py` measures it in both directions), so a harness -# with the wrong name here would fail every claim for the wrong reason. -demo_host=$(sed -n 's/^[[:space:]]*server_name \([^;[:space:]]*\);$/\1/p' "$default_conf") -if [ -z "$demo_host" ]; then - printf 'no server_name in %s: the harness has no Host to ask for\n' "$default_conf" >&2 - exit 2 -fi - -sed \ - -e "s#^pid /dev/shm/nginx.pid;#pid $work/nginx.pid;#" \ - -e "s#^error_log /dev/stderr crit;#error_log $work/error.log crit;#" \ - -e "s#/dev/shm/client_temp#$work/tmp/client_temp#" \ - -e "s#/dev/shm/proxy_temp#$work/tmp/proxy_temp#" \ - -e "s#/dev/shm/fastcgi_temp#$work/tmp/fastcgi_temp#" \ - -e "s#/dev/shm/uwsgi_temp#$work/tmp/uwsgi_temp#" \ - -e "s#/dev/shm/scgi_temp#$work/tmp/scgi_temp#" \ - -e "s#include /etc/nginx/conf.d/\*.conf;#include $work/conf.d/*.conf;#" \ - "$server_conf" >"$work/nginx.conf" - -sed \ - -e "s#^\( *\)listen 8080 ssl;#\1listen 127.0.0.1:$listen_port;#" \ - -e "/^ *ssl_certificate/d" \ - -e "s#http://selvaged:8080#http://127.0.0.1:$server_port#g" \ - -e "s#http://selvage-web:8080#http://127.0.0.1:$page_port#g" \ - -e "s#^\( *\)root $www_root;#\1root $proxy/www;#" \ - "$default_conf" >"$work/conf.d/default.conf" - -cp "$proxy/conf.d/cloudflare-ips.conf" "$work/conf.d/" - -# Every string the two `sed`s above rewrite must still be in the real file, and -# must be gone from the harness. A front whose shape changed — a third -# `proxy_pass`, a second listener, an upstream renamed — stops this script -# instead of being quietly rewritten into something that passes. -rewritten() { - local needle=$1 file=$2 - if [ "$(grep -cF -- "$needle" "$proxy/$file" 2>/dev/null || true)" -lt 1 ]; then - bad "'$needle' is gone from $file; this harness rewrites it and must be updated" - return 0 - fi - local harness_file="$work/$file" - if grep -qF -- "$needle" "$harness_file" 2>/dev/null; then - bad "'$needle' survived into the harness copy of $file" - fi -} - -rewritten '/dev/shm/nginx.pid' 'nginx.conf' -rewritten '/dev/stderr crit' 'nginx.conf' -rewritten '/dev/shm/client_temp' 'nginx.conf' -rewritten '/dev/shm/proxy_temp' 'nginx.conf' -rewritten '/dev/shm/fastcgi_temp' 'nginx.conf' -rewritten '/dev/shm/uwsgi_temp' 'nginx.conf' -rewritten '/dev/shm/scgi_temp' 'nginx.conf' -rewritten '/etc/nginx/conf.d/*.conf' 'nginx.conf' -rewritten 'listen 8080 ssl;' 'conf.d/default.conf' -rewritten 'http://selvaged:8080' 'conf.d/default.conf' -rewritten 'http://selvage-web:8080' 'conf.d/default.conf' -rewritten "root $www_root;" 'conf.d/default.conf' - -# The certificate pair is dropped rather than rewritten, so it is counted: the -# front terminates TLS and a copy of its configuration without a certificate is -# this script's, not the deployment's. -certs=$(grep -c '^ *ssl_certificate' "$default_conf" || true) -if [ "$certs" != 2 ]; then - bad "$default_conf has $certs ssl_certificate lines, expected 2 (certificate and key)" -fi -if grep -q '^ *ssl_certificate' "$work/conf.d/default.conf"; then - bad 'a ssl_certificate line survived into the harness' -fi - -if grep -qF -- "www/ $www_root" "$proxy/Dockerfile"; then - ok "the image installs www/ at $www_root, where the /404.html location reads it" -else - bad "the image does not install www/ at $www_root, so a missing path would not answer with this instance's own page" -fi - -say "starting the front" - -# The page container's stand-in. It answers the root with 200, so the front can -# be seen proxying to it, and a path it does not have with its own 404, which the -# front must replace with this instance's page. -cat >"$work/stub/index.html" <<'HTML' - - - the page container's stand-in -

the page container's stand-in

- -HTML - -python3 -m http.server "$page_port" --bind 127.0.0.1 --directory "$work/stub" \ - >"$work/page.log" 2>&1 & -stub_pid=$! - -"$ngx" -c "$work/nginx.conf" -p "$work/prefix" -e "$work/error.log" - -deadline=$((SECONDS + 15)) -# The predicate is the front answering `200`, not merely answering: the page -# container's stand-in takes a moment to bind, and a `502` from the front before -# it does is a response `curl` would otherwise call success. -until [ "$(curl -sS -o /dev/null -w '%{http_code}' --max-time 2 -H "Host: $demo_host" "http://127.0.0.1:$listen_port/")" = 200 ]; do - if [ "$SECONDS" -ge "$deadline" ]; then - bad 'the front did not answer / within 15s' - printf ' front log:\n' - sed 's/^/ /' "$work/error.log" || true - printf ' page log:\n' - sed 's/^/ /' "$work/page.log" || true - exit 1 - fi - sleep 0.25 -done -ok "the front is listening on 127.0.0.1:$listen_port" - -say "the not-found page, in place of the page container's" - -# The stand-in answers a path it does not have with its own 404 page; without -# the interception that page is what the visitor would receive. -answer=$(fetch "http://127.0.0.1:$listen_port/no/such/path" "$work/served-missing.html") -if [ "${answer%% *}" = 404 ]; then - ok 'a missing path still answers 404' -else - bad "a missing path answers ${answer%% *}, want 404" -fi -case ${answer#* } in -text/html*) ok "the not-found page is served as ${answer#* }" ;; -*) bad "the not-found page is served as ${answer#* }" ;; -esac -if cmp -s "$work/served-missing.html" "$proxy/www/404.html"; then - ok 'the bytes served for a missing path are www/404.html as it is' -else - bad 'a missing path is not answered with www/404.html as it is' -fi -if grep -q 'GET /no/such/path' "$work/page.log"; then - ok 'the missing path was asked of the page container first' -else - bad 'the missing path never reached the page container' -fi - -answer=$(fetch "http://127.0.0.1:$listen_port/404.html" "$work/served-direct.html") -if [ "${answer%% *}" = 404 ]; then - ok '/404.html is not an address of its own: it answers 404' -else - bad "/404.html answers ${answer%% *}, want 404" -fi - -say "the name the front is the server for" - -# The front's block is the only one on its port, so nginx would otherwise make it -# the default and answer any name that resolves here. `selvage.dontblameme.dev` -# is the project's landing page, served somewhere else entirely, and a request -# naming it must not reach the demo's locations. `444` is a closed connection -# with no response, which curl reports as `000` and a non-zero status. -# -# The positive half of the pair is every fetch above: they all name `$demo_host`, -# read out of the configuration, and none of them could bring a body through if -# that were not the name the front is the server for. -answer=$(curl -sS --max-time 5 -o /dev/null -w '%{http_code}' \ - -H 'Host: selvage.dontblameme.dev' "http://127.0.0.1:$listen_port/" 2>/dev/null || true) -if [ "$answer" = 000 ]; then - ok 'a request naming another host is closed rather than served' -else - bad "a request naming another host answered $answer: the front answers a name it is not the server for" -fi - -say "result" -if [ "$failures" = 0 ]; then - printf " a missing path answered with this instance's own page, and the front served only its own name\n" -else - printf ' %s assertion(s) failed\n' "$failures" >&2 -fi -# The last command, so the script's status is this and the EXIT trap above still -# runs. `exit` here would be reported as making that trap unreachable. -[ "$failures" = 0 ] diff --git a/deploy/compose.yaml b/deploy/compose.yaml deleted file mode 100644 index 7eda2f2..0000000 --- a/deploy/compose.yaml +++ /dev/null @@ -1,154 +0,0 @@ -# The public demo at `selvage-demo.dontblameme.dev`, and nothing else. -# -# Three containers on one origin, on an Azure `Standard_B2ats_v2`: 2 vCPU, -# 892 MiB of RAM and a 10 GiB swapfile. The front terminates TLS for the -# Cloudflare Origin CA certificate and routes; the server answers `/session` and -# `/meta`; the page answers everything else. `web_client`'s README owns the page. -# -# The box runs a copy of this directory at `/srv/selvage/`, which is -# self-contained: this file, `.env`, `proxy/` and `tls/`. The update timer beside -# this file pulls the tags `.env` names. -# -# Every service below is hardened the same way, and the readback of that is what -# the deployment is gated on: read-only root filesystem, every capability -# dropped, no process able to gain one, and a non-root user with no mount it -# does not need. -# -# The memory limits are the backstop, not a budget. Without them an -# over-committed server drags the host into swap or the kernel chooses a victim -# on it; with them the container dies inside its own cgroup and `restart: -# unless-stopped` brings it back in seconds, having dropped every room — visible -# and bounded. The arithmetic: 892 MiB total, about 120 MiB for the Docker -# daemon and containerd and about 350 MiB of stock Ubuntu and Tailscale, leaving -# roughly 420 for the three. 48 + 48 + 320 is 416. - -name: selvage-prod - -services: - proxy: - build: - context: ./proxy - # Built on the box from the files beside this one, never pulled: there is no - # published image for this front and there should not be one, because its - # configuration is the deployment's own. - image: selvage-prod-proxy:local - # Built only when the image is missing, so an `up -d` that changes nothing - # else leaves the front and its WebSockets alone. A change to `proxy/` is - # deployed with `docker compose up -d --build proxy`. - # Started after the two upstreams so that their names resolve. The front - # resolves `selvaged` and `selvage-web` once, at startup, and caches the - # addresses, so `restart: true` matters as much as the ordering: recreating - # an upstream can give it a new address, and a proxy left running would go on - # dialling the old one. Compose restarts this service when it recreates - # either of those. - depends_on: - selvaged: - condition: service_started - restart: true - selvage-web: - condition: service_started - restart: true - ports: - # The only port any of the three publishes. It is 443 on the host because - # Cloudflare connects to it; inside the container it is 8080, because - # nginx runs as uid 101 with every capability dropped and a non-root - # process cannot bind below 1024. - # - # Reachability is the network security group's job, not this file's: 443 - # is admitted from Cloudflare's published ranges and from nowhere else. - # Nothing here listens on 80 — Cloudflare serves the redirect at its edge. - - "443:8080" - # The one mount in this deployment, and the only file the front reads from - # outside its own image. Read-only, twice over: the front never writes a - # certificate and cannot, and every directory it does need to write — the - # pid file and the five temp paths — is already on the runtime's own tmpfs. - # The target path is the one `proxy/conf.d/default.conf` names. - # - # The key is mode 640 owned by `root` and group 101 on the host, which is - # the group uid 101 is in inside this image. - volumes: - - ./tls/origin.pem:/etc/selvage/tls/origin.pem:ro - - ./tls/origin.key:/etc/selvage/tls/origin.key:ro - read_only: true - cap_drop: - - ALL - security_opt: - - no-new-privileges:true - mem_limit: 48m - restart: unless-stopped - - selvaged: - image: ${SELVAGED_IMAGE:?set SELVAGED_IMAGE in .env} - # The image's own command is the server alone, and the page is the `selvage-web` - # container below; the limits here are the ones sized for this box. The short - # form is that `--max-connections × --outbound-queue-bytes` is the server's own - # outbound ceiling, and 32 × 8454144 is 258 MiB, the largest one this host can - # be surprised by. - # - # 8454144 is the smallest queue `selvaged` accepts at all: the 8 MiB frame - # bound plus the 64 KiB envelope headroom its own `smallest_queue_bytes` - # counts. Below it the server exits 2 with the floor named, and the - # container restart-loops; `deploy/test_compose_args.py` runs this - # command line so that a value below the floor cannot be committed again. - # - # The grace period is the reference value on purpose: `/meta` advertises it - # and both clients size their reconnect budget from it. - command: - - --listen - - 0.0.0.0:8080 - - --room-grace-ms - - "30000" - - --max-connections - - "32" - - --max-rooms - - "64" - - --max-peers-per-room - - "8" - - --outbound-queue-bytes - - "8454144" - - --max-envelope-bytes - - "5242880" - - --inbound-bytes-per-sec - - "1048576" - - --inbound-burst-bytes - - "33554432" - # No `ports:`. The server is reachable from the two containers beside it and - # from nothing else; every packet that reaches it came through the front. - read_only: true - cap_drop: - - ALL - security_opt: - - no-new-privileges:true - mem_limit: 320m - restart: unless-stopped - - selvage-web: - image: ${SELVAGE_WEB_IMAGE:?set SELVAGE_WEB_IMAGE in .env} - # No `ports:` here either. The page image already runs as uid 101 on 8080 - # with the base's own hardening (`web_client/compose.yaml`), so this service - # is the same shape with the two things added that the one-origin deployment - # needs: it is only reachable through the front, and it has a memory limit. - # - # An invite link is a page link — `/?room=…&token=…` — so a request line - # carries the room token, which `PROTOCOL.md` §12 makes "a deployment MUST - # NOT log request URLs" a MUST: the token is the room's whole permission. - # - # The page image has turned its own request log off — `web_client`'s - # `packaging/nginx.conf` sets `access_log off` and keeps its error log at - # `crit`, above every level at which nginx logs something request-scoped — - # and the channel is closed here as well rather than filtered: the `none` - # driver discards this container's output outright, so this is the - # deployment's own guarantee rather than the image's, and a later image that - # logs again still reaches no log this box keeps. This container's errors are - # discarded too, which is small: it is a static file server whose failures - # the front and the server beside it already show, and the front's own log is - # silent by design for the same reason. - logging: - driver: "none" - read_only: true - cap_drop: - - ALL - security_opt: - - no-new-privileges:true - mem_limit: 48m - restart: unless-stopped diff --git a/deploy/deploy.py b/deploy/deploy.py deleted file mode 100755 index dc8d57a..0000000 --- a/deploy/deploy.py +++ /dev/null @@ -1,326 +0,0 @@ -#!/usr/bin/env python3 -"""Point the public demo at published image tags, and bring it up to them. - -Installed by hand as `/usr/local/sbin/selvage-deploy`, root-owned and mode 0755, -and the only command the `deployci` user may run through sudo -(`deploy/deployci.sudoers`, whose line ends in `""` so that sudo permits -no argument at all rather than any). That confinement is why this takes **no -arguments**: an argument to a script that reaches `docker compose` is a root shell -with extra steps. The request arrives on stdin instead — one or both image -references — and every value it may carry is matched against a fixed pattern -before anything else happens. The argument refusal below is the second lock on -that door, not the first. - -What a request can and cannot do, because that is the whole security argument: - -* it names a tag of one of the two published `ghcr.io/selvage-protocol/` images - and nothing else — no path, no flag, no shell word, no other repository; -* it may omit an image, which leaves that line of `.env` exactly as it is; -* it rewrites those lines of `/srv/selvage/.env` and nothing else. The compose - file, `proxy/` and `tls/` are the owner's to edit by hand and are never written - here, so a request cannot add a port, drop a capability or mount a file. - -A run that fails leaves `.env` as it found it. The new file is staged as -`.env.deploy`, which `pull`, `up` and the convergence check read, and `.env` is -written only once the containers run what was asked for. All of it happens under -the lock `selvage-update.service` takes, so a timer tick cannot run compose in the -middle of a deploy, and the first tick after a failed one brings the box back to -what `.env` still names. - -The residual, plainly: a deploy request is a deployment. Whoever can send one -chooses which published tag runs, ends every live room by replacing the server, -and can move the deployment to an older release. The content behind a tag is the -publisher's; following tags rather than digests is the owner's choice. -""" - -import fcntl -import os -import re -import subprocess -import sys -import tempfile -import time -from pathlib import Path - -SRV = Path("/srv/selvage") -ENV_FILE = SRV / ".env" -ENV_PREV = SRV / ".env.prev" -ENV_STAGED = SRV / ".env.deploy" -# Shared with `selvage-update.service`, which names the same path. -LOCK = SRV / ".update.lock" -# A timer tick holds the lock for as long as its pull takes. -LOCK_WAIT_SECONDS = 600.0 - -# The two variables the compose file interpolates, and the image repository each -# may name, which is also the compose service it lands on. -PINS = { - "SELVAGED_IMAGE": "selvaged", - "SELVAGE_WEB_IMAGE": "selvage-web", -} -SERVICES = ("proxy", "selvaged", "selvage-web") - -# A request is a few hundred bytes at most; the bound is here so a caller cannot -# make a root process read for as long as it likes. -MAX_REQUEST_BYTES = 4096 - -# The OCI tag grammar: a version, `latest`, or a commit-stamped `-`. -_TAG = r"[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}" -IMAGE_PATTERN = { - key: re.compile(rf"^ghcr\.io/selvage-protocol/{name}:{_TAG}$") for key, name in PINS.items() -} - - -class Refused(Exception): - """The request is not one this box acts on, or the deploy did not converge.""" - - -def parse_request(data: bytes) -> dict: - """The request, or `Refused` naming what about it is not allowed. - - The grammar is deliberately narrow: `KEY=VALUE` lines, one of the `PINS` - keys each, no blank line, no control character, no duplicate, and each value - matched against the one fixed shape its key admits. Nothing here is a path, and - nothing here reaches a shell. - """ - if len(data) > MAX_REQUEST_BYTES: - raise Refused(f"request is longer than {MAX_REQUEST_BYTES} bytes") - try: - text = data.decode("utf-8") - except UnicodeDecodeError as error: - raise Refused(f"request is not UTF-8: {error}") from error - - lines = text.split("\n") - if lines and lines[-1] == "": - lines.pop() - - request = {} - for line in lines: - if not line: - raise Refused("request has a blank line") - if any(ord(character) < 0x20 for character in line): - raise Refused("request has a control character") - key, separator, value = line.partition("=") - if not separator: - raise Refused(f"request line is not KEY=VALUE: {line!r}") - if key not in IMAGE_PATTERN: - raise Refused(f"{key!r} is not a key this box acts on") - if key in request: - raise Refused(f"{key} appears twice") - if not IMAGE_PATTERN[key].match(value): - raise Refused(f"{key} is not a ghcr.io/selvage-protocol/{PINS[key]}: reference: {value!r}") - request[key] = value - - if not request: - raise Refused("no image named: send SELVAGED_IMAGE, SELVAGE_WEB_IMAGE or both") - return request - - -def rewrite_env(text: str, requested: dict) -> str: - """`text` with each requested key's line replaced, and every other line kept. - - A key the file does not have is appended. Comments, blank lines and anything - the owner added by hand come through byte for byte. - """ - lines = text.split("\n") - if lines and lines[-1] == "": - lines.pop() - seen = set() - for index, line in enumerate(lines): - key = line.strip().partition("=")[0].strip() - if key in requested: - lines[index] = f"{key}={requested[key]}" - seen.add(key) - lines.extend(f"{key}={value}" for key, value in requested.items() if key not in seen) - return "".join(f"{line}\n" for line in lines) - - -def read_env() -> str: - """The current `.env`, never through a link.""" - try: - descriptor = os.open(ENV_FILE, os.O_RDONLY | os.O_NOFOLLOW) - except FileNotFoundError: - return "" - with os.fdopen(descriptor, encoding="utf-8") as handle: - try: - return handle.read() - except UnicodeDecodeError as error: - raise Refused(f"{ENV_FILE} is not UTF-8, so it is not rewritten: {error}") from error - - -def atomic_write(path: Path, text: str) -> None: - """Replace `path` with `text`, mode 0600, owned by whoever owns the directory. - - The file is created fresh beside its target and renamed over it, so an - existing link at `path` is replaced rather than followed. The directory's - owner is `selvage`, whose compose and timer read these files. - """ - owner = os.stat(path.parent) - descriptor, temporary = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.") - try: - with os.fdopen(descriptor, "w", encoding="utf-8") as handle: - os.fchmod(handle.fileno(), 0o600) - os.fchown(handle.fileno(), owner.st_uid, owner.st_gid) - handle.write(text) - os.replace(temporary, path) - except BaseException: - Path(temporary).unlink(missing_ok=True) - raise - - -def record(request: dict) -> bool: - """Write the requested lines into `.env`, keeping the file it replaces as `.env.prev`. - - Called only once the containers have converged. `.env` is read again here - rather than reused from the start of the deploy, because hand commands do not - take the lock: an edit made to it while `pull` and `up` ran survives, and - `.env.prev` is the file actually replaced. A no-op leaves both files alone, so - `.env.prev` keeps naming the last real previous state. - """ - current = read_env() - text = rewrite_env(current, request) - if text == current: - return False - atomic_write(ENV_PREV, current) - atomic_write(ENV_FILE, text) - return True - - -def take_lock() -> int: - """Hold the lock the update timer takes, waiting out a tick in progress.""" - descriptor = os.open(LOCK, os.O_RDONLY | os.O_CREAT | os.O_NOFOLLOW, 0o644) - deadline = time.monotonic() + LOCK_WAIT_SECONDS - while True: - try: - fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB) - return descriptor - except BlockingIOError: - if time.monotonic() >= deadline: - os.close(descriptor) - raise Refused( - f"{LOCK} is still held after {LOCK_WAIT_SECONDS:.0f}s; " - f"`systemctl status selvage-update.service` shows what holds it" - ) from None - time.sleep(1) - - -def compose_argv(env_file: Path, *arguments: str) -> list[str]: - """The project's command line, run in `SRV` as the timer and every hand command are. - - No `-f`: Compose finds `compose.yaml` in the working directory, and a - `compose.override.yaml` beside it too, so a deploy runs the same shape the - next tick does. `--env-file` replaces `.env`, which is how the staged file is - read instead. - """ - return ["docker", "compose", "--env-file", str(env_file), *arguments] - - -def compose(env_file: Path, *arguments: str) -> subprocess.CompletedProcess: - return subprocess.run(compose_argv(env_file, *arguments), cwd=SRV, text=True, check=False) - - -def run(argv: list[str]) -> subprocess.CompletedProcess: - return subprocess.run(argv, cwd=SRV, text=True, capture_output=True, check=False) - - -def image_id(reference: str) -> str: - return run(["docker", "image", "inspect", "--format", "{{.Id}}", reference]).stdout.strip() - - -def repo_digest(reference: str) -> str: - """What the tag named when this box pulled it: the record of what was deployed.""" - listed = run( - ["docker", "image", "inspect", "--format", '{{join .RepoDigests " "}}', reference] - ) - return listed.stdout.strip() or "-" - - -def service_state(service: str, env_file: Path) -> tuple[str, str]: - """The image and status of the container this service runs, or `("", "")`.""" - listed = run(compose_argv(env_file, "ps", "-q", "--all", service)) - container = listed.stdout.strip().split("\n")[0].strip() - if not container: - return "", "" - inspected = run(["docker", "inspect", "--format", "{{.Image}}|{{.State.Status}}", container]) - if inspected.returncode != 0: - return "", "" - image, _, status = inspected.stdout.strip().partition("|") - return image, status - - -def assert_converged(request: dict, env_file: Path) -> None: - """Every service runs, and each requested one runs the image its tag pulled.""" - for service in SERVICES: - _image, status = service_state(service, env_file) - if status != "running": - raise Refused(f"{service} is {status or 'missing'} after `up -d`, not running") - for key, reference in request.items(): - pulled = image_id(reference) - if not pulled: - raise Refused(f"{reference} is not in the local image store after `pull`") - image, _status = service_state(PINS[key], env_file) - if image != pulled: - raise Refused(f"{PINS[key]} runs {image} but {reference} is {pulled}") - - -def deploy(request: dict) -> None: - named = [PINS[key] for key in PINS if key in request] - - print("=== request ===") - for key in PINS: - if key in request: - print(f"{key}={request[key]}") - - atomic_write(ENV_STAGED, rewrite_env(read_env(), request)) - - print(f"=== pull {' '.join(named)} ===") - if compose(ENV_STAGED, "pull", *named).returncode != 0: - raise Refused(f"`docker compose pull {' '.join(named)}` failed; {ENV_FILE} was not written") - - print("=== up -d ===") - if compose(ENV_STAGED, "up", "-d").returncode != 0: - raise Refused( - f"`docker compose up -d` failed; {ENV_FILE} was not written, and the next " - f"update tick goes back to what it names" - ) - - assert_converged(request, ENV_STAGED) - - if record(request): - print(f"wrote {ENV_FILE}; the file it replaced is {ENV_PREV}") - else: - print(f"{ENV_FILE} already named these") - ENV_STAGED.unlink(missing_ok=True) - - print("=== deployed ===") - for key in PINS: - if key in request: - print(f"{request[key]} = {repo_digest(request[key])}") - compose(ENV_FILE, "ps") - - -def main(argv: list[str]) -> int: - if len(argv) != 1: - print("selvage-deploy takes no arguments; the request arrives on stdin", file=sys.stderr) - return 2 - if os.geteuid() != 0: - print("selvage-deploy must run as root", file=sys.stderr) - return 2 - - try: - request = parse_request(sys.stdin.buffer.read(MAX_REQUEST_BYTES + 1)) - lock = take_lock() - try: - deploy(request) - finally: - os.close(lock) - return 0 - except Refused as refusal: - print(f"refused: {refusal}", file=sys.stderr) - return 1 - except OSError as error: - print(f"refused: {error}", file=sys.stderr) - return 1 - - -if __name__ == "__main__": - sys.exit(main(sys.argv)) diff --git a/deploy/deployci.sudoers b/deploy/deployci.sudoers deleted file mode 100644 index 23bd174..0000000 --- a/deploy/deployci.sudoers +++ /dev/null @@ -1,26 +0,0 @@ -# The one root command the CI user on the public demo may run, and nothing else. -# -# Tailscale SSH cannot restrict a command — the tailnet policy's `ssh` rules -# carry `action`, `src`, `dst`, `users`, `checkPeriod`, `acceptEnv` and -# `srcPosture`, and there is no `cmd` field — so an SSH grant is a shell grant. -# `selvage` on that box has blanket passwordless sudo, so granting CI `selvage` -# would mean "GitHub can be root on production". Hence a user of its own, whose -# only privilege is this line. -# -# There is deliberately **no argument wildcard**, and the trailing `""` is what -# says so: `/usr/local/sbin/selvage-deploy ""` permits that one program and no -# argument at all, whereas the same line without the `""` would permit *any* -# argument, because an empty argument list in sudoers means "any" rather than -# "none". That distinction is the whole bound: without the `""` the argument -# list is the script's own problem, and a wildcard there is a root shell. -# -# It is also why the deploy request arrives on stdin, and why the script refuses -# its own arguments as well: the marker is what sudo enforces, and the script -# check is the second lock on the same door. -# -# The script is root-owned mode 0755 under `/usr/local/sbin` (root:root 0755), so -# the user it is granted to cannot change what it does. -# -# Installs to `/etc/sudoers.d/selvage-deploy`, root:root, mode 0440, and is read -# with `visudo -c -f` before it is put there. -deployci ALL=(root) NOPASSWD: /usr/local/sbin/selvage-deploy "" diff --git a/deploy/install_shape.py b/deploy/install_shape.py deleted file mode 100755 index 6810141..0000000 --- a/deploy/install_shape.py +++ /dev/null @@ -1,421 +0,0 @@ -#!/usr/bin/env python3 -"""Install the box's shape from a tar stream, then bring the front up to it. - -Installed by hand as `/usr/local/sbin/selvage-install-shape`, root-owned and mode -0755, and one of the two commands the `deployci` user may run through sudo -(`deploy/installci.sudoers`, whose line ends in `""` so that sudo permits no -argument at all rather than any). That confinement is why this takes **no -arguments**: an argument to a script that reaches `docker compose` is a root shell -with extra steps. The shape arrives as a tar stream on stdin instead, and the -producer the runbook names is a bare-name archive of the two tracked paths: - - git archive --format=tar :deploy compose.yaml proxy | ssh \ - '/usr/bin/sudo /usr/local/sbin/selvage-install-shape' - -What the set is, and why it is those two: `compose.yaml` is the shape Compose -reads, and `proxy/` is the front's build context, whose files its image bakes at -`/etc/nginx/nginx.conf`, `/etc/nginx/conf.d/` and `/usr/share/selvage/www/` rather -than mounting. **`deploy/.env.example` is deliberately not in the set**: the file -it seeds, `/srv/selvage/.env`, is live — the deploy path rewrites its image lines -and the owner edits the rest — so this stays out of that pair entirely instead of -holding a lever on the file beside it. `.env.example` is copied once by hand at a -first install, the systemd units are installed by hand, and `tls/` is the box's -own; the production demo's runbook owns all three. - -What a stream can and cannot do, because that is the whole of the argument: - -* it may name entries of that set, by one fixed grammar: relative, plain names, - no absolute path, no `.` or `..` component, and no link, hardlink, device or - fifo member. Anything else is refused, and a refusal writes nothing; -* the whole stream is read and validated before the first write, so a stream - refused at its last entry installs none of the ones before it; -* every step below `/srv/selvage` is opened inside the descriptor the step before - it found, with `O_NOFOLLOW` on each, so nothing is validated as a path and then - used as one, and a link planted in the way is refused rather than followed; -* it overwrites the shape's files and creates the directories it needs, and it - **never deletes**: a file a release removes from `proxy/` stays in the build - context until someone removes it by hand. That is the one residual of the - install — deleting under a root process on the strength of a stream is a bigger - lever than installing one needs. - -**It does nothing it does not have to**, because a release now installs the shape -on every deploy and the front serves live sessions. The shape on disk is compared -with the stream *before* the write, by content and not by mtime — a rewrite of the -bytes that were already there changes nothing, and rebuilding the front for it -costs the WebSockets through it a second or two — and three cases follow: - -* every entry already holds what the stream carries: nothing is written, no - `docker compose` runs at all, and the run says so and exits 0; -* only `compose.yaml` differs: the services are brought up to it with - `docker compose up -d`, which recreates the service that changed and nothing - else; -* anything under `proxy/` differs, missing or added files included: the front's - configuration is baked into its image, so that one is built with - `docker compose up -d --build proxy`. - -The comparison is taken before the write for the obvious reason — after it there -is nothing left to compare with — and the run prints which of the three cases it -took. - -And the residual that is a race rather than a decision: between the preflight and -the write, something with access to `/srv/selvage` (`selvage` owns it) could -replace a directory with a link. The write then refuses that entry, because every -step is opened with `O_NOFOLLOW` inside its parent — so a swap costs a failed -install, not an escape. - -The install holds the lock the update timer and `selvage-deploy` hold, so a tick -cannot run `up -d` against a half-written build context. -""" - -import fcntl -import io -import os -import re -import stat -import subprocess -import sys -import tarfile -import time -from pathlib import Path - -SRV = Path("/srv/selvage") -# Shared with `selvage-update.service` and `selvage-deploy`. -LOCK = SRV / ".update.lock" -LOCK_WAIT_SECONDS = 600.0 - -FRONT = "proxy" -UP_ARGV = ["docker", "compose", "up", "-d"] -REBUILD_ARGV = [*UP_ARGV, "--build", FRONT] -FILE_MODE = 0o644 -DIRECTORY_MODE = 0o755 - -# The bound is here so a caller cannot make a root process read for as long as it -# likes, the same reasoning as `deploy.py`'s -# request bound, with room for whatever the page brings with it. -MAX_STREAM_BYTES = 8 * 1024 * 1024 - -# One component: a plain name, so `.` and `..` are not names this grammar has and -# a stream has no room for a parser difference. -_COMPONENT = r"[A-Za-z0-9][A-Za-z0-9._-]*" -# `\Z` rather than `$`: `$` also matches before a trailing newline, and a name -# that ends in one is not a name this box takes. -_NAME = re.compile(rf"^{_COMPONENT}(?:/{_COMPONENT})*\Z") - -COMPOSE = "compose.yaml" - - -class Refused(Exception): - """The stream is not one this box acts on, or the install did not converge.""" - - -class Entry: - """One member of the stream that is in the set: its name, and its bytes.""" - - def __init__(self, name: str, content: bytes | None): - self.name = name - self.content = content - - @property - def is_directory(self) -> bool: - return self.content is None - - -def _in_shape(name: str, directory: bool) -> bool: - """`compose.yaml` the file, and `proxy` or anything below it.""" - if name == FRONT: - return directory - if name == COMPOSE: - return not directory - return name.startswith(f"{FRONT}/") - - -def _classify(member: tarfile.TarInfo) -> str: - """The member's name, or `Refused` naming what about it is not allowed.""" - name = member.name.rstrip("/") if member.isdir() else member.name - if member.issym(): - raise Refused(f"{name} is a symbolic link") - if member.islnk(): - raise Refused(f"{name} is a hard link") - if member.ischr() or member.isblk(): - raise Refused(f"{name} is a device node") - if member.isfifo(): - raise Refused(f"{name} is a fifo") - if not member.isfile() and not member.isdir(): - raise Refused(f"{name} is neither a regular file nor a directory") - if not _NAME.match(name): - raise Refused(f"{name} is not a relative path of plain names") - if not _in_shape(name, member.isdir()): - raise Refused(f"{name} is not part of the box's shape") - return name - - -def read_stream(data: bytes) -> list[Entry]: - """Every entry of `data`, validated, or `Refused` naming the first one that is not. - - Nothing here writes, and the caller installs only once this has returned: a - stream whose last entry is refused leaves the box as it found it. - """ - if not data: - raise Refused("the stream is empty; send the shape as a tar archive") - if len(data) > MAX_STREAM_BYTES: - raise Refused(f"the stream is longer than {MAX_STREAM_BYTES} bytes") - try: - archive = tarfile.open(fileobj=io.BytesIO(data), mode="r:") - except tarfile.TarError as error: - raise Refused(f"the stream is not a tar archive: {error}") from error - - entries: list[Entry] = [] - seen: set[str] = set() - with archive: - for member in archive: - name = _classify(member) - if name in seen and member.isdir(): - continue - if name in seen: - raise Refused(f"{name} appears twice") - seen.add(name) - if member.isdir(): - entries.append(Entry(name, None)) - continue - content = archive.extractfile(member) - if content is None: - raise Refused(f"{name} carries no content") - entries.append(Entry(name, content.read())) - - if not any(not entry.is_directory for entry in entries): - raise Refused("the stream carries no file of the box's shape") - return entries - - -def open_below(relative: str, create: bool = False) -> int: - """The descriptor of `relative` below `SRV`, or an `OSError` saying why not. - - Each component is opened inside the descriptor the component before it found - and with `O_NOFOLLOW`, so a link at any step is refused rather than followed - and no step is a path that was checked and then used. `create` makes a missing - component, and gives it to the owner of its parent, so the box's own user can - still edit what root installed. - """ - flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW - descriptor = os.open(SRV, flags) - try: - for part in relative.split("/") if relative else []: - try: - step = os.open(part, flags, dir_fd=descriptor) - except FileNotFoundError: - if not create: - raise - os.mkdir(part, DIRECTORY_MODE, dir_fd=descriptor) - owner = os.fstat(descriptor) - step = os.open(part, flags, dir_fd=descriptor) - os.fchmod(step, DIRECTORY_MODE) - os.fchown(step, owner.st_uid, owner.st_gid) - os.close(descriptor) - descriptor = step - return descriptor - except BaseException: - os.close(descriptor) - raise - - -def preflight(entries: list[Entry]) -> None: - """Every entry resolves inside `SRV` as far as it exists, before any write. - - A component that is not there ends the walk: below it the install creates its - own directories, and a link cannot be one of those. A component that is there - and is not a directory — a link out of the box, a file where a directory - belongs, a shape file that has become a link — is refused here, with the box - untouched. - """ - for entry in entries: - parts = entry.name.split("/") - # A directory member's own name is a step; a file's last part is not, and - # is looked at as a leaf instead. - steps = parts if entry.is_directory else parts[:-1] - for stop in range(len(steps) + 1): - try: - os.close(open_below("/".join(steps[:stop]))) - except FileNotFoundError: - # From here down the install makes its own directories, and a link - # cannot be one of those. - break - except OSError as error: - where = f"{SRV}/{'/'.join(steps[:stop])}" - raise Refused(f"{entry.name} does not resolve: {where} is not a directory ({error.strerror})") from error - if entry.is_directory: - continue - try: - parent = open_below("/".join(parts[:-1])) - except OSError: - # The steps above already refuse whatever the parent walk can find - # wrong; a change between the two walks costs the install, which then - # fails on the write rather than following anything. - continue - try: - leaf = os.stat(parts[-1], dir_fd=parent, follow_symlinks=False) - except FileNotFoundError: - continue - finally: - os.close(parent) - if not stat.S_ISREG(leaf.st_mode): - raise Refused(f"{entry.name} is there and is not a regular file") - - -def _directory_is_there(name: str) -> bool: - """Whether `SRV/name` resolves, through directories only, to a directory.""" - try: - os.close(open_below(name)) - return True - except OSError: - return False - - -def _carries_the_bytes(name: str, content: bytes) -> bool: - """Whether `SRV/name` is a regular file holding exactly `content`.""" - parent_name, _, leaf = name.rpartition("/") - try: - descriptor = open_below(parent_name) - except OSError: - return False - try: - handle = os.open(leaf, os.O_RDONLY | os.O_NOFOLLOW, dir_fd=descriptor) - except OSError: - return False - finally: - os.close(descriptor) - try: - with os.fdopen(handle, "rb") as stream: - return stream.read() == content - except OSError: - return False - - -def differences(entries: list[Entry]) -> list[str]: - """The entries whose content is not what `SRV` already holds, in name order. - - Read before the write, and by content rather than by mtime: an install that - rewrites the bytes that were already there has changed nothing, and a - `--build` for it rebuilds the front for nothing. A missing file, a missing - directory and a file that is there with other bytes are all differences. - """ - changed = [] - for entry in sorted(entries, key=lambda item: item.name): - if entry.is_directory: - if not _directory_is_there(entry.name): - changed.append(entry.name) - elif not _carries_the_bytes(entry.name, entry.content or b""): - changed.append(entry.name) - return changed - - -def install(entries: list[Entry]) -> list[str]: - """Write the shape under `SRV`, in name order, and return what was written.""" - written = [] - for entry in sorted(entries, key=lambda item: item.name): - if entry.is_directory: - os.close(open_below(entry.name, create=True)) - continue - parent_name, _, leaf = entry.name.rpartition("/") - descriptor = open_below(parent_name, create=True) - try: - owner = os.fstat(descriptor) - handle = os.open( - leaf, - os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, - FILE_MODE, - dir_fd=descriptor, - ) - with os.fdopen(handle, "wb") as stream: - stream.write(entry.content) - os.fchmod(stream.fileno(), FILE_MODE) - os.fchown(stream.fileno(), owner.st_uid, owner.st_gid) - finally: - os.close(descriptor) - written.append(entry.name) - return written - - -def take_lock() -> int: - """Hold the lock the update timer takes, waiting out a tick in progress.""" - descriptor = os.open(LOCK, os.O_RDONLY | os.O_CREAT | os.O_NOFOLLOW, 0o644) - deadline = time.monotonic() + LOCK_WAIT_SECONDS - while True: - try: - fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB) - return descriptor - except BlockingIOError: - if time.monotonic() >= deadline: - os.close(descriptor) - raise Refused( - f"{LOCK} is still held after {LOCK_WAIT_SECONDS:.0f}s; " - f"`systemctl status selvage-update.service` shows what holds it" - ) from None - time.sleep(1) - - -def compose(argv: list[str]) -> subprocess.CompletedProcess: - """One of the two commands that make an installed shape live: as root, in `SRV`. - - No `-f`: Compose finds `compose.yaml` in the working directory, and a - `compose.override.yaml` beside it too, exactly as the timer and every hand - command do. The front's files are baked into its image, so an installed - `proxy/` is not what runs until `--build` rebuilds it; a `compose.yaml` alone - needs no build and takes the shorter command. Which one is `differences`' - answer, not this function's. - """ - return subprocess.run(argv, cwd=SRV, check=False) - - -def main(argv: list[str]) -> int: - if len(argv) != 1: - print("selvage-install-shape takes no arguments; the shape arrives on stdin", file=sys.stderr) - return 2 - if os.geteuid() != 0: - print("selvage-install-shape must run as root", file=sys.stderr) - return 2 - - try: - entries = read_stream(sys.stdin.buffer.read(MAX_STREAM_BYTES + 1)) - preflight(entries) - lock = take_lock() - try: - changed = differences(entries) - if not changed: - print("=== already current ===") - print( - f"nothing differs: every entry of the shape under {SRV} already holds " - f"what this stream carries, so nothing was written and no container was touched" - ) - return 0 - # A `compose.yaml` alone is read by Compose at `up -d`; the front's files - # are baked into its image, so they need the build. - rebuilding = any(name == FRONT or name.startswith(f"{FRONT}/") for name in changed) - argv = REBUILD_ARGV if rebuilding else UP_ARGV - written = install(entries) - print("=== installed ===") - for name in written: - print(f"{SRV}/{name}") - print(f"left alone: {SRV}/.env (live; selvage-deploy and the owner write it)") - print(f"left alone: {SRV}/.env.example, tls/ and the systemd units (never part of the shape)") - print(f"changed ({len(changed)}): {' '.join(changed)}") - print(f"=== docker compose {' '.join(argv[2:])} ===") - if compose(argv).returncode != 0: - residual = ( - "the front was not rebuilt, so it goes on serving the previous configuration" - if rebuilding - else "the services were not brought up, so they go on running what they had" - ) - raise Refused(f"`docker compose {' '.join(argv[2:])}` failed; the shape is on disk and {residual}") - finally: - os.close(lock) - return 0 - except Refused as refusal: - print(f"refused: {refusal}", file=sys.stderr) - return 1 - except OSError as error: - print(f"refused: {error}", file=sys.stderr) - return 1 - - -if __name__ == "__main__": - sys.exit(main(sys.argv)) diff --git a/deploy/installci.sudoers b/deploy/installci.sudoers deleted file mode 100644 index 5bdef64..0000000 --- a/deploy/installci.sudoers +++ /dev/null @@ -1,26 +0,0 @@ -# The other root command the CI user on the public demo may run, and nothing else. -# -# `selvage-install-shape` installs the box's shape — `compose.yaml` and `proxy/` — -# from a tar stream on stdin, then rebuilds the front from it. It is what makes a -# release that changed `deploy/` installable with nobody at a keyboard; the -# `deployci` account's other line is `selvage-deploy`, which moves which image -# tags run and never writes a file of the shape. `deployci.sudoers` has the rest -# of why this user exists at all (Tailscale SSH carries no command restriction, so -# an SSH grant is a shell grant, and the box's own user has blanket sudo). -# -# There is deliberately **no argument wildcard**, and the trailing `""` is what -# says so: `/usr/local/sbin/selvage-install-shape ""` permits that one program and -# no argument at all, whereas the same line without the `""` would permit *any* -# argument, because an empty argument list in sudoers means "any" rather than -# "none". That distinction is the whole bound: a command named in sudoers without -# an argument list permits any argument. It is also why the shape arrives on stdin, -# and why the script refuses its own arguments as well: the marker is what sudo -# enforces, and the script check is the second lock on the same door. -# -# The script is root-owned mode 0755 under `/usr/local/sbin` (root:root 0755), so -# the user it is granted to cannot change what it does. -# -# Installs to `/etc/sudoers.d/selvage-install-shape`, root:root, mode 0440 — a -# file per command, so each line's bound is one file and neither can be lost with -# the other — and is read with `visudo -c -f` before it is put there. -deployci ALL=(root) NOPASSWD: /usr/local/sbin/selvage-install-shape "" diff --git a/deploy/proxy/Dockerfile b/deploy/proxy/Dockerfile deleted file mode 100644 index 5221ed3..0000000 --- a/deploy/proxy/Dockerfile +++ /dev/null @@ -1,57 +0,0 @@ -# syntax=docker/dockerfile:1 -# -# The public demo's TLS terminator: nginx on the same base image the page image -# runs, configured by the files beside this one and by nothing else. -# -# The image exists so that the proxy's only mount is its certificate. nginx's -# configuration could be bind-mounted instead, but a mount is a view of the host -# the container did not have to be given, and this deployment's stance is that -# each container gets the fewest of those it can work with — `deploy/compose.yaml` -# names the one this service has. -# -# The base is pinned by the index digest the tag resolved to, not by the tag: -# a tag is a name someone else can repoint, and this container terminates TLS -# for the public origin. The digest is the multi-architecture index, so -# `TARGETARCH` is still resolved at pull time. To move it, resolve the tag again -# (the flow in `reference_server/scripts/assert-multiarch-layers.py`) and change -# this line in a pull request. -# -# The runtime is `nginx-unprivileged`: uid 101, listening on 8080, so nothing -# here needs a capability or a privileged port, and `cap_drop: [ALL]` costs the -# container nothing. Its writable paths — the pid file and the five temp -# directories — are moved onto `/dev/shm` by `nginx.conf`, the tmpfs the -# container runtime mounts itself, which is what lets it run under `read_only` -# with no writable mount at all. -FROM nginxinc/nginx-unprivileged:1.30-alpine-slim@sha256:6917744e63b3c4bde796d9d4f55e572dd77d1de860228616cad7301f2e5d1930 - -LABEL org.opencontainers.image.title="selvage-prod-proxy" \ - org.opencontainers.image.description="TLS terminator and router for the public Selvage demo" \ - org.opencontainers.image.source="https://github.com/selvage-protocol/reference_server" \ - org.opencontainers.image.licenses="MIT OR Apache-2.0" - -# The base image's own `conf.d/default.conf` answers every request with the -# nginx welcome page on 8080. Replaced wholesale rather than overlaid: a server -# block that is still listening when this one fails to start is a front that -# looks healthy and is not. -RUN rm -f /etc/nginx/conf.d/*.conf - -COPY --chown=101:101 nginx.conf /etc/nginx/nginx.conf -COPY --chown=101:101 conf.d/ /etc/nginx/conf.d/ - -# The instance's own not-found page, served from disk by the `/404.html` -# location in `conf.d/default.conf`. It is the image's only content rather than -# configuration: a page is a file, not a directive, and a file is what a -# reviewer can read and edit. -COPY --chown=101:101 www/ /usr/share/selvage/www/ - -# Straight to nginx, past the base image's `/docker-entrypoint.sh`. Those scripts -# exist to rewrite the configuration at startup — enabling the IPv6 listen, -# substituting environment variables into templates, sizing the worker count — -# and this image's configuration is a reviewed file, not a template: what runs -# has to be what is in this repository, and a script that edits it at boot is a -# second source of truth that only appears on the machine. Nothing here needs -# what they add; `30-tune-worker-processes.sh` in particular would override the -# `worker_processes 1` that `nginx.conf` reasons about for this box. -ENTRYPOINT ["/usr/sbin/nginx", "-g", "daemon off;"] - -EXPOSE 8080 diff --git a/deploy/proxy/conf.d/cloudflare-ips.conf b/deploy/proxy/conf.d/cloudflare-ips.conf deleted file mode 100644 index 8a378bb..0000000 --- a/deploy/proxy/conf.d/cloudflare-ips.conf +++ /dev/null @@ -1,39 +0,0 @@ -# Cloudflare's published edge ranges, and the whole of the front's trust in the -# `CF-Connecting-IP` header: `real_ip` rewrites `$remote_addr` from that header -# only when the peer is one of these addresses, so a request that did not come -# through Cloudflare cannot name its own source and cannot escape the per-source -# caps in `nginx.conf`. -# -# The Azure network security group on this box admits 443 from the same list and -# from nowhere else, so these two are the same fact written twice — once where -# the packet is refused and once where the source is read. Refresh both together -# from `https://api.cloudflare.com/client/v4/ips`; the ranges change rarely and -# Cloudflare announces a change before it takes effect. -# -# `set_real_ip_from` is an http-level directive, which is why this file is a -# sibling of `default.conf` rather than part of it: the server block beside it -# is included in the same alphabetical pass and only needs the zones. - -set_real_ip_from 173.245.48.0/20; -set_real_ip_from 103.21.244.0/22; -set_real_ip_from 103.22.200.0/22; -set_real_ip_from 103.31.4.0/22; -set_real_ip_from 141.101.64.0/18; -set_real_ip_from 108.162.192.0/18; -set_real_ip_from 190.93.240.0/20; -set_real_ip_from 188.114.96.0/20; -set_real_ip_from 197.234.240.0/22; -set_real_ip_from 198.41.128.0/17; -set_real_ip_from 162.158.0.0/15; -set_real_ip_from 104.16.0.0/13; -set_real_ip_from 104.24.0.0/14; -set_real_ip_from 172.64.0.0/13; -set_real_ip_from 131.0.72.0/22; - -set_real_ip_from 2400:cb00::/32; -set_real_ip_from 2606:4700::/32; -set_real_ip_from 2803:f800::/32; -set_real_ip_from 2405:b500::/32; -set_real_ip_from 2405:8100::/32; -set_real_ip_from 2a06:98c0::/29; -set_real_ip_from 2c0f:f248::/32; diff --git a/deploy/proxy/conf.d/default.conf b/deploy/proxy/conf.d/default.conf deleted file mode 100644 index 5963e69..0000000 --- a/deploy/proxy/conf.d/default.conf +++ /dev/null @@ -1,155 +0,0 @@ -# The front's one server block: TLS, then two destinations. -# -# Cloudflare terminates the visitor's TLS and speaks TLS again to this listener -# under Full (strict), so the certificate is the Cloudflare Origin CA pair -# covering `selvage-demo.dontblameme.dev` — the only thing this container -# reads from outside its own image, and the mount named in `../compose.yaml`. -# Port 80 is not listened on: Cloudflare's redirect is served at Cloudflare's -# edge, and the origin's network security group denies 80 outright. -# -# The split is the owner's: `/session` and `/meta` are the -# server's two endpoints and belong to `selvaged`; everything else, the page -# included, is `selvage-web`'s. The page and the socket then share an origin, so -# the page's advisory `/meta` read is same-origin and a guest link needs no CORS -# or `?server=`. - -server { - listen 8080 ssl; - # One name, the demo's own: `selvage.dontblameme.dev` is the project's - # landing page, so a request arriving here with that Host is not the demo. - server_name selvage-demo.dontblameme.dev; - - # This is the only block on the port, so nginx makes it the default and - # would answer *any* name that resolves to this origin — the landing page's - # name included, and every stray name someone points here. A request's Host - # is the visitor's to say, not this front's to guess at, so a request for a - # name this block is not the server for is refused rather than proxied: - # `444` closes the connection and sends no response at all. - # - # `$server_name` is the `server_name` above, so the name stays in one place; - # a written-out copy would be a second home for the string a rename moves. - # `return` is the one thing an `if` at server level is for, and the guard - # runs before the limit zones are counted, so a refused name spends nothing. - # `check-front.sh` and `test_front_limits.py` measure both directions. - if ($host != $server_name) { - return 444; - } - - ssl_certificate /etc/selvage/tls/origin.pem; - ssl_certificate_key /etc/selvage/tls/origin.key; - - # Origin CA certificates are not in any browser's trust store and never need - # to be: only Cloudflare talks to this listener. TLS 1.0 and 1.1 are off - # because the peer is Cloudflare and Cloudflare speaks 1.2 and 1.3. - ssl_protocols TLSv1.2 TLSv1.3; - ssl_prefer_server_ciphers off; - ssl_session_cache shared:SSL:2m; - ssl_session_timeout 1h; - - # No `Strict-Transport-Security` here, and that is the decision rather than - # an omission: the field a visitor receives is Cloudflare's, set for the - # whole zone, and a second one from this server would be a duplicate field. - # `test_front_limits.py` fails if one is added. - server_tokens off; - - # The front's own log decision lives in `../nginx.conf`; it is repeated in - # the server block for the same reason it exists at all — a location that - # adds an `access_log` would be a location that disagrees. - access_log off; - - # Every 404 this front answers itself, and the page container's (see `location /`), - # is the instance's own page. `/meta` and `/session` do not intercept, so the - # server's own JSON 404 reaches its client unchanged. - error_page 404 /404.html; - - # Per source, keyed on the client address `real_ip` recovered rather than on - # the Cloudflare edge every request arrives from. The default is the page's: - # generous, because a page load is a burst of small reads and an asset - # refused here is a page that does not render. The two endpoints that cost - # the server something get their own, tighter zones below. - limit_conn perip 32; - - # `/session` is the WebSocket endpoint, and the whole of what a source may - # hold there is the front's contribution to `PROTOCOL.md` §12's "connection - # cap, an idle deadline and a rate limit". The server bounds the total it - # will seat (`--max-connections`) but cannot see who is asking; this can. - # - # The upgrade is passed through as it arrives: `proxy_http_version 1.1` and - # the two upgrade headers are what turn nginx into a byte pump, and without - # them the 101 never reaches the client and the session dies at the - # handshake. - location = /session { - limit_conn persession 8; - limit_req zone=handshake burst=10 nodelay; - - proxy_pass http://selvaged:8080; - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection $connection_upgrade; - proxy_set_header Host $host; - - # A server that is not there should say so in seconds. Docker removes a - # stopped container's address from the network, so a connect to it is - # dropped rather than refused, and nginx's default 60-second connect - # timeout would hold the visitor's socket open saying nothing. - proxy_connect_timeout 5s; - - # Above the server's ping, with room. `selvaged` sends a ping every 30 s - # and a live socket is therefore never quiet for a minute, so this only - # ever fires on a connection that is genuinely gone. Cloudflare's own - # 100-second idle close is above the ping too; nothing here lengthens - # either. - proxy_read_timeout 300s; - proxy_send_timeout 300s; - } - - # `/meta` is one small JSON read. It is a plain request, so it needs no - # upgrade, and a source has little reason to want more than a few of them - # open at once. - # - # Its own request zone, not `/session`'s. The page reads `/meta` on every - # load and opens `/session` on the click that follows, so one zone for the - # two means a visitor refreshing the page spends the allowance the - # handshake needs and is refused `429` at the join — measured on the live - # instance. - location = /meta { - limit_conn permeta 4; - limit_req zone=metaread burst=10 nodelay; - - proxy_pass http://selvaged:8080; - proxy_http_version 1.1; - proxy_set_header Host $host; - proxy_connect_timeout 5s; - proxy_read_timeout 30s; - } - - # A path nothing here has, answered with this instance's own not-found page - # rather than the page container's. `internal` keeps it off the address bar, - # where `/404.html` is a 404 like any other missing path. - # - # `default_type` and `charset` are set because `nginx.conf` replaces the base - # image's wholesale and includes no `mime.types`, so a file served from disk - # would otherwise arrive as `text/plain` and render as source. - location = /404.html { - internal; - root /usr/share/selvage/www; - default_type text/html; - charset utf-8; - } - - # The page, and everything that is not one of the paths above. - # The page container answers its own media types; this front replaces its - # 404 and changes nothing else about the response. - location / { - proxy_pass http://selvage-web:8080; - proxy_http_version 1.1; - proxy_set_header Host $host; - proxy_connect_timeout 5s; - proxy_read_timeout 60s; - - # The page container's 404 is replaced by the server-level `error_page`, - # so a missing path answers this instance's own not-found page rather - # than the container's. `check-front.sh` reads the served bytes back. - proxy_intercept_errors on; - } -} diff --git a/deploy/proxy/nginx.conf b/deploy/proxy/nginx.conf deleted file mode 100644 index 77d6e12..0000000 --- a/deploy/proxy/nginx.conf +++ /dev/null @@ -1,106 +0,0 @@ -# The front's nginx, replacing the base image's `/etc/nginx/nginx.conf` -# wholesale. Everything this file decides is http-level or process-level; where -# a request goes and what it is allowed is `conf.d/default.conf`. -# -# It runs as uid 101 with every capability dropped and a read-only root -# filesystem, so the pid file and the five temp paths are the only writes and -# all six are declared onto `/dev/shm`, the tmpfs the container runtime mounts -# itself. There is no `user` directive: the master is already the unprivileged -# user, and one would ask it to setuid without the capability to do it. - -# One worker, not `auto`. The box this runs on has two vCPUs shared with the -# server and the page, and the front's work per connection is a TLS handshake -# and a byte pump; a second worker costs memory on a host with 892 MiB and no -# swap and buys nothing at demo traffic. -worker_processes 1; -pid /dev/shm/nginx.pid; - -# No request URL reaches either log. The access log is off (below), and this -# one is at `crit`. That matters because nginx appends the request line to every -# error it logs while a request is in flight — a throttled handshake, an -# upstream that is restarting — and the request line of `/session` and of the -# page both carry the room token in the query string, which `PROTOCOL.md` §12 -# makes a MUST: "a deployment MUST NOT log request URLs". -# -# `crit` is above every level at which nginx logs something request-scoped. The -# two this deployment can actually produce are both `error`: `limit_req` and -# `limit_conn` refusals, and a failed connect to an upstream that is being -# recreated. What is kept is every process-level fault — a worker that died, a -# resource exhausted, a port that could not be bound — and none of those carries -# a request. `error_log` takes a file or `stderr` and no filter, so the level is -# the only control there is; the residual is a `crit`-level message emitted -# while a request is in flight. -error_log /dev/stderr crit; - -events { - # Per worker, and counting both the client and the upstream half of each - # proxied request. 256 client connections is a ceiling this box would not - # enjoy reaching; `selvaged` refuses past its own `--max-connections` well - # before this, and `conf.d/default.conf` caps what one source may hold. - worker_connections 512; -} - -http { - # The log that would have recorded every URL, including the query string - # that carries the token. Disabled rather than filtered: there is nothing in - # a request line this deployment is allowed to keep. - access_log off; - - # nginx creates each of its five temp directories at startup and treats a - # failure as fatal, so none of them is left to the base image's compiled - # default: every one is declared onto the runtime's own tmpfs, which is the - # only writable path this container has. - client_body_temp_path /dev/shm/client_temp; - proxy_temp_path /dev/shm/proxy_temp; - fastcgi_temp_path /dev/shm/fastcgi_temp; - uwsgi_temp_path /dev/shm/uwsgi_temp; - scgi_temp_path /dev/shm/scgi_temp; - - # Counting and pricing are per source, and behind Cloudflare the source is - # not the peer on the wire: every connection arrives from a Cloudflare edge. - # `conf.d/cloudflare-ips.conf` names Cloudflare's published ranges, and the - # real_ip module trusts `CF-Connecting-IP` only from those addresses, so - # these keys are the end client's address and a request that did not come - # through Cloudflare cannot choose its own. - real_ip_header CF-Connecting-IP; - real_ip_recursive on; - - # What one source may hold at once, and how fast it may open the two - # endpoints that cost the server something. The server has no per-source - # view at all — these are the numbers only a front can keep, and the - # server's own caps (`--max-connections`, `--max-rooms`, - # `--inbound-bytes-per-sec`) bound what is left. - # - # One zone per metered location, for both directives, and never one zone - # named twice. Both `limit_conn` and `limit_req` count per zone, so two - # locations that name the same zone share one counter and their limits - # interfere: a source reading `/meta` would spend the budget it also needs - # for the socket it is about to open. The page reads `/meta` on every load - # (`web_client`'s `engine/meta.ts`) and opens `/session` when the visitor - # joins, so the pair is not hypothetical. Different keys would be a second way - # to split them; separate zones are the one that also keeps each endpoint's - # number its own. - limit_conn_zone $binary_remote_addr zone=perip:1m; - limit_conn_zone $binary_remote_addr zone=persession:1m; - limit_conn_zone $binary_remote_addr zone=permeta:1m; - limit_req_zone $binary_remote_addr zone=handshake:1m rate=5r/s; - limit_req_zone $binary_remote_addr zone=metaread:1m rate=5r/s; - - # A 429 rather than a 503: what the source did is open too much too fast, - # and that is a status a client may retry. - limit_conn_status 429; - limit_req_status 429; - - # The upgrade header is `upgrade` on a WebSocket dial and absent on - # everything else, and a `Connection` that says `upgrade` on an ordinary - # request is a lie to the upstream. Derived rather than hardcoded. - map $http_upgrade $connection_upgrade { - default upgrade; - '' close; - } - - send_timeout 60s; - keepalive_timeout 65s; - - include /etc/nginx/conf.d/*.conf; -} diff --git a/deploy/proxy/www/404.html b/deploy/proxy/www/404.html deleted file mode 100644 index 23985fe..0000000 --- a/deploy/proxy/www/404.html +++ /dev/null @@ -1,104 +0,0 @@ - - - - - - Selvage demo: page not found - - - - - -
- -

404 Not found

-

This link is mistyped or out of date. Head back to start or join a session.

- Back to the demo -
- - diff --git a/deploy/selvage-update.service b/deploy/selvage-update.service deleted file mode 100644 index 001b062..0000000 --- a/deploy/selvage-update.service +++ /dev/null @@ -1,27 +0,0 @@ -# Pulls the tags `/srv/selvage/.env` names and brings the deployment up to them. -# `up -d` recreates only a service whose image or configuration changed, and the -# front is never pulled: it is built on the box. Pruning drops the images a -# recreation left dangling, which is what keeps the disk from filling. -# -# The lock is the one `/usr/local/sbin/selvage-deploy` holds for a CI deploy, so -# the two never run compose at once; a tick that finds it taken does nothing. -# -# A tick runs `up -d`, so it undoes a hand `docker compose stop` or `down`: stop -# the timer first. `Requisite=` fails a tick while Docker is stopped rather than -# starting it again, as `Requires=` would. -# -# `selvage` is in the `docker` group, which is root-equivalent, so no sandboxing -# here would bound anything. Installs to `/etc/systemd/system/`. -[Unit] -Description=Pull and apply the Selvage demo's images -Wants=network-online.target -After=network-online.target docker.service -Requisite=docker.service - -[Service] -Type=oneshot -User=selvage -WorkingDirectory=/srv/selvage -ExecStart=/usr/bin/flock --nonblock --conflict-exit-code 0 /srv/selvage/.update.lock \ - /bin/sh -c 'docker compose pull --ignore-buildable --quiet && docker compose up -d && docker image prune --force' -TimeoutStartSec=15min diff --git a/deploy/selvage-update.timer b/deploy/selvage-update.timer deleted file mode 100644 index 8b441a6..0000000 --- a/deploy/selvage-update.timer +++ /dev/null @@ -1,11 +0,0 @@ -# Runs `selvage-update.service` every five minutes. Installs to -# `/etc/systemd/system/`; `systemctl enable --now selvage-update.timer`. -[Unit] -Description=Pull and apply the Selvage demo's images every five minutes - -[Timer] -OnCalendar=*:0/5 -RandomizedDelaySec=30 - -[Install] -WantedBy=timers.target diff --git a/deploy/test_compose_args.py b/deploy/test_compose_args.py deleted file mode 100644 index 6214a48..0000000 --- a/deploy/test_compose_args.py +++ /dev/null @@ -1,278 +0,0 @@ -"""The guard around the command line each deployed shape gives `selvaged`. - -A command line this server refuses is a deployment that never starts. The box's -copy of `compose.yaml` is installed from the file tracked here, so `docker -compose up` with a refused line is a container that exits 2 and restart-loops -under `restart: unless-stopped`, and a front that upstreams to it is down with -it. - -The authority on what the binary accepts is the binary. This file restates no -rule and no number: it reads the `command:` each tracked shape declares, hands -it to `selvaged`, and fails if the server does not come up. - -The deployed compose shape is read: `deploy/compose.yaml`, the public -demo. The shapes are listed rather than globbed, and a shape that declares no -`command:` fails instead of being skipped, so one cannot drop out of this guard -without a reader seeing it. - -The one flag replaced is the bind address: `--listen` is the container's own -boundary rather than a limit, and a guard that took `0.0.0.0:8080` would fight -whatever is on the host. It is appended, and the last `--listen` is the one the -server takes. Every flag that carries a limit is the shape's own. - -Run it directly, with a `selvaged` on `PATH` or one built into `target/`: - - python3 deploy/test_compose_args.py - -or as the flake check the workflows run: -`nix build .#checks..deploy-args`. -""" - -import json -import os -import re -import select -import shutil -import subprocess -import time -import unittest -from pathlib import Path - -HERE = Path(__file__).resolve().parent -REPO = HERE.parent - -# The tracked shapes that hand `selvaged` a command line, in the order the tests -# below name them. -SHAPES = (HERE / "compose.yaml",) -QUEUE_FLAG = "--outbound-queue-bytes" - -# The banner `selvaged` prints once it is bound and serving. The address is a free -# loopback port rather than the shape's own, for the reason the docstring gives. -SERVING = "selvaged listening on" -BIND = "127.0.0.1:0" - -# A process that either refuses the command line and exits on the spot or binds -# and stays up is not waited on for long; the bound is here so that a hang is -# reported as one instead of stalling the check. -STARTUP_TIMEOUT = 20.0 -STOP_TIMEOUT = 10.0 - -_SERVICE = re.compile(r"^ ([a-z][a-z0-9_-]*):$") - - -def compose_body(text: str) -> str: - """The file's directives, with its comment lines dropped. - - Every read below is a scan, and a scan that walks the prose too reports what - the prose says rather than what the file declares. - """ - return "\n".join( - line for line in text.split("\n") if not line.lstrip().startswith("#") - ) - - -def service_blocks(text: str) -> dict: - """Each service the file defines, as the lines that follow its name.""" - blocks = {} - in_services = False - name = None - for line in compose_body(text).split("\n"): - if line.startswith("services:"): - in_services = True - continue - if not in_services: - continue - if line and not line.startswith(" "): - break - if match := _SERVICE.fullmatch(line): - name = match.group(1) - blocks[name] = [] - elif name is not None: - blocks[name].append(line) - return blocks - - -def scalar(token: str) -> str: - """One YAML scalar, as the argument the server would see. - - A value the shapes quote (`"30000"`) is JSON and parsed as one; a plain - token is taken as it stands. - """ - if token.startswith('"'): - return json.loads(token) - if token.startswith("'") and token.endswith("'"): - return token[1:-1] - return token - - -def command_block(block: list) -> list | None: - """The `command:` of one service, as argv, in either YAML spelling.""" - for index, line in enumerate(block): - stripped = line.strip() - if not stripped.startswith("command:"): - continue - rest = stripped[len("command:") :].strip() - if rest.startswith("["): - # A flow sequence. The shapes write it JSON-compatible, which is what - # `json.loads` requires; anything else is refused here rather than - # silently read as one argument. - return json.loads(rest) - argv = [] - for following in block[index + 1 :]: - token = following.strip() - if not token.startswith("- "): - break - argv.append(scalar(token[2:].strip())) - return argv - return None - - -def selvaged_command(path: Path) -> list | None: - """The command line `path` gives its `selvaged` service.""" - blocks = service_blocks(path.read_text(encoding="utf-8")) - if "selvaged" not in blocks: - return None - return command_block(blocks["selvaged"]) - - -def binary() -> str: - """The `selvaged` to run: `SELVAGED`, then `PATH`, then a checkout's build.""" - for candidate in ( - os.environ.get("SELVAGED"), - shutil.which("selvaged"), - str(REPO / "target" / "debug" / "selvaged"), - str(REPO / "target" / "release" / "selvaged"), - ): - if candidate and Path(candidate).is_file(): - return candidate - raise AssertionError( - "no `selvaged` to run: build one (`cargo build -p selvaged`) or run this " - "as the flake check (`nix build .#checks..deploy-args`), which " - "puts the built binary on `PATH`" - ) - - -def serve(command: list) -> tuple: - """Runs one shape's command line and reports what the server did. - - Returns `(serving, status, stdout, stderr)`: `serving` is true when the - banner was printed, `status` the exit status once the process stopped, and - the two streams as they were read. - """ - proc = subprocess.Popen( - [binary(), *command, "--listen", BIND], - stdout=subprocess.PIPE, - stderr=subprocess.PIPE, - text=True, - ) - try: - return observe(proc) - finally: - stop(proc) - - -def observe(proc) -> tuple: - """Waits for the process to print its banner or to stop, whichever it does. - - Neither is a sleep in front of an assertion: a refused command line exits - while `select` is still returning, and an accepted one prints the banner. - The deadline only decides when a process that does neither is reported as - the hang it is. - """ - deadline = time.monotonic() + STARTUP_TIMEOUT - out, err = "", "" - watched = [proc.stdout, proc.stderr] - while watched: - remaining = deadline - time.monotonic() - if remaining <= 0: - return False, proc.poll(), out, err - for stream in select.select(watched, [], [], remaining)[0]: - line = stream.readline() - if not line: - watched.remove(stream) - continue - if stream is proc.stdout: - out += line - if SERVING in line: - return True, None, out, err - else: - err += line - # Both streams are at EOF, so the process is on its way out; the status is - # what the guard reports it as. - try: - proc.wait(timeout=STOP_TIMEOUT) - except subprocess.TimeoutExpired: - pass - return False, proc.poll(), out, err - - -def stop(proc) -> None: - """Ends the serving process, and leaves nothing behind if it does not go.""" - if proc.poll() is None: - proc.terminate() - try: - proc.wait(timeout=STOP_TIMEOUT) - except subprocess.TimeoutExpired: - proc.kill() - proc.wait(timeout=STOP_TIMEOUT) - for stream in (proc.stdout, proc.stderr): - stream.close() - - -class ComposeCommandTest(unittest.TestCase): - """The command line each shape gives the server is one the server accepts.""" - - def test_the_scan_reads_a_command_out_of_every_shape_it_guards(self): - """A scan that matches nothing reports a clean tree, so say what it read.""" - for path in SHAPES: - with self.subTest(shape=path.name): - self.assertTrue(path.is_file(), f"{path} is not there to guard") - command = selvaged_command(path) - self.assertTrue( - command, - f"no `command:` was read out of {path}'s `selvaged` service, " - "so this shape is not being guarded", - ) - - def test_a_guarded_shape_still_names_the_flag_this_guard_is_for(self): - """The queue flag is this guard's subject; dropping it is a decision. - - A shape that stops naming it takes the server's own default, which is - above the floor, so nothing here is broken by that — but a guard whose - subject has quietly gone is a guard that reports clean. Whoever removes - it removes this test with it and says so. - """ - naming = [ - path.name - for path in SHAPES - if QUEUE_FLAG in (selvaged_command(path) or []) - ] - self.assertTrue( - naming, - f"none of {[path.name for path in SHAPES]} names {QUEUE_FLAG} any " - "more, which is the flag this guard exists for", - ) - - def test_the_public_demo_command_line_starts_the_server(self): - self.assert_starts(SHAPES[0]) - - def assert_starts(self, path: Path) -> None: - """`path`'s command line, run: the server comes up, or this says why not.""" - command = selvaged_command(path) - self.assertTrue(command, f"no command to run in {path}") - serving, status, out, err = serve(command) - if serving: - return - how = ( - f"neither started the server nor stopped it within {STARTUP_TIMEOUT}s" - if status is None - else f"did not start the server: exit {status}" - ) - self.fail( - f"{path.name}'s command line {how}, stdout {out!r}, stderr {err!r}\n" - f"the command line was: {' '.join(command)}" - ) - - -if __name__ == "__main__": - unittest.main(verbosity=2) diff --git a/deploy/test_deploy.py b/deploy/test_deploy.py deleted file mode 100644 index 973b59e..0000000 --- a/deploy/test_deploy.py +++ /dev/null @@ -1,480 +0,0 @@ -"""The guard around `deploy.py`, which is the whole of the box's privilege model. - -`/usr/local/sbin/selvage-deploy` is the only command `deployci` may run as root -(`deployci.sudoers`), so the request it reads on stdin is the only lever anything -holding a CI credential has on production. What carries that weight is asserted -here rather than argued: - -1. **Only a tag of the two published images, and nothing else.** Every value a - request may carry is matched against one fixed pattern, so most tests below are - the shapes one might *hope* a script would refuse: the sibling repository under - the wrong key, another registry, a shell metacharacter, a traversal, a control - character, a duplicate key. -2. **Only the requested lines of `.env` move.** Everything else in the file is the - owner's and comes through byte for byte. -3. **A deploy never runs compose beside the update timer**, and a failed one leaves - `.env` naming what it named. - -The rest is the tracked shape and units the script is paired with: the variables -the compose file interpolates are the ones the script writes, the front is not -rebuilt by a plain `up`, and the timer takes the lock the script takes. - -Run it directly: - - python3 deploy/test_deploy.py - -or as the flake check the workflows run: `nix build .#checks..prod-deploy`. -""" - -import contextlib -import fcntl -import io -import os -import re -import subprocess -import sys -import tempfile -import types -import unittest -from pathlib import Path -from unittest import mock - -HERE = Path(__file__).resolve().parent -sys.path.insert(0, str(HERE)) - -import deploy # noqa: E402 (the path above is what makes this importable) - -SELVAGED = "ghcr.io/selvage-protocol/selvaged:0.4.6" -WEB = "ghcr.io/selvage-protocol/selvage-web:latest" - - -def request(*lines: str) -> bytes: - return ("\n".join(lines) + "\n").encode() - - -class ParseRequestTest(unittest.TestCase): - def test_both_images(self): - parsed = deploy.parse_request(request(f"SELVAGED_IMAGE={SELVAGED}", f"SELVAGE_WEB_IMAGE={WEB}")) - self.assertEqual(parsed, {"SELVAGED_IMAGE": SELVAGED, "SELVAGE_WEB_IMAGE": WEB}) - - def test_one_image_alone_is_a_request(self): - parsed = deploy.parse_request(request(f"SELVAGED_IMAGE={SELVAGED}")) - self.assertNotIn("SELVAGE_WEB_IMAGE", parsed) - - def test_the_trailing_newline_is_optional(self): - without = deploy.parse_request(f"SELVAGED_IMAGE={SELVAGED}".encode()) - self.assertEqual(without["SELVAGED_IMAGE"], SELVAGED) - - def test_a_request_that_names_no_image_deploys_nothing(self): - for raw in (b"", b"\n"): - with self.subTest(raw=raw), self.assertRaises(deploy.Refused): - deploy.parse_request(raw) - - def test_the_tags_a_release_publishes_are_accepted(self): - for tag in ("latest", "0.4.6", "0.4.6-97ff967", "1.0.0-rc.1", "v2_x"): - with self.subTest(tag=tag): - value = f"ghcr.io/selvage-protocol/selvaged:{tag}" - self.assertEqual(deploy.parse_request(request(f"SELVAGED_IMAGE={value}"))["SELVAGED_IMAGE"], value) - - def test_a_tag_outside_the_grammar_is_refused(self): - for tag in ("", ".hidden", "-flag", "a" * 129, "a/b", "a:b", "a b", "0.4.6 ", "$(id)", "a#b", "é"): - with self.subTest(tag=tag), self.assertRaisesRegex(deploy.Refused, "SELVAGED_IMAGE"): - deploy.parse_request(request(f"SELVAGED_IMAGE=ghcr.io/selvage-protocol/selvaged:{tag}")) - - def test_a_digest_or_a_bare_repository_is_not_a_tag(self): - for value in ( - "ghcr.io/selvage-protocol/selvaged@sha256:" + "a" * 64, - "ghcr.io/selvage-protocol/selvaged:0.4.6@sha256:" + "a" * 64, - "ghcr.io/selvage-protocol/selvaged", - "0.4.6", - ): - with self.subTest(value=value), self.assertRaisesRegex(deploy.Refused, "SELVAGED_IMAGE"): - deploy.parse_request(request(f"SELVAGED_IMAGE={value}")) - - def test_a_reference_cannot_name_the_other_key_s_repository(self): - with self.assertRaisesRegex(deploy.Refused, "SELVAGED_IMAGE"): - deploy.parse_request(request(f"SELVAGED_IMAGE={WEB}")) - - def test_a_reference_cannot_leave_this_registry(self): - for value in ( - "ghcr.io/selvage-protocol-elsewhere/selvaged:latest", - "ghcr.io/other/selvaged:latest", - "docker.io/selvage-protocol/selvaged:latest", - "localhost/selvage-protocol/selvaged:latest", - "selvaged:latest", - "ghcr.io/selvage-protocol/../other/selvaged:latest", - ): - with self.subTest(value=value), self.assertRaisesRegex(deploy.Refused, "SELVAGED_IMAGE"): - deploy.parse_request(request(f"SELVAGED_IMAGE={value}")) - - def test_a_shell_metacharacter_is_not_a_tag(self): - for suffix in (";id", "$(id)", "`id`", "&&id", "|id", "'", '"', "${HOME}"): - with self.subTest(suffix=suffix), self.assertRaises(deploy.Refused): - deploy.parse_request(request(f"SELVAGED_IMAGE={SELVAGED}{suffix}")) - - def test_a_newline_in_a_value_is_a_second_line_and_nothing_more(self): - """The grammar is per line, so there is no value that can smuggle one in.""" - parsed = deploy.parse_request(request(f"SELVAGED_IMAGE={SELVAGED}\nSELVAGE_WEB_IMAGE={WEB}")) - self.assertEqual(parsed, {"SELVAGED_IMAGE": SELVAGED, "SELVAGE_WEB_IMAGE": WEB}) - with self.assertRaisesRegex(deploy.Refused, "not a key this box acts on"): - deploy.parse_request(request(f"SELVAGED_IMAGE={SELVAGED}\nCOMPOSE_CMD=id")) - - def test_a_key_this_box_does_not_act_on_is_refused_rather_than_ignored(self): - for line in ("SELVAGE_EXTRA_IMAGE=x", "COMPOSE_SHA256=" + "c" * 64, "COMPOSE_PROJECT_NAME=x"): - with self.subTest(line=line), self.assertRaisesRegex(deploy.Refused, "not a key this box acts on"): - deploy.parse_request(request(f"SELVAGED_IMAGE={SELVAGED}", line)) - - def test_a_duplicate_key_is_refused(self): - with self.assertRaisesRegex(deploy.Refused, "appears twice"): - deploy.parse_request(request(f"SELVAGED_IMAGE={SELVAGED}", f"SELVAGED_IMAGE={SELVAGED}")) - - def test_the_grammar_has_no_room_for_a_parser_difference(self): - for raw, why in ( - (b"SELVAGED_IMAGE=" + SELVAGED.encode() + b"\r\nSELVAGE_WEB_IMAGE=" + WEB.encode(), "CRLF"), - (b"\nSELVAGED_IMAGE=" + SELVAGED.encode(), "a leading blank line"), - (b"SELVAGED_IMAGE=" + SELVAGED.encode() + b"\n\nSELVAGE_WEB_IMAGE=" + WEB.encode(), "a blank line"), - (b"SELVAGED_IMAGE=" + SELVAGED.encode() + b"\tSELVAGE_WEB_IMAGE=" + WEB.encode(), "a tab"), - (b"SELVAGED_IMAGE = " + SELVAGED.encode(), "spaces around the separator"), - (b"selvaged_image=" + SELVAGED.encode(), "a lower-case key"), - (b"SELVAGED-IMAGE=" + SELVAGED.encode(), "a dashed key"), - (b"SELVAGED_IMAGE" + SELVAGED.encode(), "no separator"), - (b"SELVAGED_IMAGE=" + SELVAGED.encode() + b"\x00", "a NUL"), - (b"\xff\xfe", "bytes that are not UTF-8"), - ): - with self.subTest(why=why), self.assertRaises(deploy.Refused): - deploy.parse_request(raw) - - def test_an_oversized_request_is_refused_before_it_is_parsed(self): - body = (f"SELVAGED_IMAGE={SELVAGED}\n" * 200).encode() - self.assertGreater(len(body), deploy.MAX_REQUEST_BYTES) - with self.assertRaisesRegex(deploy.Refused, "longer than"): - deploy.parse_request(body) - - -class RewriteEnvTest(unittest.TestCase): - HAND = ( - "# the owner's note\n" - "\n" - "SELVAGED_IMAGE=ghcr.io/selvage-protocol/selvaged:latest\n" - "SELVAGE_WEB_IMAGE=ghcr.io/selvage-protocol/selvage-web@sha256:" + "b" * 64 + "\n" - "OTHER=1\n" - ) - - def test_only_the_requested_line_moves(self): - rewritten = deploy.rewrite_env(self.HAND, {"SELVAGED_IMAGE": SELVAGED}) - self.assertEqual(rewritten, self.HAND.replace("selvaged:latest", "selvaged:0.4.6")) - - def test_a_missing_key_is_appended(self): - rewritten = deploy.rewrite_env("# only a comment\n", {"SELVAGE_WEB_IMAGE": WEB}) - self.assertEqual(rewritten, f"# only a comment\nSELVAGE_WEB_IMAGE={WEB}\n") - - def test_a_file_without_a_final_newline_gains_one(self): - self.assertEqual( - deploy.rewrite_env("OTHER=1", {"SELVAGED_IMAGE": SELVAGED}), - f"OTHER=1\nSELVAGED_IMAGE={SELVAGED}\n", - ) - - def test_every_line_for_the_key_moves_and_a_commented_one_does_not(self): - text = "# SELVAGED_IMAGE=old\nSELVAGED_IMAGE=a\n SELVAGED_IMAGE = b\n" - rewritten = deploy.rewrite_env(text, {"SELVAGED_IMAGE": SELVAGED}) - self.assertEqual(rewritten, f"# SELVAGED_IMAGE=old\nSELVAGED_IMAGE={SELVAGED}\nSELVAGED_IMAGE={SELVAGED}\n") - - -class FilesTest(unittest.TestCase): - def test_the_file_it_replaced_is_kept_and_both_belong_to_the_directory_s_owner(self): - """Ownership is read from the calls: a non-root run owns every file it makes anyway.""" - with tempfile.TemporaryDirectory() as directory: - env_file = Path(directory) / ".env" - previous = Path(directory) / ".env.prev" - env_file.write_text("SELVAGED_IMAGE=old\n") - owned = [] - with mock.patch.multiple(deploy, ENV_FILE=env_file, ENV_PREV=previous), mock.patch( - "os.fchown", lambda _fd, uid, gid: owned.append((uid, gid)) - ): - self.assertTrue(deploy.record({"SELVAGED_IMAGE": SELVAGED})) - self.assertEqual(previous.read_text(), "SELVAGED_IMAGE=old\n") - owner = os.stat(directory) - self.assertEqual(owned, [(owner.st_uid, owner.st_gid)] * 2) - for path in (env_file, previous): - self.assertEqual(path.stat().st_mode & 0o777, 0o600, path) - self.assertEqual(env_file.read_text(), f"SELVAGED_IMAGE={SELVAGED}\n") - self.assertEqual(sorted(p.name for p in Path(directory).iterdir()), [".env", ".env.prev"]) - - def test_an_unchanged_file_is_not_rewritten(self): - with tempfile.TemporaryDirectory() as directory: - env_file = Path(directory) / ".env" - previous = Path(directory) / ".env.prev" - previous.write_text("the last real previous state\n") - env_file.write_text(f"SELVAGED_IMAGE={SELVAGED}\n") - with mock.patch.multiple(deploy, ENV_FILE=env_file, ENV_PREV=previous): - self.assertFalse(deploy.record({"SELVAGED_IMAGE": SELVAGED})) - self.assertEqual(previous.read_text(), "the last real previous state\n") - - def test_a_linked_env_is_neither_read_nor_written_through(self): - with tempfile.TemporaryDirectory() as directory: - elsewhere = Path(directory) / "elsewhere" - elsewhere.write_text("not the deployment's\n") - env_file = Path(directory) / ".env" - env_file.symlink_to(elsewhere) - with mock.patch.multiple(deploy, ENV_FILE=env_file), self.assertRaises(OSError): - deploy.read_env() - deploy.atomic_write(env_file, "written\n") - self.assertFalse(env_file.is_symlink()) - self.assertEqual(elsewhere.read_text(), "not the deployment's\n") - - def test_a_missing_env_reads_as_empty(self): - with tempfile.TemporaryDirectory() as directory: - with mock.patch.multiple(deploy, ENV_FILE=Path(directory) / ".env"): - self.assertEqual(deploy.read_env(), "") - - -class MainTest(unittest.TestCase): - """`main()` itself, and what it does before docker is ever reached.""" - - def run_main(self, request_bytes, **paths): - stdin = types.SimpleNamespace(buffer=io.BytesIO(request_bytes)) - with mock.patch.object(sys, "stdin", stdin), mock.patch.object( - deploy, "compose", lambda *a: self.fail(f"docker compose {a} was called") - ), mock.patch.object(deploy, "run", lambda *a: self.fail("a docker command was run")), mock.patch( - "os.geteuid", return_value=0 - ), mock.patch.multiple(deploy, **paths) if paths else contextlib.nullcontext(): - return deploy.main(["selvage-deploy"]) - - def test_arguments_are_refused(self): - self.assertEqual(deploy.main(["selvage-deploy", "--rollback"]), 2) - self.assertEqual(deploy.main(["selvage-deploy", SELVAGED]), 2) - - def test_a_refused_request_never_reaches_docker(self): - self.assertEqual(self.run_main(b"SELVAGED_IMAGE=latest\n"), 1) - - def test_a_deploy_waits_for_the_timer_and_gives_up_without_touching_docker(self): - with tempfile.TemporaryDirectory() as directory: - srv = Path(directory) - (srv / ".env").write_text(f"SELVAGED_IMAGE={SELVAGED}\n") - lock = srv / ".update.lock" - with open(lock, "w") as held, mock.patch.multiple( - deploy, SRV=srv, ENV_FILE=srv / ".env", ENV_STAGED=srv / ".env.deploy", LOCK=lock, - LOCK_WAIT_SECONDS=0.0, - ): - fcntl.flock(held, fcntl.LOCK_EX) - self.assertEqual(self.run_main(request(f"SELVAGED_IMAGE={WEB.replace('selvage-web', 'selvaged')}")), 1) - self.assertFalse((srv / ".env.deploy").exists()) - self.assertEqual((srv / ".env").read_text(), f"SELVAGED_IMAGE={SELVAGED}\n") - - def test_a_linked_lock_is_neither_followed_nor_created_through(self): - """Root opens the lock in a directory `selvage` owns, so a link there is refused.""" - for existing in (True, False): - with self.subTest(existing=existing), tempfile.TemporaryDirectory() as directory: - srv = Path(directory) - target = srv / "elsewhere" - if existing: - target.write_text("not the lock\n") - (srv / ".update.lock").symlink_to(target) - status = self.run_main( - request(f"SELVAGED_IMAGE={SELVAGED}"), - SRV=srv, ENV_FILE=srv / ".env", ENV_STAGED=srv / ".env.deploy", LOCK=srv / ".update.lock", - ) - self.assertEqual(status, 1) - if existing: - self.assertEqual(target.read_text(), "not the lock\n") - else: - self.assertFalse(target.exists()) - self.assertFalse((srv / ".env.deploy").exists()) - - -class StagedDeployTest(unittest.TestCase): - """A failed deploy must not move the box's record of what it intends to run. - - `.env` is what the next timer tick and every hand `up -d` read, so the new - references go into `.env.deploy` first, and `.env` is written only once the - containers run what was asked for. - """ - - OTHER = "ghcr.io/selvage-protocol/selvaged:0.4.7" - BEFORE = f"# kept\nSELVAGED_IMAGE={SELVAGED}\nSELVAGE_WEB_IMAGE={WEB}\nEXTRA=1\n" - - def deploy(self, srv, request_bytes, compose_stub, run_stub): - stdin = types.SimpleNamespace(buffer=io.BytesIO(request_bytes)) - with mock.patch.multiple( - deploy, - SRV=srv, - ENV_FILE=srv / ".env", - ENV_PREV=srv / ".env.prev", - ENV_STAGED=srv / ".env.deploy", - LOCK=srv / ".update.lock", - ), mock.patch.object(sys, "stdin", stdin), mock.patch.object( - deploy, "compose", compose_stub - ), mock.patch.object(deploy, "run", run_stub), mock.patch("os.geteuid", return_value=0): - return deploy.main(["selvage-deploy"]) - - def compose_failing(self, verb, asked): - def stub(env_file, *arguments): - asked.append((env_file, arguments)) - return subprocess.CompletedProcess([], 1 if arguments[:1] == (verb,) else 0, "", "") - - return stub - - def run_converged(self, argv): - running = "sha256:" + "e" * 64 - if argv[:2] == ["docker", "image"]: - return subprocess.CompletedProcess(argv, 0, running + "\n", "") - if argv[:2] == ["docker", "inspect"]: - return subprocess.CompletedProcess(argv, 0, f"{running}|running\n", "") - return subprocess.CompletedProcess(argv, 0, "one\n", "") - - def test_a_failed_pull_or_up_leaves_env_alone(self): - for verb in ("pull", "up"): - with self.subTest(verb=verb), tempfile.TemporaryDirectory() as directory: - srv = Path(directory) - (srv / ".env").write_text(self.BEFORE) - asked = [] - status = self.deploy( - srv, - request(f"SELVAGED_IMAGE={self.OTHER}"), - self.compose_failing(verb, asked), - self.run_converged, - ) - self.assertEqual(status, 1) - self.assertEqual((srv / ".env").read_text(), self.BEFORE) - self.assertFalse((srv / ".env.prev").exists()) - self.assertIn(self.OTHER, (srv / ".env.deploy").read_text()) - self.assertEqual({env for env, _ in asked}, {srv / ".env.deploy"}) - - def test_a_deploy_that_does_not_converge_leaves_env_alone(self): - with tempfile.TemporaryDirectory() as directory: - srv = Path(directory) - (srv / ".env").write_text(self.BEFORE) - - def run_stub(argv): - if argv[:2] == ["docker", "inspect"]: - return subprocess.CompletedProcess(argv, 0, "sha256:old|running\n", "") - return self.run_converged(argv) - - status = self.deploy(srv, request(f"SELVAGED_IMAGE={self.OTHER}"), self.compose_failing("none", []), run_stub) - self.assertEqual(status, 1) - self.assertEqual((srv / ".env").read_text(), self.BEFORE) - - def test_a_service_that_is_not_running_leaves_env_alone(self): - def exited(argv): - if argv[:2] == ["docker", "inspect"]: - return subprocess.CompletedProcess(argv, 0, "sha256:" + "e" * 64 + "|exited\n", "") - return self.run_converged(argv) - - def missing(argv): - if argv[:2] == ["docker", "compose"] and "ps" in argv: - return subprocess.CompletedProcess(argv, 0, "\n", "") - return self.run_converged(argv) - - for why, run_stub in (("proxy is exited", exited), ("proxy is missing", missing)): - with self.subTest(why=why), tempfile.TemporaryDirectory() as directory, mock.patch( - "sys.stderr", new_callable=io.StringIO - ) as stderr: - srv = Path(directory) - (srv / ".env").write_text(self.BEFORE) - status = self.deploy(srv, request(f"SELVAGED_IMAGE={self.OTHER}"), self.compose_failing("none", []), run_stub) - self.assertEqual(status, 1) - self.assertIn(f"refused: {why} after `up -d`", stderr.getvalue()) - self.assertEqual((srv / ".env").read_bytes(), self.BEFORE.encode()) - self.assertFalse((srv / ".env.prev").exists()) - - def test_an_env_that_is_not_utf8_is_refused_and_left_alone(self): - with tempfile.TemporaryDirectory() as directory: - srv = Path(directory) - (srv / ".env").write_bytes(b"SELVAGED_IMAGE=\xff\n") - asked = [] - status = self.deploy(srv, request(f"SELVAGED_IMAGE={self.OTHER}"), self.compose_failing("none", asked), self.run_converged) - self.assertEqual(status, 1) - self.assertEqual((srv / ".env").read_bytes(), b"SELVAGED_IMAGE=\xff\n") - self.assertEqual(asked, []) - - def test_a_hand_edit_made_during_the_deploy_survives_it(self): - """Hand commands do not take the lock, so `.env` can move while `up` runs.""" - pinned = self.BEFORE.replace(WEB, "ghcr.io/selvage-protocol/selvage-web:0.4.5") - with tempfile.TemporaryDirectory() as directory: - srv = Path(directory) - (srv / ".env").write_text(self.BEFORE) - - def compose_stub(env_file, *arguments): - if arguments[:1] == ("up",): - (srv / ".env").write_text(pinned) - return subprocess.CompletedProcess([], 0, "", "") - - status = self.deploy(srv, request(f"SELVAGED_IMAGE={self.OTHER}"), compose_stub, self.run_converged) - self.assertEqual(status, 0) - self.assertEqual((srv / ".env").read_text(), pinned.replace(SELVAGED, self.OTHER)) - self.assertEqual((srv / ".env.prev").read_text(), pinned) - - def test_a_converged_deploy_moves_one_line_and_clears_the_stage(self): - with tempfile.TemporaryDirectory() as directory: - srv = Path(directory) - (srv / ".env").write_text(self.BEFORE) - asked = [] - status = self.deploy( - srv, request(f"SELVAGED_IMAGE={self.OTHER}"), self.compose_failing("none", asked), self.run_converged - ) - self.assertEqual(status, 0) - self.assertEqual((srv / ".env").read_text(), self.BEFORE.replace(SELVAGED, self.OTHER)) - self.assertEqual((srv / ".env.prev").read_text(), self.BEFORE) - self.assertFalse((srv / ".env.deploy").exists()) - self.assertEqual([arguments for _, arguments in asked][:2], [("pull", "selvaged"), ("up", "-d")]) - - -class TrackedShapeTest(unittest.TestCase): - """The compose file and the units the script is installed beside.""" - - def setUp(self): - self.compose = "\n".join( - line - for line in (HERE / "compose.yaml").read_text(encoding="utf-8").split("\n") - if not line.lstrip().startswith("#") - ) - self.service = (HERE / "selvage-update.service").read_text(encoding="utf-8") - - def test_the_shape_interpolates_exactly_the_variables_the_deploy_writes(self): - variables = set(re.findall(r"\$\{([A-Z_][A-Z0-9_]*)", self.compose)) - self.assertEqual(variables, set(deploy.PINS)) - - def test_the_shape_names_exactly_the_services_the_deploy_checks(self): - services = set(re.findall(r"^ ([a-z][a-z0-9_-]*):$", self.compose, re.MULTILINE)) - self.assertEqual(services, set(deploy.SERVICES)) - - def test_a_plain_up_does_not_rebuild_the_front(self): - self.assertIn("build:", self.compose) - self.assertNotIn("pull_policy", self.compose) - - def test_the_directory_is_self_contained(self): - self.assertNotRegex(self.compose, r"\n\s+- /", "a host path outside the project directory") - self.assertNotRegex(self.compose, r"source:\s*/", "a host path outside the project directory") - self.assertIn("- ./tls/origin.key:", self.compose) - - def test_the_timer_takes_the_lock_the_deploy_takes(self): - self.assertIn(f"flock --nonblock --conflict-exit-code 0 {deploy.LOCK} ", self.service) - self.assertIn(f"WorkingDirectory={deploy.SRV}\n", self.service) - self.assertIn("User=selvage\n", self.service) - - def test_a_tick_never_starts_a_docker_the_owner_stopped(self): - self.assertIn("Requisite=docker.service\n", self.service) - self.assertNotRegex(self.service, r"(?m)^Requires=") - - def test_a_deploy_loads_compose_the_way_the_timer_and_the_owner_do(self): - """In `SRV` with no `-f`, so a `compose.override.yaml` there applies to all three.""" - self.assertNotRegex(self.service, r"docker compose -f|--project-directory") - called = [] - with mock.patch.object(deploy, "SRV", Path("/srv/elsewhere")), mock.patch( - "subprocess.run", - lambda argv, **options: called.append((argv, options.get("cwd"))) or subprocess.CompletedProcess(argv, 0, "", ""), - ): - deploy.compose(deploy.ENV_STAGED, "up", "-d") - deploy.service_state("selvaged", deploy.ENV_STAGED) - self.assertEqual({cwd for _, cwd in called}, {Path("/srv/elsewhere")}) - for argv, _ in called: - self.assertNotIn("-f", argv) - self.assertNotIn("--project-directory", argv) - - def test_the_timer_skips_the_front_and_prunes(self): - self.assertIn("docker compose pull --ignore-buildable", self.service) - self.assertIn("docker image prune --force", self.service) - - -if __name__ == "__main__": - unittest.main(verbosity=2) diff --git a/deploy/test_front_limits.py b/deploy/test_front_limits.py deleted file mode 100755 index b317db4..0000000 --- a/deploy/test_front_limits.py +++ /dev/null @@ -1,561 +0,0 @@ -#!/usr/bin/env python3 -"""The front's own contribution to a response: the name it answers, its -per-source limits, and the `Strict-Transport-Security` field it deliberately -does not add. - - python3 -B test_front_limits.py - -The front is the only layer in this deployment with a per-source view: the -server sees connections, not who opened them, so `PROTOCOL.md` §12's connection -cap and rate limit are kept here or nowhere. What matters is therefore not what -the zones say in the file but that a source is refused, and that one endpoint's -traffic cannot spend another's budget — the page reads `/meta` on every load and -opens `/session` on the click that follows, so a shared counter is a visitor -refused at the join. - -All of it is driven against the front's real `nginx.conf` and -`conf.d/default.conf`, under nginx with the two upstream names answered on -loopback and TLS off, exactly as `check-front.sh` does it. Five claims cannot -be made by reading the files and are made by measuring: - - - a request naming a Host the front is not the server for is closed rather - than proxied to the demo's locations, and one naming the front's own Host is - served — `selvage.dontblameme.dev` is the project's landing page, served - somewhere else entirely; - - `/session` refuses past its own burst (`limit_req`), with a real 429; - - `/meta` refuses past its own concurrency (`limit_conn`), with a real 429; - - a source that has just spent one metered endpoint is *not* refused on the - other; - - the front serves no `Strict-Transport-Security` field of its own, on any of - its three locations. - -Three of them come with their own control, in this file: the same run against a -copy of the configuration with the host guard removed, one whose `/meta` names -the `/session` request zone, and one that adds an HSTS field to the server -block. Each copy must *fail* the claim it is the control for. A control that -passes would mean the test cannot see the defect it exists for. - -Every client is a loopback address of its own (`127.0.0.2` and up), because the -zones are keyed on `$binary_remote_addr`. A fresh address is a fresh bucket, so -no claim here waits for a rate to refill, and no assertion is made about a -sleep: the status of the request that follows is the measured thing. -""" - -import http.client -import http.server -import os -import re -import shutil -import socket -import subprocess -import sys -import threading -import time - -# The harness's own upstream host, assembled rather than written as one -# `http://127.0.0.1:port` literal: a bare URL in a text file is something the -# repository's link check fetches, and a loopback port is not fetchable. -LOOPBACK = "127.0.0.1" -HERE = os.path.dirname(os.path.abspath(__file__)) -PROXY = os.path.join(HERE, "proxy") -SERVER_CONF = os.path.join(PROXY, "nginx.conf") -DEFAULT_CONF = os.path.join(PROXY, "conf.d", "default.conf") - -failures = [] - - -def ok(what): - print(f" ok {what}") - - -def bad(what): - print(f" FAIL {what}") - failures.append(what) - - -def say(what): - print(f"\n=== {what} ===") - - -def nginx_binary(): - if os.environ.get("NGINX_BIN"): - return os.environ["NGINX_BIN"] - found = shutil.which("nginx") - if found: - return found - print("no nginx on PATH and no NGINX_BIN set; nothing was proved", file=sys.stderr) - raise SystemExit(2) - - -def work_root(): - """Where the harness writes. Not `/tmp` by default: it is a RAM-backed tmpfs - on this project's host, and a build there has taken a machine down.""" - root = os.environ.get("FRONT_LIMITS_WORKDIR") - if not root: - root = os.path.join(os.path.dirname(HERE), ".tmp", "front-limits") - shutil.rmtree(root, ignore_errors=True) - return root - - -def server_name(text): - """The one name the front's block is the server for, read out of the shipped - configuration rather than repeated here. - - Every request below has to name it: the front closes the connection for any - other Host, so a harness asking under a name of its own would fail every - claim for the wrong reason. The first name is the one the guard compares - against, which is why only it is read. - """ - found = re.search(r"^\s*server_name\s+([^;\s]+);", text, re.M) - if not found: - print(f"no server_name in {DEFAULT_CONF}: the harness has no Host to ask for", file=sys.stderr) - raise SystemExit(2) - return found.group(1) - - -# ---------------------------------------------------------------- the rewrite -# -# Every substitution the harness makes is asserted in both directions: the -# needle has to be in the real file, and it has to be gone from the harness -# copy. A front whose shape changed — a second listener, an upstream renamed, a -# root moved — stops this script instead of being quietly rewritten into -# something that passes. - -def rewrite(text, pairs, where): - for needle, replacement in pairs: - if needle not in text: - bad(f"'{needle}' is gone from {where}; this harness rewrites it and must be updated") - continue - text = text.replace(needle, replacement) - if needle in text: - bad(f"'{needle}' survived into the harness copy of {where}") - return text - - -def harness_configs(work, listen_port, stub_port, default_text=None): - os.makedirs(os.path.join(work, "conf.d"), exist_ok=True) - os.makedirs(os.path.join(work, "tmp"), exist_ok=True) - os.makedirs(os.path.join(work, "prefix"), exist_ok=True) - - with open(SERVER_CONF, encoding="utf-8") as handle: - server = handle.read() - server = rewrite(server, [ - ("pid /dev/shm/nginx.pid;", f"pid {work}/nginx.pid;"), - ("error_log /dev/stderr crit;", f"error_log {work}/error.log crit;"), - ("/dev/shm/client_temp", f"{work}/tmp/client_temp"), - ("/dev/shm/proxy_temp", f"{work}/tmp/proxy_temp"), - ("/dev/shm/fastcgi_temp", f"{work}/tmp/fastcgi_temp"), - ("/dev/shm/uwsgi_temp", f"{work}/tmp/uwsgi_temp"), - ("/dev/shm/scgi_temp", f"{work}/tmp/scgi_temp"), - ("include /etc/nginx/conf.d/*.conf;", f"include {work}/conf.d/*.conf;"), - ], "nginx.conf") - - if default_text is None: - with open(DEFAULT_CONF, encoding="utf-8") as handle: - default_text = handle.read() - root = re.search(r"^\s*root (.*);$", default_text, re.M) - if not root: - bad(f"no root directive in {DEFAULT_CONF}: the harness cannot point the not-found page at anything") - pairs = [ - ("listen 8080 ssl;", f"listen 127.0.0.1:{listen_port};"), - ("http://selvaged:8080", f"http://{LOOPBACK}:{stub_port}"), - ("http://selvage-web:8080", f"http://{LOOPBACK}:{stub_port}"), - ] - if root: - pairs.append((f"root {root.group(1)};", f"root {PROXY}/www;")) - default = rewrite(default_text, pairs, "conf.d/default.conf") - - certs = len(re.findall(r"^\s*ssl_certificate", default, re.M)) - if certs != 2: - bad(f"{DEFAULT_CONF} has {certs} ssl_certificate lines, expected 2") - default = re.sub(r"^\s*ssl_certificate.*$", "", default, flags=re.M) - if re.search(r"^\s*ssl_certificate", default, re.M): - bad("an ssl_certificate line survived into the harness") - - with open(os.path.join(work, "nginx.conf"), "w", encoding="utf-8") as handle: - handle.write(server) - with open(os.path.join(work, "conf.d", "default.conf"), "w", encoding="utf-8") as handle: - handle.write(default) - shutil.copy(os.path.join(PROXY, "conf.d", "cloudflare-ips.conf"), os.path.join(work, "conf.d")) - return default - - -# ----------------------------------------------------------------- the stub -# -# Stands in for `selvaged` and `selvage-web` at once. It answers everything -# `200 text/html`. `/meta?slow=1` is held open for a moment, so -# that concurrent connections genuinely overlap: `limit_conn` counts requests in -# flight, and against a stub that answers instantly nothing ever is. - -class Stub(http.server.BaseHTTPRequestHandler): - protocol_version = "HTTP/1.1" - - def do_GET(self): # noqa: N802 - http.server's naming - if self.path.startswith("/meta") and "slow=1" in self.path: - time.sleep(0.6) - body = b"the upstream's stand-in" - self.send_response(200) - self.send_header("Content-Type", "text/html") - self.send_header("Content-Length", str(len(body))) - self.end_headers() - self.wfile.write(body) - - def log_message(self, *_args): - pass - - -def start_stub(): - stub = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Stub) - threading.Thread(target=stub.serve_forever, daemon=True).start() - return stub, stub.server_address[1] - - -# --------------------------------------------------------------- the clients - -def source_conn(port, source, timeout=15): - """A client whose source address is `source`, so its zone key is its own.""" - sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) - sock.settimeout(timeout) - sock.bind((source, 0)) - sock.connect(("127.0.0.1", port)) - conn = http.client.HTTPConnection("127.0.0.1", port, timeout=timeout) - conn.sock = sock - return conn - - -def get_response(conn, path, host): - conn.request("GET", path, headers={"Host": host, "User-Agent": "front-limits"}) - response = conn.getresponse() - headers = {name.lower(): value for name, value in response.getheaders()} - response.read() - return response.status, headers - - -def get(conn, path, host): - return get_response(conn, path, host)[0] - - -def attempt(port, source, path, host): - """One request's outcome: the status the front answered, or how the connection - ended when it answered nothing. - - `444` is a connection closed with no response, which `http.client` reports as - the peer hanging up rather than as a status, so that is what a refusal reads - as here. - """ - conn = source_conn(port, source) - try: - return get(conn, path, host), "" - except (http.client.HTTPException, OSError) as error: - return None, type(error).__name__ - finally: - conn.close() - - -def refuse_after(conn, path, budget, host): - """Send until the front refuses, and report which request was refused.""" - for index in range(1, budget + 1): - if get(conn, path, host) == 429: - return index - return None - - -# ---------------------------------------------------------------- the phases - -def phase_host_routing(port, label, host, expect_wrong_served): - """The Host a request names, not the address it arrives at, decides whether - the front serves it. - - The demo's block is the only one on its port, so nginx makes it the default - and would otherwise answer any name that resolves to this origin — - `selvage.dontblameme.dev` is the project's landing page, served somewhere - else entirely, and every stray name pointed here would reach the demo's - locations too. What the front does with the refused name is its own choice; - `444` closes the connection without a response, which is what `attempt` - reports as a failure rather than a status. - - The refusal is a negative, so the claim carries its own control: the same run - against a copy with the guard removed has to *serve* the wrong name, or the - claim cannot see the defect it exists for. - """ - wrong = "selvage.dontblameme.dev" - for path, what in (("/", "the page"), ("/meta", "the server's JSON")): - status, how = attempt(port, "127.0.0.7", path, host) - if status == 200: - ok(f"[{label}] {path} named {host} is served ({what})") - else: - bad(f"[{label}] {path} named the front's own Host answered {status or how}: the demo stopped answering") - - for path in ("/", "/meta"): - status, how = attempt(port, "127.0.0.8", path, wrong) - served = status == 200 - if expect_wrong_served: - if served: - ok(f"[{label}] the copy with no host guard served {path} for {wrong}: this claim can see the defect") - else: - bad(f"[{label}] the control removes the host guard and {path} for {wrong} answered {status or how}: the claim cannot see the defect") - elif served: - bad(f"[{label}] {path} named {wrong} was served ({status}): the front answers a name it is not the server for") - else: - ok(f"[{label}] {path} named {wrong} was not served ({status or how})") - - -def phase_own_limits(port, host): - say("each metered endpoint refuses on its own account") - conn = source_conn(port, "127.0.0.3") - refused = refuse_after(conn, "/session", 30, host) - conn.close() - if refused: - ok(f"/session was refused (429) at request {refused} of 30 from one source") - else: - bad("/session was never refused in 30 requests: its rate limit is not in force") - - # Six sockets at once from one source, each held open by the stub, against - # `limit_conn permeta 4`. Separate sockets, one address: the same key. - statuses = [None] * 6 - gate = threading.Barrier(len(statuses)) - - def reader(index): - try: - conn = source_conn(port, "127.0.0.4") - gate.wait(timeout=10) - statuses[index] = get(conn, "/meta?slow=1", host) - conn.close() - except Exception as error: # noqa: BLE001 - reported, not raised - statuses[index] = f"error {error}" - - threads = [threading.Thread(target=reader, args=(index,)) for index in range(len(statuses))] - for thread in threads: - thread.start() - for thread in threads: - thread.join() - if 429 in statuses: - ok(f"6 concurrent /meta reads from one source were refused: {statuses}") - else: - bad(f"6 concurrent /meta reads from one source were all served: {statuses} — limit_conn is not in force") - - -def phase_independence(port, label, host, expect_refusal=False): - """Spend `/meta` from one source, then ask that same source for `/session`. - - The claim is about the status of the request that follows the spend, not - about a sleep: the source is one whose buckets are otherwise untouched, and - the spend is not reported as having happened unless `/meta` was really - refused first. - """ - conn = source_conn(port, "127.0.0.2") - spent_at = refuse_after(conn, "/meta", 60, host) - if spent_at is None: - bad(f"[{label}] /meta was never refused in 60 requests: the spend did not happen") - conn.close() - return - first = get(conn, "/session", host) - rest = [get(conn, "/session", host) for _ in range(2)] - conn.close() - if expect_refusal: - if first == 429: - ok(f"[{label}] /meta spent at request {spent_at}; the very next /session was refused — the zones are shared") - else: - bad(f"[{label}] /meta spent at request {spent_at} but /session answered {first} ({rest}): the control cannot see the defect") - elif first != 429: - ok(f"[{label}] /meta spent at request {spent_at}; /session answered {first} right after ({rest})") - else: - bad(f"[{label}] /meta spent at request {spent_at} and /session was refused: one endpoint's budget spent another's") - - -def phase_header_posture(port, label, host, expect_sts): - """The `Strict-Transport-Security` field the front adds: none. - - The demo's HSTS is the edge's. Cloudflare emits one field for every response - on the zone, the ones the origin never writes included, and a policy is a - property of the host rather than of the response that carried it -- so a - second field here would buy the deployment nothing and would make which of - the two a browser honours depend on their order, since a user agent - processes only the first (`RFC 6797` §8.1). - - The claim is a negative, so it carries the check that it is reading the - thing it claims to: a response with no header block at all would satisfy it - for the wrong reason, and every path asked for has to answer with a media - type before its silence about HSTS means anything. - """ - asked = (("/", "page"), ("/404.html", "the front's own not-found page"), ("/meta", "the server's JSON")) - silent = [] - sent = [] - for path, what in asked: - conn = source_conn(port, "127.0.0.6") - try: - status, headers = get_response(conn, path, host) - finally: - conn.close() - if not headers.get("content-type"): - bad(f"[{label}] {path} ({what}) answered with no media type: this claim is not reading headers") - if "strict-transport-security" in headers: - sent.append(f"{path} -> {headers['strict-transport-security']!r}") - else: - silent.append(f"{path} -> {status} ({what})") - if expect_sts: - if sent: - ok(f"[{label}] the copy that adds an HSTS field was seen carrying one: {'; '.join(sent)}") - else: - bad(f"[{label}] the control adds an HSTS field and this claim did not see it: it cannot see the defect it exists for") - elif not sent: - ok(f"[{label}] the front added no Strict-Transport-Security: {'; '.join(silent)}") - else: - bad( - f"[{label}] the front added Strict-Transport-Security: {'; '.join(sent)} — the edge already " - f"emits one for the zone and RFC 6797 §8.1 makes a browser honour only the first" - ) - - -def phase_page_independence(port, host): - conn = source_conn(port, "127.0.0.5") - for _ in range(15): - get(conn, "/", host) - first = get(conn, "/session", host) - conn.close() - if first != 429: - ok(f"15 page reads from one source left /session answerable ({first})") - else: - bad("15 page reads from one source refused the /session that followed") - - -# ----------------------------------------------------------------- the runs - -def stop_front(ngx, work): - subprocess.run([ngx, "-c", f"{work}/nginx.conf", "-p", f"{work}/prefix", "-e", f"{work}/error.log", "-s", "stop"], - check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) - - -def wait_ready(port, host, deadline=15.0): - end = time.monotonic() + deadline - while time.monotonic() < end: - try: - conn = source_conn(port, "127.0.0.9", timeout=2) - answer = get(conn, "/", host) - conn.close() - if answer == 200: - return True - except OSError: - pass - time.sleep(0.2) - return False - - -def port_free(port): - with socket.socket() as probe: - try: - probe.bind(("127.0.0.1", port)) - except OSError: - return False - return True - - -def run(ngx, work, stub_port, label, host, default_text=None, expect_refusal=False, expect_sts=False, - expect_wrong_host_served=False): - """Start the front on a port of its own and make the claims against it. - - A run whose nginx failed to bind (a leftover from a killed run holding the - port) must not go on to measure the leftover: the pid file nginx itself - wrote has to be there, and the front has to answer, before any claim is - made. A busy port is not an assertion failure, only an exhausted range is. - """ - default = None - started = False - for port in range(18440, 18500): - if not port_free(port): - continue - default = harness_configs(work, port, stub_port, default_text) - subprocess.run([ngx, "-c", f"{work}/nginx.conf", "-p", f"{work}/prefix", "-e", f"{work}/error.log"], - check=True) - started = os.path.exists(f"{work}/nginx.pid") and wait_ready(port, host) - if started: - break - stop_front(ngx, work) - if not started: - bad(f"[{label}] the harness could not start a front of its own on any port in 18440-18499") - return default - try: - ok(f"[{label}] the front is listening on 127.0.0.1:{port}") - phase_host_routing(port, label, host, expect_wrong_host_served) - phase_own_limits(port, host) - phase_independence(port, label, host, expect_refusal=expect_refusal) - phase_page_independence(port, host) - phase_header_posture(port, label, host, expect_sts=expect_sts) - finally: - stop_front(ngx, work) - return default - - -def main(): - ngx = nginx_binary() - - # nginx reads `NGINX` as the list of sockets a socket-activated parent handed it, the one - # environment variable it does not ignore. A value that is not a socket number is logged - # and passed over, but its *presence* is what nginx acts on: it takes itself for - # inherited and skips daemonising, so the start below would run a master in the - # foreground and block here for good rather than answering. An inherited value is dropped. - os.environ.pop("NGINX", None) - root = work_root() - stub, stub_port = start_stub() - - with open(DEFAULT_CONF, encoding="utf-8") as handle: - shipped = handle.read() - host = server_name(shipped) - - say("the shipped configuration") - run(ngx, os.path.join(root, "front"), stub_port, "the shipped configuration", host) - - # The control: the same configuration with the host guard removed. That is - # the front that answers any name that resolves to it — the landing page's - # name included — and the host-routing claim above has to fail against it or - # it is not testing anything. The real file is not touched; the copy is a - # string. - say("the control: no guard on the Host the front answers") - guard = " if ($host != $server_name) {\n return 444;\n }\n" - if guard not in shipped: - bad("the host guard is not in the server block; the control has nothing to mutate") - else: - run(ngx, os.path.join(root, "host-control"), stub_port, "the host control", host, - default_text=shipped.replace(guard, ""), expect_wrong_host_served=True) - - # The control: the same configuration with `/meta` pointed at `/session`'s - # request zone. That is the defect the split exists to prevent, and the - # independence claim above has to fail against it or the claim is not - # testing anything. The real file is not touched; the copy is a string. - say("the control: /meta naming the session request zone") - needle = "limit_req zone=metaread burst=10 nodelay;" - if needle not in shipped: - bad(f"'{needle}' is not in the /meta location; the control has nothing to mutate") - else: - control = shipped.replace(needle, "limit_req zone=handshake burst=10 nodelay;") - run(ngx, os.path.join(root, "control"), stub_port, "the control", host, - default_text=control, expect_refusal=True) - - # The second control: the shipped configuration with an HSTS field added to - # the server block. That is what a reader who took HSTS for the front's to - # set would write, and the posture claim above has to fail against it or it - # is not testing anything. - say("the control: the front adding a Strict-Transport-Security field") - marker = " server_tokens off;" - if marker not in shipped: - bad(f"'{marker}' is not in the server block; the control has nothing to mutate") - else: - sts_control = shipped.replace( - marker, - marker + '\n add_header Strict-Transport-Security "max-age=0; includeSubDomains; preload" always;', - ) - run(ngx, os.path.join(root, "sts-control"), stub_port, "the STS control", host, - default_text=sts_control, expect_sts=True) - stub.shutdown() - - say("result") - if failures: - print(f" {len(failures)} assertion(s) failed") - return 1 - print(" the front answered only its own name, refused on its own account, one " - "endpoint's traffic spent no other's, and it added no HSTS of its own") - return 0 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/deploy/test_install_shape.py b/deploy/test_install_shape.py deleted file mode 100644 index ea263cc..0000000 --- a/deploy/test_install_shape.py +++ /dev/null @@ -1,582 +0,0 @@ -"""The guard around `install_shape.py`, which is half of the box's privilege model. - -`/usr/local/sbin/selvage-install-shape` is one of the two commands `deployci` may -run as root (`installci.sudoers`), and the tar stream it reads on stdin is a -root-owned write into `/srv/selvage` that ends in `docker compose up -d --build -proxy`. What carries that weight is asserted here rather than argued: - -1. **Only the box's shape, and nothing else.** `compose.yaml` and anything under - `proxy/`, by one grammar: relative, plain names. Every test below is a shape - one might *hope* a script would refuse — an entry outside the set, an absolute - path, a traversal, a symlink, a hardlink, a device, a fifo. -2. **A refusal writes nothing.** Each of those seeds a valid entry *before* the - refused one, so a stream that was installed as it was read would show up here, - and each compares the whole tree byte for byte. -3. **A step is resolved inside the descriptor the step before it found.** A - symlinked *directory* — not the symlinked file the obvious guard already - rejects — is the shape that catches a check-then-use, and it is refused with - the directory it points at left alone. -4. **The files the shape does not own are not touched**: `.env`, `.env.example`, - `tls/`, and anything else in the box. - -The composer of the stream is the runbook's own command — -`git archive --format=tar :deploy compose.yaml proxy` — so the last test -feeds the **tracked** shape through the parser: if a file is added to `proxy/` -that a real release would send and this refuses, that test fails rather than the -install. - -Run it directly: - - python3 -B deploy/test_install_shape.py - -or as the flake check the workflows run: `nix build .#checks..prod-shape`. -""" - -import contextlib -import io -import os -import shutil -import stat -import subprocess -import sys -import tarfile -import tempfile -import types -import unittest -from pathlib import Path -from unittest import mock - -HERE = Path(__file__).resolve().parent -sys.path.insert(0, str(HERE)) - -import install_shape # noqa: E402 (the path above is what makes this importable) - -COMPOSE = b"services:\n proxy:\n build: ./proxy\n" -DEFAULT_CONF = b"server { listen 8080; }\n" - - -def work_root() -> str: - """Where the harness writes. Not `/tmp` by default: it is a RAM-backed tmpfs - on this project's host, and a build there has taken a machine down.""" - root = os.environ.get("INSTALL_SHAPE_WORKDIR") - if not root: - root = os.path.join(os.path.dirname(HERE), ".tmp", "install-shape") - shutil.rmtree(root, ignore_errors=True) - os.makedirs(root, exist_ok=True) - return root - - -def archive(specs, format=tarfile.PAX_FORMAT) -> bytes: - """A tar stream of `(kind, name, payload)` specifications. - - `PAX_FORMAT` is what `git archive` writes, so the pseudo-header that carries a - long name is exercised rather than assumed away. - """ - buffer = io.BytesIO() - with tarfile.open(fileobj=buffer, mode="w:", format=format) as writing: - for kind, name, payload in specs: - info = tarfile.TarInfo(name) - if kind == "dir": - info.type = tarfile.DIRTYPE - info.mode = 0o755 - elif kind == "file": - info.type = tarfile.REGTYPE - info.mode = 0o644 - info.size = len(payload) - elif kind == "sym": - info.type = tarfile.SYMTYPE - info.linkname = payload.decode() - elif kind == "hard": - info.type = tarfile.LNKTYPE - info.linkname = payload.decode() - elif kind in ("chr", "blk"): - info.type = tarfile.CHRTYPE if kind == "chr" else tarfile.BLKTYPE - info.devmajor, info.devminor = 1, 3 - elif kind == "fifo": - info.type = tarfile.FIFOTYPE - else: - raise AssertionError(kind) - writing.addfile(info, io.BytesIO(payload) if kind == "file" else None) - return buffer.getvalue() - - -def tracked_shape() -> bytes: - """The tracked shape under the two names the runbook's archive writes.""" - specs = [("file", "compose.yaml", (HERE / "compose.yaml").read_bytes())] - for path in sorted((HERE / "proxy").rglob("*")): - relative = f"proxy/{path.relative_to(HERE / 'proxy')}" - if path.is_dir(): - specs.append(("dir", f"{relative}/", b"")) - else: - specs.append(("file", relative, path.read_bytes())) - return archive(specs) - - -def shape() -> bytes: - """A stream that is entirely in the set: the front's three files and a document.""" - return archive( - [ - ("file", "compose.yaml", COMPOSE), - ("dir", "proxy/", b""), - ("file", "proxy/Dockerfile", b"FROM nginx\n"), - ("dir", "proxy/conf.d/", b""), - ("file", "proxy/conf.d/default.conf", DEFAULT_CONF), - ] - ) - - -def conf_stream() -> bytes: - """The front's configuration alone, with no directory member to refuse first.""" - return archive( - [ - ("file", "compose.yaml", COMPOSE), - ("file", "proxy/conf.d/default.conf", DEFAULT_CONF), - ] - ) - - -def snapshot(root: Path) -> dict: - """Every path under `root`: its kind, its mode, its mtime and its bytes. - - The mtime is what makes "writes nothing" a claim a refusal and an - already-current install have to meet rather than describe: a rewrite of the - same bytes does not change the mode or the content, and would slip past a - snapshot that recorded only those. - """ - taken = {} - for path in sorted(root.rglob("*")): - info = path.lstat() - relative = str(path.relative_to(root)) - if stat.S_ISLNK(info.st_mode): - taken[relative] = ("link", os.readlink(path)) - elif stat.S_ISDIR(info.st_mode): - taken[relative] = ("dir", info.st_mode & 0o777, info.st_mtime_ns) - else: - taken[relative] = ("file", info.st_mode & 0o777, info.st_mtime_ns, path.read_bytes()) - return taken - - -class Box: - """A stand-in for `/srv/selvage`, and the one compose call the script makes.""" - - def __init__(self): - self.root = Path(tempfile.mkdtemp(prefix="box-", dir=work_root())) - self.srv = self.root / "srv" / "selvage" - self.srv.mkdir(parents=True) - self.outside = self.root / "outside" - self.outside.mkdir() - self.calls = [] - self.status = 0 - self.stdout = "" - self.stderr = "" - - def seed(self, name: str, text: str): - path = self.srv / name - path.parent.mkdir(parents=True, exist_ok=True) - path.write_text(text, encoding="utf-8") - return path - - def link(self, name: str, target) -> None: - (self.srv / name).symlink_to(target) - - def compose(self, argv): - self.calls.append(list(argv)) - return subprocess.CompletedProcess(list(argv), self.status, "", "") - - def run(self, stream: bytes, argv=("selvage-install-shape",), root=True, status=0, bound=None, compose=None): - self.status = status - patches = [ - mock.patch.multiple(install_shape, SRV=self.srv, LOCK=self.srv / ".update.lock"), - mock.patch.object(install_shape, "compose", compose or self.compose), - mock.patch("os.geteuid", return_value=0 if root else 1000), - ] - if bound is not None: - patches.append(mock.patch.object(install_shape, "MAX_STREAM_BYTES", bound)) - stdin = types.SimpleNamespace(buffer=io.BytesIO(stream)) - out, err = io.StringIO(), io.StringIO() - with contextlib.ExitStack() as stack: - for patch in patches: - stack.enter_context(patch) - stack.enter_context(mock.patch.object(sys, "stdin", stdin)) - stack.enter_context(contextlib.redirect_stdout(out)) - stack.enter_context(contextlib.redirect_stderr(err)) - code = install_shape.main(list(argv)) - self.stdout, self.stderr = out.getvalue(), err.getvalue() - return code - - -class RefusalTest(unittest.TestCase): - """Every one of these leaves the box byte for byte as it was.""" - - def setUp(self): - self.box = Box() - self.before = snapshot(self.box.srv) - - def assert_refused(self, stream: bytes, named: str, says: str | None = None, **options): - """`named` is the entry the refusal names; `says` is what it says it was.""" - code = self.box.run(stream, **options) - message = self.box.stdout + self.box.stderr - self.assertEqual(code, 1, message) - self.assertIn("refused:", self.box.stderr) - self.assertIn(named, self.box.stderr) - if says is not None: - self.assertIn(says, self.box.stderr) - self.assertEqual(snapshot(self.box.srv), self.before, "a refusal wrote to the box") - self.assertEqual(self.box.calls, [], "a refusal reached docker compose") - - def test_an_entry_outside_the_shape_is_refused(self): - for name in ("deploy/.env.example", ".env", ".env.example", "other.txt", "proxy", "compose.yml"): - with self.subTest(name=name): - stream = archive([("file", "compose.yaml", COMPOSE), ("file", name, b"x")]) - self.assert_refused(stream, name) - - def test_an_absolute_path_is_refused(self): - for name in ("/etc/passwd", "/srv/selvage/compose.yaml", "//etc/passwd"): - with self.subTest(name=name): - self.assert_refused(archive([("file", name, b"x")]), name) - - def test_a_parent_component_is_refused(self): - for name in ("proxy/../compose.yaml", "../compose.yaml", "proxy/conf.d/../../x", "./compose.yaml"): - with self.subTest(name=name): - self.assert_refused(archive([("file", "compose.yaml", COMPOSE), ("file", name, b"x")]), name) - - def test_a_symlink_member_is_refused(self): - stream = archive([("file", "compose.yaml", COMPOSE), ("sym", "proxy/nginx.conf", b"/etc/passwd")]) - self.assert_refused(stream, "proxy/nginx.conf", says="is a symbolic link") - - def test_a_hardlink_member_is_refused(self): - stream = archive( - [ - ("file", "compose.yaml", COMPOSE), - ("file", "proxy/nginx.conf", b"worker_processes 1;\n"), - ("hard", "proxy/other.conf", b"proxy/nginx.conf"), - ] - ) - self.assert_refused(stream, "proxy/other.conf", says="is a hard link") - - def test_a_device_member_is_refused(self): - for kind in ("chr", "blk"): - with self.subTest(kind=kind): - stream = archive([("file", "compose.yaml", COMPOSE), (kind, "proxy/zero", b"")]) - self.assert_refused(stream, "proxy/zero", says="is a device node") - - def test_a_fifo_member_is_refused(self): - stream = archive([("file", "compose.yaml", COMPOSE), ("fifo", "proxy/pipe", b"")]) - self.assert_refused(stream, "proxy/pipe", says="is a fifo") - - def test_an_empty_stream_is_refused(self): - self.assert_refused(b"", "the stream is empty") - - def test_a_tar_with_no_entries_is_refused(self): - self.assert_refused(archive([]), "carries no file") - - def test_a_stream_of_directories_alone_is_refused(self): - self.assert_refused(archive([("dir", "proxy/", b""), ("dir", "proxy/conf.d/", b"")]), "carries no file") - - def test_a_stream_that_is_not_a_tar_is_refused(self): - self.assert_refused(b"not a tar archive at all\n", "not a tar archive") - - def test_a_stream_longer_than_the_bound_is_refused(self): - body = b"x" * 2048 - self.assert_refused(body, "longer than 1024", bound=1024) - - def test_a_shape_file_that_has_become_a_link_is_refused(self): - target = self.box.outside / "elsewhere.yaml" - target.write_text("not the shape\n", encoding="utf-8") - self.box.link("compose.yaml", target) - self.before = snapshot(self.box.srv) - self.assert_refused(archive([("file", "compose.yaml", COMPOSE)]), "compose.yaml") - self.assertEqual(target.read_text(encoding="utf-8"), "not the shape\n") - - def test_a_leaf_where_a_directory_belongs_is_refused_with_nothing_written(self): - """Both entries are in the set; the second is refused before the first lands.""" - (self.box.srv / "proxy").mkdir() - (self.box.srv / "proxy" / "www").mkdir() - self.before = snapshot(self.box.srv) - stream = archive( - [ - ("file", "proxy/conf.d/default.conf", DEFAULT_CONF), - ("file", "proxy/www", b"x"), - ] - ) - self.assert_refused(stream, "proxy/www") - - def test_a_symlinked_directory_inside_the_target_is_refused(self): - """The shape the obvious guard misses: a *directory* that is a link. - - The stream names `proxy/conf.d/default.conf`, and `proxy` is a link out of - the box. A guard that checks names and then extracts would follow it. - """ - self.box.link("proxy", self.box.outside) - self.before = snapshot(self.box.srv) - outside_before = snapshot(self.box.outside) - self.assert_refused(conf_stream(), "proxy/conf.d/default.conf") - self.assertEqual(snapshot(self.box.outside), outside_before, "the link was followed") - self.assertEqual(sorted(p.name for p in self.box.outside.iterdir()), []) - - def test_a_link_that_leaves_the_target_at_a_deeper_step_is_refused(self): - (self.box.srv / "proxy").mkdir() - (self.box.outside / "conf.d").mkdir() - self.box.link("proxy/conf.d", self.box.outside / "conf.d") - self.before = snapshot(self.box.srv) - outside_before = snapshot(self.box.outside) - self.assert_refused(conf_stream(), "proxy/conf.d/default.conf") - self.assertEqual(snapshot(self.box.outside), outside_before) - - def test_a_directory_member_that_is_a_link_is_refused(self): - (self.box.srv / "proxy").mkdir() - (self.box.outside / "www").mkdir() - self.box.link("proxy/www", self.box.outside / "www") - self.before = snapshot(self.box.srv) - self.assert_refused(archive([("file", "compose.yaml", COMPOSE), ("dir", "proxy/www/", b"")]), "proxy/www") - - def test_arguments_are_refused(self): - for argv in (("selvage-install-shape", "--force"), ("selvage-install-shape", "/etc/passwd")): - with self.subTest(argv=argv): - self.assertEqual(self.box.run(shape(), argv=argv), 2) - self.assertEqual(snapshot(self.box.srv), self.before) - self.assertEqual(self.box.calls, []) - - def test_a_run_that_is_not_root_is_refused(self): - self.assertEqual(self.box.run(shape(), root=False), 2) - self.assertIn("must run as root", self.box.stderr) - self.assertEqual(snapshot(self.box.srv), self.before) - self.assertEqual(self.box.calls, []) - - -class InstallTest(unittest.TestCase): - def setUp(self): - self.box = Box() - - def test_the_shape_is_installed_and_the_front_brought_up(self): - self.box.seed(".env", "SELVAGED_IMAGE=ghcr.io/selvage-protocol/selvaged:0.5.1\n") - self.box.seed(".env.example", "# an example\n") - self.box.seed("tls/origin.key", "the certificate\n") - code = self.box.run(shape()) - self.assertEqual(code, 0, self.box.stderr) - - self.assertEqual((self.box.srv / "compose.yaml").read_bytes(), COMPOSE) - self.assertEqual((self.box.srv / "proxy" / "Dockerfile").read_bytes(), b"FROM nginx\n") - self.assertEqual((self.box.srv / "proxy" / "conf.d" / "default.conf").read_bytes(), DEFAULT_CONF) - for name in ("compose.yaml", "proxy/Dockerfile", "proxy/conf.d/default.conf"): - self.assertEqual((self.box.srv / name).stat().st_mode & 0o777, 0o644, name) - for name in ("proxy", "proxy/conf.d"): - self.assertEqual((self.box.srv / name).stat().st_mode & 0o777, 0o755, name) - - # The box's own files, and the files nothing here owns, are untouched. - self.assertEqual((self.box.srv / ".env").read_text(encoding="utf-8"), "SELVAGED_IMAGE=ghcr.io/selvage-protocol/selvaged:0.5.1\n") - self.assertEqual((self.box.srv / ".env.example").read_text(encoding="utf-8"), "# an example\n") - self.assertEqual((self.box.srv / "tls" / "origin.key").read_text(encoding="utf-8"), "the certificate\n") - - self.assertEqual(self.box.calls, [["docker", "compose", "up", "-d", "--build", "proxy"]]) - for name in ("compose.yaml", "proxy/Dockerfile", "proxy/conf.d/default.conf"): - self.assertIn(f"{self.box.srv}/{name}\n", self.box.stdout) - self.assertIn("left alone", self.box.stdout) - - def test_every_installed_file_is_owned_by_the_box_s_directory_owner(self): - owner = os.stat(self.box.srv) - self.box.run(shape()) - for name in ("compose.yaml", "proxy", "proxy/Dockerfile", "proxy/conf.d", "proxy/conf.d/default.conf"): - installed = os.stat(self.box.srv / name) - self.assertEqual((installed.st_uid, installed.st_gid), (owner.st_uid, owner.st_gid), name) - - def test_a_directory_the_stream_does_not_name_is_created_and_a_missing_one_is_kept(self): - self.box.seed("kept.txt", "not the shape's\n") - code = self.box.run(shape()) - self.assertEqual(code, 0, self.box.stderr) - self.assertEqual((self.box.srv / "kept.txt").read_text(encoding="utf-8"), "not the shape's\n") - self.assertEqual(sorted(p.name for p in self.box.srv.iterdir()), [".update.lock", "compose.yaml", "kept.txt", "proxy"]) - - def test_an_installed_shape_is_replaced_rather_than_merged(self): - self.box.seed("proxy/nginx.conf", "the old configuration\n") - self.box.seed("proxy/gone.conf", "a file nothing sends any more\n") - self.box.run(shape()) - self.assertEqual((self.box.srv / "proxy" / "nginx.conf").read_text(encoding="utf-8"), "the old configuration\n") - self.assertTrue((self.box.srv / "proxy" / "gone.conf").exists(), "the install must not delete what it does not send") - - def test_the_front_is_the_only_service_and_the_command_is_the_hand_command(self): - self.box.run(shape()) - self.assertEqual(self.box.calls, [["docker", "compose", "up", "-d", "--build", "proxy"]]) - for argv in (install_shape.UP_ARGV, install_shape.REBUILD_ARGV): - for argument in ("-f", "--project-directory", "--env-file"): - self.assertNotIn(argument, argv) - - def test_compose_runs_in_the_box_directory(self): - called = [] - with mock.patch("subprocess.run", lambda argv, **options: called.append((argv, options.get("cwd"))) or subprocess.CompletedProcess(argv, 0, "", "")): - install_shape.compose(install_shape.UP_ARGV) - self.assertEqual(called, [(install_shape.UP_ARGV, install_shape.SRV)]) - - def test_a_front_that_fails_to_build_is_a_non_zero_exit(self): - code = self.box.run(shape(), status=1) - self.assertEqual(code, 1) - self.assertIn("refused:", self.box.stderr) - self.assertIn("not rebuilt", self.box.stderr) - self.assertEqual((self.box.srv / "compose.yaml").read_bytes(), COMPOSE) - - def test_the_box_is_locked_while_it_installs(self): - import fcntl - - held = [] - - def composing(argv): - probe = open(self.box.srv / ".update.lock", "r") - try: - fcntl.flock(probe, fcntl.LOCK_EX | fcntl.LOCK_NB) - except BlockingIOError: - held.append(True) - else: - held.append(False) - finally: - probe.close() - return self.box.compose(argv) - - self.assertEqual(self.box.run(shape(), compose=composing), 0) - self.assertEqual(held, [True], "the install did not hold the update timer's lock") - - def test_the_tracked_shape_is_a_stream_this_installs(self): - """A file a release adds under `proxy/` must not need a change here.""" - code = self.box.run(tracked_shape()) - self.assertEqual(code, 0, self.box.stderr) - self.assertEqual((self.box.srv / "compose.yaml").read_bytes(), (HERE / "compose.yaml").read_bytes()) - for path in sorted((HERE / "proxy").rglob("*")): - if path.is_file(): - self.assertEqual((self.box.srv / "proxy" / path.relative_to(HERE / "proxy")).read_bytes(), path.read_bytes(), path) - -class IdempotenceTest(unittest.TestCase): - """A release installs the shape on every deploy, so the box must not be - restarted for a stream it already holds, and the two differences that can be - left are the two compose commands there are.""" - - def setUp(self): - self.box = Box() - self.assertEqual(self.box.run(shape()), 0, self.box.stderr) - self.box.calls = [] - - def test_a_stream_the_box_already_holds_writes_nothing_and_runs_nothing(self): - # By content, not by mtime: a file whose bytes are right is right however - # old it looks, and a reinstall that rewrote it would restart a live front. - os.utime(self.box.srv / "compose.yaml") - os.utime(self.box.srv / "proxy" / "conf.d" / "default.conf") - before = snapshot(self.box.srv) - self.assertEqual(self.box.run(shape()), 0, self.box.stderr) - self.assertEqual(snapshot(self.box.srv), before, "an already-current install wrote to the box") - self.assertEqual(self.box.calls, [], "an already-current install reached docker compose") - self.assertIn("nothing differs", self.box.stdout) - self.assertNotIn("=== installed ===", self.box.stdout) - - def test_a_compose_only_change_brings_the_services_up_without_a_build(self): - moved = COMPOSE + b" web:\n image: example\n" - stream = archive( - [ - ("file", "compose.yaml", moved), - ("dir", "proxy/", b""), - ("file", "proxy/Dockerfile", b"FROM nginx\n"), - ("dir", "proxy/conf.d/", b""), - ("file", "proxy/conf.d/default.conf", DEFAULT_CONF), - ] - ) - self.assertEqual(self.box.run(stream), 0, self.box.stderr) - self.assertEqual(self.box.calls, [["docker", "compose", "up", "-d"]]) - self.assertEqual((self.box.srv / "compose.yaml").read_bytes(), moved) - self.assertIn("compose.yaml", self.box.stdout) - self.assertIn("=== docker compose up -d ===", self.box.stdout) - - def test_a_proxy_change_rebuilds_the_front(self): - moved = b"server { listen 8080; listen 8081; }\n" - stream = archive( - [ - ("file", "compose.yaml", COMPOSE), - ("dir", "proxy/", b""), - ("file", "proxy/Dockerfile", b"FROM nginx\n"), - ("dir", "proxy/conf.d/", b""), - ("file", "proxy/conf.d/default.conf", moved), - ] - ) - self.assertEqual(self.box.run(stream), 0, self.box.stderr) - self.assertEqual(self.box.calls, [["docker", "compose", "up", "-d", "--build", "proxy"]]) - self.assertEqual((self.box.srv / "proxy" / "conf.d" / "default.conf").read_bytes(), moved) - self.assertIn("proxy/conf.d/default.conf", self.box.stdout) - self.assertIn("=== docker compose up -d --build proxy ===", self.box.stdout) - - def test_a_file_the_box_does_not_have_yet_is_a_rebuild(self): - stream = archive( - [ - ("file", "compose.yaml", COMPOSE), - ("file", "proxy/Dockerfile", b"FROM nginx\n"), - ("file", "proxy/www/404.html", b"

not found

\n"), - ] - ) - self.assertEqual(self.box.run(stream), 0, self.box.stderr) - self.assertEqual(self.box.calls, [["docker", "compose", "up", "-d", "--build", "proxy"]]) - self.assertEqual((self.box.srv / "proxy" / "www" / "404.html").read_bytes(), b"

not found

\n") - - -class SudoersTest(unittest.TestCase): - """The line that bounds the script, asserted rather than read by eye. - - The trailing `""` is the whole of the argument bound — without it sudo permits - *any* argument, because an empty argument list in sudoers means "any" rather - than "none" — and it is one keystroke from being dropped. - """ - - def test_the_one_command_is_named_with_no_argument_list(self): - lines = [ - line - for line in (HERE / "installci.sudoers").read_text(encoding="utf-8").splitlines() - if line and not line.startswith("#") - ] - self.assertEqual(lines, ['deployci ALL=(root) NOPASSWD: /usr/local/sbin/selvage-install-shape ""']) - - -class ParserTest(unittest.TestCase): - """The parts a stream is read with, called directly.""" - - def test_the_name_grammar_admits_a_component_and_refuses_everything_else(self): - admitted = ("compose.yaml", "proxy", "proxy/nginx.conf", "proxy/conf.d/default.conf", "proxy/www/a-b_c.html") - refused = ("", "/", "/compose.yaml", "proxy/", ".", "..", "proxy/.", "proxy/..", "proxy//x", "proxy/x/", " x", "proxy/ x", "-x/compose.yaml", "proxy/x\n", "proxy/\\x") - for name in admitted: - with self.subTest(name=name): - self.assertTrue(install_shape._NAME.match(name)) - for name in refused: - with self.subTest(name=name): - self.assertIsNone(install_shape._NAME.match(name)) - - def test_the_set_is_compose_yaml_and_everything_under_proxy(self): - self.assertTrue(install_shape._in_shape("compose.yaml", False)) - self.assertTrue(install_shape._in_shape("proxy/anything/at/all", False)) - self.assertFalse(install_shape._in_shape("compose.yaml", True)) - self.assertFalse(install_shape._in_shape("compose.yaml/x", False)) - self.assertFalse(install_shape._in_shape("proxytail/x", False)) - self.assertFalse(install_shape._in_shape("deploy/proxy/x", False)) - self.assertFalse(install_shape._in_shape(".env.example", False)) - self.assertTrue(install_shape._in_shape("proxy", True)) - self.assertFalse(install_shape._in_shape("proxy", False)) - - def test_a_duplicated_entry_is_refused(self): - stream = archive([("file", "compose.yaml", COMPOSE), ("file", "compose.yaml", COMPOSE)]) - with self.assertRaisesRegex(install_shape.Refused, "appears twice"): - install_shape.read_stream(stream) - - def test_the_same_directory_twice_is_one_directory(self): - stream = archive([("dir", "proxy/", b""), ("dir", "proxy", b""), ("file", "proxy/nginx.conf", b"x\n")]) - names = [entry.name for entry in install_shape.read_stream(stream)] - self.assertEqual(names, ["proxy", "proxy/nginx.conf"]) - - def test_a_pax_named_entry_and_a_gnu_named_entry_are_read(self): - long_name = "proxy/www/" + "a" * 150 + ".html" - for format in (tarfile.PAX_FORMAT, tarfile.GNU_FORMAT): - with self.subTest(format=format): - stream = archive([("file", long_name, b"x")], format=format) - self.assertEqual([entry.name for entry in install_shape.read_stream(stream)], [long_name]) - - def test_a_name_that_is_longer_than_the_bounded_read_is_still_read(self): - """The bound is on the stream, not on one member's name.""" - served = archive([("file", "compose.yaml", b"x" * 200)]) - entries = install_shape.read_stream(served) - self.assertEqual(len(entries), 1) - self.assertEqual(entries[0].content, b"x" * 200) - - -if __name__ == "__main__": - unittest.main(verbosity=2) diff --git a/docs/deploying.md b/docs/deploying.md index 4eaffe9..e206375 100644 --- a/docs/deploying.md +++ b/docs/deploying.md @@ -34,11 +34,10 @@ the deployer's to supply; put a TLS terminator in front (`tailscale serve`, caddy, or your edge) and hand out the `https://` or `wss://` URL. There is no TLS inside `selvaged`, and none is claimed. -## The published image and the tracked shape +## The published image and the self-host shape The image is built multi-arch, so an arm64 host pulls the same tag as an amd64 -one, and it carries the server alone. The public demo is a tracked shape of its -own in [`deploy/`](../deploy): a compose file, a proxy and an update timer. +one, and it carries the server alone. [`compose.yaml`](../compose.yaml) at the root is the self-host shape, and `docker compose up` runs the server beside the published page image, both read-only with every capability dropped. diff --git a/docs/operating-the-demo.md b/docs/operating-the-demo.md deleted file mode 100644 index 50e3986..0000000 --- a/docs/operating-the-demo.md +++ /dev/null @@ -1,166 +0,0 @@ -# Operating the public demo - -The demo at runs the tracked -[`deploy/`](../deploy) shape. For general self-hosting and TLS requirements, see -[Deploying](deploying.md); for page-serving privacy requirements, see -[Serving the page](serving-the-page.md). This guide describes the operational -contract, not a live host inventory. Read image versions, digests, credentials, -firewall rules, and installed files from their authoritative systems. - -## Installation and privilege boundary - -The Compose project is `selvage-prod`, rooted at `/srv/selvage`. It contains the -TLS front, `selvaged`, and the separate page image. Only the front publishes a -port. The proxy configuration is baked into its locally built image; a proxy -change requires a rebuild, not just a restart. - -Initial provisioning is an administrator's operation, not a CI deploy: - -1. Provision Docker Compose, the host's firewall, TLS origin certificate, and - Tailscale SSH access. Restrict origin ingress to the intended edge. Refresh - the firewall's Cloudflare ranges together with - [`cloudflare-ips.conf`](../deploy/proxy/conf.d/cloudflare-ips.conf). -2. Install `deploy/compose.yaml` and `deploy/proxy/` from a reviewed commit into - `/srv/selvage`. Copy `deploy/.env.example` to `.env` once, edit it for this - instance, and make `.env` mode `0600`; never overwrite it during an upgrade. -3. Install the origin certificate in `tls/origin.pem` (`root:root`, `0644`) and - key in `tls/origin.key` (`root:101`, `0640`), inside `tls/` (`root:root`, - `0750`). Certificates and keys are instance material, not repository files. -4. Install `deploy/selvage-update.service` and `deploy/selvage-update.timer` in - `/etc/systemd/system/`, then run `systemctl daemon-reload`. Bring the shape - up from `/srv/selvage` with `docker compose up -d --build proxy`; enable the - timer only after checking the configured images and origin responses. -5. Create the unprivileged `deployci` account. Install `deploy/deploy.py` as - `/usr/local/sbin/selvage-deploy` and `deploy/install_shape.py` as - `/usr/local/sbin/selvage-install-shape`, both `root:root`, `0755`. Validate - the corresponding `deployci.sudoers` and `installci.sudoers` with `visudo -c` - before installing them in `/etc/sudoers.d/` as `root:root`, `0440`. - -The two sudoers commands must retain the trailing `""`: it permits **no -arguments**. Omitting that argument constraint permits arbitrary arguments. -Read the result with `sudo -l -U deployci`. Do not grant CI Docker-group -membership, blanket sudo, or permission to replace these scripts or sudoers -files. Changing either privileged program, the systemd units, `.env` settings -other than image references, or TLS material remains administrator work. - -The image deployer accepts only tags of the two allowed GHCR images on stdin. -The shape installer accepts only `compose.yaml` and `proxy/` from a tar stream; -it rejects traversal, absolute paths, links, and special files. Shape access is -still powerful: a reviewed Compose file controls mounts, ports, and capabilities. -The installer does not delete obsolete proxy files; removed files need an -administrator's cleanup before rebuilding the front. - -Instance-specific `compose.override.yaml` and notice files are not installed by -CI. A notice mounted into the front must survive shape upgrades. In particular, -nginx `sub_filter` directives at a more specific location replace the inherited -list rather than appending to it; `nginx -t` alone cannot prove a notice renders. - -## CI access - -[deploy-prod.yml](../.github/workflows/deploy-prod.yml) is dispatched at `main`. -It has **no environment approval gate**. Tailscale workload identity federation -matches the GitHub OIDC subject exactly: - -```text -repo:selvage-protocol@328844633/reference_server@1368869493:ref:refs/heads/main -``` - -The numeric IDs are part of the organization's immutable subject form. Adding -an `environment:` to this job changes the subject and breaks the exchange. -Repository secrets `TS_OAUTH_CLIENT_ID` and `TS_AUDIENCE` name the credential -pair; their values belong in the credential console and GitHub, not this guide. -The ephemeral runner receives `tag:ci`. Tailnet policy must restrict it to SSH on -`tag:selvaged-prod`, with the SSH rule permitting only `deployci`. Tailscale SSH -cannot constrain the command: the host's two argument-free sudo rules are the -command boundary. Tailnet Lock requires a separate authentication design if -enabled; do not silently replace federation with a broad reusable key. - -To rotate the pair, create a replacement identity with the same constrained -subject, update both repository secrets, verify a deploy, then remove the old -identity. An exchange refusal needs the actual claims and credential inspected: -a missing identity and a rejected subject are different failures. Never loosen -the subject or host privileges to make a retry pass. - -## Deploy and verify - -From any checkout, explicitly name this repository: - -```sh -gh workflow run deploy-prod.yml -R selvage-protocol/reference_server --ref main \ - -f server_version= -gh workflow run deploy-prod.yml -R selvage-protocol/reference_server --ref main \ - -f server_version= -f install_shape=true -``` - -An empty image input leaves that line unchanged; `latest` unpins it. The server -release changes its own `SELVAGED_IMAGE` line. The page repository normally -changes `SELVAGE_WEB_IMAGE` independently. The deploy accepts tags, not digests: -a version tag is a deliberate pin but is still mutable by a registry writer. - -With `install_shape=true`, CI streams the tracked pair from the run's `main` -ref, installs it under the update lock, and reads installed file hashes back. -Matching files are a no-op; a Compose-only change runs `up -d`; a proxy change -rebuilds the front. To install the same reviewed shape by hand from this repo: - -```sh -git archive --format=tar :deploy compose.yaml proxy \ - | ssh deployci@selvage-protocol-prod \ - '/usr/bin/sudo /usr/local/sbin/selvage-install-shape' -``` - -The image deploy holds `/srv/selvage/.update.lock`, stages `.env.deploy`, and -writes `.env` only after convergence, keeping `.env.prev`. A failed deploy can -already have changed running containers even though `.env` is unchanged; inspect -both, then reconcile with the intended references. A healthy origin is asserted -through the front over SSH: `/meta` must report the requested server version -when one was specified, and `/` must answer successfully. Read current state: - -```sh -ssh selvage@selvage-protocol-prod 'cd /srv/selvage && docker compose ps && docker compose images' -ssh selvage@selvage-protocol-prod \ - "curl -sk -H 'Host: selvage-demo.dontblameme.dev' https://127.0.0.1/meta" -``` - -The public edge may challenge a datacenter client. Verification reports a -challenge or unreadable public response; it does not bypass bot controls or -claim that the public path passed. A readable public version different from the -requested version fails the deploy. `latest` has no expected version to compare. -A page answering 200 is **not proof of its build identity**. Neither these reads -nor local proxy tests verify the separately hosted site's deployed response -headers or their limits. Read those from the deployed response before claiming -them. Automated checks do not establish human acceptance. - -## Timer, recovery, and downtime - -The update timer pulls configured tags every five minutes under the same lock. -A line left at `latest` follows registry updates without another approval. -Inspect with `systemctl list-timers selvage-update.timer` and -`journalctl -u selvage-update.service -n 50`. - -For manual operations, run Compose as the instance operator in `/srv/selvage`, -without a `-f` override, so it reads the same `.env` and optional override as the -timer. **Stop the timer before stopping services** or its next tick undoes the -stop. To keep it stopped across boots, disable it as well. - -```sh -sudo systemctl stop selvage-update.timer -cd /srv/selvage -docker compose down -# Restore the reviewed shape and intended image references before restarting. -docker compose pull --ignore-buildable -docker compose up -d --build proxy -sudo systemctl start selvage-update.timer -``` - -Rollback is an explicit pin to a known previous image tag followed by pull and -up. After a successful deploy, `.env.prev` is the previous environment; inspect -it before copying it back. Restore older proxy files from a reviewed commit and -rebuild for a front rollback. These are recovery procedures, not a claim that a -live rollback has been exercised. - -Replacing `selvaged` ends every room: all state is in memory, with no drain or -restart reclaim. A front replacement drops WebSockets and requires clients to -reconnect; it does not itself restore lost server state. Coordinate disruptive -changes with users rather than treating a green deploy as a seamless upgrade. - -The repository's [publishing guide](publishing.md) covers release/image recovery. diff --git a/docs/publishing.md b/docs/publishing.md index 2ce5344..f146420 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -37,16 +37,7 @@ environment is configured in that workflow. Tags are `-`, dispatches the image workflow because a tag push using `GITHUB_TOKEN` does not start it automatically. -## Deployment and recovery - -After the image becomes available, release dispatches `deploy-prod.yml` at -`main` for its own server version. It sets `install_shape=true` when `deploy/` -changed, waits for the resulting deploy run, and fails unless that run succeeds. -A published tag or image can therefore remain after a red release. A green run -means the deploy's assertions passed, not that human acceptance or a live -rollback was performed. The host privilege boundary, credentials by name, -verification limits, and rollback procedure are in -[Operating the demo](operating-the-demo.md). +## Recovery Recover the failed stage rather than dispatching a new bump blindly: @@ -59,18 +50,14 @@ Recover the failed stage rather than dispatching a new bump blindly: The image workflow reasserts tag/manifest agreement. Do not move the tag to include a packaging fix; fix forward with a new version instead. -- **Image exists, demo deploy failed:** inspect the deploy's origin/read-back - failure, then retry the bounded deploy at `main` with the intended version - and shape input. Another release dispatch would compute a new version. - **Image exists, GitHub Release missing:** the image workflow creates the - GitHub Release in a separate job; the image and even the deployed demo can - exist while that job is red. Inspect its failure, then rerun `image.yml` at + GitHub Release in a separate job; the image can exist while that job is red. Inspect its failure, then rerun `image.yml` at the existing `v` tag as above to create the missing release. Do not dispatch another version bump merely to recover the release record. - **Atomic push refused:** reconcile with current `main` and tags before planning again. Do not force the old candidate over concurrent work. -Verify the artifact and deployed version, not just a tag's existence: +Verify the artifact, not just a tag's existence: ```sh gh release view 'v' -R selvage-protocol/reference_server --json tagName,assets @@ -80,4 +67,4 @@ docker run --rm ghcr.io/selvage-protocol/selvaged: --version Inspect the published multi-platform manifest and its per-platform layers when checking architecture claims. A two-platform manifest alone does not prove the binaries inside differ. The image workflow's smoke and layer checks cover that -artifact contract; origin `/meta` checks cover the running server version. +artifact contract. diff --git a/flake.nix b/flake.nix index ae02c71..4274320 100644 --- a/flake.nix +++ b/flake.nix @@ -246,66 +246,6 @@ inherit src; }; - # The guard around `deploy/deploy.py`, which is the whole of the - # public demo's privilege model: `/usr/local/sbin/selvage-deploy` is the - # only root command the CI user on that box may run. Nothing else in this - # repository can see what its request grammar refuses, or that the compose - # file and the update unit agree with it. - prod-deploy = - pkgs.runCommand "prod-deploy-test" { - nativeBuildInputs = [pkgs.python3]; - } '' - cd ${./deploy} - python3 -B test_deploy.py - touch $out - ''; - - # The guard around `deploy/install_shape.py`, the second root command - # the CI user on that box may run: the box's shape — `compose.yaml` and - # `proxy/` — arrives as a tar stream on stdin, and every other name, - # absolute or traversing path, link, device and fifo is refused with the - # box untouched. Nothing else in this repository can see what it refuses, - # or that a step is resolved inside the descriptor the step before it - # found rather than checked and then used. - prod-shape = - pkgs.runCommand "prod-shape-test" { - nativeBuildInputs = [pkgs.python3]; - } '' - cd ${./deploy} - INSTALL_SHAPE_WORKDIR="''${TMPDIR:-/build}/install-shape" python3 -B test_install_shape.py - touch $out - ''; - - # The public demo's front, under its real configuration and a real nginx: - # whether a source is refused at all, whether one metered endpoint can - # spend another's budget, whether a missing path is answered with this - # instance's own not-found page, and whether a request naming another - # host is closed rather than served. All four are questions about a - # running proxy, and the second is the reason the front's zones are one - # per location; nothing else in this repository can see any of them. - prod-front = - pkgs.runCommand "prod-front-test" { - nativeBuildInputs = [pkgs.python3 pkgs.nginx pkgs.curl]; - } '' - cd ${./deploy} - FRONT_LIMITS_WORKDIR="''${TMPDIR:-/build}/front-limits" python3 -B test_front_limits.py - CHECK_FRONT_WORKDIR="''${TMPDIR:-/build}/check-front" bash check-front.sh - touch $out - ''; - - # The command lines the tracked compose shapes give the server, run - # against the binary that runs them: a value it refuses is a container - # that exits 2 and restart-loops, which takes the front beside it down - # with it. - deploy-args = - pkgs.runCommand "deploy-args-test" { - nativeBuildInputs = [pkgs.python3 package]; - } '' - cd ${./deploy} - python3 -B test_compose_args.py - touch $out - ''; - # The guard around `scripts/bump-version.sh`, the command this # repository's release workflow runs before it commits a version: a bump # word in, the next version on the last line of stdout, and the two files @@ -322,36 +262,6 @@ touch $out ''; - # The deploy workflow's verification: what it asserts (the origin, - # read on the box through the front over the SSH path the deploy itself - # used) and what it only reports (the public URL, behind an edge that - # serves a managed challenge to a programmatic client on a datacenter - # address). The first is the half that has to fail when the box serves - # the wrong version; nothing else in this repository can see either. - deploy-verify = - pkgs.runCommand "deploy-verify-test" { - nativeBuildInputs = [pkgs.python3]; - } '' - cd ${./scripts} - python3 -B test_verify_deploy.py - touch $out - ''; - - # The watcher the release's last step runs (`scripts/wait_for_deploy.py`): - # `gh workflow run` prints no run id, so the run to wait on is the newest - # one of the workflow that is not the newest seen before the dispatch, and - # the release fails unless that run concludes `success`. The suite drives - # the poll loops with injected reads and runs the `gh`-facing edges against - # a stand-in on `PATH`, so it needs no network, no token and no real run. - deploy-wait = - pkgs.runCommand "deploy-wait-test" { - nativeBuildInputs = [pkgs.python3]; - } '' - cd ${./scripts} - python3 -B test_wait_for_deploy.py - touch $out - ''; - # Exercise plan, retry and exact remote tag checks without publishing. release-retry = pkgs.runCommand "release-retry-test" { diff --git a/lychee.toml b/lychee.toml index 6730ac5..be6d649 100644 --- a/lychee.toml +++ b/lychee.toml @@ -1,6 +1,5 @@ -# `exclude` is the addresses lychee cannot read as live links from here. The ones -# that belong to a deployment say what they answer where that deployment runs; -# none of them is a broken link. +# `exclude` is the addresses lychee cannot read as live links from here. Loopback and test +# placeholders answer only on a machine running a proof, so none of them is a broken link. # # The gate over the reader-facing front matter, `scripts/ci-local.sh links` and the # `links` step of the workflow's `checks` job, runs this over `README.md` and @@ -9,27 +8,15 @@ # staged text file instead and reads this same configuration, which is why the # entries below stay even though the gate's two directories carry none of them. # -# `root_dir` is what lets a root-relative link be checked at all: without one, -# lychee refuses to resolve `/...` out of a file on disk rather than trying. The -# not-found page's way back to the demo is exactly that link — same-origin by -# design, so it must not name the origin — and against this checkout it resolves -# to the repository root, which is here. That the link is served when the front -# answers a missing path is `deploy/check-front.sh`'s assertion, which fetches -# the page. +# `root_dir` is what lets a root-relative link be checked at all: without one, lychee +# refuses to resolve `/...` out of a file on disk rather than trying. root_dir = "." exclude = [ "https://fsf.org/", # The runner expands this workflow template before fetching the release asset. '^[h]ttps://github[.]com/lycheeverse/lychee/releases/download/lychee-v[$]([{]|%7[Bb])LYCHEE_VERSION', - # The public demo's front proxying to its sibling containers by their Compose - # service names (`deploy/`). Those names resolve only inside that - # deployment's own network. - "http://selvaged:8080", - "http://selvage-web:8080", # Loopback is an address on whichever machine is running the proof — the image - # smoke's own server on 18080 (`scripts/image-smoke.sh`), the front's limits - # harness, and the deploy workflow's `https://127.0.0.1/meta` read on the public - # demo's box. It answers only while that is running, and it is never a link + # smoke's own server on 18080 (`scripts/image-smoke.sh`) — and it is never a link # anything can check from a checkout. "^https?://127\\.0\\.0\\.1[:/]", # `h` is the placeholder host a client test builds its links from @@ -37,10 +24,8 @@ exclude = [ # browser speaks. No such host exists to answer, and `ws://` is already # unsupported rather than checked. "^https?://h[:/]", - # The demo's own address is `127.0.0.1` and a port the script was given: the - # `demo.sh` and `record.sh` lines that carry it are read as a link by the hook, - # which is handed every staged text file, and there is nothing for lychee to - # fetch in a `$port`. + # The hook is handed every staged text file, and scripts carry loopback addresses + # with a port the script was given, which has nothing for lychee to fetch in a `$port`. "^wss?://127\\.0\\.0\\.1[:/]", ] # `vectors/` is vendored test data, not this repository's prose: the specification diff --git a/scripts/ci-local.sh b/scripts/ci-local.sh index 20c5788..07cf9ab 100755 --- a/scripts/ci-local.sh +++ b/scripts/ci-local.sh @@ -3,11 +3,8 @@ # Runs the steps of .github/workflows/ci.yml on this machine, without containers (this host # has no Docker or Podman, so `act` cannot run here). # -# scripts/ci-local.sh checks # the `checks` job: format, clippy, tests, the package, licences, eval, the public -# # demo's deploy guard, front and command line, the version -# # bump, the deploy workflow's verification, -# # the release's wait for its deploy, the release workflow's -# # dry_run gating, lint, typos, links +# scripts/ci-local.sh checks # the `checks` job: format, clippy, tests, the package, licences, eval, +# # the version bump, the release's dry_run gating, lint, typos, links # scripts/ci-local.sh nightly # coverage, the rest of cargo-deny and cargo-audit (slow) # scripts/ci-local.sh lint # actionlint over the workflow files, on its own # scripts/ci-local.sh links # lychee over the README and the docs tree @@ -80,44 +77,11 @@ job_checks() { nix develop . -c cargo deny check licenses say "checks: evaluate every check" nix flake check --no-build . - # The guard around the public demo's deploy script, which is the whole of that - # box's privilege model: one request grammar, and a shape the deploy verifies - # rather than writes. - say "checks: the public demo's deploy guard" - nix build .#checks.x86_64-linux.prod-deploy --no-link --print-build-logs - # The other root command the CI user on that box may run: the box's shape — - # `compose.yaml` and `proxy/` — arrives as a tar stream, and every other name, - # link, device and traversing path is refused with the box untouched. - say "checks: the public demo's shape installer" - nix build .#checks.x86_64-linux.prod-shape --no-link --print-build-logs - # The public demo's front under a real nginx, in both halves: that a source is - # refused and that one metered endpoint cannot spend another's budget - # (`test_front_limits.py`), and that a missing path is answered with this - # instance's own not-found page and a request naming another host is closed - # (`check-front.sh`). Every one is about a running proxy, so none can be read - # out of the configuration. - say "checks: the public demo's front" - nix build .#checks.x86_64-linux.prod-front --no-link --print-build-logs - # The command lines the tracked compose shapes give the server, run against the - # binary: a value it refuses is a container that exits 2 and restart-loops. - say "checks: the deployed command line" - nix build .#checks.x86_64-linux.deploy-args --no-link --print-build-logs # The version bump this repository's release workflow runs before it commits: # the next version from a bump word, on the last line of stdout, and nothing # written for a word or a manifest it cannot compute from. say "checks: the version bump" nix build .#checks.x86_64-linux.bump-version --no-link --print-build-logs - # The deploy workflow's verification: what it asserts (the origin, on the box - # through the front) and what it only reports (the public URL, behind an edge - # that answers a datacenter client with a challenge). - say "checks: the deploy workflow's verification" - nix build .#checks.x86_64-linux.deploy-verify --no-link --print-build-logs - # The watcher the release's last step runs: `gh workflow run` prints no run id, - # so the run to wait on is the newest one not seen before the dispatch, and the - # release fails unless it concludes `success`. The suite drives the polls with - # injected reads and a stand-in `gh` on `PATH`. - say "checks: the release waits for its deploy" - nix build .#checks.x86_64-linux.deploy-wait --no-link --print-build-logs # The guard around a workflow's `dry_run` input: a plan step prints what a real # run would do, and every step after it has to be excluded from a dry run. # `actionlint` lints those workflows clean, so this reads the workflows back and refuses diff --git a/scripts/release-tags.sh b/scripts/release-tags.sh index 2e6bc69..a04e64a 100755 --- a/scripts/release-tags.sh +++ b/scripts/release-tags.sh @@ -13,8 +13,7 @@ # there — the tag run is where that rule is enforced. # # `latest=false` for a prerelease, a version with a `-` suffix (`1.0.0-rc.1`): -# the public demo follows `latest` without an approval, so only a release moves -# it. +# only a release moves it. set -euo pipefail ref="${1:-}" diff --git a/scripts/test_verify_deploy.py b/scripts/test_verify_deploy.py deleted file mode 100644 index addc3ea..0000000 --- a/scripts/test_verify_deploy.py +++ /dev/null @@ -1,432 +0,0 @@ -"""What `verify_deploy.py` asserts, and what it only reports. - -The two reads it separates cost a session to tell apart, so both are pinned here. - -* The **origin**, read on the box through the front, is the assertion: a version - that is not the one asked for, or a page that stops answering, fails the run and - says what it saw. -* The **public** read is three shapes, and only one of them decides the run. A - challenge, an unreadable read and any other answer that is not a version are - reports, exit 0; a 200 that parses to a version other than the one this deploy - named is red, because in that scenario the origin is right and the edge is - serving something else. The classifier is fed the response Cloudflare really sent - — recorded from a runner — and the attempt is asserted to end on the first - challenge rather than polling a deadline it cannot pass. - -The poll loops are driven with real, tiny deadlines and injected reads, and the -one test that has to see several iterations stops its own loop from the fake read -rather than racing the wall clock; the two subprocess halves are driven against -stubs on `PATH`, which is where a mistake in an argument would otherwise only show -up on a runner. - -Run it directly: - - python3 scripts/test_verify_deploy.py -""" - -import io -import os -import subprocess -import sys -import tempfile -import unittest -from contextlib import redirect_stderr, redirect_stdout -from pathlib import Path -from unittest import mock - -sys.path.insert(0, str(Path(__file__).resolve().parent)) - -import verify_deploy as verify # noqa: E402 (the path above is what makes this importable) - -# The refusal Cloudflare serves a programmatic client on a datacenter address, -# as recorded from the box and from a GitHub runner. The read keeps the headers -# and the body, which is what makes this shape visible at all. -CHALLENGE_HEADERS = ( - "HTTP/2 403 \r\n" - "date: Tue, 22 Sep 2026 06:21:30 GMT\r\n" - "content-type: text/html; charset=UTF-8\r\n" - "cf-mitigated: challenge\r\n" - "server: cloudflare\r\n" - "content-length: 5177\r\n" -) -CHALLENGE_BODY = ( - "Just a moment..." -) - - -class Enough(Exception): - """Stops a poll loop from a fake read, so a test never waits on the clock.""" - - -def meta(version): - return '{"capabilities":["awareness"],"server":"selvaged/%s","wire_versions":["selvage/2"]}' % version - - -def public(status, body, headers="HTTP/2 200 \r\nserver: cloudflare\r\n"): - return verify.Public(status=status, headers=headers, body=body) - - -def origin(page="200", version="0.2.1", error=""): - return verify.Origin(page=page, meta=meta(version) if version else "", error=error) - - -class TheChallengeTest(unittest.TestCase): - - def test_the_recorded_challenge_is_a_challenge(self): - verdict, detail = verify.classify_public(public("403", CHALLENGE_BODY, CHALLENGE_HEADERS), "0.2.1") - self.assertEqual(verdict, verify.CHALLENGE) - self.assertIn("cf-mitigated: challenge", detail) - self.assertIn("403", detail) - - def test_a_challenge_without_the_header_is_still_a_challenge(self): - verdict, detail = verify.classify_public( - public("403", CHALLENGE_BODY, "HTTP/2 403 \r\nserver: cloudflare\r\n"), "0.2.1" - ) - self.assertEqual(verdict, verify.CHALLENGE) - self.assertIn("interstitial", detail) - - def test_the_challenge_ends_the_attempt_rather_than_burning_the_deadline(self): - calls = [] - - def read(): - calls.append(1) - return public("403", CHALLENGE_BODY, CHALLENGE_HEADERS) - - verdict, _ = verify.wait_for_public(read, "0.2.1", deadline=180.0, interval=5.0) - self.assertEqual(verdict, verify.CHALLENGE) - self.assertEqual(len(calls), 1, "a challenge is an answer, not a reason to keep polling") - - def test_a_challenge_after_a_retry_still_ends_them(self): - reads = [public("502", "bad gateway", ""), public("403", CHALLENGE_BODY, CHALLENGE_HEADERS)] - calls = [] - - def read(): - calls.append(1) - return reads[len(calls) - 1] - - verdict, _ = verify.wait_for_public(read, "0.2.1", deadline=60.0, interval=0.01) - self.assertEqual(verdict, verify.CHALLENGE) - self.assertEqual(len(calls), 2) - - -class ThePublicReadTest(unittest.TestCase): - def test_a_read_that_gets_through_is_reported(self): - verdict, detail = verify.classify_public(public("200", meta("0.2.1")), "0.2.1") - self.assertEqual((verdict, detail), (verify.REPORTED, "selvaged/0.2.1")) - - def test_another_version_is_a_mismatch(self): - verdict, detail = verify.classify_public(public("200", meta("0.2.0")), "0.2.1") - self.assertEqual(verdict, verify.MISMATCH) - self.assertEqual(detail, "selvaged/0.2.0") - - def test_a_mismatch_is_retried_to_the_deadline_before_it_is_reported(self): - calls = [] - - def read(): - calls.append(1) - if len(calls) == 3: - raise Enough - return public("200", meta("0.2.0")) - - with self.assertRaises(Enough): - verify.wait_for_public(read, "0.2.1", deadline=60.0, interval=0.01) - self.assertEqual(len(calls), 3, "a mismatch is worth retrying; only a challenge is not") - - def test_an_edge_that_never_answers_ends_at_the_deadline_with_what_it_said(self): - calls = [] - - def read(): - calls.append(1) - return public("502", "bad gateway", "") - - verdict, detail = verify.wait_for_public(read, "0.2.1", deadline=0.05, interval=0.01) - self.assertEqual(verdict, verify.UNREADABLE) - self.assertIn("502", detail) - self.assertGreaterEqual(len(calls), 1) - - def test_the_read_retries_before_it_reports(self): - calls = [] - - def read(): - calls.append(1) - if len(calls) == 3: - raise Enough - return public("502", "bad gateway", "") - - with self.assertRaises(Enough): - verify.wait_for_public(read, "0.2.1", deadline=60.0, interval=0.01) - self.assertEqual(len(calls), 3, "a 502 is worth retrying; only a challenge is not") - - def test_a_read_that_never_arrives_is_unreadable_not_a_failure(self): - unreadable = verify.Public("", "", "", "curl exited 6: Could not resolve host") - verdict, detail = verify.wait_for_public(lambda: unreadable, "0.2.1", 0.03, 0.01) - self.assertEqual(verdict, verify.UNREADABLE) - self.assertIn("Could not resolve host", detail) - - def test_a_page_only_deploy_reads_the_public_version_without_comparing_it(self): - verdict, detail = verify.classify_public(public("200", meta("0.1.0")), None) - self.assertEqual((verdict, detail), (verify.REPORTED, "selvaged/0.1.0")) - - def test_a_200_without_a_server_field_is_a_report(self): - verdict, detail = verify.classify_public(public("200", "nope"), "0.2.1") - self.assertEqual(verdict, verify.UNREADABLE) - self.assertIn("no server field", detail) - - -class TheOriginTest(unittest.TestCase): - def test_the_origin_must_serve_the_version_it_was_asked_for(self): - with self.assertRaises(verify.OriginAssertion) as raised: - verify.wait_for_origin(lambda: origin(version="0.2.0"), "0.2.1", 0.05, 0.01) - message = str(raised.exception) - self.assertIn("/meta reports selvaged/0.2.0", message) - self.assertIn("the page answered 200", message) - - def test_it_recovers_when_the_origin_converges(self): - readings = [origin(version="0.2.0"), origin(version="0.2.0"), origin(version="0.2.1")] - calls = [] - - def read(): - calls.append(1) - return readings[min(len(calls), len(readings)) - 1] - - result = verify.wait_for_origin(read, "0.2.1", deadline=5.0, interval=0.01) - self.assertEqual(verify.json_server(result.meta), "selvaged/0.2.1") - self.assertEqual(len(calls), 3) - - def test_a_page_that_is_not_200_fails_the_run(self): - with self.assertRaises(verify.OriginAssertion) as raised: - verify.wait_for_origin(lambda: origin(page="502"), "0.2.1", 0.03, 0.01) - self.assertIn("the page answered 502", str(raised.exception)) - - def test_an_ssh_that_never_answers_fails_the_run(self): - unreachable = verify.Origin("", "", "ssh to deployci@box exited 255: no route") - with self.assertRaises(verify.OriginAssertion) as raised: - verify.wait_for_origin(lambda: unreachable, "0.2.1", 0.03, 0.01) - self.assertIn("exited 255", str(raised.exception)) - - def test_a_web_only_deploy_reads_the_origin_version_without_comparing_it(self): - reading = verify.wait_for_origin(lambda: origin(version="0.1.0"), None, 0.03, 0.01) - self.assertEqual(verify.json_server(reading.meta), "selvaged/0.1.0") - - def test_meta_without_a_server_field_is_not_a_read(self): - with self.assertRaises(verify.OriginAssertion) as raised: - verify.wait_for_origin( - lambda: verify.Origin("200", "nope"), "0.2.1", 0.03, 0.01 - ) - self.assertIn("no server field", str(raised.exception)) - - -class TheEndingTest(unittest.TestCase): - """`main`'s endings: the origin decides the colour, and so does a readable mismatch.""" - - def run_main(self, origin_read, public_read, expect="0.2.1"): - argv = ["--origin-deadline", "0.05", "--public-deadline", "0.05", "--poll-interval", "0.01"] - if expect is not None: - argv += ["--expect-version", expect] - with mock.patch.object(verify, "read_origin", origin_read), mock.patch.object( - verify, "read_public", public_read - ): - out, err = io.StringIO(), io.StringIO() - with redirect_stdout(out), redirect_stderr(err): - code = verify.main(argv) - return code, out.getvalue(), err.getvalue() - - def test_a_challenged_public_read_leaves_a_healthy_deploy_green(self): - code, out, err = self.run_main( - lambda *a: origin(version="0.2.1"), - lambda *a: public("403", CHALLENGE_BODY, CHALLENGE_HEADERS), - ) - self.assertEqual(code, 0) - self.assertEqual(err, "") - self.assertIn("selvaged/0.2.1", out) - self.assertIn("not asserted", out) - self.assertIn("Cloudflare", out) - self.assertIn("cf-mitigated: challenge", out) - self.assertIn("datacenter address", out) - - def test_a_public_read_that_is_not_a_challenge_is_reported_and_green(self): - code, out, err = self.run_main( - lambda *a: origin(version="0.2.1"), lambda *a: public("502", "bad gateway", "") - ) - self.assertEqual(code, 0) - self.assertEqual(err, "") - self.assertIn("502", out) - self.assertIn("did not fail the run", out) - self.assertIn("selvaged/0.2.1", out) - self.assertEqual(out.count("the origin:"), 1) - - def test_a_readable_mismatch_is_red(self): - code, out, err = self.run_main( - lambda *a: origin(version="0.2.1"), lambda *a: public("200", meta("0.2.0")) - ) - self.assertEqual(code, 1) - self.assertEqual(out.count("the origin:"), 1) - self.assertIn("selvaged/0.2.0", err) - self.assertIn("selvaged/0.2.1", err) - self.assertIn("fails the run", err) - - def test_a_200_without_a_server_field_is_reported_and_green(self): - code, out, err = self.run_main( - lambda *a: origin(version="0.2.1"), lambda *a: public("200", "nope") - ) - self.assertEqual(code, 0) - self.assertEqual(err, "") - self.assertIn("did not fail the run", out) - - def test_a_wrong_origin_is_red_before_the_public_read_happens(self): - public_calls = [] - - def never(*a): - public_calls.append(1) - return public("200", meta("0.2.1")) - - code, _, err = self.run_main(lambda *a: origin(version="0.2.0"), never) - self.assertEqual(code, 1) - self.assertEqual(public_calls, []) - self.assertIn("selvaged/0.2.0", err) - - def test_a_page_only_dispatch_prints_the_origin_without_comparing(self): - code, out, err = self.run_main( - lambda *a: origin(version="0.1.0"), lambda *a: public("200", meta("0.1.0")), expect=None - ) - self.assertEqual(code, 0) - self.assertEqual(err, "") - self.assertIn("not compared", out) - - -class TheSubprocessTest(unittest.TestCase): - """The half that only a real argument list, or a missing binary, would break.""" - - def stub(self, workdir, name, body): - path = Path(workdir) / name - path.write_text("#!/bin/sh\n" + body, encoding="utf-8") - path.chmod(0o755) - return path - - def test_the_ssh_read_parses_what_the_box_prints(self): - with tempfile.TemporaryDirectory() as workdir: - argv_file = Path(workdir) / "argv" - bin_dir = Path(workdir) / "bin" - bin_dir.mkdir() - self.stub( - bin_dir, - "ssh", - 'printf "%s\\n" "$@" >"$STUB_ARGV"\n' - "printf 'origin-page:%s\\n' 200\n" - "printf 'origin-meta:%s\\n' '{\"server\":\"selvaged/0.2.1\"}'\n", - ) - with mock.patch.dict( - os.environ, - {"PATH": f"{bin_dir}:{os.environ['PATH']}", "STUB_ARGV": str(argv_file)}, - ): - reading = verify.read_origin("deployci@box", "https://127.0.0.1") - self.assertEqual(reading, verify.Origin("200", '{"server":"selvaged/0.2.1"}')) - sent = argv_file.read_text(encoding="utf-8") - self.assertIn("deployci@box", sent) - self.assertIn("BatchMode=yes", sent) - self.assertIn("https://127.0.0.1/", sent) - self.assertIn("https://127.0.0.1/meta", sent) - - def test_the_remote_command_carries_nothing_from_the_dispatch(self): - command = verify.remote_read("https://127.0.0.1") - self.assertIn("origin-page:", command) - self.assertIn("origin-meta:", command) - for foreign in ("0.2.1", "server_version", "SERVER_VERSION", "@VERSION@"): - self.assertNotIn(foreign, command) - - def test_the_remote_command_names_the_host_the_front_answers(self): - """The front is the server for the demo's name and closes the connection - for any other, so a loopback read that named only `127.0.0.1` would come - back with nothing rather than with the origin, and the deploy would go - red for a reason that is not the box's.""" - command = verify.remote_read("https://127.0.0.1") - self.assertIn(f"-H 'Host: {verify.DEMO_HOST}'", command) - self.assertEqual(command.count(f"Host: {verify.DEMO_HOST}"), 2, "both the page and /meta carry it") - self.assertIn(f"https://{verify.DEMO_HOST}", verify.PUBLIC_URL) - - def test_the_url_reaches_the_remote_shell_as_data(self): - with tempfile.TemporaryDirectory() as workdir: - bin_dir = Path(workdir) / "bin" - bin_dir.mkdir() - seen = Path(workdir) / "seen" - pwned = Path(workdir) / "pwned" - self.stub(bin_dir, "curl", f'printf "%s\\n" "$@" >"{seen}"\nprintf 200\n') - hostile = f"https://127.0.0.1/$(touch {pwned});id" - done = subprocess.run( - ["/bin/sh", "-c", verify.remote_read(hostile)], - capture_output=True, - text=True, - check=False, - env=dict(os.environ, PATH=f"{bin_dir}:{os.environ['PATH']}"), - ) - self.assertFalse(pwned.exists(), f"the remote shell executed the URL: {done.stdout}") - self.assertIn(hostile + "/", seen.read_text(encoding="utf-8")) - self.assertEqual(done.stdout.splitlines()[0], "origin-page:200") - - def test_an_ssh_that_refuses_is_a_read_that_fails(self): - with tempfile.TemporaryDirectory() as workdir: - bin_dir = Path(workdir) / "bin" - bin_dir.mkdir() - self.stub(bin_dir, "ssh", "echo 'no route to host' >&2\nexit 255\n") - with mock.patch.dict(os.environ, {"PATH": f"{bin_dir}:{os.environ['PATH']}"}): - reading = verify.read_origin("deployci@box", "https://127.0.0.1") - self.assertEqual(reading.page, "") - self.assertIn("exited 255", reading.error) - self.assertIn("no route to host", reading.error) - - def test_a_missing_ssh_is_a_read_that_fails_rather_than_a_traceback(self): - with tempfile.TemporaryDirectory() as empty: - with mock.patch.dict(os.environ, {"PATH": empty}): - reading = verify.read_origin("deployci@box", "https://127.0.0.1") - self.assertEqual(reading.page, "") - self.assertIn("could not be run", reading.error) - - def test_a_missing_curl_is_a_read_that_fails_rather_than_a_traceback(self): - with tempfile.TemporaryDirectory() as empty: - with mock.patch.dict(os.environ, {"PATH": empty}): - reading = verify.read_public("https://selvage-demo.dontblameme.dev") - self.assertEqual(reading.status, "") - self.assertIn("could not be run", reading.error) - - def test_the_public_read_keeps_the_headers_a_challenge_arrives_in(self): - with tempfile.TemporaryDirectory() as workdir: - bin_dir = Path(workdir) / "bin" - bin_dir.mkdir() - self.stub( - bin_dir, - "curl", - "while [ $# -gt 0 ]; do case \"$1\" in -D) headers=$2; shift 2 ;; " - "-o) body=$2; shift 2 ;; *) shift ;; esac; done\n" - "printf 'HTTP/2 403 \\r\\ncf-mitigated: challenge\\r\\nserver: cloudflare\\r\\n' >\"$headers\"\n" - "printf '%s' 'Just a moment...' >\"$body\"\n" - "printf '403'\n", - ) - with mock.patch.dict(os.environ, {"PATH": f"{bin_dir}:{os.environ['PATH']}"}): - reading = verify.read_public("https://selvage-demo.dontblameme.dev") - self.assertEqual(reading.status, "403") - verdict, detail = verify.classify_public(reading, "0.2.1") - self.assertEqual(verdict, verify.CHALLENGE) - self.assertIn("cf-mitigated: challenge", detail) - - def test_a_transfer_that_fails_after_the_status_line_is_not_an_answer(self): - with tempfile.TemporaryDirectory() as workdir: - bin_dir = Path(workdir) / "bin" - bin_dir.mkdir() - self.stub( - bin_dir, - "curl", - "while [ $# -gt 0 ]; do case \"$1\" in -D) headers=$2; shift 2 ;; " - "-o) body=$2; shift 2 ;; *) shift ;; esac; done\n" - "printf 'HTTP/2 200 \\r\\nserver: cloudflare\\r\\n' >\"$headers\"\n" - "printf '%s' '{\"server\":\"selvaged/0.2.1\"}' >\"$body\"\n" - "printf '200'\nexit 28\n", - ) - with mock.patch.dict(os.environ, {"PATH": f"{bin_dir}:{os.environ['PATH']}"}): - reading = verify.read_public("https://selvage-demo.dontblameme.dev") - self.assertIn("exited 28", reading.error) - verdict, _ = verify.classify_public(reading, "0.2.1") - self.assertEqual(verdict, verify.UNREADABLE) - - -if __name__ == "__main__": - unittest.main(verbosity=2) diff --git a/scripts/test_wait_for_deploy.py b/scripts/test_wait_for_deploy.py deleted file mode 100755 index 61b3f82..0000000 --- a/scripts/test_wait_for_deploy.py +++ /dev/null @@ -1,445 +0,0 @@ -#!/usr/bin/env python3 -"""What `scripts/wait_for_deploy.py` watches, and what it does when it cannot. - -`gh workflow run` prints no run id, so the release has to read the workflow's runs -to find the one its dispatch created. The choices that decide a release's colour -are all here: - - * **the run to watch is the newest one that is not the newest seen before the - dispatch**, read from `gh run list` on both sides of the dispatch; - * **the completion deadline outlasts the deploy's own `timeout-minutes`**, and a - deadline that passes reports the last read rather than looking hung; - * **three failures, each named as itself** and each saying what remains: the - release is out, the demo did not take it, and the deploy's own run is the next - thing to read, with the `gh workflow run` that repeats the dispatch; - * **watching a run that already exists** (`--run-id`) needs no dispatch, which is - how the wait is proved without cutting a release. - -The poll loops are driven with real, tiny deadlines and injected reads, and a fake -read stops its own loop rather than racing the wall clock. The `gh`-facing edges -run against a stand-in on `PATH`, where a mistake in an argument, a missing binary -or a `gh` that never answers would otherwise only show up on a runner. - -Run it directly: - - python3 -B scripts/test_wait_for_deploy.py -""" - -import io -import json -import os -import sys -import tempfile -import unittest -from contextlib import contextmanager, redirect_stderr, redirect_stdout -from pathlib import Path -from unittest import mock - -sys.path.insert(0, str(Path(__file__).resolve().parent)) - -import wait_for_deploy as wait # noqa: E402 (the path above makes this importable) - -GREEN = wait.Run(36327799545, "https://github.com/selvage-protocol/web_client/actions/runs/36327799545", "completed", "success") -RED = wait.Run(36326818510, "https://github.com/selvage-protocol/web_client/actions/runs/36326818510", "completed", "failure") - - -def run_url(run_id: int) -> str: - """`GREEN`'s run URL with this id in place of its own. - - `GREEN` and `RED` are runs that exist, so their links are spelled out above and - the link check reads them. The two ids below name no run at all, so a URL - spelled in full for one would be an address that check fetches and gets a 404 - from. - """ - return GREEN.url.replace(str(GREEN.id), str(run_id)) - - -BEFORE = wait.Run(36100000000, run_url(36100000000), "completed", "success") -RUNNING = wait.Run(36330000000, run_url(36330000000), "in_progress", "") - -LIST_FIELDS = ["run", "list", "--workflow", "deploy-prod.yml", "--limit", "1", "--json", wait.FIELDS] - -# A stand-in `gh`: records the argv it was handed, answers stdout/stderr/status from -# the environment, so the tests read the argument list rather than a network. The -# interpreter is named by its absolute path because a build sandbox has no -# `/usr/bin/env`. -STUB_GH = f'''\ -#!{sys.executable} -import os -import sys - -with open(os.environ["STUB_LOG"], "a", encoding="utf-8") as handle: - handle.write(" ".join(sys.argv[1:]) + "\\n") -sys.stdout.write(os.environ.get("STUB_STDOUT", "")) -sys.stderr.write(os.environ.get("STUB_STDERR", "")) -sys.exit(int(os.environ.get("STUB_STATUS", "0"))) -''' - - -class TheRunToWatchTest(unittest.TestCase): - def test_the_run_created_is_the_newest_one_not_seen_before(self): - readings = [BEFORE, BEFORE, GREEN] - calls = [] - - def read(): - calls.append(1) - return readings[min(len(calls), len(readings)) - 1] - - found = wait.wait_for_new_run(BEFORE.id, read, deadline=5.0, interval=0.01) - self.assertEqual(found, GREEN) - self.assertEqual(len(calls), 3, "the two reads that matched the snapshot are not the run") - - def test_a_workflow_with_no_runs_before_takes_the_first_run_it_sees(self): - found = wait.wait_for_new_run(None, lambda: GREEN, deadline=1.0, interval=0.01) - self.assertEqual(found, GREEN) - - def test_a_run_that_never_appears_is_its_own_failure(self): - with self.assertRaises(wait.NeverAppeared) as raised: - wait.wait_for_new_run(BEFORE.id, lambda: BEFORE, deadline=0.03, interval=0.01) - self.assertEqual(raised.exception.before, BEFORE.id) - self.assertEqual(raised.exception.last, BEFORE) - self.assertEqual(raised.exception.deadline, 0.03) - - def test_a_workflow_that_has_runs_at_all_is_worth_retrying(self): - readings = [None, None, GREEN] - calls = [] - - def read(): - calls.append(1) - return readings[min(len(calls), len(readings)) - 1] - - found = wait.wait_for_new_run(None, read, deadline=5.0, interval=0.01) - self.assertEqual(found, GREEN) - self.assertEqual(len(calls), 3) - - -class TheConclusionTest(unittest.TestCase): - def test_a_completed_run_is_returned_with_its_conclusion(self): - final = wait.wait_for_conclusion(lambda: GREEN, deadline=1.0, interval=0.01) - self.assertEqual(final, GREEN) - - def test_a_run_that_does_not_finish_is_its_own_failure(self): - with self.assertRaises(wait.DidNotFinish) as raised: - wait.wait_for_conclusion(lambda: RUNNING, deadline=0.03, interval=0.01) - self.assertEqual(raised.exception.last, RUNNING) - self.assertEqual(raised.exception.deadline, 0.03) - - def test_a_run_still_going_is_worth_retrying_before_the_deadline(self): - readings = [RUNNING, RUNNING, RED] - calls = [] - - def read(): - calls.append(1) - return readings[min(len(calls), len(readings)) - 1] - - final = wait.wait_for_conclusion(read, deadline=5.0, interval=0.01) - self.assertEqual(final, RED) - self.assertEqual(len(calls), 3) - - def test_an_unfinished_run_carries_no_conclusion(self): - self.assertEqual(wait.to_run({"databaseId": 7, "status": "queued"}), wait.Run(7, "", "queued", "")) - - -class TheReadingsTest(unittest.TestCase): - """`gh`'s JSON, and the command lines that produce it.""" - - @contextmanager - def with_stub(self, stdout="", status=0, stderr=""): - with tempfile.TemporaryDirectory() as workdir: - bin_dir = Path(workdir) / "bin" - bin_dir.mkdir() - stub = bin_dir / "gh" - stub.write_text(STUB_GH, encoding="utf-8") - stub.chmod(0o755) - log = Path(workdir) / "argv" - with mock.patch.dict( - os.environ, - { - "PATH": f"{bin_dir}:{os.environ['PATH']}", - "STUB_LOG": str(log), - "STUB_STDOUT": stdout, - "STUB_STDERR": stderr, - "STUB_STATUS": str(status), - }, - ): - yield log - - def argv(self, log): - return log.read_text(encoding="utf-8").strip() - - def test_the_newest_run_is_parsed_from_the_run_list(self): - payload = json.dumps( - [{"databaseId": GREEN.id, "url": GREEN.url, "status": "completed", "conclusion": "success"}] - ) - with self.with_stub(stdout=payload) as log: - found = wait.newest_run(None, "deploy-prod.yml") - sent = self.argv(log) - self.assertEqual(found, GREEN) - self.assertEqual(sent, " ".join(LIST_FIELDS)) - - def test_a_workflow_with_no_runs_reads_as_none(self): - with self.with_stub(stdout="[]"): - self.assertIsNone(wait.newest_run(None, "deploy-prod.yml")) - - def test_one_run_is_read_by_id(self): - payload = json.dumps( - {"databaseId": RED.id, "url": RED.url, "status": "completed", "conclusion": "failure"} - ) - with self.with_stub(stdout=payload) as log: - found = wait.read_run(None, RED.id) - sent = self.argv(log) - self.assertEqual(found, RED) - self.assertEqual(sent, f"run view {RED.id} --json {wait.FIELDS}") - - def test_the_dispatch_sends_the_inputs_and_the_ref(self): - with self.with_stub() as log: - wait.dispatch_run( - None, "deploy-prod.yml", "main", ["server_version=0.6.0", "install_shape=true"] - ) - sent = self.argv(log) - self.assertEqual( - sent, - "workflow run deploy-prod.yml --ref main -f server_version=0.6.0 -f install_shape=true", - ) - - def test_a_named_repository_reaches_gh_as_repo(self): - with self.with_stub(stdout="[]") as log: - wait.newest_run("selvage-protocol/web_client", "deploy-prod.yml") - sent = self.argv(log) - self.assertTrue(sent.endswith("--repo selvage-protocol/web_client"), sent) - - def test_a_gh_that_exits_nonzero_is_an_error_that_carries_its_stderr(self): - with self.with_stub(status=1, stderr="HTTP 404: not found"): - with self.assertRaises(wait.GhError) as raised: - wait.newest_run(None, "deploy-prod.yml") - self.assertIn("HTTP 404", str(raised.exception)) - - def test_a_missing_gh_is_an_error_rather_than_a_traceback(self): - with mock.patch.object(wait, "GH", "/nonexistent/gh-for-the-test"): - with self.assertRaises(wait.GhError) as raised: - wait.newest_run(None, "deploy-prod.yml") - self.assertIn("could not be run", str(raised.exception)) - - def test_a_gh_that_never_answers_is_an_error(self): - with tempfile.TemporaryDirectory() as workdir: - bin_dir = Path(workdir) / "bin" - bin_dir.mkdir() - stub = bin_dir / "gh" - stub.write_text(f"#!{sys.executable}\nimport time\ntime.sleep(5)\n", encoding="utf-8") - stub.chmod(0o755) - with mock.patch.dict(os.environ, {"PATH": f"{bin_dir}:{os.environ['PATH']}"}): - with mock.patch.object(wait, "GH_TIMEOUT_SECONDS", 0.05): - with self.assertRaises(wait.GhError) as raised: - wait.newest_run(None, "deploy-prod.yml") - self.assertIn("did not answer", str(raised.exception)) - - -class TheWordsTest(unittest.TestCase): - def test_an_input_is_read_by_name(self): - inputs = ["server_version=0.6.0", "install_shape=true"] - self.assertEqual(wait.input_value(inputs, "server_version"), "0.6.0") - self.assertEqual(wait.input_value(inputs, "install_shape"), "true") - self.assertEqual(wait.input_value(inputs, "web_version"), "") - - def test_the_redispatch_is_the_dispatch_it_repeats(self): - self.assertEqual( - wait.redispatch_command("deploy-prod.yml", "main", ["server_version=0.6.0"]), - "gh workflow run deploy-prod.yml --ref main -f server_version=0.6.0", - ) - self.assertEqual( - wait.redispatch_command( - "deploy-prod.yml", "main", ["server_version=0.6.0", "install_shape=true"] - ), - "gh workflow run deploy-prod.yml --ref main -f server_version=0.6.0 -f install_shape=true", - ) - - def test_a_finished_run_names_its_conclusion_its_url_and_its_log(self): - report = wait.conclusion_report(RED) - self.assertIn("concluded failure", report) - self.assertIn(RED.url, report) - self.assertIn(f"gh run view {RED.id} --log-failed", report) - - def test_a_deadline_names_the_last_read(self): - report = wait.did_not_finish_report("deploy-prod.yml run 36330000000", RUNNING, 1800.0) - self.assertIn("did not finish within 1800s", report) - self.assertIn(RUNNING.url, report) - self.assertIn("status=in_progress", report) - - def test_what_remains_names_the_release_the_demo_and_the_redispatch(self): - report = wait.remains( - "deploy-prod.yml", "main", ["server_version=0.6.0", "install_shape=true"], None - ) - self.assertIn("the release is already out", report) - self.assertIn("v0.6.0 is tagged and published", report) - self.assertIn("The public demo did not take it", report) - self.assertIn("the next thing to read", report) - self.assertIn( - "gh workflow run deploy-prod.yml --ref main -f server_version=0.6.0 -f install_shape=true", - report, - ) - - -class TheEndingTest(unittest.TestCase): - """`main`'s endings, with the `gh`-facing reads injected.""" - - def run_main(self, reads, dispatch=None, argv=None): - argv = argv if argv is not None else ["--dispatch", "-f", "server_version=0.6.0"] - argv += ["--deadline", "0.05", "--appear-deadline", "0.05", "--poll-interval", "0.01"] - patches = [ - mock.patch.object(wait, "read_run", reads["read_run"]), - mock.patch.object(wait, "newest_run", reads["newest_run"]), - ] - if dispatch is not None: - patches.append(mock.patch.object(wait, "dispatch_run", dispatch)) - for patch in patches: - patch.start() - try: - out, err = io.StringIO(), io.StringIO() - with redirect_stdout(out), redirect_stderr(err): - code = wait.main(argv) - finally: - for patch in reversed(patches): - patch.stop() - return code, out.getvalue(), err.getvalue() - - @staticmethod - def sequence(*runs): - reads = list(runs) - - def read(*_): - return reads.pop(0) if len(reads) > 1 else reads[0] - - return read - - def test_a_successful_dispatch_is_green_and_names_the_run(self): - reads = {"newest_run": self.sequence(BEFORE, GREEN), "read_run": self.sequence(GREEN)} - code, out, err = self.run_main(reads, dispatch=lambda *a: None) - self.assertEqual(code, 0) - self.assertEqual(err, "") - self.assertIn(f"watching run {GREEN.id}: {GREEN.url}", out) - self.assertIn(f"deploy-prod.yml run {GREEN.id} concluded success", out) - - def test_a_failed_deploy_fails_the_release_and_says_what_remains(self): - reads = {"newest_run": self.sequence(BEFORE, RED), "read_run": self.sequence(RED)} - code, out, err = self.run_main( - reads, dispatch=lambda *a: None, argv=["--dispatch", "-f", "server_version=0.6.0", "-f", "install_shape=true"] - ) - self.assertEqual(code, 1) - self.assertIn(f"watching run {RED.id}", out) - self.assertIn("concluded failure", err) - self.assertIn(RED.url, err) - self.assertIn(f"gh run view {RED.id} --log-failed", err) - self.assertIn("the release is already out", err) - self.assertIn("v0.6.0 is tagged and published", err) - self.assertIn( - "gh workflow run deploy-prod.yml --ref main -f server_version=0.6.0 -f install_shape=true", - err, - ) - - def test_a_conclusion_that_is_not_success_names_itself(self): - skipped = wait.Run(RED.id, RED.url, "completed", "skipped") - reads = {"newest_run": self.sequence(BEFORE, skipped), "read_run": self.sequence(skipped)} - code, _, err = self.run_main(reads, dispatch=lambda *a: None) - self.assertEqual(code, 1) - self.assertIn("concluded skipped", err) - - def test_a_run_that_does_not_finish_names_the_last_read(self): - reads = {"newest_run": self.sequence(BEFORE, RUNNING), "read_run": self.sequence(RUNNING)} - code, _, err = self.run_main(reads, dispatch=lambda *a: None) - self.assertEqual(code, 1) - self.assertIn("did not finish within 0s", err) - self.assertIn(RUNNING.url, err) - self.assertIn("status=in_progress", err) - self.assertIn("What remains", err) - - def test_a_run_that_never_appears_names_what_remains(self): - reads = {"newest_run": self.sequence(BEFORE, BEFORE), "read_run": self.sequence(BEFORE)} - code, _, err = self.run_main(reads, dispatch=lambda *a: None) - self.assertEqual(code, 1) - self.assertIn("no new run of deploy-prod.yml appeared within 0s of the dispatch", err) - self.assertIn("the one seen before the dispatch", err) - self.assertIn("the release is already out", err) - self.assertIn( - "gh workflow run deploy-prod.yml --ref main -f server_version=0.6.0", err - ) - - def test_a_dispatch_that_gh_refuses_is_named_where_it_failed(self): - reads = {"newest_run": self.sequence(BEFORE), "read_run": self.sequence(BEFORE)} - - def refuse(*_): - raise wait.GhError("gh exited 1: workflow not found") - - code, _, err = self.run_main(reads, dispatch=refuse) - self.assertEqual(code, 1) - self.assertIn("could not dispatch deploy-prod.yml", err) - self.assertIn("workflow not found", err) - - def test_watching_an_existing_run_needs_no_dispatch(self): - reads = {"newest_run": self.sequence(BEFORE), "read_run": self.sequence(GREEN)} - code, out, err = self.run_main( - reads, - argv=["--run-id", str(GREEN.id), "--repo", "selvage-protocol/web_client"], - ) - self.assertEqual(code, 0) - self.assertEqual(err, "") - self.assertIn(f"watching run {GREEN.id}", out) - - def test_watching_an_existing_failed_run_names_it_and_its_log(self): - reads = {"newest_run": self.sequence(BEFORE), "read_run": self.sequence(RED)} - code, _, err = self.run_main( - reads, - argv=["--run-id", str(RED.id), "--repo", "selvage-protocol/web_client"], - ) - self.assertEqual(code, 1) - self.assertIn(f"run {RED.id} concluded failure", err) - self.assertIn(RED.url, err) - self.assertIn( - f"gh run view {RED.id} --log-failed --repo selvage-protocol/web_client", err - ) - self.assertNotIn("the release is already out", err) - - def test_watching_an_existing_run_that_is_not_finished_names_the_last_read(self): - reads = {"newest_run": self.sequence(BEFORE), "read_run": self.sequence(RUNNING)} - code, _, err = self.run_main(reads, argv=["--run-id", str(RUNNING.id)]) - self.assertEqual(code, 1) - self.assertIn(f"run {RUNNING.id} did not finish within 0s", err) - self.assertNotIn("deploy-prod.yml", err) - self.assertIn("status=in_progress", err) - - def test_watching_for_the_next_run_without_a_dispatch(self): - reads = {"newest_run": self.sequence(None), "read_run": self.sequence(RUNNING)} - code, _, err = self.run_main(reads, argv=["--watch-next"]) - self.assertEqual(code, 1) - self.assertIn("no runs of deploy-prod.yml are visible", err) - - def test_a_workflow_that_has_no_runs_is_its_own_read(self): - reads = {"newest_run": self.sequence(None, None), "read_run": self.sequence(BEFORE)} - code, _, err = self.run_main(reads, argv=["--watch-next"]) - self.assertEqual(code, 1) - self.assertIn("no runs of deploy-prod.yml are visible", err) - - def test_a_watch_of_an_existing_workflow_names_the_run_it_saw(self): - reads = {"newest_run": self.sequence(BEFORE, BEFORE), "read_run": self.sequence(BEFORE)} - code, _, err = self.run_main(reads, argv=["--watch-next"]) - self.assertEqual(code, 1) - self.assertIn("no new run of deploy-prod.yml appeared within 0s.", err) - self.assertIn("the one seen before the watch began", err) - self.assertNotIn("of the dispatch", err) - - def test_a_gh_that_errors_before_dispatching_is_named(self): - def refuse(*_): - raise wait.GhError("HTTP 404: workflow not found") - - reads = {"newest_run": refuse, "read_run": self.sequence(BEFORE)} - code, _, err = self.run_main(reads, dispatch=lambda *a: None) - self.assertEqual(code, 1) - self.assertIn("cannot read deploy-prod.yml's runs before dispatching", err) - - def test_a_mode_is_required(self): - with redirect_stderr(io.StringIO()): - with self.assertRaises(SystemExit): - wait.main([]) - - -if __name__ == "__main__": - unittest.main() diff --git a/scripts/verify_deploy.py b/scripts/verify_deploy.py deleted file mode 100755 index 58e52cc..0000000 --- a/scripts/verify_deploy.py +++ /dev/null @@ -1,466 +0,0 @@ -#!/usr/bin/env python3 -"""Verify that the box a deploy just reached serves what was asked for. - -Two reads, and only one of them decides the run's colour. - -* **The origin**, over the Tailscale SSH path the deploy itself used, through the - front on the box's own loopback: `https://127.0.0.1/meta` and the page at `/`, - both naming the demo's own `Host`. That is the honest source — it is what is - running, with no edge between the reader and it — so it **fails the run** when - the version asked for is not the version served, and when the page stops - answering 200. -* **The public origin**, over Cloudflare, from this runner. It is read in three - shapes and only one of them decides the run's colour: - - - a **challenge**, an **unreadable** read or any other answer that is not a - version is a **report**. Cloudflare serves a managed challenge to a - programmatic client on a datacenter address and an edge is not something a - deploy can fix, so a challenge is named in plain words and ends the attempt - at the first challenge response rather than polling a deadline it cannot - pass; - - a read that answers 200 with a parsed `server` that is **not** the version - this deploy named is **red**. The origin assertion cannot see that: in that - scenario the origin is right and the edge is serving something else — a stale - cache, a different origin, a route pointing elsewhere — which is the failure - this step exists to catch; - - a read that answers 200 reporting **that** version is green, so where the edge - does let a client through the check comes back on its own. - -The origin read needs `-k`: the certificate is the Cloudflare Origin CA pair -issued for the public name, which is in no trust store and does not match -`127.0.0.1` in any case. The front is reached directly, not through the edge, and -nothing from the dispatch reaches the remote shell. It also needs the `Host` -header, because the front is the server for `selvage-demo.dontblameme.dev` and -closes the connection for any other name: a loopback address is where the front -is, not a name it answers. - - scripts/verify_deploy.py --expect-version x.x.x - scripts/verify_deploy.py # a page-only deploy: /meta is read, not compared -""" - -import argparse -import json -import shlex -import subprocess -import sys -import tempfile -import time -from functools import partial -from pathlib import Path -from typing import NamedTuple - -SSH_TARGET = "deployci@selvage-protocol-prod" -ORIGIN_URL = "https://127.0.0.1" -# The name the deployment's front is the server for, and the one it answers; a -# request naming any other Host is closed rather than served. Both reads carry it: -# the public one in the URL, and the origin read — which dials the box's own -# loopback, with no edge in the way — as an explicit `Host`, because an address is -# not a name and `127.0.0.1` is not one the front serves. -DEMO_HOST = "selvage-demo.dontblameme.dev" -PUBLIC_URL = f"https://{DEMO_HOST}" - -# Long enough for a front that a deploy has just recreated to answer again, and -# short enough that a step which cannot pass says so instead of looking hung. -ORIGIN_DEADLINE_SECONDS = 60.0 -PUBLIC_DEADLINE_SECONDS = 60.0 -POLL_INTERVAL_SECONDS = 5.0 -CURL_MAX_SECONDS = 10 -SPAWN_TIMEOUT_SECONDS = 60 - -PAGE_MARKER = "origin-page:" -META_MARKER = "origin-meta:" - -# The whole of what `deployci` runs on the box, in one line each so the answer is -# parsed without depending on a JSON parser being installed there. Neither the -# version nor anything else out of the dispatch is in here: it is a comparison on -# this side and never a word in a remote shell. -REMOTE_READ = """\ -printf 'origin-page:%s\\n' "$(curl -sk -o /dev/null -w '%{http_code}' --max-time @MAX@ -H 'Host: @HOST@' @URL@/)" -printf 'origin-meta:%s\\n' "$(curl -sk --max-time @MAX@ -H 'Host: @HOST@' @URL@/meta | tr -d '\\n')" -""" - -CHALLENGE = "challenge" -REPORTED = "reported" -MISMATCH = "mismatch" -UNREADABLE = "unreadable" - -# The header is the reliable half of the observation — Cloudflare's managed -# challenge came back as a 403 carrying `cf-mitigated: challenge` — and the body -# markers are the belt to its braces, because an interstitial served without the -# header would otherwise read as a real failure and turn a healthy deploy red. -MITIGATION_HEADER = "cf-mitigated" -INTERSTITIAL_BODY_MARKERS = ( - "just a moment", - "cdn-cgi/challenge-platform", - "attention required! | cloudflare", -) - - -class Origin(NamedTuple): - """What one read of the box's front produced.""" - - page: str - meta: str - error: str = "" - - -class Public(NamedTuple): - """What one read of the public origin produced.""" - - status: str - headers: str - body: str - error: str = "" - - -class OriginAssertion(Exception): - """The origin did not serve what was asked for before the deadline.""" - - -def json_server(body: str) -> str: - """The `server` field of a `/meta` body, or "" when it does not carry one.""" - try: - parsed = json.loads(body) - except (TypeError, ValueError): - return "" - if not isinstance(parsed, dict): - return "" - served = parsed.get("server") - return served if isinstance(served, str) else "" - - -def header_value(headers: str, name: str) -> str: - """The first value of `name` in a raw header block, or "".""" - for line in headers.splitlines(): - field, _, value = line.partition(":") - if field.strip().lower() == name.lower(): - return value.strip() - return "" - - -def origin_problem(reading: Origin, expect_version: str | None) -> str | None: - """Why this origin read is not yet the read that was asked for, or None.""" - if reading.error: - return reading.error - if reading.page != "200": - return f"the page answered {reading.page or 'nothing'}" - served = json_server(reading.meta) - if not served: - return f"/meta carried no server field: {(reading.meta or 'nothing')[:200]!r}" - if expect_version is not None and served != f"selvaged/{expect_version}": - return f"/meta reports {served}" - return None - - -def observed(reading: Origin) -> str: - """The state a failed origin poll reports rather than guessing at.""" - if reading.error: - return reading.error - return f"the page answered {reading.page or 'nothing'} and /meta says {json_server(reading.meta) or 'nothing'}" - - -def wait_for_origin( - read, expect_version: str | None, deadline: float, interval: float -) -> Origin: - """Poll the origin until it serves what was asked for, or the deadline passes. - - A dead line with a stated observation, not a sleep and a hope: the failure - carries what the last read actually said. - """ - started = time.monotonic() - while True: - reading = read() - problem = origin_problem(reading, expect_version) - if problem is None: - return reading - if time.monotonic() - started >= deadline: - raise OriginAssertion(f"{problem}; last read: {observed(reading)}") - time.sleep(interval) - - -def classify_public(reading: Public, expect_version: str | None) -> tuple[str, str]: - """What one public read says, in the three shapes this run cares about.""" - if reading.error: - return UNREADABLE, reading.error - mitigated = header_value(reading.headers, MITIGATION_HEADER) - lowered = reading.body.lower() - marker = next((m for m in INTERSTITIAL_BODY_MARKERS if m in lowered), "") - if mitigated or marker: - detail = f"{reading.status or 'no status'} with " - detail += ( - f"{MITIGATION_HEADER}: {mitigated}" - if mitigated - else f"a Cloudflare interstitial body ({marker})" - ) - return CHALLENGE, detail - if reading.status == "200": - served = json_server(reading.body) - if not served: - # A 200 carrying nothing parseable is the edge being unhelpful rather than - # the deployment disagreeing: what `/meta` must look like is asserted on - # the origin above, where nothing can rewrite the answer. - return UNREADABLE, "200 reporting no server field" - if expect_version is None or served == f"selvaged/{expect_version}": - return REPORTED, served - return MISMATCH, served - return UNREADABLE, f"{reading.status or 'no status'}" - - -def wait_for_public( - read, expect_version: str | None, deadline: float, interval: float -) -> tuple[str, str]: - """Read the public origin, ending at the first challenge rather than polling it. - - A challenge is an answer about the edge, not about the deployment, and it cannot - be passed by waiting, so the attempt is over the moment it arrives. Anything else - that is not a matching version is worth retrying to the deadline — a front a - deploy has just recreated answers again in seconds, and a stale cache expires — - and the **last** read is the one that is reported: a mismatch that persists to - the deadline is the edge serving something the deploy did not put behind it, and - that fails the run. - """ - started = time.monotonic() - while True: - verdict, detail = classify_public(read(), expect_version) - if verdict in (CHALLENGE, REPORTED): - return verdict, detail - if time.monotonic() - started >= deadline: - return verdict, detail - time.sleep(interval) - - -def remote_read(origin_url: str) -> str: - """The command `deployci` runs on the box, with the URL quoted into it. - - The SSH client hands this string to the remote user's shell, so a - `--origin-url` carrying shell syntax has to arrive as data rather than as - syntax. The seconds placeholder is a number this module owns, and the Host is - the name above, quoted the same way. - """ - return ( - REMOTE_READ.replace("@MAX@", str(CURL_MAX_SECONDS)) - .replace("@HOST@", shlex.quote(DEMO_HOST)) - .replace("@URL@", shlex.quote(origin_url)) - ) - - -def read_origin(ssh_target: str, origin_url: str) -> Origin: - """One read of the front on the box, as `deployci` over Tailscale SSH.""" - argv = [ - "ssh", - "-o", - "BatchMode=yes", - "-o", - "ConnectTimeout=10", - "-o", - "StrictHostKeyChecking=accept-new", - ssh_target, - remote_read(origin_url), - ] - try: - done = subprocess.run( - argv, - capture_output=True, - text=True, - timeout=SPAWN_TIMEOUT_SECONDS, - check=False, - ) - except subprocess.TimeoutExpired: - return Origin( - "", - "", - f"ssh to {ssh_target} did not answer within {SPAWN_TIMEOUT_SECONDS}s", - ) - except OSError as failed: - return Origin("", "", f"ssh could not be run: {failed}") - if done.returncode != 0: - return Origin( - "", - "", - f"ssh to {ssh_target} exited {done.returncode}: {done.stderr.strip()}", - ) - page = "" - meta = "" - for line in done.stdout.splitlines(): - if line.startswith(PAGE_MARKER): - page = line[len(PAGE_MARKER) :].strip() - elif line.startswith(META_MARKER): - meta = line[len(META_MARKER) :].strip() - if not page: - return Origin( - "", "", f"the read produced no page status: {done.stdout.strip()!r}" - ) - return Origin(page, meta) - - -def read_public(public_url: str) -> Public: - """One read of the public origin from here, headers and body kept. - - `-f` is deliberately absent: the body and the headers of a refusal are the - whole of what this read is for. Any non-zero exit is a read that produced no - answer, whatever status code got as far as being printed — a transfer that - timed out mid-body is not a response. - """ - with tempfile.TemporaryDirectory() as workdir: - headers = Path(workdir) / "headers" - body = Path(workdir) / "body" - argv = [ - "curl", - "-sS", - "--max-time", - str(CURL_MAX_SECONDS), - "-D", - str(headers), - "-o", - str(body), - "-w", - "%{http_code}", - f"{public_url}/meta", - ] - try: - done = subprocess.run( - argv, - capture_output=True, - text=True, - timeout=SPAWN_TIMEOUT_SECONDS, - check=False, - ) - except subprocess.TimeoutExpired: - return Public( - "", "", "", f"curl did not answer within {SPAWN_TIMEOUT_SECONDS}s" - ) - except OSError as failed: - return Public("", "", "", f"curl could not be run: {failed}") - status = done.stdout.strip() - header_text = ( - headers.read_text(encoding="utf-8", errors="replace") - if headers.exists() - else "" - ) - body_text = ( - body.read_text(encoding="utf-8", errors="replace") if body.exists() else "" - ) - if done.returncode != 0: - return Public( - status, - header_text, - body_text, - f"curl exited {done.returncode}: {done.stderr.strip()}", - ) - return Public(status, header_text, body_text) - - -def origin_sentence( - reading: Origin, origin_url: str, ssh_target: str, expect_version: str | None -) -> str: - """The line a passing origin assertion prints.""" - sentence = ( - f"the origin: {origin_url} through the front on {ssh_target} reports " - f"{json_server(reading.meta)}, and the page answers {reading.page}" - ) - if expect_version is None: - sentence += ( - " (no server version was dispatched, so /meta is read and not compared)" - ) - return sentence - - -CHALLENGE_REPORT = """\ -the public read: {url}/meta was answered with a Cloudflare challenge, so it is not asserted this run. - Cloudflare answered {detail}. A managed challenge is answered at Cloudflare's edge, before the - request reaches this origin, and no programmatic client on a datacenter address can pass it: - not this runner, and not the Azure box itself. The same read from a residential address does - answer, which is how the edge was told apart from the deployment. What is asserted above is the - origin's own answer, read on the box through the front. This read is a report and not what the - run is decided by.""" - -UNREADABLE_REPORT = """\ -the public read: {url}/meta did not report {expected} within {seconds:g}s; the last answer was - {detail}. This read is a report and did not fail the run: what is asserted is the origin's own - answer, read on the box through the front above, and an edge that answers a datacenter client - badly is not something a deploy can fix. A public path that answers this way while the origin is - serving the version that was asked for is still worth a look.""" - -MISMATCH_REPORT = """\ -the public read: {url}/meta reports {served}, not {expected}. - The origin on the box above is serving {expected}, read through the front, so the public path is - answering with a version this deploy did not put behind it — a stale cache, a different origin, or - a route pointing elsewhere. The origin assertion cannot see that: in this scenario the origin is - right and the edge is wrong, which is why it fails the run.""" - - -def main(argv: list[str] | None = None) -> int: - parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) - parser.add_argument("--ssh-target", default=SSH_TARGET) - parser.add_argument("--origin-url", default=ORIGIN_URL) - parser.add_argument("--public-url", default=PUBLIC_URL) - parser.add_argument( - "--expect-version", - default=None, - help="the selvaged version this run deployed; without it /meta is read and not compared", - ) - parser.add_argument( - "--origin-deadline", type=float, default=ORIGIN_DEADLINE_SECONDS - ) - parser.add_argument( - "--public-deadline", type=float, default=PUBLIC_DEADLINE_SECONDS - ) - parser.add_argument("--poll-interval", type=float, default=POLL_INTERVAL_SECONDS) - args = parser.parse_args(argv) - - try: - origin = wait_for_origin( - partial(read_origin, args.ssh_target, args.origin_url), - args.expect_version, - args.origin_deadline, - args.poll_interval, - ) - except OriginAssertion as failed: - print(f"the origin did not serve what was deployed: {failed}", file=sys.stderr) - return 1 - print( - origin_sentence(origin, args.origin_url, args.ssh_target, args.expect_version) - ) - - verdict, detail = wait_for_public( - partial(read_public, args.public_url), - args.expect_version, - args.public_deadline, - args.poll_interval, - ) - if verdict == CHALLENGE: - print(CHALLENGE_REPORT.format(url=args.public_url, detail=detail)) - elif verdict == REPORTED: - print(f"the public read: {args.public_url}/meta reports {detail}") - elif verdict == MISMATCH: - # The origin line has been printed, and a reader of the log wants it before the - # reason the run is red rather than after it. - sys.stdout.flush() - print( - MISMATCH_REPORT.format( - url=args.public_url, - served=detail, - expected=f"selvaged/{args.expect_version}", - ), - file=sys.stderr, - ) - return 1 - else: - expected = ( - f"selvaged/{args.expect_version}" - if args.expect_version - else "a server version" - ) - print( - UNREADABLE_REPORT.format( - url=args.public_url, - expected=expected, - seconds=args.public_deadline, - detail=detail, - ) - ) - return 0 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/scripts/wait_for_deploy.py b/scripts/wait_for_deploy.py deleted file mode 100755 index d06324f..0000000 --- a/scripts/wait_for_deploy.py +++ /dev/null @@ -1,435 +0,0 @@ -#!/usr/bin/env python3 -"""Dispatch this repository's deploy workflow, then wait for the run it creates. - -`gh workflow run` prints no run id, so a release that dispatches `deploy-prod.yml` -and looks away cannot tell a deploy that succeeded from one that never started or -one that failed. This dispatches and then watches the run the dispatch created, -and exits non-zero unless that run concludes `success`. - -The run to watch is the newest run of the workflow that is not the newest one seen -before the dispatch; `gh run list` is read before the dispatch and polled after it. -The run is named with its id and URL before it is waited on, so the log says what -was watched, and each failure names itself: no run appeared, the run did not finish -inside the deadline, or the run finished with a conclusion that is not `success`. - - scripts/wait_for_deploy.py --dispatch --workflow deploy-prod.yml --ref main \ - -f server_version=0.6.0 [-f install_shape=true] - -Watching a run that already exists, and dispatching nothing — how the wait above is -proved without cutting a release (any repository `gh` can read works, hence -`--repo`): - - scripts/wait_for_deploy.py --run-id 36327799545 --repo selvage-protocol/web_client - -Or waiting for the next run of a workflow to appear and finish, on its own, for a -dispatch whose id was lost: - - scripts/wait_for_deploy.py --watch-next --workflow deploy-prod.yml - -A deadline that passes names the last read and what remains rather than looking -hung. The completion deadline outlasts `deploy-prod.yml`'s own `timeout-minutes: 20` -plus the queue time ahead of it, so a deploy that hangs is reported by the deploy's -own timeout before it is reported here. - -`gh` is reached through `PATH` (or `SELVAGE_GH`); on a host that has it only under -Nix, run this under `nix shell nixpkgs#gh -c ...`. -""" - -from __future__ import annotations - -import argparse -import json -import os -import subprocess -import sys -import textwrap -import time -from functools import partial -from typing import Callable, NamedTuple - -GH = os.environ.get("SELVAGE_GH", "gh") - -DEFAULT_WORKFLOW = "deploy-prod.yml" -DEFAULT_REF = "main" -# `deploy-prod.yml`'s own job carries `timeout-minutes: 20`; the extra ten minutes -# are for the queue ahead of it and the Tailscale join, so a deploy that hangs is -# reported by the deploy's own timeout rather than by this. -DEFAULT_DEADLINE_SECONDS = 1800.0 -# A run `gh workflow run` accepted reaches `gh run list` in seconds; this bounds -# the wait for that read-after-write lag rather than the deploy itself. -DEFAULT_APPEAR_DEADLINE_SECONDS = 300.0 -DEFAULT_POLL_INTERVAL_SECONDS = 10.0 -GH_TIMEOUT_SECONDS = 60.0 -FIELDS = "databaseId,url,status,conclusion" - -SUCCESS = "success" -COMPLETED = "completed" - - -class GhError(Exception): - """`gh` could not be run, exited non-zero, or did not answer in time.""" - - -class Run(NamedTuple): - """One run of a workflow, as `gh` reports it.""" - - id: int - url: str - status: str - conclusion: str - - -class NeverAppeared(Exception): - """No run of the workflow was newer than the one seen before the dispatch.""" - - def __init__(self, before: int | None, last: Run | None, deadline: float): - super().__init__("no run appeared") - self.before = before - self.last = last - self.deadline = deadline - - -class DidNotFinish(Exception): - """The run was still going when the deadline passed.""" - - def __init__(self, last: Run, deadline: float): - super().__init__("the run did not finish") - self.last = last - self.deadline = deadline - - -def run_gh(argv: list[str], repository: str | None = None) -> str: - """Run one `gh` command and return its stdout, or raise `GhError`.""" - command = [GH, *argv] - if repository: - command += ["--repo", repository] - try: - done = subprocess.run( - command, - capture_output=True, - text=True, - check=False, - timeout=GH_TIMEOUT_SECONDS, - ) - except OSError as failed: - raise GhError(f"{GH} could not be run: {failed}") from failed - except subprocess.TimeoutExpired as failed: - raise GhError( - f"{GH} did not answer within {GH_TIMEOUT_SECONDS:.0f}s: {' '.join(command)}" - ) from failed - if done.returncode != 0: - detail = (done.stderr or done.stdout).strip() - raise GhError(f"{GH} exited {done.returncode}: {' '.join(command)}\n{detail}") - return done.stdout - - -def to_run(payload: dict) -> Run: - """One entry of `gh run list`/`gh run view`, normalized. - - `conclusion` is absent or null until the run completes, which is not the same - as any of the conclusions, so it becomes the empty string rather than None. - """ - conclusion = payload.get("conclusion") - return Run( - int(payload["databaseId"]), - payload.get("url") or "", - payload.get("status") or "", - conclusion if isinstance(conclusion, str) else "", - ) - - -def newest_run(repository: str | None, workflow: str) -> Run | None: - """The newest run of the workflow, or None when it has no runs at all.""" - listed = json.loads( - run_gh( - ["run", "list", "--workflow", workflow, "--limit", "1", "--json", FIELDS], - repository, - ) - ) - return to_run(listed[0]) if listed else None - - -def read_run(repository: str | None, run_id: int) -> Run: - """One read of a run by id.""" - return to_run( - json.loads(run_gh(["run", "view", str(run_id), "--json", FIELDS], repository)) - ) - - -def dispatch_run( - repository: str | None, workflow: str, ref: str, inputs: list[str] -) -> None: - """`gh workflow run --ref -f ...`, whose run id it does not print.""" - argv = ["workflow", "run", workflow, "--ref", ref] - for item in inputs: - argv += ["-f", item] - run_gh(argv, repository) - - -def wait_for_new_run( - before_id: int | None, - read_newest: Callable[[], Run | None], - deadline: float, - interval: float, -) -> Run: - """Poll until a run other than the one seen before the dispatch appears. - - The deadline is for the appearance alone: a dispatch `gh` accepted should appear - in the run list within seconds, and a workflow that never produces one is a - different failure from a deploy that runs long. - """ - started = time.monotonic() - last: Run | None = None - while True: - last = read_newest() - if last is not None and last.id != before_id: - return last - if time.monotonic() - started >= deadline: - raise NeverAppeared(before_id, last, deadline) - time.sleep(interval) - - -def wait_for_conclusion( - read_run: Callable[[], Run], deadline: float, interval: float -) -> Run: - """Poll the run until it completes, or the deadline passes with the last read.""" - started = time.monotonic() - while True: - last = read_run() - if last.status == COMPLETED: - return last - if time.monotonic() - started >= deadline: - raise DidNotFinish(last, deadline) - time.sleep(interval) - - -def input_value(inputs: list[str], key: str) -> str: - """The value of one `KEY=VALUE` dispatch input, or "" when it is absent.""" - for item in inputs: - name, _, value = item.partition("=") - if name == key: - return value - return "" - - -def gh_command(parts: list[str], repository: str | None = None) -> str: - """A `gh` command line a reader can paste, with `--repo` when one was named.""" - command = " ".join(["gh", *parts]) - if repository: - command += f" --repo {repository}" - return command - - -def redispatch_command( - workflow: str, ref: str, inputs: list[str], repository: str | None = None -) -> str: - """The `gh workflow run` that repeats the dispatch, with the same inputs.""" - parts = ["workflow", "run", workflow, "--ref", ref] - for item in inputs: - parts += ["-f", item] - return gh_command(parts, repository) - - -def log_command(run_id: int, repository: str | None = None) -> str: - """The `gh run view` that reads a failed run's log.""" - return gh_command(["run", "view", str(run_id), "--log-failed"], repository) - - -def watches(run: Run) -> str: - """The line that names the run being watched.""" - return f"watching run {run.id}: {run.url}" - - -def conclusion_report(final: Run, repository: str | None = None) -> str: - return textwrap.dedent(f"""\ - run {final.id} concluded {final.conclusion or 'without a conclusion'}: - {final.url} - Read its log with: - {log_command(final.id, repository)}""") - - -def never_appeared_report( - workflow: str, before: int | None, last: Run | None, deadline: float, dispatched: bool -) -> str: - if last is None: - saw = f"no runs of {workflow} are visible" - elif last.id == before: - since = "the dispatch" if dispatched else "the watch began" - saw = f"the newest run is still {last.id} ({last.url}), the one seen before {since}" - else: - saw = f"the newest run is {last.id} ({last.url})" - return textwrap.dedent(f"""\ - no new run of {workflow} appeared within {deadline:.0f}s{(' of the dispatch') if dispatched else ''}. - The last read: {saw}.""") - - -def did_not_finish_report(label: str, last: Run, deadline: float) -> str: - return textwrap.dedent(f"""\ - {label} did not finish within {deadline:.0f}s: - {last.url} - The last read said status={last.status or 'unknown'}.""") - - -def remains(workflow: str, ref: str, inputs: list[str], repository: str | None) -> str: - """What a reader has left when this step fails after the release is out.""" - version = input_value(inputs, "server_version") - released = ( - f"v{version} is tagged and published, and its image exists" - if version - else "it is tagged and published" - ) - return textwrap.dedent(f"""\ - What remains: - the release is already out — {released}. The public demo did not take it, and - this step cannot move it further. The dispatch above is the button that moves - the demo, and its run is the next thing to read; re-dispatch it with: - {redispatch_command(workflow, ref, inputs, repository)}""") - - -def dispatch_mode(args: argparse.Namespace) -> int: - repository = args.repo - workflow = args.workflow - read_newest = partial(newest_run, repository, workflow) - - try: - before = read_newest() - except GhError as failed: - print(f"cannot read {workflow}'s runs before dispatching: {failed}", file=sys.stderr) - return 1 - try: - dispatch_run(repository, workflow, args.ref, args.inputs) - except GhError as failed: - print(f"could not dispatch {workflow}: {failed}", file=sys.stderr) - return 1 - - try: - run = wait_for_new_run( - before.id if before else None, - read_newest, - args.appear_deadline, - args.poll_interval, - ) - except NeverAppeared as failed: - print( - never_appeared_report( - workflow, failed.before, failed.last, failed.deadline, dispatched=True - ), - file=sys.stderr, - ) - print(remains(workflow, args.ref, args.inputs, repository), file=sys.stderr) - return 1 - except GhError as failed: - print(f"lost contact with gh after dispatching {workflow}: {failed}", file=sys.stderr) - return 1 - return watch_to_conclusion(args, run) - - -def watch_to_conclusion(args: argparse.Namespace, run: Run) -> int: - repository = args.repo - workflow = args.workflow - # A run named by `--run-id` is not necessarily one of `--workflow`'s — the - # default names this repository's deploy — so only a dispatch or a watch of a - # workflow gets to name it. - label = f"{workflow} run {run.id}" if (args.dispatch or args.watch_next) else f"run {run.id}" - print(watches(run), flush=True) - try: - final = wait_for_conclusion( - partial(read_run, repository, run.id), args.deadline, args.poll_interval - ) - except DidNotFinish as failed: - print( - did_not_finish_report(label, failed.last, failed.deadline), - file=sys.stderr, - ) - if args.dispatch: - print(remains(workflow, args.ref, args.inputs, repository), file=sys.stderr) - return 1 - except GhError as failed: - print(f"lost contact with gh while watching run {run.id}: {failed}", file=sys.stderr) - return 1 - - if final.conclusion != SUCCESS: - print(conclusion_report(final, repository), file=sys.stderr) - if args.dispatch: - print(remains(workflow, args.ref, args.inputs, repository), file=sys.stderr) - return 1 - print(f"{label} concluded {SUCCESS}: {final.url}") - return 0 - - -def main(argv: list[str] | None = None) -> int: - parser = argparse.ArgumentParser( - description=__doc__.splitlines()[0], - formatter_class=argparse.RawDescriptionHelpFormatter, - ) - parser.add_argument( - "--repo", default=None, help="OWNER/NAME; without it, gh resolves the checkout" - ) - parser.add_argument("--workflow", default=DEFAULT_WORKFLOW) - parser.add_argument("--ref", default=DEFAULT_REF) - mode = parser.add_mutually_exclusive_group(required=True) - mode.add_argument("--run-id", type=int, help="watch this run; dispatch nothing") - mode.add_argument( - "--dispatch", action="store_true", help="dispatch, then watch the run it creates" - ) - mode.add_argument( - "--watch-next", - action="store_true", - help="wait for the next run of --workflow; dispatch nothing", - ) - parser.add_argument( - "--deadline", type=float, default=DEFAULT_DEADLINE_SECONDS, - help="seconds to wait for the run to conclude", - ) - parser.add_argument( - "--appear-deadline", type=float, default=DEFAULT_APPEAR_DEADLINE_SECONDS, - help="seconds to wait for a dispatched run to appear", - ) - parser.add_argument("--poll-interval", type=float, default=DEFAULT_POLL_INTERVAL_SECONDS) - parser.add_argument( - "-f", "--input", dest="inputs", action="append", default=[], metavar="KEY=VALUE" - ) - args = parser.parse_args(argv) - - if args.dispatch: - return dispatch_mode(args) - - repository = args.repo - workflow = args.workflow - if args.run_id is not None: - try: - run = read_run(repository, args.run_id) - except GhError as failed: - print(f"cannot read run {args.run_id}: {failed}", file=sys.stderr) - return 1 - return watch_to_conclusion(args, run) - - read_newest = partial(newest_run, repository, workflow) - try: - before = read_newest() - except GhError as failed: - print(f"cannot read {workflow}'s runs: {failed}", file=sys.stderr) - return 1 - try: - run = wait_for_new_run( - before.id if before else None, - read_newest, - args.appear_deadline, - args.poll_interval, - ) - except NeverAppeared as failed: - print( - never_appeared_report( - workflow, failed.before, failed.last, failed.deadline, dispatched=False - ), - file=sys.stderr, - ) - return 1 - except GhError as failed: - print(f"lost contact with gh while waiting for {workflow}: {failed}", file=sys.stderr) - return 1 - return watch_to_conclusion(args, run) - - -if __name__ == "__main__": - sys.exit(main()) From 5efae53bb286798e0b4cc2f619f222977d99111c Mon Sep 17 00:00:00 2001 From: DontBlameMe Date: Thu, 19 Nov 2026 22:43:00 +0100 Subject: [PATCH 2/2] docs: correct the release wait comment The deploy step is gone; the following step waits only for the published image. --- .github/workflows/release.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 80710da..eb7e0a7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -279,8 +279,7 @@ jobs: gh workflow run image.yml --ref "$tag" # A green `publish` job is not the image existing: the run is queued before - # the build starts, and the deploy below names a tag that has to be in the - # registry by then. So this waits on the registry itself, anonymously, and a + # the build starts, so this waits on the registry itself, anonymously, and a # deadline that cannot pass says what it last saw rather than looking hung. - name: wait for the image this release published env: