Agent-Hellboy / Agent-Hellboy/mcp-runtime
refactor(mcp-gateway): introduce a fixed ordered request filter pipeline
- Lingua principale
- Go
- Stelle
- 6
- Fork
- 1
- Merge medio
- 11h 33m
- PR unite (30g)
- 13
Descrizione
## Problem
`services/mcp-gateway` currently handles multiple security-sensitive responsibilities in the gateway request path, including RPC inspection, policy loading, authentication, identity extraction, authorization, upstream proxying, and audit/analytics emission. As these concerns grow, keeping them in one handler increases change blast radius and makes security ordering harder to review and test.
Umbrella issue #268 already identifies the need to split `handleGateway` into explicit stages. Issue #258 proposes a broader pluggable guardrail system. This issue tracks the smaller internal refactor that should establish a maintainable request pipeline before adding configurable providers or extension points.
## Goal
Introduce a small, fixed, ordered internal filter pipeline for MCP gateway request processing. Make stage ownership, termination behavior, shared request state, and security-sensitive ordering explicit without creating an Envoy-compatible filter manager or public plugin API.
## Proposed pipeline
Initial fixed order:
1. Request/RPC inspection and bounded body handling
2. Policy snapshot acquisition
3. Authentication and identity extraction
4. Authorization and session/grant evaluation
5. Upstream request preparation and forwarding
6. Response/audit/analytics finalization
The exact package names and interfaces should follow existing gateway patterns, but the core contract should remain small. For example:
```go
type Filter interface {
Handle(context.Context, *Exchange) Result
}
type Result int
const (
Continue Result = iota
Reject
Respond
)
```
`Exchange` should contain only request-scoped state needed across stages, such as the HTTP request/response writer, RPC inspection result, immutable policy snapshot, authenticated identity, authorization decision, and audit metadata.
## Design constraints
- Filter order is fixed in code for the first implementation.
- Authentication and route/tool normalization must complete before authorization.
- No later stage may mutate authorization inputs after a policy decision without forcing reevaluation.
- A stage can continue, reject, or produce a terminal response.
- Terminal paths must preserve existing JSON-RPC/HTTP error behavior and audit semantics.
- Policy snapshots must be immutable for the lifetime of one exchange.
- Keep upstream proxy behavior based on the existing `httputil.ReverseProxy`.
- Preserve bounded request-body handling and current non-RPC bypass behavior.
## Acceptance criteria
- [ ] `handleGateway` becomes orchestration around explicit ordered stages rather than owning all request logic directly.
- [ ] Each stage has focused unit tests for continue, reject, and relevant terminal behavior.
- [ ] Existing OAuth/header identity, grant/session authorization, proxying, and audit behavior remains compatible.
- [ ] Security-sensitive stage ordering is documented and covered by tests.
- [ ] Tests prove authorization inputs cannot be changed after authorization without reevaluation.
- [ ] Every rejection and upstream outcome is audited exactly once where current behavior requires an event.
- [ ] Existing gateway tests continue to pass, with broad handler tests retained for end-to-end stage composition.
- [ ] A package-level comment or gateway architecture document explains stage ownership and ordering.
## Non-goals
- User-configurable filter ordering.
- Dynamic plugins, WASM, external filter discovery, or hot-loaded code.
- Envoy xDS, listener filters, network filters, or stop/resume callback machinery.
- Implementing the guardrail providers proposed by #258.
- Changing policy snapshot schema/activation work tracked by #295.
## Relationship to existing issues
- Extracts gateway request pipeline item 7 from #268 into actionable scope.
- Provides an internal foundation that #258 may use later, without committing to its plugin model.
- Keeps policy snapshot correctness and visibility in #295.
## Relevant code
- `services/mcp-gateway/proxy.go`
- `services/mcp-gateway/types.go`
- `services/mcp-gateway/policy_cache.go`
- `services/mcp-gateway/main_test.go`
- `pkg/policy/evaluator.go`
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Direzione di ricerca
Start with services/mcp-gateway/proxy.go and types.go to trace handleGateway and the request state it currently owns; read policy_cache.go and pkg/policy/evaluator.go for policy snapshot and authorization behavior. Run the existing gateway tests in services/mcp-gateway/main_test.go before changing anything. Done means fixed ordered stages, terminal and audit behavior preserved, ordering and reevaluation covered by focused tests, and the existing suite still passes.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- go
- Ambito
- api, backend, security
- Tipo di issue
- Refactoring
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 35/100