[SShogun]

Summary

• Compile static route configuration into a deterministic matcher with host, path, method, and header precedence; reject ambiguous selectors.
• Add cluster endpoint selection with round-robin and smooth weighted round-robin policies, health thresholds, and bounded cancellable health probes.
• Integrate validated listener, route, and cluster configuration with the data-plane gateway and stable route/cluster/endpoint telemetry.
• Preserve escaped probe paths on the wire and correctly classify transport failures versus valid upstream error responses.
• Include race, fuzz, benchmark, and regression coverage for the M2 acceptance gates.

Verification

• Pinned Go 1.26.9 make verify passed on the M1-integrated tree: vet, Staticcheck, Buf lint and compatibility fixtures, generation cleanliness, module verification, shuffled unit tests, race tests, and govulncheck (no vulnerabilities found).
• Focused RED/GREEN regressions cover escaped health paths, host normalization in the independent fuzz oracle, startup health scheduling, transport outcome logging, and the previously audited routing/health edge cases.
• The 3-second FuzzRouteMatch smoke completed 374,404 executions.
• BenchmarkMatch10KRoutes recorded 239.4 ns/op, 32 B/op, and 1 alloc/op on Go 1.27.1-X:nodwarf3; the benchmark runtime differs from the pinned verification runtime.
• git diff --check passed.
• Exact-head GitHub CI will run after this draft is marked ready; the current local evidence does not substitute for that remote result.

Plan status

All listed M2 local acceptance gates are evidenced in docs/Gatehouse_PLAN.md and docs/Gatehouse_TESTING_CI.md. The branch includes the M1 fix through a normal merge. M3 dynamic configuration storage and publication are not part of this PR.

Summary by Sourcery

Implement deterministic static routing, health-aware cluster endpoint selection, and gateway integration for the M2 data plane.

New Features:

• Add deterministic static route matching with host, path, method, and header precedence plus validation of ambiguous selectors.
• Add cluster endpoint selection with round-robin and smooth weighted round-robin policies, health thresholds, and bounded cancellable HTTP health checks.
• Integrate compiled listener, route, and cluster configuration into the data-plane gateway with stable route, cluster, and endpoint telemetry.

Bug Fixes:

• Preserve escaped health-check paths and distinguish transport failures from valid upstream HTTP error responses.
• Prevent startup health probes from racing incomplete gateway construction and ensure unhealthy endpoints are excluded from selection.

Enhancements:

• Advance the documented project state to M2 static routing, clusters, and health capabilities while retaining the static environment-based command configuration.

Documentation:

• Document M2 acceptance evidence and verification results.

Tests:

• Add routing precedence, ambiguity, fuzz, benchmark, cluster selection, health transition, scheduler cancellation, concurrency, gateway integration, and regression coverage.

[sourcery-ai]

Reviewer's Guide

This PR completes the static M2 data-plane foundation by compiling validated routes into a deterministic matcher, selecting and health-filtering cluster endpoints, running bounded cancellable probes, and integrating the resulting runtime with the gateway, telemetry, command wiring, and acceptance-test coverage.

Sequence diagram for deterministic request routing and endpoint selection

sequenceDiagram
    participant Client
    participant Listener
    participant Gateway
    participant Matcher
    participant Cluster
    participant Proxy
    participant Endpoint

    Client->>Listener: HTTP request
    Listener->>Gateway: ServeHTTP
    Gateway->>Matcher: Match
    Matcher-->>Gateway: Route
    Gateway->>Cluster: Select
    Cluster-->>Gateway: Endpoint
    Gateway->>Proxy: ServeHTTP
    Proxy->>Endpoint: Forward request
    Endpoint-->>Proxy: HTTP response
    Proxy-->>Client: HTTP response

Loading

Sequence diagram for scheduled endpoint health checks

sequenceDiagram
    participant Scheduler
    participant Gateway
    participant Endpoint
    participant Cluster

    Scheduler->>Gateway: checkEndpoint
    Gateway->>Endpoint: GET health path
    alt transport failure or non-2xx response
        Endpoint-->>Gateway: probe failure
        Gateway->>Cluster: MarkResult false
    else successful response
        Endpoint-->>Gateway: 2xx response
        Gateway->>Cluster: MarkResult true
    end
    Cluster-->>Gateway: updated health state
    Scheduler->>Scheduler: schedule next bounded probe

Loading

File-Level Changes

Change	Details	Files
Introduces a compiled, deterministic route matcher with validation, precedence ordering, host normalization, header semantics, and ambiguity rejection.	Compile static routes into a path-indexed immutable matcher. Apply host, exact/prefix path, method, and header precedence with lexical tie-breaking. Validate selectors, cluster references, and reject overlapping ambiguous routes. Add fuzz, regression, and 10K-route benchmark coverage.	internal/router/router.go internal/router/router_test.go internal/router/testdata/fuzz/FuzzRouteMatch/12587131861cbc78 internal/router/testdata/fuzz/FuzzRouteMatch/3ef996ad05a4b442
Adds cluster endpoint selection and health-state management with deterministic round-robin policies and threshold-based eligibility.	Support round-robin and smooth weighted round-robin endpoint selection. Track Unknown, Healthy, and Unhealthy states with consecutive success/failure thresholds. Exclude disabled or threshold-marked unhealthy endpoints while preserving unknown endpoint availability. Cover weighted cycles, tie sources, health transitions, and concurrent selection tests.	internal/cluster/cluster.go internal/cluster/cluster_test.go
Adds bounded, cancellable periodic health probing and integrates probe outcomes into endpoint health.	Start immediate and periodic probes with configurable timeout, jitter, and concurrency limits. Support cancellation, removal, and scheduler shutdown without worker leaks. Preserve escaped probe paths and classify incomplete bodies, HTTP errors, and transport failures correctly. Test timeout bounds, cancellation, concurrency, startup ordering, and health transitions.	internal/cluster/scheduler.go internal/cluster/scheduler_test.go internal/gateway/gateway.go internal/gateway/gateway_test.go
Adds validated static listener, route, and cluster configuration and wires it into the gateway runtime and data-plane command.	Validate listener addresses, endpoint URLs, policies, IDs, health checks, and route/cluster cross-references. Construct compiled routes, cluster runtimes, reusable endpoint proxies, and health schedules from one configuration snapshot. Replace the single proxy command wiring with a default route and cluster configuration while retaining environment overrides. Ensure gateway shutdown joins health workers and closes proxy idle connections.	internal/config/config.go internal/config/config_test.go internal/gateway/gateway.go cmd/gatehouse-data/main.go
Improves gateway observability and documents the completed M2 implementation and verification evidence.	Emit stable route, cluster, endpoint, status, and duration telemetry for matched, unavailable, and aborted requests. Preserve valid upstream error responses as successful proxy transport outcomes. Update project status, M2 plan gates, and local verification documentation.	internal/gateway/gateway.go internal/gateway/gateway_test.go README.md docs/Gatehouse_PLAN.md docs/Gatehouse_TESTING_CI.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Needs a human reviewer. Incorrect route matching, endpoint selection, or health transitions could send live requests to the wrong backend or exclude all eligible backends, causing traffic failures or an outage before the change is reverted. Reverting stops the new behavior but does not undo requests already misrouted or downtime that already occurred.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook