diff --git a/.github/scripts/pages-static-assets.mjs b/.github/scripts/pages-static-assets.mjs new file mode 100644 index 000000000..ca5ea6867 --- /dev/null +++ b/.github/scripts/pages-static-assets.mjs @@ -0,0 +1,87 @@ +import { appendFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"; +import { resolve, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { deploymentMatrix } from "./pages-projects.mjs"; + +export function staticAssetsMatrix(projects, targets) { + const pages = deploymentMatrix(projects).include; + const configured = JSON.parse(targets || "[]"); + if (!Array.isArray(configured) || configured.length > pages.length) throw new Error("Invalid static asset targets"); + const seenProjects = new Set(); + const seenWorkers = new Set(); + const seenDomains = new Set(); + return { include: configured.map((target) => { + if (!target || Object.keys(target).some((key) => !["project", "worker", "domains"].includes(key))) throw new Error("Invalid static asset target"); + const page = pages.find((entry) => entry.project === target.project); + if (!page || typeof target.worker !== "string" || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(target.worker)) throw new Error("Unknown project or invalid Worker name"); + if (!Array.isArray(target.domains) || target.domains.length > 10) throw new Error("Explicit domains required"); + for (const domain of target.domains) { + if (typeof domain !== "string" || domain.length > 253 || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(domain) || seenDomains.has(domain)) throw new Error("Invalid or duplicate custom domain"); + seenDomains.add(domain); + } + if (seenProjects.has(target.project) || seenWorkers.has(target.worker)) throw new Error("Duplicate static asset target"); + seenProjects.add(target.project); + seenWorkers.add(target.worker); + return { ...page, worker: target.worker, domains: target.domains }; + }) }; +} + +export function prepareStaticAssets({ target, sourceRoot, destination, sourceSha, release }) { + if (!/^[a-f0-9]{40}$/.test(sourceSha) || !/^v\d+\.\d+\.\d+$/.test(release)) throw new Error("Exact release identity required"); + const output = resolve(sourceRoot, target.output_dir); + const dest = resolve(destination); + if (existsSync(dest)) throw new Error("Use a new artifact directory"); + let files = 0; + function check(path) { + const stat = lstatSync(path); + if (stat.isSymbolicLink()) throw new Error("Static artifacts must not contain symlinks"); + if (stat.isDirectory()) { + for (const entry of readdirSync(path)) check(join(path, entry)); + } else if (!stat.isFile() || stat.size > 25 * 1024 * 1024 || ++files > 19999) { + throw new Error("Artifact exceeds Workers Free asset limits"); + } + } + check(output); + if (!existsSync(join(output, "index.html")) || !existsSync(join(output, "_headers"))) throw new Error("Frontend index and response headers required"); + if (existsSync(join(output, "_worker.js")) || existsSync(join(output, "_routes.json"))) throw new Error("Only static artifacts are supported"); + mkdirSync(dest, { recursive: true }); + cpSync(output, join(dest, "assets"), { recursive: true }); + if (target.app === "admin") { + const redirects = join(dest, "assets", "_redirects"); + if (existsSync(redirects)) { + const rules = readFileSync(redirects, "utf8").split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#")); + if (rules.length !== 1 || !/^\/\*\s+\/index\.html\s+200$/.test(rules[0])) throw new Error("Review changed admin redirect rules before publishing static assets"); + // The asset platform's SPA mode replaces the Pages-only catch-all rewrite. + rmSync(redirects); + } + } + mkdirSync(join(dest, "assets", ".well-known"), { recursive: true }); + writeFileSync(join(dest, "assets", ".well-known", "warmbly-release.json"), JSON.stringify({ release, sourceSha, app: target.app, project: target.project }) + "\n"); + const config = { + name: target.worker, + compatibility_date: "2025-10-11", + workers_dev: false, + preview_urls: false, + assets: { directory: "./assets", html_handling: "auto-trailing-slash", not_found_handling: target.app === "admin" ? "single-page-application" : "404-page" }, + routes: target.domains.map((pattern) => ({ pattern, custom_domain: true })), + }; + writeFileSync(join(dest, "wrangler.json"), JSON.stringify(config, null, 2) + "\n"); + return config; +} + +if (process.argv[1] === fileURLToPath(import.meta.url)) { + try { + const matrix = staticAssetsMatrix(process.env.CLOUDFLARE_PAGES_PROJECTS, process.env.CLOUDFLARE_STATIC_ASSETS_TARGETS); + if (["prepare", "prepare-if-configured"].includes(process.argv[2])) { + const target = matrix.include.find((entry) => entry.project === process.env.CLOUDFLARE_PAGES_PROJECT_NAME); + if (!target && process.argv[2] === "prepare") throw new Error("Project is not configured for static assets"); + if (process.env.GITHUB_OUTPUT) appendFileSync(process.env.GITHUB_OUTPUT, `enabled=${Boolean(target)}\n`); + if (target) prepareStaticAssets({ target, sourceRoot: process.cwd(), destination: process.env.STATIC_ASSETS_ARTIFACT_DIR, sourceSha: process.env.SOURCE_SHA, release: process.env.RELEASE_TAG }); + } else { + appendFileSync(process.env.GITHUB_OUTPUT, `matrix=${JSON.stringify(matrix)}\nenabled=${matrix.include.length > 0}\n`); + } + } catch { + console.error("::error::Invalid static asset configuration or artifact. Require unique configured Pages projects, Worker names, explicit domains and an exact release identity."); + process.exitCode = 1; + } +} diff --git a/.github/scripts/pages-static-assets.test.mjs b/.github/scripts/pages-static-assets.test.mjs new file mode 100644 index 000000000..e96988949 --- /dev/null +++ b/.github/scripts/pages-static-assets.test.mjs @@ -0,0 +1,77 @@ +import assert from "node:assert/strict"; +import { cpSync, existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { test } from "node:test"; +import { staticAssetsMatrix, prepareStaticAssets } from "./pages-static-assets.mjs"; + +const projects = JSON.stringify([{ app: "web", project: "dashboard" }, { app: "admin", project: "admin" }, { app: "docs", project: "docs" }]); +const configured = [{ project: "dashboard", worker: "warmbly-dashboard", domains: ["stage.warmbly.com"] }]; +const sha = "a".repeat(40); + +test("static assets are disabled unless exact Pages projects are configured", () => { + assert.deepEqual(staticAssetsMatrix(projects), { include: [] }); + const target = staticAssetsMatrix(projects, JSON.stringify(configured)).include[0]; + assert.equal(target.output_dir, "web/dist"); + assert.equal(target.environment, "dashboard-production"); + assert.equal(target.worker, "warmbly-dashboard"); + assert.deepEqual(target.domains, ["stage.warmbly.com"]); +}); + +test("rejects unknown projects, paths, domains, duplicate mappings and overrides", () => { + for (const value of [null, {}, [null], [{ ...configured[0], project: "unknown" }], [{ ...configured[0], output_dir: "/tmp" }], [{ ...configured[0], worker: "../worker" }], [{ ...configured[0], domains: ["*.warmbly.com"] }], [{ ...configured[0], domains: ["stage.warmbly.com/path"] }], [{ ...configured[0], domains: ["stage.warmbly.com", "stage.warmbly.com"] }], [configured[0], configured[0]], [configured[0], { project: "admin", worker: "admin", domains: ["stage.warmbly.com"] }]]) { + assert.throws(() => staticAssetsMatrix(projects, JSON.stringify(value))); + } +}); + +function fixture(app, fn) { + const root = mkdtempSync(join(tmpdir(), "static-assets-")); + try { + const target = staticAssetsMatrix(projects, JSON.stringify([{ project: app === "web" ? "dashboard" : app, worker: "fixture", domains: [] }])).include[0]; + const output = join(root, target.output_dir); + mkdirSync(output, { recursive: true }); + writeFileSync(join(output, "index.html"), "

Warmbly fixture

"); + for (const name of ["_headers", "_redirects", "404.html"]) { + try { cpSync(new URL(`../../${app}/public/${name}`, import.meta.url), join(output, name)); } catch (error) { if (error.code !== "ENOENT") throw error; } + } + fn({ root, target, output, destination: join(root, "artifact") }); + } finally { rmSync(root, { recursive: true, force: true }); } +} + +test("publishes only assets and preserves exact route/header/404 files and release identity", () => { + fixture("web", ({ root, target, output, destination }) => { + const config = prepareStaticAssets({ target, sourceRoot: root, destination, sourceSha: sha, release: "v0.6.74" }); + assert.equal(config.main, undefined); + assert.equal(config.workers_dev, false); + assert.equal(config.preview_urls, false); + assert.equal(config.assets.not_found_handling, "404-page"); + assert.deepEqual(config.routes, []); + for (const name of ["index.html", "_headers", "_redirects", "404.html"]) assert.deepEqual(readFileSync(join(output, name)), readFileSync(join(destination, "assets", name))); + assert.deepEqual(JSON.parse(readFileSync(join(destination, "assets/.well-known/warmbly-release.json"))), { release: "v0.6.74", sourceSha: sha, app: "web", project: "dashboard" }); + assert.throws(() => prepareStaticAssets({ target, sourceRoot: root, destination, sourceSha: sha, release: "v0.6.74" })); + }); +}); + +test("admin preserves its SPA fallback and domains are explicit custom-domain bindings", () => { + fixture("admin", ({ root, target, destination }) => { + const config = prepareStaticAssets({ target: { ...target, domains: ["admin-stage.warmbly.com"] }, sourceRoot: root, destination, sourceSha: sha, release: "v0.6.74" }); + assert.equal(config.assets.not_found_handling, "single-page-application"); + assert.equal(existsSync(join(destination, "assets", "_redirects")), false); + assert.deepEqual(config.routes, [{ pattern: "admin-stage.warmbly.com", custom_domain: true }]); + }); +}); + +test("refuses unpinned releases, executable Pages functions and symlink artifacts", () => { + for (const kind of ["sha", "tag", "function", "symlink"]) fixture("web", ({ root, target, output, destination }) => { + if (kind === "function") writeFileSync(join(output, "_worker.js"), "export default {}"); + if (kind === "symlink") symlinkSync("/etc/hosts", join(output, "outside")); + assert.throws(() => prepareStaticAssets({ target, sourceRoot: root, destination, sourceSha: kind === "sha" ? "main" : sha, release: kind === "tag" ? "latest" : "v0.6.74" })); + }); +}); + +test("changed admin redirect behavior requires explicit review", () => { + fixture("admin", ({ root, target, output, destination }) => { + writeFileSync(join(output, "_redirects"), "/old /new 301\n"); + assert.throws(() => prepareStaticAssets({ target, sourceRoot: root, destination, sourceSha: sha, release: "v0.6.74" })); + }); +}); diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ae87b7764..d39b16784 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -110,6 +110,7 @@ jobs: - 'scripts/check-cli-installer.sh' - 'scripts/build-cli.sh' pages: + - '.github/workflows/static-assets.yml' - 'deploy/cloudflare/**' - '.github/scripts/pages-*' - '.github/workflows/release.yml' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d8645eac6..ee6170452 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -657,3 +657,33 @@ jobs: --branch "$CLOUDFLARE_PAGES_PRODUCTION_BRANCH" \ --commit-hash "$GITHUB_SHA" \ --commit-message "$RELEASE_TAG" + + - name: Prepare optional static asset mirror + id: static-assets + if: vars.CLOUDFLARE_STATIC_ASSETS_DEPLOY_ENABLED == 'true' + env: + CLOUDFLARE_PAGES_PROJECTS: ${{ vars.CLOUDFLARE_PAGES_PROJECTS }} + CLOUDFLARE_STATIC_ASSETS_TARGETS: ${{ vars.CLOUDFLARE_STATIC_ASSETS_TARGETS }} + SOURCE_SHA: ${{ github.sha }} + RELEASE_TAG: ${{ github.ref_name }} + run: | + export STATIC_ASSETS_ARTIFACT_DIR="$RUNNER_TEMP/static-assets" + node .github/scripts/pages-static-assets.mjs prepare-if-configured + + - name: Publish the same artifact to the configured static asset host + if: steps.static-assets.outputs.enabled == 'true' + env: + CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_STATIC_ASSETS_ACCOUNT_ID }} + CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_STATIC_ASSETS_API_TOKEN }} + WRANGLER_SEND_METRICS: "false" + run: | + test -n "$CLOUDFLARE_ACCOUNT_ID" + test -n "$CLOUDFLARE_API_TOKEN" + pnpm dlx wrangler@4.45.0 deploy --config "$RUNNER_TEMP/static-assets/wrangler.json" + + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + if: steps.static-assets.outputs.enabled == 'true' + with: + name: static-assets-${{ matrix.project }}-${{ github.ref_name }}-${{ github.run_id }} + path: ${{ runner.temp }}/static-assets + retention-days: 30 diff --git a/.github/workflows/static-assets.yml b/.github/workflows/static-assets.yml new file mode 100644 index 000000000..0490d6f35 --- /dev/null +++ b/.github/workflows/static-assets.yml @@ -0,0 +1,116 @@ +name: Publish released static assets + +on: + workflow_dispatch: + inputs: + release_tag: + description: Existing stable release tag to rebuild (no new release) + required: true + type: string + expected_sha: + description: Full commit SHA of that release + required: true + type: string + +permissions: + contents: read + +concurrency: + group: release + cancel-in-progress: false + +jobs: + targets: + if: github.ref == 'refs/heads/main' && vars.CLOUDFLARE_STATIC_ASSETS_DEPLOY_ENABLED == 'true' + runs-on: ubuntu-latest + outputs: + matrix: ${{ steps.targets.outputs.matrix }} + enabled: ${{ steps.targets.outputs.enabled }} + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + with: + node-version: "22" + - run: node --test .github/scripts/pages-*.test.mjs + - id: targets + env: + CLOUDFLARE_PAGES_PROJECTS: ${{ vars.CLOUDFLARE_PAGES_PROJECTS }} + CLOUDFLARE_STATIC_ASSETS_TARGETS: ${{ vars.CLOUDFLARE_STATIC_ASSETS_TARGETS }} + run: node .github/scripts/pages-static-assets.mjs + + publish: + needs: targets + if: needs.targets.outputs.enabled == 'true' + strategy: + fail-fast: false + matrix: ${{ fromJSON(needs.targets.outputs.matrix) }} + runs-on: ubuntu-latest + timeout-minutes: 30 + environment: ${{ matrix.environment }} + env: + PAGES_APP: ${{ matrix.app }} + CLOUDFLARE_PAGES_PROJECT_NAME: ${{ matrix.project }} + SOURCE_SHA: ${{ inputs.expected_sha }} + RELEASE_TAG: ${{ inputs.release_tag }} + WRANGLER_SEND_METRICS: "false" + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + fetch-depth: 0 + persist-credentials: false + - name: Pin the existing release source + run: | + [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] + [[ "$SOURCE_SHA" =~ ^[0-9a-f]{40}$ ]] + test "$(git rev-parse "refs/tags/$RELEASE_TAG^{commit}")" = "$SOURCE_SHA" + git merge-base --is-ancestor "$SOURCE_SHA" origin/main + git worktree add --detach "$RUNNER_TEMP/frontend-source" "$SOURCE_SHA" + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + with: + node-version: "22" + - name: Load existing public frontend configuration + env: + CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} + CLOUDFLARE_PAGES_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }} + run: | + test -n "$CLOUDFLARE_API_TOKEN" + test -n "$CLOUDFLARE_PAGES_ACCOUNT_ID" + curl --fail --silent --show-error \ + --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ + "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_PAGES_ACCOUNT_ID/pages/projects/$CLOUDFLARE_PAGES_PROJECT_NAME" \ + | node "$RUNNER_TEMP/frontend-source/.github/scripts/pages-production-config.mjs" + - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4 + with: + version: "11.9.0" + - name: Build the released frontend artifact + env: + APP_DIRECTORY: ${{ matrix.directory }} + BUILD_SCRIPT: ${{ matrix.build_script }} + VITE_SENTRY_RELEASE: ${{ inputs.release_tag }} + run: | + cd "$RUNNER_TEMP/frontend-source/$APP_DIRECTORY" + pnpm install --frozen-lockfile + pnpm run "$BUILD_SCRIPT" + - name: Prepare the configured static asset deployment + env: + CLOUDFLARE_PAGES_PROJECTS: ${{ vars.CLOUDFLARE_PAGES_PROJECTS }} + CLOUDFLARE_STATIC_ASSETS_TARGETS: ${{ vars.CLOUDFLARE_STATIC_ASSETS_TARGETS }} + run: | + export STATIC_ASSETS_ARTIFACT_DIR="$RUNNER_TEMP/static-assets" + cd "$RUNNER_TEMP/frontend-source" + node "$GITHUB_WORKSPACE/.github/scripts/pages-static-assets.mjs" prepare + - name: Publish assets without a request Worker + env: + CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_STATIC_ASSETS_ACCOUNT_ID }} + CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_STATIC_ASSETS_API_TOKEN }} + run: | + test -n "$CLOUDFLARE_ACCOUNT_ID" + test -n "$CLOUDFLARE_API_TOKEN" + pnpm dlx wrangler@4.45.0 deploy --config "$RUNNER_TEMP/static-assets/wrangler.json" + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: static-assets-${{ matrix.project }}-${{ inputs.release_tag }}-${{ github.run_id }} + path: ${{ runner.temp }}/static-assets + retention-days: 30 diff --git a/docs/content/docs/development/configuration.mdx b/docs/content/docs/development/configuration.mdx index 837c5506a..b1a0d7d19 100644 --- a/docs/content/docs/development/configuration.mdx +++ b/docs/content/docs/development/configuration.mdx @@ -677,6 +677,46 @@ Stage each hostname, verify effective TLS and frontend responses, and retain the Pages association and DNS needed for rollback before moving production traffic. The deployment procedure is in `deploy/cloudflare/README.md`. +### Optional hosted static assets + +Workers Static Assets can serve the same built frontend files directly, without a +request Worker. This is a separate opt-in delivery path. The existing Pages +projects remain the public build-configuration source and the rollback copy. +Self-hosted containers and their configuration are unchanged. + +| GitHub variable or secret | What it does | Default | +|---|---|---| +| `CLOUDFLARE_STATIC_ASSETS_DEPLOY_ENABLED` | Set the repository variable to `true` to enable configured static asset deployments alongside release Pages uploads, and permit the manual frontend-only workflow | unset | +| `CLOUDFLARE_STATIC_ASSETS_TARGETS` | Repository variable containing JSON entries with `project`, `worker` and explicit `domains`. Projects must already appear in `CLOUDFLARE_PAGES_PROJECTS`. Domains are Worker custom-domain bindings; use a staging domain before any production hostname | `[]` | +| `CLOUDFLARE_STATIC_ASSETS_ACCOUNT_ID` | Cloudflare account that owns the Workers custom domains, configured in the corresponding frontend's GitHub environment | unset | +| `CLOUDFLARE_STATIC_ASSETS_API_TOKEN` | GitHub environment secret permitting Workers asset deployment and the explicitly configured custom domains in that account | unset | + +For example, a staging entry is +`[{"project":"dashboard-project","worker":"dashboard-assets-stage","domains":["assets-stage.example.com"]}]`. +No wildcard domain is accepted. Empty domains publish an unattached artifact; +`workers.dev` and preview URLs stay disabled. The publisher preserves +`_headers` and the dashboard's `_redirects`. For admin it replaces the Pages +catch-all rewrite with the platform's SPA fallback and keeps the other +frontends' 404 behavior. It rejects symlinks, Pages Functions, files above 25 MiB +and artifacts exceeding the Free plan's 20,000-file limit. + +The manual **Publish released static assets** workflow rebuilds an existing +stable release using its tag and exact commit SHA. It does not create a tag, +release, application deployment or worker-fleet update. It uses current public +Pages configuration, so a rebuilt artifact can differ from the earlier build if +that configuration changed. The deployed artifact includes +`/.well-known/warmbly-release.json` and is retained as a workflow artifact. +Subsequent releases publish the same built files to Pages and configured static +asset targets. Static asset requests do not invoke a Worker script; confirm the +account's current limits and pricing before enabling any other Workers feature. + +Before moving a production hostname, verify the staging site's certificate, +TLS policy, root and nested routes, assets, response headers and redirects. +Archive its existing Pages association and DNS. If verification fails after a +cutover, restore that association and DNS, or deploy the saved asset artifact to +the same Worker name. Keep the Pages deployment and its configuration available +through the rollback window. A source merge alone does not attach a domain. + ### Whole-domain connects A workspace can connect every mailbox on a [Google Workspace domain or Microsoft 365 organization](/guides/mailbox-import/#connect-a-whole-google-workspace-domain) through one administrator's grant (**Add account > Google > Whole Workspace domain**, **Add account > Microsoft > Whole organization**). These are read by the backend only: it mints every token for those mailboxes itself and hands them to workers per use, so workers need nothing here. The complete setup, step by step, is in [whole-domain mailbox connects](/development/whole-domain-connect/).