proxy

type NoopRouter ¶

type NoopRouter struct{}

NoopRouter is the default Router used when per-call routing has not been wired into a server (e.g. unit tests for the wrapper that only care about the local-handler path, or a future build that disables routing). Every Dispatch returns a tool-error result rather than silently falling through to the local handler — silent fallback would mask the wiring bug this issue exists to prevent.

func (NoopRouter) Dispatch(
	_ context.Context, want versionroute.Quarter, _ mcp.CallToolRequest,
) (*mcp.CallToolResult, error)

type PoolOption ¶

type PoolOption interface {
	// contains filtered or unexported methods
}

PoolOption configures NewPoolRouter. Matches the project's functional-options convention (.claude/rules/go-conventions.md).

func WithIdleTimeout(d time.Duration) PoolOption

func WithInitTimeout(d time.Duration) PoolOption

type PoolRouter ¶

type PoolRouter struct {
	// contains filtered or unexported fields
}

PoolRouter implements Router by keeping at most one warm sibling child per Quarter for the life of the parent `crdb-sql mcp` process. The first Dispatch for a Quarter spawns the child and runs the MCP initialize handshake; subsequent Dispatch calls reuse the warm child, amortizing spawn + handshake cost across calls.

Lifecycle:

• Lazy spawn: a Quarter's child is only started on the first Dispatch for that Quarter.
• Bounded concurrency per Quarter: one child, serialized by the entry's mutex. mark3labs/mcp-go's stdio Client is not safe for concurrent CallTool, so per-quarter requests queue.
• Idle eviction: the janitor goroutine sweeps every janitorTick; entries unused for longer than idleTimeout are closed. The next Dispatch re-spawns transparently.
• Dead-child recovery: if CallTool returns a transport-layer error, the entry is evicted and closed before Dispatch returns. The next Dispatch re-spawns transparently.
• Graceful shutdown: Close stops the janitor and closes every pooled child. cmd/mcp.go defers it after server.ServeStdio returns so a clean parent exit propagates to all children.

The error contract is the same as the package-level Router doc: transport failures (spawn, init, broken pipe) propagate as Go errors; missing-sibling and tool-level failures come back as IsError=true *mcp.CallToolResult with a nil error.

func NewPoolRouter(opts ...PoolOption) *PoolRouter

func (p *PoolRouter) Close() error

func (p *PoolRouter) Dispatch(
	ctx context.Context, want versionroute.Quarter, req mcp.CallToolRequest,
) (*mcp.CallToolResult, error)

type Router ¶

type Router interface {
	Dispatch(
		ctx context.Context, want versionroute.Quarter, req mcp.CallToolRequest,
	) (*mcp.CallToolResult, error)
}

Router dispatches an MCP tool call to a sibling crdb-sql backend whose parser quarter matches the caller's requested target_version. A successful Dispatch returns the sibling's *mcp.CallToolResult verbatim — including the sibling's parser_version stamp on the envelope, which is the visible signal that routing actually happened.

Error contract: implementations distinguish two failure modes because the wrapper layer surfaces them differently to the caller.

• Transport failures (cannot spawn the sibling, broken pipe, JSON-RPC framing error, initialize timeout, any error returned by the sibling's MCP client other than an IsError=true result) are returned as a non-nil Go error. The wrapper propagates these as Go errors from the tool handler so the MCP server reports a transport-layer failure rather than fabricating an envelope.
• Tool-level failures (sibling answered with IsError=true, or the requested sibling is not installed) are returned as a non-nil *mcp.CallToolResult with IsError=true and a nil error. The wrapper forwards these verbatim so the client sees the same shape it would for a local tool error.

A Router that constructs results itself (NoopRouter, missingBackendResult) must NOT touch output.Envelope — those results bypass the local handler's envelope stamping entirely, so the saved "preserve env.Errors" rule does not apply here.