mirror of
https://github.com/storytold/artcraft-services.git
synced 2026-11-19 08:53:03 +01:00
Serve the API docs on storyteller-docs.artcraft.team from a Cloudflare Worker
This commit is contained in:
1 parent
999b402564
commit
1ce37b5f28
9 files changed
+41859
-18
No files matched your search
@@ -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.
|
||||
|
||||
@@ -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.
@@ -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
@@ -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"
|
||||
}
|
||||
}
|
||||
@@ -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)"
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
;;
|
||||
|
||||
Reference in new issue
Block a user