Skip to content

Simplify CPEX hooks with operation modules and typed request state #134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lucarlig merged 1 commit into from
Sep 7, 2026
Merged

Simplify CPEX hooks with operation modules and typed request state #134

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 28 additions & 1 deletion _context/wiki/routing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,4 +49,31 @@ For clients on `≥ 2026-07-28`, `call_tool` validates `Mcp-Param-*` headers aga

## Plugin hooks

`call_tool` and `get_prompt` run `before_*/after_*` hooks when a `GatewayPluginRuntimeHandle` is configured. Pre-hook may rewrite arguments or deny; post-hook may rewrite or reject the response. Pre-hook state is passed to the post-hook.
`call_tool`, `get_prompt`, and `read_resource` run pre/post hooks when a
`GatewayPluginRuntimeHandle` is configured. Pre-hooks can deny a request or edit
tool/prompt arguments or the resource URI. Resource URI edits must resolve through
the caller's published routes. Post-hooks can rewrite or reject the response.

The handle selects a runtime before backend I/O. It returns typed request state
whose `after_*` method runs the post-hook on that same runtime, even after a reload
or a reload failure. A request that started without post-hooks never gains one
mid-flight. Tool state is shared under a mutex so progress notifications and the
final response use the same correlation ID and serialize plugin-context updates.
Prompt and resource state is owned by a single request and needs no mutex.

The internal CPEX crate separates these responsibilities:

| Module | Owns |
| --- | --- |
| `registry/` | Runtime selection, factory registration, config reloads, and the watcher |
| `runtime.rs` | Manager lifecycle, shared pre/post execution, and request context |
| `tools/`, `prompts/`, `resources/` | Typed request state, operation-specific CMF conversion, and conversion tests |
| `cmf.rs` | Hook inventory, message envelopes, and the `CmfResponse` conversion trait |
| `hooks.rs` | Shared argument edits and pre-hook results |
| `config.rs`, `factory.rs` | Config decoding/storage and compiled-in plugin factories |

Each response adapter implements `CmfResponse`; the runner handles invocation,
unchanged payloads, context propagation, and denial. Conversion and rejection
rules remain operation-specific: tools, rendered prompts, and resource reads
have different MCP representations. See [Config](config.md#tool-call-hook-behavior)
for those contracts.
Loading