Skip to content

Align guide docs with the code on main - #373

Open
aram356 wants to merge 3 commits into
mainfrom
worktree-docs-align-guides-with-main
Open

Align guide docs with the code on main#373
aram356 wants to merge 3 commits into
mainfrom
worktree-docs-align-guides-with-main

Conversation

@aram356

@aram356 aram356 commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Summary

  • A page-by-page audit of docs/guide against the current crates found names that no longer exist, behaviour the code contradicts, and public surface with no coverage. This PR fixes what the audit turned up, so a reader following the guides lands on APIs and commands that exist and behave as described.
  • The audit ran as a rerunnable identifier/flag/link cross-check over every page plus a source-cited review per page group; 66 findings landed, each verified against the cited source line before editing.

Changes

Crate / File Change
docs/guide/adapters/fastly.md Replace phantom dispatch_with_config* with the FastlyService builder; add Custom entry points (runtime_env_config, dispatch_with_registries, RUNTIME_ENV_STORE_NAME, both footguns); buffering, -C, manifest_version = 3, [setup], proxy:: import
docs/guide/adapters/cloudflare.md CloudflareService builder; worker-build build command; context:: / proxy:: imports; wrangler kv key put; Secret Store section; kv/config merged-id collision
docs/guide/adapters/axum.md dev_server::run_app, AxumProxyClient::try_new(), bind-address precedence, EDGEZERO__LOGGING__LEVEL, owns_logging; KV Storage and Secret Store sections; KV no longer listed as unavailable
docs/guide/adapters/spin.md Logging, Proxy Client, Context Access, Testing sections; required = true vs default = ""
docs/guide/adapters/overview.md Streaming current state, proxy-header and logging lists include Spin, Spin Tests, Store Capabilities table, Adapter trait hooks in onboarding
docs/guide/streaming.md, proxying.md Only Cloudflare preserves progressive delivery; SpinProxyClient, AxumProxyClient::try_new()?
docs/guide/routing.md, handlers.md, middleware.md, kv.md Duplicate routes panic at build; Store Extractors (Kv, Config, Secrets, AppConfig<C>); FnMiddleware / middleware_arc; Axum KV file naming
docs/guide/configuration.md app! argument table; adapter metadata component / host / port; auth-* command overrides; rename_all and store_ref rules; compiling secret-resolution example
docs/guide/blob-app-config-migration.md config push --staging as the supported staging path; Axum env-var and wrangler secret put forms; canary key in examples; config.rs diff entry point
docs/guide/manifest-store-migration.md EDGEZERO__LOGGING__* rows; drop dispatch_with_*_handle
docs/guide/cli-reference.md, cli-walkthrough.md -C / --manifest-path serve and deploy forms; healthcheck outputs and token behaviour; Cloudflare --binding --local; pushed-key / pushed-store; EDGEZERO_MANIFEST scope; my-app.toml in the tree; lifecycle commands in the generated CLI
docs/guide/deploy-github-actions.md, docs/specs/edgezero-deploy-github-action.md cache/restore@v6 + cache/save@v6, no checkout; cache-key components; artifact retention and job summary
docs/guide/architecture.md, what-is-edgezero.md, roadmap.md, docs/index.md Spin in the layout, adapter list, feature table, platform table, feature cards; Spin moved to Completed; dispatch_with_config dropped from the diagram
docs/.vitepress/config.mts KV Storage added to the sidebar
crates/edgezero-adapter-axum/src/key_value_store.rs Module doc: .edgezero/kv-<slug>-<hash>.redb, not the removed .edgezero/kv.redb default

Closes

Closes #372
Closes #361
Closes #77

Test plan

  • cargo fmt --all -- --check
  • Docs build: cd docs && npm run lint && npm run format && npm run build
  • Other: every behavioural claim edited was checked against the cited source line; the identifier/flag/link cross-check over docs/guide reports only placeholder app names and third-party names
  • cargo test --workspace --all-targets (no Rust code changed; one //! comment)
  • cargo clippy --workspace --all-targets --all-features -- -D warnings (not applicable)
  • cargo check --workspace --all-targets --features "fastly cloudflare spin" (not applicable)
  • WASM builds (not applicable)
  • examples/app-demo workspace (not applicable)
  • Manual testing via edgezero serve --adapter axum (not applicable)

Checklist

  • Changes follow CLAUDE.md conventions
  • No Tokio deps added to core or adapter crates
  • Route params use {id} syntax (not :id)
  • Types imported from edgezero_core (not http crate)
  • Store wiring goes through KvRegistry / ConfigRegistry / SecretRegistry (not the legacy single-handle setters) — see spec §6.6
  • New code has tests (docs only)
  • No secrets or credentials committed

@aram356
Align guide docs with the code on main
58fc673 
A page-by-page audit of docs/guide against the current crates found
names that no longer exist, behaviour descriptions the code contradicts,
and public surface with no coverage. This commit fixes what the audit
turned up.

Phantom names: dispatch_with_config / dispatch_with_config_handle
(fastly, cloudflare, architecture), AxumProxyClient::default(),
EDGEZERO_SECRET_ prefix, wrangler secret put --binding, diff.rs entry
point, dispatch_with_*_handle, crate-root imports for types that live
in proxy:: / context:: / dev_server::.

Behaviour: response streaming is preserved only on Cloudflare (Fastly,
Spin and Axum buffer); duplicate routes panic at build rather than
first-registered-wins; Axum honours the axum.toml port through the CLI
and reads EDGEZERO__LOGGING__LEVEL, not edgezero.toml; Axum KV files are
.edgezero/kv-<slug>-<hash>.redb; healthcheck emits status-code only when
an HTTP status arrived and degrades to service-level without a token;
EDGEZERO_MANIFEST and the missing-manifest fallback apply to
build/deploy/serve only; Cloudflare local push selects by --binding;
deploy actions use cache/restore@v6 + cache/save@v6 and no checkout;
the cache key includes the workspace path and build-args hash.

Coverage: Fastly custom entry points (runtime_env_config,
dispatch_with_registries, RUNTIME_ENV_STORE_NAME and the two footguns);
FastlyService / CloudflareService builders; store extractors (Kv,
Config, Secrets, AppConfig<C>); FnMiddleware and middleware_arc; app!
argument list; adapter metadata component/host/port and auth-* command
overrides; EDGEZERO__LOGGING__* rows; config push --staging as the
supported staging path; Spin everywhere it was missing (landing page,
platform table, architecture, roadmap, overview tests and capability
table, and Logging / Proxy / Context / Testing sections on its page);
Axum KV and Secret Store sections; Cloudflare Secret Store and the
kv/config merged-id collision; scaffold tree and generated CLI surface;
KV page added to the sidebar.
@aram356
Fix stale KV storage path in Axum key_value_store module doc
4f8a2fd 
The dev server derives .edgezero/kv-<slug>-<hash>.redb for every
declared id (kv_store_path in dev_server.rs); the hard-coded
.edgezero/kv.redb default the module doc described no longer exists.
@aram356 aram356 self-assigned this Sep 6, 2026
ChristianPavilonis
ChristianPavilonis approved these changes Sep 7, 2026
View reviewed changes

@ChristianPavilonis ChristianPavilonis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary

Reviewed the locked PR revision against its base. The documentation alignment is broadly correct, with five actionable documentation corrections noted inline.

Comment thread docs/guide/adapters/cloudflare.md Outdated
Comment thread docs/guide/routing.md Outdated
Comment thread docs/guide/manifest-store-migration.md Outdated
Comment thread docs/guide/streaming.md Outdated
Comment thread docs/guide/cli-reference.md Outdated
@aram356
Address review on docs alignment
fa40699 
Five inline comments from the PR 373 review, each checked against
source before editing.

"Cloudflare's documented manual dispatch call does not compile": the
builder's dispatch takes (req, env, ctx) and is async. Documented the
real call with a complete entrypoint example.

"Duplicate routes are not always caught at startup": only Axum builds
the router once at startup; Fastly, Cloudflare, and Spin call
build_app() per request, so the panic lands on the first request after
a successful deploy. Said so and pointed at the Axum dev server as the
pre-deploy check.

"These Fastly logging controls are not applied on the runtime-env path":
FastlyLogging::from(&EnvConfig) derives logger use from ENDPOINT alone
and hard-codes echo_stdout. Marked USE_FASTLY_LOGGER and ECHO_STDOUT as
resolved but not applied, and noted that ENDPOINT is what enables the
logger.

"Buffering adapters do not provide the claimed memory benefit": Axum
collects into an unbounded buffer and Spin caps at 16 MiB. Scoped the
memory claim to Cloudflare and described streaming on the buffering
adapters as composability only.

"EDGEZERO_MANIFEST also applies to auth": run_auth calls
load_manifest_optional and has no --manifest flag. Added auth to the
env-var scope and the missing-manifest fallback.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ChristianPavilonis ChristianPavilonis ChristianPavilonis approved these changes
@prk-Jr prk-Jr Awaiting requested review from prk-Jr

Assignees

@aram356 aram356

Labels

None yet

Projects

None yet

Milestone

No milestone

2 participants

@aram356 @ChristianPavilonis