PaperMC build numbers

A small authenticated Cloudflare Worker that allocates monotonically increasing build numbers. One SQLite Durable Object stores all tracks, allowing them to be enumerated centrally.

Every successful allocation request consumes a number. There is intentionally no idempotency or retry handling.

API

All routes require Authorization: Bearer <token>.

List tracks

GET /v1/tracks

{ "tracks": [{ "track": "paper-26.2", "number": 1 }] }

Create a track

PUT /v1/tracks/:track
Content-Type: application/json

{"number":123}

number is required and represents the track's current or last-used build number; the next allocation returns 124. Use 0 when explicitly creating a fresh track. Creation returns 409 if the track already exists, so this cannot be used to rewrite its current number.

Allocate a number

POST /v1/tracks/:track/next

{ "track": "paper-26.2", "number": 1 }

Allocating from an unknown track creates it automatically and returns 1.

Read the current number

GET /v1/tracks/:track

An uninitialized track returns 404.

Delete a track

DELETE /v1/tracks/:track

Deletion is permanent and returns 404 if the track does not exist.

Track names are URL-encoded UTF-8 strings between 1 and 256 bytes. Control characters are rejected.

Development

pnpm install
cp .dev.vars.example .dev.vars
pnpm dev

Run checks with:

pnpm check

Deployment

An administrator must bootstrap the Worker from an authenticated checkout before connecting Workers Builds. Generate a high-entropy token, place it in an ignored .env.production file, and perform the initial deployment:

openssl rand -hex 32
printf 'AUTH_TOKEN=replace-with-generated-token\n' > .env.production
pnpm exec wrangler deploy --secrets-file .env.production
rm .env.production

Then, in the Worker's Cloudflare dashboard, an administrator should connect this Git repository under Settings > Build and configure:

• Production branch: main
• Build command: pnpm build
• Deploy command: pnpm deploy
• Non-production branch deployments: disabled

The Git connection and Workers Builds settings cannot be configured through wrangler.jsonc. AUTH_TOKEN is a runtime secret under Variables & Secrets, not a Workers Builds secret. The initial deployment configures it, and subsequent Workers Builds deployments preserve it. It can be rotated through the dashboard or wrangler secret put AUTH_TOKEN.

Non-production deployments should remain disabled so preview versions cannot allocate numbers from the production Durable Object.

For a GitHub Actions job, derive the track from the build and expose it as a step output. The allocation step can then fetch a number and expose it to later steps:

- name: Determine build number track
  id: build_number_track
  run: |
    track="$(./gradlew -q printBuildTrack)"
    echo "track=$track" >> "$GITHUB_OUTPUT"

- name: Allocate build number
  env:
    BUILD_NUMBER_TOKEN: ${{ secrets.BUILD_NUMBER_TOKEN }}
    BUILD_NUMBER_TRACK: ${{ steps.build_number_track.outputs.track }}
  run: |
    number="$(
      curl --fail-with-body -X POST \
        -H "Authorization: Bearer $BUILD_NUMBER_TOKEN" \
        "https://build-numbers.example.com/v1/tracks/$BUILD_NUMBER_TRACK/next" \
      | jq -er '.number'
    )"
    echo "BUILD_NUMBER=$number" >> "$GITHUB_ENV"

Do not enable automatic HTTP retries unless skipped numbers are acceptable.