Serve the API docs on storyteller-docs.artcraft.team from a Cloudflare Worker

This commit is contained in:
Dylan M. Taylor authored and GitHub committed 2026-11-18 12:03:54 -05:00
1 parent 999b402564
commit 1ce37b5f28
9 files changed
+41859 -18

No files matched your search

+15 -6
View File
@@ -200,17 +200,18 @@ The website runs at `http://localhost:3000`. Repository-root launchers are in
### Cloudflare deployment
All three frontends deploy to Cloudflare Workers from this repository. Each
All three frontends and the API docs site deploy to Cloudflare Workers from this repository. Each
Worker's build command is its app-specific `npm run build:<app>` and its deploy
command is `npm run deploy:<app>`; those scripts select the app in
[`cloudflare_app.sh`](./script/website/cloudflare_app.sh), so no build variable
is needed to tell the projects apart:
| Worker | Build / deploy commands | Hostname | Wrangler config | Build secrets |
|----------------------|----------------------------------------|---------------------------|---------------------------------------------------|--------------------------------------------------------------|
| `artcraft-services` | `build:website` / `deploy:website` | `getartcraft.com` | `wrangler.jsonc` | `LAUNCHER_CATALOG_SIGNING_KEY`; optional `LINUX_SIGNING_KEY` |
| `artcraft-webapp` | `build:webapp` / `deploy:webapp` | `app.getartcraft.com` | `frontend/apps/artcraft-webapp/wrangler.jsonc` | none |
| `artcraft-dashboard` | `build:dashboard` / `deploy:dashboard` | `dashboard.artcraft.team` | `frontend/apps/artcraft-dashboard/wrangler.jsonc` | none |
| Worker | Build / deploy commands | Hostname | Wrangler config | Build secrets |
|------------------------|------------------------------------------|----------------------------------|-----------------------------------------------------|----------------------------------------------------------------|
| `artcraft-services` | `build:website` / `deploy:website` | `getartcraft.com` | `wrangler.jsonc` | `LAUNCHER_CATALOG_SIGNING_KEY`; optional `LINUX_SIGNING_KEY` |
| `artcraft-webapp` | `build:webapp` / `deploy:webapp` | `app.getartcraft.com` | `frontend/apps/artcraft-webapp/wrangler.jsonc` | none |
| `artcraft-dashboard` | `build:dashboard` / `deploy:dashboard` | `dashboard.artcraft.team` | `frontend/apps/artcraft-dashboard/wrangler.jsonc` | none |
| `storyteller-docs` | `build:docs` / `deploy:docs` | `storyteller-docs.artcraft.team` | `frontend/api_docs/wrangler.jsonc` | none |
The bare `npm run build` / `npm run deploy` pair falls back to the website and
needs an `ARTCRAFT_APP` build variable, and the default `npx wrangler deploy`
@@ -225,6 +226,14 @@ build variables, not runtime secrets. The admin dashboard is a standalone pnpm
app and sets `NODE_VERSION=22`; see
[its README](./frontend/apps/artcraft-dashboard/README.md).
The API docs Worker is the exception to the build/deploy pairing: its Swagger UI
page and OpenAPI document are committed under
[`frontend/api_docs/public`](./frontend/api_docs), because the document comes from
a Rust binary (`cargo run --bin docs-cli`) that Workers Builds cannot run. Its
build command only validates those files; regenerate them with
`bash script/build_api_docs.sh` when the HTTP API changes. See
[the API docs README](./frontend/api_docs/README.md).
## Automated Craft Release Version Updates
The `.github/workflows/update-craft-release-versions.yml` workflow automatically updates the release versions of the Craft Launcher and Crafting Apps.
+46
View File
@@ -0,0 +1,46 @@
# API docs — storyteller-docs.artcraft.team
Swagger UI for the `storyteller-web` HTTP API. Production:
<https://storyteller-docs.artcraft.team>.
This is a static-assets Cloudflare Worker with no server-side code:
| Path | What |
|-----------------------|---------------------------------------------------------------------------|
| `public/index.html` | Swagger UI page; loads `api.json` from its own directory |
| `public/api.json` | OpenAPI 3.1 document generated from the Rust sources |
| `wrangler.jsonc` | Worker `storyteller-docs`, custom domain `storyteller-docs.artcraft.team` |
## Why the spec is committed
`public/api.json` is produced by `cargo run --bin docs-cli`
(`crates/service/web/storyteller_web/src/api_doc_cli.rs`), which builds the whole
workspace. Cloudflare Workers Builds has no Rust toolchain and that build would be
far too slow for a deploy, so the generated document is committed and the Worker
has no build step of its own: the build command validates the artifacts and the
deploy command uploads them.
Refresh it whenever the HTTP API changes:
```bash
bash script/build_api_docs.sh
```
Then commit `public/api.json` alongside the endpoint change, so the diff shows the
API surface that moved.
## Deploying
```bash
npm run build:docs # validates the artifacts
npm run deploy:docs # npx wrangler deploy --config frontend/api_docs/wrangler.jsonc
```
Workers Builds runs both from the repository root. `storyteller-docs.artcraft.team` is a
`custom_domain` route, so Cloudflare creates the DNS record and certificate; the
`artcraft.team` zone must be on the same account as the Worker (the setup
`dashboard.artcraft.team` already uses).
These docs previously lived at `storyteller-docs.netlify.app`, built by
[`script/netlify_build_docs.sh`](../../script/netlify_build_docs.sh), which is kept
only as the rollback path. The Worker deliberately reuses that name.
File diff suppressed because it is too large. Load diff
File renamed without changes.
+20
View File
@@ -0,0 +1,20 @@
{
// Static-assets Worker for storyteller-docs.artcraft.team: the Swagger UI page plus the
// storyteller-web OpenAPI document. There is no server-side code and no build
// here — both files are committed under public/ because the document is
// generated by a Rust binary that Workers Builds cannot run (see README.md).
// Deploy from the repository root with ARTCRAFT_APP=storyteller-docs (see
// script/website/cloudflare_app.sh).
"name": "storyteller-docs",
"compatibility_date": "2026-11-18",
"assets": {
// Assets-only Worker: no `main` script, so an assets binding is not allowed.
"directory": "./public"
},
"routes": [
{
"pattern": "storyteller-docs.artcraft.team",
"custom_domain": true
}
]
}
+3 -1
View File
@@ -9,6 +9,8 @@
"build:webapp": "ARTCRAFT_APP=artcraft-webapp bash script/website/cloudflare_app.sh build",
"deploy:webapp": "ARTCRAFT_APP=artcraft-webapp bash script/website/cloudflare_app.sh deploy",
"build:dashboard": "ARTCRAFT_APP=artcraft-dashboard bash script/website/cloudflare_app.sh build",
"deploy:dashboard": "ARTCRAFT_APP=artcraft-dashboard bash script/website/cloudflare_app.sh deploy"
"deploy:dashboard": "ARTCRAFT_APP=artcraft-dashboard bash script/website/cloudflare_app.sh deploy",
"build:docs": "ARTCRAFT_APP=storyteller-docs bash script/website/cloudflare_app.sh build",
"deploy:docs": "ARTCRAFT_APP=storyteller-docs bash script/website/cloudflare_app.sh deploy"
}
}
+31
View File
@@ -0,0 +1,31 @@
#!/bin/bash
#
# Regenerate the committed OpenAPI document served at storyteller-docs.artcraft.team.
#
# bash script/build_api_docs.sh
#
# The document is produced by the `docs-cli` binary (utoipa), which builds the
# whole workspace. Cloudflare Workers Builds cannot run that, so
# frontend/api_docs/public/api.json is committed and this script refreshes it.
# Run it after changing an endpoint or a request/response type, then commit the
# regenerated file with the change.
set -euo pipefail
cd "$(dirname "$0")/.."
export SQLX_OFFLINE=true
# boring-sys2 uses bindgen (libclang) to generate BoringSSL FFI bindings. On
# machines where clang cannot find stddef.h on its own, point it at GCC's own
# include directory instead of installing packages.
if command -v gcc >/dev/null 2>&1; then
export BINDGEN_EXTRA_CLANG_ARGS="-I$(gcc -print-file-name=include)"
fi
cargo run --bin docs-cli
# docs-cli writes api.json into the working directory, which is the repo root.
mv api.json frontend/api_docs/public/api.json
echo "Wrote frontend/api_docs/public/api.json ($(wc -c < frontend/api_docs/public/api.json) bytes)"
+12 -10
View File
@@ -1,5 +1,13 @@
#!/bin/bash
#
# Netlify build for https://storyteller-docs.netlify.app, the previous home of
# the API docs. Production now serves storyteller-docs.artcraft.team from the Cloudflare
# Worker in frontend/api_docs, and this script exists only as the rollback path.
# The Netlify site is UI-configured (there is no netlify.toml for it):
# * Base directory: (repository root)
# * Build command: bash script/netlify_build_docs.sh
# * Publish directory: build
#
set -euxo pipefail
# Resolve the repo root regardless of where this script is invoked from
@@ -8,13 +16,6 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
cd "$REPO_ROOT"
# boring-sys2 uses bindgen (libclang) to generate Rust FFI bindings for BoringSSL.
# On Netlify's build image, clang is available but can't locate stddef.h on its
# own because the GCC system header path isn't in its default search path.
# Pointing bindgen at GCC's own include directory resolves this without any
# package installation.
export BINDGEN_EXTRA_CLANG_ARGS="-I$(gcc -print-file-name=include)"
# Install Rust toolchain
rustup update
rustup default stable
@@ -24,9 +25,10 @@ rustup show
mkdir -p ./build
SQLX_OFFLINE=true cargo run --bin docs-cli
# Regenerates frontend/api_docs/public/api.json (includes the bindgen workaround).
bash script/build_api_docs.sh
mv api.json ./build
cp ./frontend/api_docs.html ./build/index.html
cp ./frontend/api_docs/public/index.html ./build/index.html
cp ./frontend/api_docs/public/api.json ./build/api.json
+24 -1
View File
@@ -14,6 +14,8 @@
# npm run build:webapp / deploy:webapp
# artcraft-dashboard dashboard.artcraft.team, frontend/apps/artcraft-dashboard/wrangler.jsonc
# npm run build:dashboard / deploy:dashboard
# storyteller-docs storyteller-docs.artcraft.team, frontend/api_docs/wrangler.jsonc
# npm run build:docs / deploy:docs
#
# The bare `npm run build` / `npm run deploy` pair falls back to the website and
# needs an ARTCRAFT_APP build variable. Only the website builds
@@ -51,8 +53,29 @@ case "${APP}:${ACTION}" in
artcraft-dashboard:deploy)
npx --yes wrangler@4 deploy --config frontend/apps/artcraft-dashboard/wrangler.jsonc
;;
storyteller-docs:build)
# The OpenAPI document comes from `cargo run --bin docs-cli`, which Workers
# Builds cannot run, so the artifacts are committed: this build only checks
# that they are present and that the document still parses.
for required in frontend/api_docs/public/index.html frontend/api_docs/public/api.json; do
if [[ ! -f "${required}" ]]; then
echo "Missing ${required}; regenerate with: bash script/build_api_docs.sh" >&2
exit 1
fi
done
node --input-type=module -e '
const { readFileSync } = await import("node:fs");
const spec = JSON.parse(readFileSync("frontend/api_docs/public/api.json", "utf8"));
const paths = Object.keys(spec.paths ?? {});
if (paths.length === 0) throw new Error("api.json contains no paths");
console.log(`api.json: ${paths.length} paths (${spec.info?.title ?? "untitled"})`);
'
;;
storyteller-docs:deploy)
npx --yes wrangler@4 deploy --config frontend/api_docs/wrangler.jsonc
;;
*)
echo "Usage: ARTCRAFT_APP=<artcraft-website|artcraft-webapp|artcraft-dashboard> $0 <build|deploy>" >&2
echo "Usage: ARTCRAFT_APP=<artcraft-website|artcraft-webapp|artcraft-dashboard|storyteller-docs> $0 <build|deploy>" >&2
echo "Got ARTCRAFT_APP='${APP}', action='${ACTION}'." >&2
exit 1
;;