test(consistency): exercise the Azure backend against Azurite

Adds an Azurite service and a scenario that audits the Azure backend
through `?storage=azurite`. It is the only coverage of that code path in
the tree: `AzureBlobBackend` has unit tests for its name parser and
ordering, but nothing else speaks the protocol, and a paid account is
not an option for CI. Azurite implements the real Blob REST API, so this
exercises SharedKey signing, prefix/marker paging, and the 256-way shard
walk with its termination.

## Harness

`docker-compose.test.yml` gains an azurite service on 10000 (tmpfs, so
it dies with the stack). `spawn-db.sh` provisions the container itself,
because `AzureBlobBackend::initialize` verifies rather than creates —
signed by hand with curl + openssl rather than pulling a ~700 MB `az`
image for one PUT. Two traps are commented there: the account key is
base64 but HMAC wants raw bytes, and the canonicalized resource repeats
the account name (`/{acc}/{acc}/{container}`) because the emulator puts
in the path what real Azure puts in the host. Getting that wrong yields
403, not a hint.

The `azurite` entry is declared in `server.env` but never activated, so
the suite's active backend stays local and only this file reaches Azure.

## What it asserts, and what it cannot

A failure surfaces as `ok: false`, because an enumeration error now
fails the run rather than degrading to a per-row probe.

It deliberately asserts no finding count. The container starts empty and
the job's grace window is an hour, so a freshly-uploaded blob is skipped
in both directions by design — an audit here can only report zero, and
"zero findings" would pass whether enumeration worked or returned
nothing. The one positive assert, `scanned_count != 0`, therefore sits
on the local control, which does hold blobs; `scanned_count` accumulates
via `checkpoint`, which the empty-page early return skips.

## No cutover, deliberately

Putting real bytes in the container means `backend_migration
?storage=azurite`, which hangs on the first blob: `head_check` issues a
~40-byte ranged GET, `azure_core` 0.21 attaches
`x-ms-range-get-content-crc64` to anything under 4 MiB, Azurite 500s,
and the deterministic error is retried forever while
`migration_readonly` refuses writes app-wide. The full chain and the
rejected workaround are in the file header. The scenario is still
ordered last in `run.sh` — it is the only one needing a second service,
and the cutover comes back there once the official SDK lands.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

tests/common/docker-compose.test.yml

@@ -14,3 +14,32 @@ services:
       interval: 2s
       timeout: 5s
       retries: 10
+
+  # Azure Blob Storage emulator. Speaks the real Blob REST API, so it is
+  # the only way to exercise the Azure backend without an account — and
+  # the account it does ship is the fixed, publicly-documented dev pair
+  # (`devstoreaccount1` + the well-known key), so nothing here is a
+  # credential worth protecting.
+  #
+  # Blob service only: `--blobHost` with no queue/table, since the backend
+  # uses blobs exclusively and the other two would just be open ports.
+  #
+  # tmpfs for the same reason postgres uses it — a run must start from an
+  # empty container, or a previous run's blobs read as orphans in the very
+  # audit this exists to test.
+  azurite-test:
+    image: mcr.microsoft.com/azure-storage/azurite:3.36.0
+    command: azurite-blob --blobHost 0.0.0.0 --blobPort 10000 --location /data --skipApiVersionCheck
+    ports:
+      - "10000:10000"
+    tmpfs:
+      - /data
+    healthcheck:
+      # Azurite answers 400 to an unauthenticated root GET, which is proof
+      # enough that the HTTP listener is up — the SDK handshake is what
+      # validates credentials, and that happens later in the backend's
+      # own `initialize`.
+      test: ["CMD-SHELL", "nc -z 127.0.0.1 10000 || exit 1"]
+      interval: 2s
+      timeout: 5s
+      retries: 15

tests/common/server.env

@@ -42,7 +42,7 @@ OXICLOUD_NEXTCLOUD_ENABLED=true
 # `s3_stub` is declared but never activated — it lets storage_config.hurl
 # assert the entries table has more than one row without needing a
 # real S3 backend.
-OXICLOUD_STORAGE_ENTRIES=local_main,s3_stub
+OXICLOUD_STORAGE_ENTRIES=local_main,s3_stub,azurite
 OXICLOUD_STORAGE_local_main_BACKEND=local
 OXICLOUD_STORAGE_s3_stub_BACKEND=s3
 OXICLOUD_STORAGE_s3_stub_S3_BUCKET=oxicloud-test-stub
@@ -51,6 +51,24 @@ OXICLOUD_STORAGE_s3_stub_S3_ENDPOINT_URL=http://127.0.0.1:9999
 OXICLOUD_STORAGE_s3_stub_S3_ACCESS_KEY=stub
 OXICLOUD_STORAGE_s3_stub_S3_SECRET_KEY=stub
 
+# `azurite` — a REAL, reachable Azure backend, unlike `s3_stub` above.
+# It points at the Azurite emulator started by spawn-db.sh, which speaks
+# the actual Blob REST API, so this is the only way to exercise the Azure
+# path without an account.
+#
+# Declared but NOT activated: the active backend stays local_main, so the
+# rest of the suite is untouched. Tests reach it explicitly through
+# `?storage=azurite` on the jobs that accept an entry name — which is
+# exactly what that parameter was added for.
+#
+# The credentials are Azurite's fixed, publicly-documented development
+# pair. They are in every Microsoft quickstart; nothing here is secret.
+OXICLOUD_STORAGE_azurite_BACKEND=azure
+OXICLOUD_STORAGE_azurite_AZURE_ACCOUNT_NAME=devstoreaccount1
+OXICLOUD_STORAGE_azurite_AZURE_ACCOUNT_KEY=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==
+OXICLOUD_STORAGE_azurite_AZURE_CONTAINER=oxicloud-test
+OXICLOUD_STORAGE_azurite_AZURE_ENDPOINT_URL=http://127.0.0.1:10000/devstoreaccount1
+
 RUST_LOG="warn,audit=info,sqlx::migrate=info"
 #RUST_LOG="warn,audit=info,oxicloud::quota=debug"
 #RUST_LOG=debug

tests/common/spawn-db.sh

@@ -52,7 +52,57 @@ wait_for_postgres_ready() {
   exit 1
 }
 
-echo "[setup] Starting test postgres..."
+# Create the blob container Azurite serves.
+#
+# `AzureBlobBackend::initialize` VERIFIES the container exists and fails
+# with a 404 if it does not — it deliberately does not create one, since
+# auto-creating would turn a typo'd container name into a silently
+# working empty container. So the harness provisions it, exactly as an
+# operator would in production.
+#
+# Signed by hand rather than shelling out to the Azure CLI: `az` would
+# mean pulling a ~700 MB image into every CI run to issue one PUT. This
+# needs only curl and openssl, both already required.
+#
+# Two things make this fiddly enough to be worth commenting:
+#   * The key is base64 and HMAC needs raw bytes, so it is decoded and
+#     re-encoded as hex for `-macopt hexkey:`.
+#   * The canonicalized resource repeats the account name —
+#     `/{account}/{account}/{container}` — because the emulator puts the
+#     account in the URL path where real Azure puts it in the host. This
+#     is the classic Azurite signing trap; getting it wrong yields 403,
+#     not a hint.
+#
+# Idempotent by result: a second run gets 409 ContainerAlreadyExists,
+# which is success for our purposes.
+create_azurite_container() {
+  local acc=devstoreaccount1
+  local cont=oxicloud-test
+  # Azurite's fixed development key — hardcoded in the image, published
+  # by Microsoft, and valid against nothing but a local emulator.
+  local key='Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw=='
+  local ver=2021-08-06
+  local date_hdr hexkey sts sig code
+  date_hdr=$(LC_ALL=C TZ=GMT date '+%a, %d %b %Y %H:%M:%S GMT')
+  hexkey=$(printf '%s' "$key" | base64 -d | od -An -tx1 | tr -d ' \n')
+  # Twelve leading empty lines are the unused standard headers
+  # (Content-*, Date, If-*, Range) the SharedKey scheme requires in
+  # fixed positions.
+  sts="PUT\n\n\n\n\n\n\n\n\n\n\n\nx-ms-date:${date_hdr}\nx-ms-version:${ver}\n/${acc}/${acc}/${cont}\nrestype:container"
+  sig=$(printf '%b' "$sts" | openssl dgst -sha256 -mac HMAC -macopt "hexkey:${hexkey}" -binary | base64)
+  code=$(curl -s -o /dev/null -w '%{http_code}' -X PUT \
+    -H "x-ms-date: ${date_hdr}" \
+    -H "x-ms-version: ${ver}" \
+    -H "Authorization: SharedKey ${acc}:${sig}" \
+    "http://127.0.0.1:10000/${acc}/${cont}?restype=container" 2>/dev/null)
+  case "$code" in
+    201) echo "[setup] Azurite container '${cont}' created." ;;
+    409) echo "[setup] Azurite container '${cont}' already exists." ;;
+    *)   echo "[setup] WARNING: could not create Azurite container '${cont}' (HTTP ${code}) — Azure-backed tests will fail." >&2 ;;
+  esac
+}
+
+echo "[setup] Starting test postgres + azurite..."
 docker compose -f "$COMPOSE_FILE" down -v 2>/dev/null || true
 docker compose -f "$COMPOSE_FILE" up -d
 echo "[setup] Waiting for postgres on port 5433..."
@@ -60,3 +110,34 @@ wait_for_port 127.0.0.1 5433
 echo "[setup] Waiting for postgres to accept queries..."
 wait_for_postgres_ready
 echo "[setup] Postgres is ready."
+
+# Azurite backs the `azurite` storage entry, which `backend_consistency`
+# audits via `?storage=azurite`. Only a port wait: the entry is declared
+# but never activated, so nothing in the suite touches it until a test
+# names it, and by then the listener has had the whole server boot to
+# settle. A failure here should not take down a run that mostly does not
+# use it — so this warns rather than exits, and the Azure test fails on
+# its own terms with a clearer message than "setup timed out".
+#
+# Its own loop rather than `wait_for_port`: that helper calls `exit 1` on
+# timeout, and `exit` inside a function ends the script whatever context
+# it was called from — so wrapping it in an `if` would not degrade, it
+# would just fail later and less clearly.
+echo "[setup] Waiting for azurite on port 10000..."
+azurite_deadline=$(( $(date +%s) + 30 ))
+until nc -z 127.0.0.1 10000 2>/dev/null; do
+  if [[ $(date +%s) -ge $azurite_deadline ]]; then
+    echo "[setup] WARNING: azurite did not come up — Azure-backed tests will fail." >&2
+    break
+  fi
+  sleep 0.5
+done
+if nc -z 127.0.0.1 10000 2>/dev/null; then
+  # Port open only means the listener is up — NOT that the tests can use
+  # it. Saying "ready" here was misleading: the container was still
+  # missing, so the first Azure job failed with a 404 while setup had
+  # already reported success. `create_azurite_container` is what makes
+  # the claim true, so it is the one that gets to announce it.
+  echo "[setup] Azurite listening; provisioning container..."
+  create_azurite_container
+fi