Skip to content

ROADMAP.adoc

Latest commit

 

History

History
108 lines (83 loc) · 5 KB

ROADMAP.adoc

File metadata and controls

108 lines (83 loc) · 5 KB

HTTP Capability Gateway Roadmap

Current Status (2026-04-16)

Version 0.1.0-dev. CRG grade C (achieved 2026-04-04).

The repository contains 19 Elixir modules, 2 Zig FFI parsers, 2 Idris2 ABI modules, and a growing test suite. The implementation covers the core gateway pipeline but verification is catching up. See STATE.adoc for the full picture.

MVP Scope Definition (v0.1.0)

The MVP is a narrow HTTP verb governance prefilter. It is NOT a general-purpose API gateway, load balancer, or TLS terminator. The scope is intentionally constrained so that every claim can be backed by an executed test.

What the MVP Does

  1. Policy loading: Read a YAML policy file (DSL v1) at startup and on reload.

  2. Policy validation: Reject malformed policies before compilation.

  3. Policy compilation: Compile validated policy into dual ETS tables (exact O(1) + regex O(r) + global O(1)).

  4. Trust extraction: Read trust level from X-Trust-Level header (stripped for non-trusted proxies).

  5. Verb governance: For each request, lookup the policy rule for (path, verb) and evaluate rank(trust) >= rank(exposure).

  6. Allow/deny: Forward allowed requests to a single configured backend via HTTP. Deny with 403 or stealth response.

  7. Stealth mode: Return configurable status codes (e.g. 404) instead of 403 to hide endpoint existence.

  8. Rate limiting: Per-client token bucket with trust-level-based quotas.

  9. Health/readiness probes: /health, /ready endpoints.

  10. Structured logging: JSON-formatted access decisions with telemetry.

  11. Atomic policy reload: Swap to new policy tables without downtime.

What the MVP Does NOT Do

  • No GraphQL or gRPC governance (handlers exist but are stubs; not MVP scope)

  • No multi-backend load balancing

  • No TLS termination

  • No dynamic trust scoring or control plane

  • No plugin system

  • No web UI dashboard

  • No distributed clustering

  • No Kubernetes operator

MVP Proof Requirements

Each claim above must have at least one passing test:

Claim Test File

Policy loading

test/policy_loader_test.exs

Policy validation

test/policy_validator_test.exs

Policy compilation

test/policy_compiler_test.exs

Trust extraction

test/security_test.exs (header handling)

Verb governance

test/gateway_test.exs, test/e2e_test.exs

Allow/deny decisions

test/e2e_test.exs (full lifecycle)

Stealth mode

test/gateway_test.exs (stealth describe block)

Rate limiting

test/gateway_test.exs (via plug pipeline)

Health/readiness

test/e2e_test.exs (health and readiness)

Structured logging

Telemetry events emitted (verified by integration)

Atomic policy reload

test/e2e_test.exs (hot-reload tests)

Request sanitization

test/security_test.exs

Trust spoofing prevention

test/security_test.exs (header stripping)

No atom exhaustion

test/fuzz_test.exs (arbitrary method strings)

No crash on arbitrary input

test/fuzz_test.exs (combined fuzzing)

P0 Release Blockers

  • ✓ Reconcile contradictory status docs so the repo has one truthful current-state story.

  • ✓ Add real security tests for request sanitization, header handling, SSRF resistance, and capability-token validation.

  • ✓ Add end-to-end tests for request lifecycle, policy hot reload, and upstream proxy behavior.

  • ✓ Remove tests/fuzz/placeholder.txt and add real property-based fuzz tests.

  • ✓ Define the supported MVP narrowly enough that it can be proven.

P1 Gateway Hardening

  • ✓ Benchmark routing, policy evaluation, and rate limiting. test/benchmark_test.exs.

  • ✓ Add concurrency and failure-mode tests for rate limiter, circuit breaker, and reload paths. test/concurrency_test.exs.

  • ✓ Tighten operator documentation around what protocols and trust sources are actually supported. docs/SUPPORTED-FEATURES.md.

  • ✓ Keep the runtime role constrained to prefiltering before origin-side enforcement. docs/SCOPED-DEPLOYMENT.md.

P2 Productization

  • ✓ Use the gateway in front of selected API routes first, not the whole application surface. See docs/SCOPED-DEPLOYMENT.md.

  • ✓ Add release criteria that require executed tests rather than topology percentages. See docs/RELEASE-CRITERIA.md.

  • ✓ Mark older design-only documents as historical where they no longer reflect the codebase. ROADMAP-v2.md, IMPLEMENTATION-ROADMAP.md, TOPOLOGY.md updated.

Milestones

v0.1.x - Narrow MVP

  • ❏ Truthful status docs

  • ❏ Request/path/verb governance solid

  • ❏ Capability checks and proxy path exercised end to end

v0.2.x - Trusted Prefilter

  • ❏ Security and concurrency tests in place

  • ❏ Benchmarks documented

  • ❏ Route-scoped production guidance ready

v1.0.0 - Stable Release

  • ❏ Claims match executed evidence

  • ❏ Gateway role is intentionally narrow and well proven

  • ❏ Operators can deploy it without relying on design-document assumptions

Future Directions

Broaden scope only after the narrow API-governance role is demonstrably trustworthy.