@rexezuge/tooling 0.0.0-stage → 1.0.1

package/src/functions/pages-proxy.ts

@@ -0,0 +1,187 @@
+/**
+ * The Cloudflare Pages catch-all proxy.
+ *
+ * Provenance: the `functions/[[path]].ts` shim duplicated in Durable-DAV,
+ * Mail-Meow and Edge-Git (and present in nine repos in total). Each copy is an
+ * `onRequest` handler that forwards the request to the API worker through a
+ * service binding, rewriting the three headers the worker routes on.
+ *
+ * What each source contributes:
+ *
+ * - **Durable-DAV / Edge-Git** — the core shape: set `X-Forwarded-Host`,
+ *   `X-Forwarded-Proto` and `X-Forwarded-Uri` from the original URL, forward the
+ *   body for non-GET/HEAD methods, and hand the request to `env.API_WORKER`.
+ * - **Mail-Meow** — the hop-by-hop header strip, and the decision to *always*
+ *   delete `X-Forwarded-For` before conditionally setting it from
+ *   `CF-Connecting-IP`. Setting it only when the header was present left a
+ *   caller-supplied value intact on any request that reached Pages without
+ *   `CF-Connecting-IP`, so the origin would trust an attacker-chosen client IP.
+ * - **Durable-DAV-Router** — `duplex: 'half'`, required whenever the forwarded
+ *   body is a stream. Without it this threw a `TypeError` on every non-GET
+ *   request rather than proxying it.
+ * - **Edge-Sonic** — the client-forwarding-header strip list, which additionally
+ *   removes `Forwarded`, `True-Client-IP` and `X-Real-Ip`. Edge-Sonic goes
+ *   further and *never* sets `X-Forwarded-For` at all, because its worker keys
+ *   the rate limiter on `CF-Connecting-IP` and refuses `X-Forwarded-For` on
+ *   purpose.
+ *
+ * ### The convergence decision on `X-Forwarded-For`
+ *
+ * The two families disagree, and the disagreement is about which worker is
+ * behind the binding. Mail-Meow's behaviour is kept as the default because it is
+ * the only one that preserves the client IP for the audit trail, which five repos
+ * read. A repo whose worker refuses the header — Edge-Sonic's — passes
+ * `forwardClientIp: false`, which deletes it and sets nothing. What is *not*
+ * available is the source repos' conditional `if (clientIp) set(...)`: that is
+ * the defect Mail-Meow recorded fixing, and a factory that could reintroduce it
+ * would be a factory that carries the bug forward.
+ *
+ * ### `duplex: 'half'` rides with the body
+ *
+ * Required by the Fetch spec whenever a `Request` is constructed with a **stream**
+ * body. workerd does not throw without it, which is why the line was absent from
+ * every Pages copy — and Node does, which is why `test/pages-proxy.test.ts` in
+ * Edge-Sonic could not drive the handler at all. It is spread only where a body
+ * is forwarded, because a `RequestInit` carrying `duplex` and no body is a shape
+ * no runtime documents; the cast is `as RequestInit` either way, since `duplex`
+ * is not in the DOM lib's type.
+ *
+ * The result is a handler factory, so a consumer's `functions/[[path]].ts` is a
+ * one-line re-export. Structural `Fetcher` and `PagesFunction` types are declared
+ * here rather than imported from `@cloudflare/workers-types`, so the kit stays
+ * zero-dependency and this module typechecks without the generated
+ * `worker-configuration.d.ts`.
+ */
+
+/**
+ * The subset of Cloudflare's `Fetcher` this proxy uses.
+ *
+ * Structural, not imported: the shim only ever calls `fetch`, and requiring
+ * `@cloudflare/workers-types` for one method would couple the kit to a generated
+ * types file that only exists inside a Wrangler project.
+ */
+export interface Fetcher {
+  fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * The environment a Pages Function is invoked with.
+ */
+export interface PagesProxyEnv {
+  readonly API_WORKER: Fetcher;
+}
+
+/**
+ * The context Cloudflare passes to `onRequest`.
+ *
+ * Only the fields this proxy reads are declared. `params` and `waitUntil` are
+ * omitted because the catch-all does not use them — a shim that named them would
+ * be claiming a contract it does not exercise.
+ */
+export interface PagesFunctionContext {
+  readonly request: Request;
+  readonly env: PagesProxyEnv;
+}
+
+/**
+ * A Pages Function handler.
+ */
+export type PagesFunction = (context: PagesFunctionContext) => Promise<Response>;
+
+/**
+ * Headers a *client* may have set, stripped before the request crosses the
+ * binding.
+ *
+ * These describe the connection between the client and the proxy. Forwarding
+ * them would let the origin believe the proxy's view of the client is the
+ * client's own claim about itself. The three the proxy sets itself are set from
+ * values it reads off the request, not from the client's headers.
+ */
+const CLIENT_FORWARDING_HEADERS: readonly string[] = [
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+  'X-Forwarded-For',
+  'X-Forwarded-Host',
+  'X-Forwarded-Proto',
+  'X-Forwarded-Uri',
+  'Forwarded',
+  'True-Client-IP',
+  'X-Real-Ip',
+];
+
+/** The header Cloudflare sets with the socket's peer address. */
+const CF_CONNECTING_IP_HEADER = 'CF-Connecting-IP';
+
+/**
+ * What `createPagesProxy` accepts.
+ */
+export interface PagesProxyOptions {
+  /**
+   * Set `X-Forwarded-For` from `CF-Connecting-IP`.
+   *
+   * Default `true` — Mail-Meow's behaviour, which five repos rely on for their
+   * audit trail. Pass `false` for a worker that refuses the header outright
+   * (Edge-Sonic's does), and the header is deleted and nothing set.
+   */
+  readonly forwardClientIp?: boolean;
+}
+
+/**
+ * The `onRequest` handler for `functions/[[path]].ts`.
+ *
+ * Usage — the consumer's `functions/[[path]].ts` becomes two lines:
+ *
+ * ```ts
+ * import { createPagesProxy } from '@rexezuge/tooling/functions/pages-proxy';
+ * export const onRequest = createPagesProxy();
+ * ```
+ *
+ * @param options see {@link PagesProxyOptions}. Omitted gives the family's
+ *   majority behaviour.
+ */
+export function createPagesProxy(options: PagesProxyOptions = {}): PagesFunction {
+  const forwardClientIp = options.forwardClientIp ?? true;
+
+  return async ({ request, env }: PagesFunctionContext): Promise<Response> => {
+    const originalUrl: URL = new URL(request.url);
+
+    const headers: Headers = new Headers(request.headers);
+    for (const header of CLIENT_FORWARDING_HEADERS) headers.delete(header);
+
+    // Set from values read off the request rather than from the client: only the
+    // proxy knows which host it served, and a service binding hands over a
+    // rewritten URL, so the original path is what has to be carried across.
+    headers.set('X-Forwarded-Host', originalUrl.host);
+    headers.set('X-Forwarded-Proto', originalUrl.protocol.replace(':', ''));
+    headers.set('X-Forwarded-Uri', `${originalUrl.pathname}${originalUrl.search}`);
+
+    if (forwardClientIp) {
+      const clientIp: string | null = request.headers.get(CF_CONNECTING_IP_HEADER);
+      if (clientIp) headers.set('X-Forwarded-For', clientIp);
+    }
+
+    // `GET`/`HEAD` carry no body, and a `Request` with one is rejected outright
+    // for those methods. The body is forwarded as a *stream*, so a large upload
+    // does not have to fit in memory on the Pages side.
+    const hasBody: boolean = request.method !== 'GET' && request.method !== 'HEAD';
+
+    const proxyRequest: Request = new Request(originalUrl.href, {
+      method: request.method,
+      headers,
+      body: hasBody ? request.body : undefined,
+      // See the header: `duplex` is not in the DOM lib's `RequestInit` type, and
+      // removing the cast would mean not forwarding bodies at all, which is a
+      // worse answer than one assertion.
+      ...(hasBody && { duplex: 'half' }),
+      redirect: request.redirect,
+    } as RequestInit);
+
+    return env.API_WORKER.fetch(proxyRequest);
+  };
+}

package/src/github/actions/retry-step/action.yml

@@ -0,0 +1,39 @@
+name: Retry Step
+description: Retry a bash command on failure
+
+inputs:
+  command:
+    description: The bash command to run
+    required: true
+  max_attempts:
+    description: Maximum number of attempts
+    required: false
+    default: '3'
+  delay:
+    description: Seconds to wait between attempts
+    required: false
+    default: '10'
+
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: |
+        attempt=0
+        max=${{ inputs.max_attempts }}
+        delay=${{ inputs.delay }}
+        while true; do
+          attempt=$(( attempt + 1 ))
+          printf '::notice title=Retry Step::Attempt %d of %d\n' "$attempt" "$max"
+          if eval "$RETRY_COMMAND"; then
+            exit 0
+          fi
+          if [ "$attempt" -ge "$max" ]; then
+            printf '::error title=Retry Step::Command failed after %d attempts\n' "$max"
+            exit 1
+          fi
+          printf '::warning title=Retry Step::Command failed, retrying in %ds...\n' "$delay"
+          sleep "$delay"
+        done
+      env:
+        RETRY_COMMAND: ${{ inputs.command }}

package/src/github/actions/setup-env/action.yml

@@ -0,0 +1,20 @@
+name: Setup Environment
+description: Install pnpm, set up Node.js with pnpm store cache, and install workspace dependencies
+
+runs:
+  using: composite
+  steps:
+    - name: Install pnpm
+      uses: pnpm/action-setup@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '24'
+        cache: pnpm
+
+    - name: Install Dependencies
+      uses: ./.github/actions/retry-step
+      with:
+        command: pnpm install
+        max_attempts: '3'

package/src/github/dependabot.yml

@@ -0,0 +1,30 @@
+# Dependabot — weekly dependency updates, grouped so one PR covers the
+# toolchain rather than twelve separate ones. @rexezuge/* updates land in
+# their own group, which is the kit's upgrade path: a bump PR per repo, and
+# the repo's own CI is the gate.
+
+version: 2
+updates:
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    open-pull-requests-limit: 5
+    labels:
+      - 'dependencies'
+    groups:
+      kit:
+        patterns:
+          - '@rexezuge/*'
+      toolchain:
+        patterns:
+          - 'typescript'
+          - 'vitest'
+          - 'vite'
+          - 'eslint'
+          - 'typescript-eslint'
+          - 'prettier'
+          - 'wrangler'
+      cloudflare:
+        patterns:
+          - '@cloudflare/*'

package/src/github/workflows/backup-main.yml

@@ -0,0 +1,46 @@
+# Backup Main Branch — mirror the repository to secondary git forges.
+#
+# Converged from the family's backup-main.yml. Destinations are opt-in by
+# secret: with neither BACKUP_REPO_AZURE_DEVOPS_SSH_KEY nor
+# BACKUP_REPO_GITLAB_* configured, the check job reports both false and every
+# downstream job is skipped. Push to main seeds the mirror; the monthly
+# schedule re-verifies it.
+
+name: Backup Main Branch
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: '0 0 5 * *'
+
+jobs:
+  check-secrets:
+    name: Check Secrets
+    runs-on: ubuntu-latest
+    outputs:
+      azure-configured: ${{ steps.check.outputs.azure }}
+      gitlab-configured: ${{ steps.check.outputs.gitlab }}
+    steps:
+      - name: Detect Configured Destinations
+        id: check
+        env:
+          AZURE_KEY: ${{ secrets.BACKUP_REPO_AZURE_DEVOPS_SSH_KEY }}
+          AZURE_URL: ${{ secrets.BACKUP_REPO_AZURE_DEVOPS_REPO_URL }}
+          GITLAB_KEY: ${{ secrets.BACKUP_REPO_GITLAB_SSH_KEY }}
+          GITLAB_URL: ${{ secrets.BACKUP_REPO_GITLAB_REPO_URL }}
+        run: |
+          if [ -n "$AZURE_KEY" ] && [ -n "$AZURE_URL" ]; then
+            echo "azure=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "azure=false" >> "$GITHUB_OUTPUT"
+          fi
+          if [ -n "$GITLAB_KEY" ] && [ -n "$GITLAB_URL" ]; then
+            echo "gitlab=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "gitlab=false" >> "$GITHUB_OUTPUT"
+          fi

package/src/github/workflows/continuous-deployment.yml

@@ -0,0 +1,188 @@
+# Continuous Deployment — deploy the worker after CI passes on main.
+#
+# Converged from the eight repos that deploy (Records-Provider and CalDAV-Bridge
+# deploy differently and are left out of this merge). The shape: a `workflow_run`
+# trigger so the deploy runs against the SHA CI actually approved, then the
+# wrangler config materialized from the template — no committed secrets — then the
+# secrets provisioned, then the database migrated, then a dry run as a gate, then
+# the deploy.
+#
+# PLACEHOLDERS:
+#   * REPLACE_ME_SCOPE      the npm scope, in `pnpm --filter @REPLACE_ME_SCOPE/web build`.
+#   * REPLACE_ME_D1_BINDING the D1 binding `wrangler d1 migrations apply` targets.
+#   * REPLACE_ME_PAGES      the Cloudflare Pages project name, for repos with a SPA.
+#
+# The two workspace variables the config step reads (`WRANGLER_JSONC`,
+# `WRANGLER_PATCH_JSON`, `WRANGLER_VARS_PATCH_JSON`) are how a repo with several
+# environments supplies per-environment settings without a second template file.
+
+name: Continuous Deployment
+
+permissions:
+  contents: read
+
+on:
+  workflow_run:
+    workflows:
+      - Continuous Integration
+    branches:
+      - main
+    types:
+      - completed
+  repository_dispatch:
+    types:
+      - Upstream Sync Deployment
+  workflow_dispatch:
+
+concurrency:
+  group: continuous-deployment-${{ github.event.workflow_run.head_branch || github.event.client_payload.branch || github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  deploy-worker:
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    name: Deploy Cloudflare Worker
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+        with:
+          # The SHA CI approved, not the tip of main: a push that lands while the
+          # workflow_run is in flight must not be what gets deployed.
+          ref: ${{ github.event.workflow_run.head_sha || github.event.client_payload.sha || github.sha }}
+
+      - name: Setup Environment
+        uses: ./.github/actions/setup-env
+
+      - name: Prepare Wrangler Configuration
+        uses: ./.github/actions/retry-step
+        with:
+          command: pnpm exec tsx scripts/prepare-wrangler-config.ts
+          max_attempts: '3'
+        env:
+          WRANGLER_JSONC: ${{ vars.WRANGLER_JSONC }}
+          WRANGLER_PATCH_JSON: ${{ vars.WRANGLER_PATCH_JSON }}
+          WRANGLER_VARS_PATCH_JSON: ${{ vars.WRANGLER_VARS_PATCH_JSON }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+      # A `secrets_store_secrets` binding fails the deploy unless the named secret
+      # already exists. Nothing creates it — Cloudflare will not generate a value —
+      # so this is the only thing standing between a fresh account and a deploy that
+      # cannot succeed. Create-if-absent: an existing value still seals every stored
+      # credential and is never replaced by a redeploy.
+      - name: Initialize Cloudflare Secrets
+        uses: ./.github/actions/retry-step
+        with:
+          command: pnpm exec tsx scripts/init-secrets.ts
+          max_attempts: '3'
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+      # PLACEHOLDER: the D1 binding to migrate.
+      - name: Apply Database Migration
+        uses: ./.github/actions/retry-step
+        with:
+          command: pnpm exec wrangler d1 migrations apply REPLACE_ME_D1_BINDING --remote
+          max_attempts: '3'
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+      # PLACEHOLDER: the workspace filter for the SPA. The API worker serves the
+      # shell this build embeds, so the build is a precondition of the deploy, not
+      # a convenience.
+      - name: Build Web App
+        run: pnpm --filter @REPLACE_ME_SCOPE/web build
+
+      # A gate, not a rehearsal. Separate from the deploy below and deliberately
+      # **not** retried: a dry run that fails is a real defect — a bundle over the
+      # size limit, a binding the template no longer declares — and retrying it
+      # three times only delays the report while making the log harder to read.
+      - name: Dry Run Deploy with Wrangler
+        run: pnpm exec wrangler deploy --dry-run
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+      - name: Deploy with Wrangler
+        uses: ./.github/actions/retry-step
+        with:
+          command: pnpm exec wrangler deploy
+          max_attempts: '3'
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+  # Repos with a Pages front end keep this job; it is the reason
+  # `functions/[[path]].ts` exists — Pages serves `dist/` as static files, and
+  # `/user/...` would resolve to a 404 without the catch-all proxy to the worker.
+  deploy-pages:
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    name: Deploy Cloudflare Pages
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha || github.event.client_payload.sha || github.sha }}
+
+      - name: Setup Environment
+        uses: ./.github/actions/setup-env
+
+      # PLACEHOLDER: the workspace filter for the SPA.
+      - name: Build Frontend
+        run: pnpm --filter @REPLACE_ME_SCOPE/web build
+
+      - name: Configure Pages Service Bindings
+        run: cp apps/web/wrangler.template.jsonc wrangler.jsonc
+
+      # PLACEHOLDER: the Pages project name. Created if absent, and then polled
+      # until it is visible, because a project that exists but is not yet listed
+      # makes the deploy below fail with an error that names the deploy rather
+      # than the propagation delay.
+      - name: Ensure Pages Project Exists
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          PROJECT: ${{ vars.CLOUDFLARE_PAGES_PROJECT_NAME || 'REPLACE_ME_PAGES' }}
+          DEPLOY_BRANCH: ${{ github.event.workflow_run.head_branch || github.event.client_payload.branch || github.ref_name }}
+        run: |
+          if CREATE_OUTPUT="$(pnpm exec wrangler pages project create "${PROJECT}" --production-branch "${DEPLOY_BRANCH}" 2>&1)"; then
+            echo "Created Pages project \"${PROJECT}\"."
+          elif echo "${CREATE_OUTPUT}" | grep -qi "already exists"; then
+            echo "Pages project \"${PROJECT}\" already exists."
+          else
+            echo "${CREATE_OUTPUT}"
+            echo "Failed to create Pages project \"${PROJECT}\"." >&2
+            exit 1
+          fi
+          for _ in $(seq 1 18); do
+            if pnpm exec wrangler pages project list 2>/dev/null | grep -qE "(^|[[:space:]])${PROJECT}([[:space:]]|$)"; then
+              echo "Pages project \"${PROJECT}\" is ready."
+              exit 0
+            fi
+            sleep 5
+          done
+          echo "Pages project \"${PROJECT}\" is still not visible after polling." >&2
+          exit 1
+
+      - name: Deploy with Wrangler Pages
+        uses: ./.github/actions/retry-step
+        with:
+          command: >
+            pnpm exec wrangler pages deploy apps/web/dist
+            --project-name "${PROJECT}"
+            --branch "${DEPLOY_BRANCH}"
+            --commit-hash "${DEPLOY_SHA}"
+            --commit-message "$(git log -1 --pretty=%s)"
+          max_attempts: '3'
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          PROJECT: ${{ vars.CLOUDFLARE_PAGES_PROJECT_NAME || 'REPLACE_ME_PAGES' }}
+          DEPLOY_BRANCH: ${{ github.event.workflow_run.head_branch || github.event.client_payload.branch || github.ref_name }}
+          DEPLOY_SHA: ${{ github.event.workflow_run.head_sha || github.event.client_payload.sha || github.sha }}