Agent-Hellboy / Agent-Hellboy/mcp-runtime
refactor(mcp-gateway): introduce a fixed ordered request filter pipeline
- 主要言語
- Go
- スター
- 6
- フォーク
- 1
- 平均マージ
- 11時間 33分
- マージ済み PR(30日)
- 13
説明
## 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`
コントリビューションガイド
このリポジトリのコントリビューションガイドは索引されていません
調査の方向性
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.
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- go
- 領域
- api, backend, security
- issue の種類
- リファクタリング
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 静か
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 35/100