Skip to content

Align guide docs with the code on main - #373

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

Align guide docs with the code on main#373
aram356 wants to merge 2 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

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.
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant