Skip to content

TODO.md

Latest commit

 

History

History
615 lines (438 loc) · 44.3 KB

TODO.md

File metadata and controls

615 lines (438 loc) · 44.3 KB

EdgeZero TODO

High-level backlog and decisions to drive the next milestones.

Queue (near-term)

High Priority

  • Core: Response::json<T: serde::Serialize> behind serde feature
  • Fastly proxy: add tests for backend send + header/body mapping
  • Cloudflare streaming: map Response::with_chunks to ReadableStream with backpressure
  • Core proxy: add async fetch facade (feature async-client) and implement Cloudflare proxy async fetch facade (feature async-client) and implement Cloudflare proxy

Medium Priority

  • Fastly demo: add optional backend example to validate req.send("backend")
  • Core: utility to serve embedded static files via include_str!/include_bytes! with proper Content-Type and HEAD (no body) handling
  • Docs: document header/method/status mapping to http crate
  • Docs: add RouteOptions + streaming policy section (examples done; expand README section)

Completed / Ongoing Maintenance

  • CLI: manifest-driven edgezero build --adapter fastly|cloudflare|axum wiring via crates/edgezero-cli/src/main.rs + adapter manifests.
  • CLI: manifest-driven edgezero deploy --adapter fastly|cloudflare wrappers that call Fastly CLI or wrangler per manifest config.
  • CI: workspace fmt, clippy, and test workflows (.github/workflows/format.yml, .github/workflows/test.yml).
  • Cloudflare demo: runnable wrangler example under examples/app-demo/crates/app-demo-adapter-cloudflare (with wrangler.toml + README instructions).
  • Core: helper to fetch all header values for a name (multi-value support)
  • Docs: clean stale references to removed hello example from README/targets
  • Docs: highlight controller-based workflow and update examples
  • Controllers: add edgezero-controller + edgezero-macros with typed extractors and #[action] helpers

Test Coverage Plan (2025-09-18)

  • Adapters: introduce Fastly/Cloudflare mapping tests (headers, streaming, proxy failure) to catch glue regressions.
  • Adapters: assert error-path mapping for Fastly/Cloudflare request conversion and re-enable the ignored Cloudflare response header test.
  • CLI: add integration tests for edgezero new scaffolding, feature-flag builds, and dev fallback app.
  • CLI: cover dev_server, generator, and template scaffolding flows with tempdir-based integration tests to guard manual HTTP parsing and shell commands.
  • CI: verify feature combinations (without dev-example, json, form) compile and run basic smoke tests.
  • Macros: add trybuild coverage for app! manifest expansion (route/middleware generation and error surfacing).
  • Core: unit-test App::build_app/Hooks wiring and PathParams::deserialize edge cases beyond indirect coverage. (Added targeted unit tests in crates/edgezero-core/src/app.rs and crates/edgezero-core/src/params.rs.)
  • Coverage hygiene: consolidate duplicate router/extractor request-parsing tests and share adapter contract fixtures to reduce redundant maintenance. (Router duplicates trimmed; extractor suite now owns request parsing checks.)
  • Router: add regression cases for overlapping routes, prefix/nest behaviour, and BodyMode error handling (Streaming vs Buffered).
  • Controller: cover negative paths (State<T> missing, ValidatedJson errors) and assert returned status/body.

Milestones

  • Fastly adapter MVP
    • Map Fastly Request -> edgezero-core::Request
    • Map edgezero-core::Response -> Fastly Response (headers/body)
    • Handle binary/text bodies and content-length
    • Example: runnable Fastly demo (examples/app-demo/crates/app-demo-adapter-fastly) with wasm32-wasip1 target and explicit logger init
    • Streaming: native streaming on Fastly via stream_to_client (wasm32-wasip1), buffered fallback elsewhere
  • Cloudflare Workers adapter MVP
    • Basic mapping: Workers Request -> EdgeZero Request
    • Basic mapping: EdgeZero Response -> Workers Response (buffered bodies)
    • Streaming behavior (ReadableStream) and backpressure
    • Example: deploy sample with wrangler (examples/app-demo/crates/app-demo-adapter-cloudflare)
  • CLI
    • edgezero new <name>: scaffold an app (lib with build_app())
    • edgezero build --adapter fastly|cloudflare
    • edgezero deploy --adapter fastly|cloudflare
    • edgezero dev improvements: better HTTP parsing, hot-reload
  • Config
    • edgezero.toml: app name, routes, provider-specific settings
    • Secrets/ENV strategy and provider bindings
  • Observability
    • Logging levels; feature-gated tracing
    • Metrics hooks; request timing middleware
  • Router
    • Wildcards (*), optional segments, query params helpers
    • HEAD/OPTIONS helpers; 405 handling
    • 501 handling
  • Responses
    • JSON helper (serde optional feature)
    • Streaming/chunked support
  • Errors
    • Unified error type in core; map provider errors to HTTP 5xx
  • Docs
    • Provider guides (Fastly, Cloudflare)
    • CLI reference
    • Example cookbook
  • CI
    • Run cargo fmt, cargo clippy, and tests

Roadmap (2025-09-24)

  • Adapter stability: formalise the provider adapter contract (request/response mapping, streaming guarantees, proxy hooks) and capture it in shared docs + integration tests so new targets plug in safely. (docs/adapter-contract.md, Fastly contract tests under crates/edgezero-adapter-fastly/tests/contract.rs, Cloudflare contract tests under crates/edgezero-adapter-cloudflare/tests/contract.rs, manifest schema in docs/manifest.md)
  • Provider additions: prototype a third adapter (e.g. AWS Lambda@Edge or Vercel Edge Functions) using the stabilized adapter API to validate cross-provider abstractions.
  • Manifest ergonomics: design an edgezero.toml schema that mirrors Spin’s manifest convenience (route triggers, env/secrets, build targets) while remaining provider-agnostic; update CLI scaffolding accordingly. (crates/edgezero-cli/src/manifest.rs, templates in crates/edgezero-cli/src/templates/root/edgezero.toml.hbs, doc docs/manifest.md, app-demo manifest examples/app-demo/edgezero.toml)
  • Tooling parity: extend edgezero-cli with template/plugin style commands (similar to Spin templates) to streamline new app scaffolds and provider-specific wiring.
  • CLI parity backlog: add edgezero --list-adapters, standardize exit codes, search up for edgezero.toml, respect RUST_LOG for dev output, and bake in hot reload for edgezero dev.

Open Design Questions (for later pickup)

  • Provider priorities: focus on Fastly Compute@Edge, then Cloudflare Workers.
  • Minimum Rust version (MSRV) target.
  • Async story: keep core sync or introduce async features (Tokio) behind flags?
  • Request/Response mapping rules (header casing, multi-value headers, binary bodies).
  • Caching/edge-specific headers: how much to standardize (e.g., Surrogate-Control)?
  • Dev UX: integrate a local hyper server behind a feature vs. keeping zero-deps TCP server.
  • Packaging/deploy: preferred tooling (Fastly CLI/API; AWS SAM/CDK or native Lambda tooling).
  • Config format: TOML/JSON/YAML; env overlays.
  • License and contribution guidelines. License set to Apache-2.0.

Execution Log

Codex Plan (2024-05-07)

  • Review repository guides (README.md, AGENTS.md) to capture stated goals and workflows.
  • Map the crate layout by skimming Cargo.toml and key crate README/doc comments.
  • Summarize findings on EdgeZero architecture, adapters, and tooling for the user's quick reference.

Familiarization Summary

  • EdgeZero centres around edgezero-core, which provides provider-neutral HTTP primitives, routing, middleware, logging, and proxy abstractions; adapters reuse these types to stay DRY.
  • Controller ergonomics live in edgezero-controller plus edgezero-macros, offering #[action] functions that extract typed inputs and return Responders.
  • Provider adapters (edgezero-adapter-fastly, edgezero-adapter-cloudflare) are feature-gated; each exposes handle plus logging/proxy helpers while delegating behaviour to the core crate.
  • Supporting crates include edgezero-std for stdout logging, edgezero-cli for dev server + scaffolding, and demo workspaces under examples/app-demo to validate provider flows.
  • Workspace Cargo.toml keeps default members lean (core only) to support offline builds; additional crates are opt-in via features when targeting specific adapters.

Codex Plan (2025-09-18 - Validation Extractors)

  • Review existing parameter/body extractors to identify integration points for validator-backed wrappers.
  • Implement validated variants for path/query (and other relevant) extractors reusing validator::Validate.
  • Add unit tests covering success and failure cases for the new extractors.
  • Update public exports/docs to surface the new API and capture the change in this TODO review.

Codex Plan (2025-09-18 - ValidateJson Alias)

  • Confirm existing JSON validation support and identify changes needed for ValidateJson ergonomics.
  • Introduce a ValidateJson alias (or equivalent helper) that reuses ValidatedJson<T>.
  • Update docs/tests to reference the new alias where appropriate and log the change in this TODO review.

Codex Plan (2025-09-18 - Remove ValidateJson Alias)

  • Remove the ValidateJson wrapper from extractors/tests/exports, keeping ValidatedJson as the canonical helper.
  • Revert docs and TODO review notes referencing ValidateJson.
  • Re-run controller crate tests to confirm everything still passes.

Review (2025-09-18 02:10 UTC)

  • Recorded a three-step familiarization plan, executed documentation + crate walkthrough, and captured architectural notes under the plan section.
  • Assumed existing docs (README.md, AGENTS.md) are the latest sources of truth; no discrepancies observed during review.
  • No outstanding issues or errors encountered; no code changes outside TODO.md updates.

Review (2025-09-18 02:15 UTC)

  • Introduced ValidatedPath and ValidatedQuery extractors leveraging validator::Validate, re-exported them, and broadened docs in README.md.
  • Added targeted unit tests verifying both success and failure cases for validated path/query extraction; cargo test -p edgezero-controller passes.
  • No additional assumptions beyond existing validation behaviour; no unresolved issues noted.

Review (2025-09-18 02:21 UTC)

  • Removed the redundant ValidateJson<T> wrapper per updated guidance, keeping ValidatedJson<T> as the single validator-backed JSON extractor.
  • Cleaned README/TODO references accordingly and pruned alias-specific tests; cargo test -p edgezero-controller still passes.
  • Validator helpers now cover path, query, and JSON via Validated* types only.

Review (2025-09-18 03:08 UTC)

  • Implemented edgezero build|deploy --adapter fastly by wiring cargo wasm32 builds and Fastly CLI invocation in the CLI.
  • Documented optional dev-example dependency in edgezero-cli/README.md and added error handling for unsupported adapters.
  • Verified builds with cargo test -p edgezero-cli.

Review (2025-09-18 03:27 UTC)

  • Moved Fastly build/deploy/serve helpers into edgezero-fastly behind a cli feature and updated edgezero-cli to call through the provider abstraction.
  • Improved Fastly manifest discovery to prefer the nearest crate manifest and added unit coverage for the new path logic. cargo test -p edgezero-fastly --features cli, cargo test -p edgezero-cli.

Codex Plan (2025-09-19 - Test Command Guidance)

  • Confirm current workspace layout to know which cargo commands exercise all crates.
  • Advise user on running full test suite and targeted variants as needed.

Codex Plan (2025-09-19 - Fix edgezero-fastly Tests)

  • Reproduce cargo test -p edgezero-fastly failure to capture the exact error. (Unable to reproduce; command succeeds locally.)
  • Inspect relevant sources/tests to identify root cause. (Fastly feature requires wasm32-wasip1 target; host builds fall back to stub with no tests.)
  • Implement minimal fix addressing the failure while staying within adapter boundaries. (Blocked: cargo test --features fastly --target wasm32-wasip1 currently fails under Viceroy with macOS keychain access errors.)
  • Re-run targeted tests (and any impacted suite) to confirm resolution. (Blocked.)
  • Summarize work and outcomes in TODO review section with timestamp. (Blocked.)

Codex Plan (2025-09-19 - Comprehensive Test Runner)

  • Audit required commands for workspace + feature coverage including Fastly wasm build.
  • Implement shell script to orchestrate the checks with Fastly-specific handling.
  • Document script usage and outcomes in TODO review section with timestamp.

Codex Plan (2025-09-19 - Test Script Adjustments)

  • Define the reduced test-only scope for scripts/run_tests.sh, including Fastly wasm coverage.
  • Update the script to drop fmt/clippy/build steps and run the desired test commands (host + wasm).
  • Ensure script messaging guides users when Fastly wasm tests cannot run (e.g., Viceroy keychain issues).
  • Record the changes and remaining caveats in TODO review section with timestamp.

Codex Plan (2025-09-19 - Test Script UX)

  • Decide on section markers/format for clearer script output.
  • Update scripts/run_tests.sh to print section headers around each major test group.
  • Verify the script still exits with helpful guidance on wasm failures.
  • Log the changes in TODO review section with timestamp.

Codex Plan (2025-09-19 - Simplify Wasm Failure Messaging)

  • Remove custom failure messaging in scripts/run_tests.sh so wasm tests fail like other sections.
  • Verify script behaviour post-change.
  • Update TODO review section with outcome and timestamp.

Codex Plan (2025-09-19 - Script Preflight Checks)

  • Consolidate binary/target verification at the top of scripts/run_tests.sh.
  • Ensure checks cover both cargo, rustup, and wasm target before any tests run.
  • Validate script after refactor and document changes in TODO review.

Codex Plan (2025-09-19 - Controller Streaming Options)

  • Inspect controller RouteSet/RouteSpec to identify extension points for route-level body mode.
  • Implement API changes allowing controllers to opt into streaming/buffered modes and wire through to core router.
  • Add tests covering streaming behaviour via controller routes.
  • Document changes in TODO review section with timestamp.

Codex Plan (2025-09-19 - App Demo Migration to Redesigned Core)

  • Audit the app-demo crates to map controller-era APIs to the redesigned edgezero-core interfaces.
  • Refactor app-demo-core handlers and routing to the new builder/extractor patterns, keeping streaming coverage intact.
  • Update Fastly/Cloudflare entrypoints (and related metadata) so they compile against the redesigned core hooks.
  • Run targeted tests for the app-demo crates and prepare review notes for TODO.md.

Codex Plan (2025-09-19 - Restore cargo test Host Compilation)

  • Pinpoint the dependency pulling in worker 0.0.24 and decide whether to remove or upgrade it so builds only use worker 0.6.x.
  • Adjust the Cloudflare adapter to drop the outdated logger dependency (or replace it) while keeping logging behaviour sensible.
  • Ensure workspace manifests stop requesting the older crate and update docs if they reference it.
  • Re-run cargo test (or equivalent host checks) to confirm the build completes, then capture the outcome in TODO review notes.

Codex Plan (2025-09-19 - Fastly Adapter Logger Module)

  • Add a dedicated logger.rs to the Fastly adapter mirroring the Cloudflare structure.
  • Re-export the new logger helper from lib.rs and update call sites if needed.
  • Ensure any docs or templates referencing Fastly logging stay accurate.
  • Run cargo test to confirm the refactor behaves as before.

Codex Plan (2025-09-19 - Code Coverage Investigation)

  • Survey current test command usage to see if any coverage tooling is documented or scripted.
  • Evaluate Rust-friendly coverage options (e.g. cargo llvm-cov, grcov) for compatibility with the workspace (wasm targets, feature flags).
  • Prototype a coverage run on a representative crate (likely edgezero-core) to gauge feasibility and capture required tooling steps.
  • Summarize recommended approach, prerequisites, and open questions in TODO review notes.

Codex Plan (2025-09-19 - Core Coverage Backfill)

  • Expand unit tests for edgezero_core::context::RequestContext to cover extraction success/failure, JSON/form parsing, and path/query edge cases.
  • Add tests for edgezero_core::error::EdgeError constructors and conversion paths, ensuring status codes + messages are asserted.
  • Exercise middleware chaining (middleware.rs) with mock handlers to cover both middleware execution and early returns.
  • Write targeted tests for Body conversions (streaming JSON failure, into_bytes panic guard, etc.) and Response helper methods.
  • Introduce extractor/responder tests to lift coverage in extractor.rs and responder.rs.
  • Add compile-fail or snapshot tests for the edgezero-macros::action proc macro to cover unsupported inputs.
  • Run cargo llvm-cov --package edgezero-core (and any new test suites) to validate coverage improvements.

Codex Plan (2025-09-19 - App Demo Workspace Dependencies)

  • Switch app-demo crates to consume workspace-shared dependencies ({ workspace = true }) for core libraries and tooling.
  • Ensure root Cargo.toml workspace dependencies cover the required crates (adding any missing entries).
  • Update adapter/demo crate manifests to drop redundant version/specification lines in favour of workspace references.
  • Run cargo test (or targeted checks) to confirm builds remain healthy.

Codex Plan (2025-09-19 - Fastly SDK 0.11 Migration)

  • Update the Fastly adapter to compile against fastly 0.11 APIs (request building, async streaming, response conversion).
  • Adjust logging helper to the new log-fastly builder API.
  • Ensure proxy tests/builds pass for streaming + compression paths.
  • Verify the app demos compile for wasm32-wasip1 with the updated SDK.

Review (2025-09-19 01:28 UTC)

  • Rebuilt app-demo-core against the redesigned edgezero-core by wiring routes through RouterService::builder, swapping controller extractors for edgezero_core equivalents, and preserving the streaming example via Body::stream.
  • Updated Fastly and Cloudflare entrypoints to rely on the adapter dispatch helpers, returning converted fallback responses when adapter conversion fails so we avoid propagating runtime errors.
  • Tests: cargo test -p app-demo-core, cargo check -p app-demo-adapter-fastly; Cloudflare host build (cargo check -p app-demo-adapter-cloudflare) still fails in worker 0.0.24 because js_sys::Iterator lacks unwrap on this toolchain—matches the prior dev warning and needs upstream crate updates for host checks.
  • Assumptions: routing defaults (no auto OPTIONS) remain acceptable for the demo; Cloudflare fallback uses Response::error to surface adapter failures until worker exposes richer constructors.

Review (2025-09-19 01:47 UTC)

  • Removed the worker_logger dependency (source of the legacy worker 0.0.24 transitive pull) and replaced it with a minimal console_log!-backed logger inside edgezero-adapter-cloudflare, so host builds only compile the current worker 0.6 tree.
  • Updated the Fastly/Cloudflare demos to call the adapter crates directly (correct crate ids) and gated the Cloudflare fetch handler behind target_arch = "wasm32" so x86 test builds don’t require Worker-only APIs.
  • Docs now reference the new logging flow, and cargo test across the workspace succeeds after the change.

Review (2025-09-19 01:50 UTC)

  • Split Fastly logging into a logger.rs module (mirroring Cloudflare) and re-exported it from the adapter, keeping log_fastly usage behind the wasm+feature gate.
  • No call-site changes were required—existing demos already target edgezero_adapter_fastly::init_logger()—but the shared structure makes the adapters consistent.
  • cargo test still passes; the log_fastly manifest warning persists (pre-existing).

Review (2025-09-19 01:56 UTC)

  • Confirmed coverage isn’t wired into existing scripts; scripts/run_tests.sh strictly runs host + wasm tests without instrumentation.
  • Verified cargo-llvm-cov is available via asdf and works against host crates: cargo llvm-cov --package edgezero-core --lcov --output-path target/coverage/edgezero-core.lcov produced an LCOV file and summary (~52% line coverage for edgezero-core, proc modules currently untested).
  • Suggested path forward: document cargo llvm-cov usage (including creating target/coverage/), limit runs to host-capable crates, and treat wasm-only crates as out-of-scope unless a wasm coverage workflow is introduced.
  • Next steps could include adding a helper script and/or CI job if coverage reporting becomes a target metric.

Review (2025-09-19 02:08 UTC)

  • Added focused unit tests across edgezero-core for request contexts (path/query/json/form), error helpers, middleware chaining, bodies/responses, extractors, and responders; mirrored coverage for the #[action] macro via direct expand_action_impl assertions.
  • Reworked Clockflare/Fastly-specific comparisons where necessary (stringy path params, async middleware helpers) so the new tests reflect real behaviour.
  • cargo test passes, and cargo llvm-cov --package edgezero-core --summary-only now reports ~69% line coverage (up from ~52%); extractor/macro modules remain partially uncovered but key runtime surfaces are exercised.

Review (2025-09-19 02:12 UTC)

  • Added workspace dependency bindings for edgezero-core, adapters, demos, fastly, and worker in the root manifest, then pointed the app-demo crates at them so they share versions with the framework.
  • Demo manifests now rely on { workspace = true } for edgezero-adapter-*, app-demo-core, log, serde, fastly, and worker, removing bespoke paths/versions.
  • cargo test passes across the workspace after the manifest refactors.

Review (2025-09-19 02:35 UTC)

  • Temporary stopgap: adapter builds against Fastly 0.11 by buffering request/response bodies and wiring a new logging helper; wasm demo (cargo build -p app-demo-adapter-fastly --target wasm32-wasip1) and cargo test now succeed.
  • Regression: streaming proxy behaviour (and streaming decompression) is currently disabled because bodies are buffered; follow-up work is required to restore async streaming under the new SDK.

Review (2025-09-19 07:35 UTC)

  • Updated edgezero_adapter_fastly::dispatch to surface fastly::Error directly; demo entrypoints can now return dispatch(&app, req) without hand-rolling fallback responses.
  • Header and request conversions match the Fastly 0.11 API, cargo test and cargo build -p app-demo-adapter-fastly --target wasm32-wasip1 remain green.

Review (2025-09-19 15:25 UTC)

  • Noted workspace members/default-members to explain why cargo test covers only core by default.
  • Documented commands for running all workspace tests plus targeted crates and feature gates.
  • No code changes required; guidance only.

Review (2025-09-19 15:55 UTC)

  • Added scripts/run_tests.sh (initially run_all_checks.sh) to bundle fmt, clippy, and workspace tests while excluding the wasm-only Fastly demo during host runs.
  • Script verifies wasm32-wasip1 availability and builds both the Fastly adapter (edgezero-fastly with fastly feature) and demo binary for the wasm target to cover edge-only code paths.
  • Provides a single entry point for comprehensive validation; Fastly tests remain blocked on native hosts, so wasm builds act as the smoke check.

Review (2025-09-19 16:05 UTC)

  • Trimmed scripts/run_tests.sh to a test-only flow: workspace tests (excluding app-demo-adapter-fastly), Fastly CLI tests, and wasm32 fastly feature tests run from the adapter crate.
  • Added failure guidance when Viceroy cannot access macOS keychain certificates; users can set SSL_CERT_FILE or run where a keychain is available before retrying.
  • Command still surfaces the Fastly wasm failure in this sandbox (certificate issue), but other suites pass; no additional code changes required.

Review (2025-09-19 16:15 UTC)

  • Added bold section separators around workspace, Fastly CLI, and wasm test phases in scripts/run_tests.sh for easier scanning.
  • Confirmed the wasm phase still surfaces the keychain guidance when Viceroy fails; other sections remain unaffected.
  • No code changes beyond the script; tests behave as before (wasm step still blocked in sandbox environment).

Review (2025-09-19 16:25 UTC)

  • Dropped the custom Viceroy guidance in scripts/run_tests.sh; now all phases use run and rely on set -e for failures.
  • Confirmed workspace and Fastly CLI sections still pass while wasm tests fail with the raw keychain error (expected in this sandbox).
  • No additional adjustments required.

Review (2025-09-19 16:32 UTC)

  • Preflight now checks for cargo, rustup, and the wasm32-wasip1 target before any test phases run, ensuring early exits on missing tooling.
  • Post-change run confirms behaviour: host tests pass, Fastly wasm still fails due to Viceroy keychain access in this sandbox—expected.
  • No further adjustments needed.

Review (2025-09-19 16:45 UTC)

  • Added per-route body mode to controller RouteSpec/RouteEntry, enabling callers to supply RouteOptions (e.g. streaming/buffered) that are preserved when applying routes to the core app.
  • Introduced RouteSet::push_entry helper so nested/merged route sets keep their body configuration.
  • Extended controller tests to cover streaming coercion and buffered rejection paths via the new API; cargo test -p edgezero-controller passes.

Codex Plan (2025-09-20 - Wasm Runner Docs)

  • Identify the best documentation spot (likely README.md) for Wasmtime/Viceroy installation instructions.
  • Draft concise install steps for Wasmtime and Viceroy, ensuring commands work on macOS/Linux.
  • Update the chosen doc section with the new prerequisites and cross-check formatting/links.

Codex Plan (2025-09-20 - Fastly Wasm Test Investigation)

  • Reproduce the failing Fastly wasm tests via cargo test --features fastly --target wasm32-wasip1 in crates/edgezero-adapter-fastly.
  • Inspect recent Fastly runtime changes to pinpoint incompatibilities (target env, required runner, feature flags).
  • Identify minimal fixes or configuration adjustments to get wasm tests passing again (no implementation yet).
  • Summarize findings and proposed solution in response; note blockers if unresolved.

Codex Plan (2025-09-20 - Async Compression Adapters)

  • Add async-compression dependency (using workspace versioning) and wire it into Fastly/Cloudflare adapter manifests.
  • Refactor Fastly adapter response/body decoding to use GzipDecoder/BrotliDecoder from async-compression, removing custom flate2 state machines.
  • Mirror the same decompression helper in the Cloudflare adapter so both adapters share behaviour.
  • Run targeted tests (cargo test --features fastly, cargo test --features cloudflare) to confirm gzip/brotli decoding paths.
  • Update docs (if needed) to reflect the new dependency or behaviour.

Codex Plan (2025-09-20 - Core Compression Helpers)

  • Introduce a compression helper module in edgezero-core that exposes shared gzip/brotli decoding for TryStream<Result<Vec<u8>>> inputs.
  • Update Fastly adapter to use the new core helper instead of its local decode_* implementations.
  • Update Cloudflare adapter to use the same helper, removing duplicate code and imports.
  • Add unit tests in edgezero-core covering gzip/brotli decoding via the helper.
  • Re-run adapter/core tests to confirm everything compiles and passes.

Codex Plan (2025-09-20 - Cloudflare Wasm MapErr Fix)

  • Restore the TryStreamExt import in the Cloudflare adapter so map_err resolves for wasm builds.
  • Run cargo test --features cloudflare --target wasm32-wasip1 -- --nocapture to confirm the wasm build clears (runner failures aside).

Codex Plan (2025-09-20 - Cloudflare Demo Build Fix)

  • Add the missing main entrypoint in examples/app-demo/crates/app-demo-adapter-cloudflare/src/main.rs (call the adapter handler).
  • Bring edgezero_core::response::IntoResponse into scope or adjust error handling so EdgeError converts correctly.
  • Drop unused Write import in the Cloudflare adapter after the refactor.
  • Re-run cargo build -p app-demo-adapter-cloudflare --features cloudflare --target wasm32-unknown-unknown to confirm the demo compiles.

Codex Plan (2025-09-20 - Cloudflare Entry Simplification)

  • Update Cloudflare adapter dispatch to return worker::Result so callers can propagate errors directly.
  • Simplify the demo entrypoint to mirror the Fastly example (build app, init logger, call dispatch).
  • Rebuild the Cloudflare demo for wasm to confirm no regressions.

Review (2025-09-20 21:30 UTC)

  • Added Wasmtime/Viceroy installation guidance plus runner instructions to README.md so wasm tests list their runtime prerequisites explicitly.
  • Reproduced the Fastly wasm test failure: Viceroy runner aborts with “No keychain is available” while loading native certs, preventing tests from executing.
  • Proposed using Wasmtime as the wasm32-wasip1 test runner (via env override or .cargo/config adjustment) or configuring Viceroy to skip the system trust store; left implementation for follow-up.
  • Logged the failing cargo test output in debug.md for future reference; no code changes were made to the adapter runtime itself.

Review (2025-09-20 22:05 UTC)

  • Added async-compression as a workspace dependency and enabled it in both adapter manifests to centralise gzip/brotli handling.
  • Replaced the bespoke flate2/brotli state machines in Fastly and Cloudflare adapters with shared GzipDecoder/BrotliDecoder pipelines over StreamReader.
  • Host-side adapter tests pass (cargo test -p edgezero-adapter-fastly, cargo test -p edgezero-adapter-cloudflare); wasm targets still require platform runners but behaviour is unchanged.
  • Documentation already covered gzip/brotli support, so no content updates were necessary beyond noting the new dependency in review.

Review (2025-09-20 22:45 UTC)

  • Added compression.rs to edgezero-core exposing shared decode_gzip_stream/decode_brotli_stream helpers over async-compression, plus unit tests that confirm round-tripping gzip and brotli blocks.
  • Fastly and Cloudflare adapters now call the core helpers, removing duplicated decoder loops and dropping their direct async-compression dependency.
  • Workspace dependencies updated (async-stream shared, futures promoted for core) and host tests pass (cargo test -p edgezero-core, cargo test -p edgezero-adapter-fastly, cargo test -p edgezero-adapter-cloudflare).

Review (2025-09-20 22:58 UTC)

  • Re-added futures_util::TryStreamExt to the Cloudflare adapter so ByteStream::map_err compiles for wasm targets.
  • cargo test --features cloudflare --target wasm32-wasip1 -- --nocapture now builds the wasm binary; execution still fails under Wasmtime because Workers headers rely on wasm-bindgen imports unavailable in this runtime, which matches prior expectations.

Review (2025-09-20 23:10 UTC)

  • Added #![cfg_attr(target_arch = "wasm32", no_main)] and imported edgezero_core::response::IntoResponse so the Cloudflare demo binary compiles to wasm without missing entrypoint errors; error handling now converts EdgeError via into_response.
  • Cleaned up the Cloudflare adapter’s stale Write import and set the demo crate to depend on edgezero-core explicitly.
  • cargo build -p app-demo-adapter-cloudflare --features cloudflare --target wasm32-unknown-unknown completes successfully (only standard warnings remain).

Review (2025-09-20 23:25 UTC)

  • edgezero_adapter_cloudflare::dispatch now returns worker::Result<Response> after converting internal EdgeErrors to worker::Error, eliminating the need for a separate helper.
  • The Cloudflare demo entrypoint matches the Fastly style: build the app, init the logger, and await dispatch.
  • cargo build -p app-demo-adapter-cloudflare --features cloudflare --target wasm32-unknown-unknown stays green (standard brotli warning only).
  • Updated CLI templates so newly scaffolded apps use edgezero_adapter_fastly::dispatch / edgezero_adapter_cloudflare::dispatch with logger init, matching the demos.

Current Task (expand_action_impl coverage + cleanup)

  • Audit expand_action_impl behaviour to list any untested code paths or edge cases (e.g., tuple destructuring errors, non-RC tuple structs, extractor invocation).
  • Add focused tests in crates/edgezero-macros/src/action.rs to cover the missing scenarios while keeping contract unchanged.
  • Simplify the implementation if warranted (e.g., helper extraction, clearer error handling) without altering observable behaviour; highlight the deltas in the review section.
  • Run cargo test workspace-wide and note results.
  • Record a new review entry summarising the changes, assumptions, and outstanding items.

Review (2025-11-07 17:52:45 UTC)

  • Summary: Extracted RequestContext pattern normalisation into a helper for clearer error aggregation and broadened the macro tests to cover attribute arguments, self receivers, tuple binding mistakes, and extractor codegen so expand_action_impl remains well-specified.
  • Assumptions: String-matching the generated FromRequest call stays stable because we don't plan to rename that trait or method; tuple destructuring for RequestContext will continue to expect a single binding.
  • Outstanding: None; cargo test (workspace) succeeded after the new tests.

Current Task (template proxy_demo parity)

  • Update crates/edgezero-cli/src/templates/core/src/handlers.rs.hbs so the generated proxy_demo matches the example handler (#[action] + RequestContext(ctx): RequestContext binding).
  • Run cargo test to ensure the template change doesn’t break the workspace.
  • Capture a review entry summarising the template update and any follow-ups.

Review (2025-11-07 17:55:17 UTC)

  • Summary: Aligned the CLI template’s proxy_demo definition with the app demo (now tagged with #[action] and destructuring RequestContext) so generated projects inherit the same extractor ergonomics.
  • Assumptions: Template consumers expect the proxy route to behave like the example app; no additional template files reference the old signature.
  • Outstanding: None; cargo test across the workspace passed after the template tweak.

Current Task (RequestContext pattern support)

  • Teach the #[action] macro to accept tuple-struct style parameters like RequestContext(ctx): RequestContext by normalising that pattern to the owned context argument (ensure the same ownership semantics and keep duplicate checks).
  • Update the proxy_demo handler in examples/app-demo/crates/app-demo-core/src/handlers.rs to demonstrate the new binding style.
  • Run cargo test for the workspace and fix any regressions.
  • Append a new review entry (summary, assumptions, outstanding items) once the change is complete.

Review (2025-11-07 17:48:52 UTC)

  • Summary: Normalised RequestContext parameters passed through #[action] so tuple-style bindings (e.g. RequestContext(ctx): RequestContext) collapse to the owned context, added regression tests covering the pattern, and showcased the syntax on proxy_demo.
  • Assumptions: Only one owned RequestContext parameter should exist per handler; tuple-style bindings only contain a single pattern element.
  • Outstanding: None; cargo test passed for the entire workspace (no warnings after the final iteration).

Review (2025-11-07 17:39:28 UTC)

  • Summary: Extended #[action] to accept a single RequestContext parameter (with duplicate detection and helper tests) and applied the attribute to proxy_demo, relying on the original handler logic.
  • Assumptions: RequestContext parameters are owned values (no reference variants needed) and only one is expected per handler.
  • Outstanding: None; cargo test across the workspace passed after the macro test adjustment.

Codex Plan (2026-01-27 - Documentation Exposure Review)

  • Diff main vs current branch to scope doc-related changes.
  • Review updated/new docs for redundancy, inconsistency, missing coverage, and verbosity.
  • Check overall documentation thoroughness and note gaps vs the framework surface area.
  • Compile review findings with file references and prioritized severity.

Review (2026-01-27 00:20:19 UTC)

  • Summary: Compared main against the feature/vitepress branch, audited the new VitePress guide set plus CLI/adapter docs, and assembled a prioritized findings list focused on inaccuracies, redundancy, missing coverage, and verbosity.
  • Assumptions: Documentation review targets current source behavior (not proposed future APIs); adapter contract expectations should reflect existing Fastly/Cloudflare/Axum implementations unless explicitly labeled aspirational.
  • Outstanding: None (review-only; no code changes applied).

Review (2026-01-27 00:50:51 UTC)

  • Summary: Aligned guide content with current EdgeZero APIs (App::build_app, adapter entrypoints, middleware signature, proxy clients), corrected routing/streaming/handlers/CLI details, and refreshed manifest/logging docs; added the missing CLI/dev features list to the roadmap.
  • Assumptions: Docs now reflect current behavior for Fastly/Cloudflare/Axum adapters and the CLI; future features are captured explicitly in the roadmap rather than implied in guides.
  • Outstanding: None (docs-only updates).

Review (2026-01-27 01:02:05 UTC)

  • Summary: Condensed the proxying guide into a single end-to-end example that uses adapter proxy handles, and added short logging-status callouts to the Fastly, Cloudflare, and Axum adapter docs.
  • Assumptions: The proxy handle approach is the preferred public pattern; adapter logging notes should stay concise and match current defaults.
  • Outstanding: None (docs-only updates).

Review (2026-01-27 01:05:18 UTC)

  • Summary: Added a dedicated docs/guide/roadmap.md page containing the current roadmap and design questions, and linked it in the VitePress sidebar.
  • Assumptions: The roadmap page mirrors TODO.md and is a public-facing summary of ongoing planning work.
  • Outstanding: None (docs-only updates).

Review (2026-01-27 01:09:04 UTC)

  • Summary: Expanded the roadmap page with doc/CLI alignment gaps found during review and added an explicit Spin support item.
  • Assumptions: The new roadmap bullets are directional and do not imply implementation order.
  • Outstanding: None (docs-only updates).

Codex Plan (2026-01-27 - Post-Merge Docs Review)

  • Diff main vs current branch to scope doc-related changes post-merge.
  • Re-review docs for redundancy, inconsistencies, missing coverage, thoroughness, and verbosity.
  • Summarize findings with file references and prioritized issues.

Review (2026-01-27 01:40:07 UTC)

  • Summary: Re-ran the post-merge documentation audit against main, flagging the top doc/behavior mismatches (CLI flags, trigger adapter filtering, Fastly backend wording) plus missing manifest field coverage and CLI passthrough docs.
  • Assumptions: Review targets current runtime behavior; undocumented manifest fields and adapter filters should be explicitly labeled as reserved/ignored if they remain unimplemented.
  • Outstanding: None (review-only; no code changes applied).

Codex Plan (2026-01-27 - Docs Fixes After Review)

  • Align CLI usage docs with actual flags (edgezero new, passthrough args) and remove/replace unsupported examples.
  • Reconcile adapter/proxy docs (Cloudflare vs Fastly outbound request wording; adapter filtering behavior).
  • Document or mark reserved manifest fields (app.version, app.kind) and trim duplicate CLI install instructions.
  • Summarize changes with file references in TODO review entry.

Review (2026-01-27 01:58:05 UTC)

  • Summary: Aligned CLI and configuration docs with actual flags and manifest behavior, clarified Fastly/Cloudflare outbound request wording, and trimmed duplicate CLI install guidance; captured test failures in debug.md.
  • Assumptions: Manifest version and kind remain reserved fields until the parser is extended; adapter filters stay informational unless app! adds enforcement.
  • Outstanding: cargo test failed in edgezero-adapter-axum integration tests due to local port bind permissions (see debug.md).

Review (2026-01-27 02:13:01 UTC)

  • Summary: Cleaned the roadmap to focus on forward-looking items, moved completed work into a "Completed (Recent)" section, removed the stale date header, and tightened Spin wording to "mirror" rather than "match."
  • Assumptions: The completed items reflect the current docs/tests baseline; future roadmap entries should be updated as features land.
  • Outstanding: cargo test failed in edgezero-adapter-axum integration tests due to local port bind permissions (see debug.md).

Review (2026-01-27 02:17:12 UTC)

  • Summary: Pruned the open design questions to only unresolved items, and moved resolved topics (platform focus, adapter mapping rules) into the completed section.
  • Assumptions: Remaining open questions reflect genuine policy decisions rather than already-shipped behavior.
  • Outstanding: cargo test failed in edgezero-adapter-axum integration tests due to local port bind permissions (see debug.md).

Codex Plan (2026-01-27 - Roadmap Cleanup)

  • Audit docs/guide/roadmap.md for redundancy, stale dating, and overlapping bullets.
  • Restructure the roadmap into clearer groupings (e.g., near-term vs later, or by theme) and tighten wording.
  • Keep Spin-related intent but ensure it reads as “mirrors” and does not overpromise; remove any duplicate items.
  • Update TODO review entry with summary and file references.

Codex Plan (2026-01-27 - Open Design Questions Cleanup)

  • Review docs/guide/roadmap.md "Open Design Questions" and identify which are already resolved.
  • Remove resolved items or move them into "Completed (Recent)" with brief phrasing.
  • Keep only genuinely open questions, tightening wording to avoid duplication.
  • Update TODO review entry with summary and file references.

Codex Plan (2026-01-27 - Roadmap Doc Page)

  • Add a dedicated roadmap page under docs/guide/roadmap.md.
  • Populate it with the roadmap content (including the CLI parity backlog list).
  • Wire the roadmap page into the VitePress sidebar/navigation.

Codex Plan (2026-01-27 - Roadmap Findings + Spin Support)

  • Add the key doc/CLI gaps found during the review to the roadmap page.
  • Add an explicit roadmap item for Spin support (define scope at the doc level).

Codex Plan (2026-01-27 - Proxying Snippet + Adapter Logging Callout)

  • Condense proxying guide into a single end-to-end example using adapter proxy handles.
  • Add a short logging status callout to the adapter docs (Axum/Cloudflare/Fastly).

Codex Plan (2026-01-27 - Docs Alignment + Roadmap Additions)

  • Update guides to reflect current APIs (App::build_app, adapter entrypoints, middleware signature, proxy client usage).
  • Correct routing, streaming, handlers, and CLI reference docs to match current behavior.
  • Refresh configuration docs to align with manifest schema and loader APIs.
  • Add missing-feature backlog (list-adapters, exit codes, manifest search-up, RUST_LOG, hot reload) to the roadmap section.

Codex Plan (2026-02-10 - License Metadata Consistency)

  • Canonicalize the Apache-2.0 LICENSE appendix URL wording to match standard text.
  • Regenerate docs/package-lock.json metadata so the root package license matches docs/package.json.
  • Standardize license wording in user-facing docs (README.md, docs footer) for consistency.
  • Run cargo test and record outcomes in a review entry with timestamp.

Review (2026-02-10 14:08:30 PST)

  • Summary: Canonicalized Apache-2.0 appendix wording in LICENSE, aligned docs package root license metadata by regenerating docs/package-lock.json, and standardized user-facing license text to "Apache License 2.0" in README.md and docs/.vitepress/config.mts.
  • Assumptions: Keeping transitive dependency license fields unchanged in docs/package-lock.json is correct; only the root package license needed alignment.
  • Outstanding: No functional issues found; cargo test passes when run without sandbox socket restrictions.