moduleproto

type Caller ¶

type Caller struct {
	// Subject is the resolved caller subject (user id, service id, …).
	Subject string `json:"subject,omitempty"`
	// Tenant is the resolved tenant id, if any.
	Tenant string `json:"tenant,omitempty"`
	// Delegation is the in-memory handle the host uses to re-attach the
	// originating request's context to a reverse host.* call.
	Delegation string `json:"delegation,omitempty"`
}

Caller is the resolved end-user context attached to a proxied call (and echoed by the child on reverse host.* requests so the host re-attaches the right request context to internal re-dispatch). The Delegation handle is an in-memory, replica-local opaque string minted by the host (§5: v1 needs no signed token; the handle never leaves shared memory).

type CancelParams ¶

type CancelParams struct {
	RequestID string `json:"request_id"`
}

CancelParams is the body of the module.cancel notification (host → module). RequestID is the inbound request's host-side correlation id (the HTTPRequestParams.RequestID for a module.http call). The child uses it to find and cancel the in-flight handler's context.

type Codec ¶

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

Codec is the full-duplex newline-delimited JSON framing layer (design §4.2).

It is transport-neutral: it speaks to an io.Reader and io.Writer pair, NOT specifically to os.Stdin / os.Stdout. The same Codec works for stdio (v1) and a future v2 socket transport — the wire format is identical, only the Reader/Writer change (design §1).

Concurrency:

• Writes are mutex-guarded. Multiple goroutines may call Codec.WriteFrame concurrently; each frame is emitted atomically as JSON + '\n'.
• Reads are NOT concurrency-safe: exactly one goroutine runs the read loop. This is the Peer's readLoop goroutine.

Over-cap policy (design §4.2): a frame exceeding max_frame_bytes on read or write produces an *OvercapError and is terminal — the peer tears down. The codec NEVER truncates; truncation would silently corrupt the wire.

func NewCodec(r io.Reader, w io.Writer, maxFrameBytes int) (*Codec, error)

func (c *Codec) MaxFrameBytes() int

func (c *Codec) ReadFrame() (*Frame, error)

func (c *Codec) WriteFrame(f *Frame) error

type DrainParams ¶

type DrainParams struct {
	Reason     string `json:"reason"`
	DeadlineMs int    `json:"deadline_ms"`
}

DrainParams asks the child to wind down in-flight work (design §4.4 module.drain). The host's drain sequence issues this before killing the child.

type DrainResult ¶

type DrainResult struct {
	Inflight int `json:"inflight"`
}

DrainResult reports the in-flight count at drain completion.

type EntityMutationParams ¶

type EntityMutationParams struct {
	Entity  string          `json:"entity"`
	Payload json.RawMessage `json:"payload,omitempty"`
	Filter  json.RawMessage `json:"filter,omitempty"`
	IDs     []string        `json:"ids,omitempty"`
	Caller  Caller          `json:"caller"`
}

EntityMutationParams is the shape for host.entity.create / update / delete. For create/update, Payload is the row(s) to write (host-side schema). For delete, Filter/IDs select the target. The host's broker re-dispatches these through the CRUD requireScope chokepoint under the derived permission.

type EntityMutationResult ¶

type EntityMutationResult struct {
	Affected int             `json:"affected,omitempty"`
	Rows     json.RawMessage `json:"rows,omitempty"`
}

EntityMutationResult reports what changed.

type EntityQueryParams ¶

type EntityQueryParams struct {
	Entity string          `json:"entity"`
	Select json.RawMessage `json:"select,omitempty"`
	Filter json.RawMessage `json:"filter,omitempty"`
	Sort   json.RawMessage `json:"sort,omitempty"`
	Limit  int             `json:"limit,omitempty"`
	Offset int             `json:"offset,omitempty"`
	Caller Caller          `json:"caller"`
}

EntityQueryParams is the module→host reverse call host.entity.query. Filter/Sort/Select are json.RawMessage because their shape is the host's existing DSL (framework/filter, framework/dsl) — and this package must NOT import any framework/* leaf. The supervisor's broker parses these with the host's real query machinery on the receive side.

type EntityQueryResult ¶

type EntityQueryResult struct {
	Rows  json.RawMessage `json:"rows"`
	Total int             `json:"total,omitempty"`
}

EntityQueryResult is the result of host.entity.query.

type Error ¶

type Error struct {
	Code    int             `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

Error is the JSON-RPC 2.0 error object carried in Frame.Error.

func AsError(err error) *Error

func (e *Error) Error() string

func (e *Error) Is(target error) bool

type EventEmitParams ¶

type EventEmitParams struct {
	Topic   string          `json:"topic"`
	Payload json.RawMessage `json:"payload"`
	Caller  Caller          `json:"caller"`
}

EventEmitParams is the module→host reverse call host.event.emit. The required permission is derived from <topic>:emit by the broker (design §4.4).

type EventEmitResult ¶

type EventEmitResult struct{}

EventEmitResult is the (currently empty) result of host.event.emit.

type Frame ¶

type Frame struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      *uint64         `json:"id,omitempty"`
	Method  string          `json:"method,omitempty"`
	Params  json.RawMessage `json:"params,omitempty"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *Error          `json:"error,omitempty"`
}

Frame is the single bidirectional envelope used by both endpoints of a moduleproto connection (design §4.3). One Frame type carries requests, notifications, and responses — discrimination happens in the read loop, not the type system.

Wire shape (JSON-RPC 2.0):

{
  "jsonrpc": "2.0",            // required; UnmarshalJSON rejects anything else
  "id":     <uint64>,          // present ⇒ request or response; absent ⇒ notification
  "method": "<name>",          // present ⇒ REQUEST (or notification); absent ⇒ RESPONSE
  "params": <raw>,             // requests / notifications only
  "result": <raw>,             // success responses only
  "error":  {code,message,data?}
}

ID semantics are load-bearing:

• id is a *uint64. nil ⇒ omit the key entirely (notification). A non-nil pointer ⇒ marshal the pointed-to value. This is NOT mcpclient's `uint64 \`json:"id,omitempty"\“ shape: that form re-purposes 0 as the notification sentinel and erases a legitimately-issued id:0. Here id:0 is impossible: the per-direction id counter starts at 1, and UnmarshalJSON rejects a decoded id:0 as malformed.

• IDs are per-direction (design §4.3): each endpoint owns an independent counter. Host-originated id:7 and child-originated id:7 never collide — see the Peer read loop and peer_test.go's interleaved test.

func NewErrorResponse(id uint64, code int, message string, data json.RawMessage) *Frame

func NewNotification(method string, params json.RawMessage) *Frame

func NewRequest(id uint64, method string, params json.RawMessage) *Frame

func NewSuccessResponse(id uint64, result json.RawMessage) *Frame

func (f *Frame) HasID() bool

func (f *Frame) IDValue() uint64

func (f *Frame) IsError() bool

func (f *Frame) IsNotification() bool

func (f *Frame) IsRequest() bool

func (f *Frame) IsResponse() bool

func (f *Frame) IsSuccess() bool

func (f Frame) MarshalJSON() ([]byte, error)

func (f *Frame) UnmarshalJSON(data []byte) error

type HTTPMethod ¶

type HTTPMethod string

HTTPMethod is the canonical method on a module.http request. We re-declare a string type rather than importing net/http to keep this package stdlib-only at the type level (the supervisor marshals real http.MethodX values into it).

type HTTPRequestParams ¶

type HTTPRequestParams struct {
	// RequestID is a host-minted correlation id for THIS proxied request.
	// It is independent of the JSON-RPC id (which lives at the envelope
	// level) and is what module.cancel references to abort in-flight work.
	RequestID string `json:"request_id"`
	// RouteID is the installed route's descriptor id.
	RouteID string `json:"route_id"`
	// Method is the HTTP method (GET/POST/...).
	Method HTTPMethod `json:"method"`
	// PathParams are the parsed route path parameters.
	PathParams map[string]string `json:"path_params,omitempty"`
	// Query is the parsed query string parameters.
	Query map[string]string `json:"query,omitempty"`
	// Headers is the allowlist-filtered subset of inbound headers.
	Headers map[string]string `json:"headers,omitempty"`
	// BodyB64 is the raw request body, base64-encoded. Empty string for
	// bodies with no content.
	BodyB64 string `json:"body_b64,omitempty"`
	// Caller carries the resolved end-user context the host delegates to
	// the child for this call.
	Caller Caller `json:"caller"`
	// DeadlineUnixMs is the absolute deadline for this call, in Unix
	// milliseconds. The child must abort by this time regardless of any
	// module.cancel notification.
	DeadlineUnixMs int64 `json:"deadline_unix_ms"`
}

HTTPRequestParams carries a single proxied HTTP request to the module (design §4.4 module.http params). The host is responsible for stripping request body to the allowlisted headers, base64-encoding the body, and attaching the caller's delegation handle.

type HTTPResponseBody ¶

type HTTPResponseBody struct {
	Kind  HTTPResponseBodyKind `json:"kind"`
	Value json.RawMessage      `json:"value"`
}

HTTPResponseBody is the body of a module.http response. The host buffers the entire response before committing any headers (the buffered-503 guarantee, design §8) — no streaming in v1.

type HTTPResponseBodyKind ¶

type HTTPResponseBodyKind string

HTTPResponseBodyKind enumerates the three kinds of body a module.http response may carry (design §4.4). kind:"ui.node.v1" is the closed UI node tree — validated, mapped, rendered, and hydrated by the host (design §9); the module NEVER emits raw HTML/CSS/JS.

const (
	// BodyKindJSON is a JSON-typed response body.
	BodyKindJSON HTTPResponseBodyKind = "json"
	// BodyKindText is a plain-text response body.
	BodyKindText HTTPResponseBodyKind = "text"
	// BodyKindUINodeV1 is a closed ui.node.v1 tree. The host validates it
	// against the allowlist before rendering; see design §9.
	BodyKindUINodeV1 HTTPResponseBodyKind = "ui.node.v1"
)

type HTTPResponseResult ¶

type HTTPResponseResult struct {
	Status  int               `json:"status"`
	Headers map[string]string `json:"headers,omitempty"`
	Body    HTTPResponseBody  `json:"body"`
}

HTTPResponseResult is the result shape for module.http (design §4.4).

type Handler ¶

type Handler func(ctx context.Context, params json.RawMessage) (result any, err error)

Handler is the server-side callback for an inbound request or notification. params is the raw JSON of the Frame.Params field; the handler unmarshals it into the typed shape it expects for its method. Returning a non-nil err causes the Peer to write a JSON-RPC error response with the standard internal-error code; for finer-grained codes, return a *Error.

For notifications (no id) the result is ignored and no response is written; only err is observed (and only for local logging — a notification cannot produce a wire response).

type HandshakeConfig ¶

type HandshakeConfig struct {
	// Expected is the set of values the child MUST echo back identically.
	// The host reads them from the operator-approved descriptor + the live
	// ProcessModuleStore (desired_generation) + its freshly-minted
	// instance_id (§4.7 step 1).
	Expected HandshakeExpected

	// Grants is the effective grant set the host is allowing this child
	// (descriptor.requested ∩ operator.approved).
	Grants []string

	// Limits is the per-child resource envelope the host enforces.
	Limits Limits

	// HostProto is the host's advertised proto range. The negotiated version
	// is min(host.Max, child.Max) if ≥ max(host.Min, child.Min); else
	// terminal. See [Negotiate].
	HostProto ProtoRange

	// HostFeatures is the host's non-critical feature list. The child may
	// ACK a subset; [HandshakeResult.AckedFeatures] is the intersection.
	HostFeatures []string

	// HostCritical is the host's REQUIRED feature list. Every name here
	// MUST appear in the child's echoed features[]; else terminal
	// ([ErrCriticalFeature]).
	HostCritical []string
}

HandshakeConfig is the host-side input to Handshake. Every opaque value here is CALLER-SUPPLIED — this package verifies the round-trip and emits a terminal HandshakeMismatchError on divergence; it makes NO trust decision about whether the expected values are themselves correct. That is the supervisor's policy (design §5 decision B).

type HandshakeExpected ¶

type HandshakeExpected struct {
	// Name is the module's operator-approved name (descriptor-supplied).
	Name string `json:"name"`
	// Version is the module's operator-approved semantic version.
	Version string `json:"version"`
	// ArtifactSHA256 is the SHA-256 of the approved executable, hex-encoded.
	ArtifactSHA256 string `json:"artifact_sha256"`
	// SurfaceSHA256 is the digest of the approved surface descriptor
	// (routes + tool list + requested permissions). Mismatch with the
	// child's echoed value is terminal.
	SurfaceSHA256 string `json:"surface_sha256"`
	// DesiredGeneration is the monotonic desired-state counter persisted in
	// ProcessModuleStore. It is READ at spawn (not minted here); the child
	// echoes it back in identity. A mismatch means the child is stale.
	DesiredGeneration uint64 `json:"desired_generation"`
	// InstanceID is the random per-spawn liveness nonce the host minted for
	// THIS spawn (§4.7 step 1). Rejects stale/duplicate connections from a
	// prior spawn. Never persisted, never monotonic.
	InstanceID string `json:"instance_id"`
}

HandshakeExpected carries the caller-supplied values the host expects the child to round-trip in module.handshake (design §4.7 steps 1-3). Every field here is an OPAQUE caller-supplied value — this package verifies the round-trip and emits a terminal HandshakeMismatchError on divergence; it does NOT decide whether the expected values are themselves trustworthy (that is the supervisor's policy — design §5 decision B).

type HandshakeMismatchError ¶

type HandshakeMismatchError struct {
	Field string // human-readable name of the mismatched field
	Want  string // caller-supplied expected value
	Got   string // child-echoed value
}

HandshakeMismatchError is returned by Handshake when the child's echoed identity or digests do not round-trip the caller-supplied expected values, or when proto negotiation fails. It is terminal per design §4.5/§4.7.

func (e *HandshakeMismatchError) Error() string

type HandshakeOutcome ¶

type HandshakeOutcome struct {
	// NegotiatedProto is the single integer version both peers MUST use.
	NegotiatedProto int

	// Identity is the child's echoed identity, verified to round-trip the
	// host's [HandshakeConfig.Expected].
	Identity Identity

	// SurfaceSHA256 is the child's echoed surface digest, verified equal
	// to the host's expected value.
	SurfaceSHA256 string

	// Ready is the child's initial ready flag. The host polls [MethodReady]
	// separately to gate on warmup completion; Ready here is informational.
	Ready bool

	// AckedFeatures is the intersection of the host's HostFeatures and the
	// child's echoed features[].
	AckedFeatures []string
}

HandshakeOutcome is the result of a successful Handshake: the negotiated proto version, the cross-checked identity, and the agreed feature set.

func Handshake(ctx context.Context, p *Peer, cfg HandshakeConfig) (*HandshakeOutcome, error)

type HandshakeParams ¶

type HandshakeParams struct {
	Expected HandshakeExpected `json:"expected"`
	Grants   []string          `json:"grants"`
	Limits   Limits            `json:"limits"`
	Features []string          `json:"features,omitempty"`
	Critical []string          `json:"critical,omitempty"`
	Proto    ProtoRange        `json:"proto"`
}

HandshakeParams is the params shape for module.handshake (design §4.4). The host is the only legitimate originator; the child cannot alter these.

type HandshakeResult ¶

type HandshakeResult struct {
	// Proto is the child's advertised proto range. The negotiated version
	// is computed by the host via [Negotiate] and returned alongside.
	Proto ProtoRange `json:"proto"`
	// Identity is the child's echoed identity — round-trips the host's
	// [HandshakeExpected] values.
	Identity Identity `json:"identity"`
	// SurfaceSHA256 is the child's view of its surface digest; the host
	// compares it to [HandshakeExpected].SurfaceSHA256.
	SurfaceSHA256 string `json:"surface_sha256"`
	// Features is the feature set the child ACKs.
	Features []string `json:"features"`
	// Ready is the child's initial ready state (typically false; the host
	// polls module.ready separately to gate on warmup completion).
	Ready bool `json:"ready"`
}

HandshakeResult is the result shape for module.handshake (design §4.4).

type HealthParams ¶

type HealthParams struct{}

HealthParams is empty — module.health takes no params.

type HealthResult ¶

type HealthResult struct {
	OK       bool `json:"ok"`
	Inflight int  `json:"inflight"`
}

HealthResult is the result of module.health. ok:false means the child is alive but unhealthy; inflight reports current in-flight request count.

type Identity ¶

type Identity struct {
	Name              string `json:"name"`
	Version           string `json:"version"`
	InstanceID        string `json:"instance_id"`
	DesiredGeneration uint64 `json:"desired_generation"`
}

Identity is the child's echoed identity in module.handshake's result. The host compares every field against HandshakeExpected — instance_id and desired_generation MUST round-trip exactly (they are the spawn-freshness and generation-staleness anchors; §4.4 vocabulary note).

type Limits ¶

type Limits struct {
	// FrameBytes is the negotiated max_frame_bytes. Default 1 MiB
	// (see [DefaultMaxFrameBytes]). Must be ≤ the codec's structural
	// scanner cap (4 MiB); the codec rejects a larger negotiated value at
	// construction.
	FrameBytes int `json:"frame_bytes"`
	// DeadlineMs is the per-call deadline ceiling for module.* requests.
	// The descriptor may lower it; never raise. Default 10 000 (10 s).
	DeadlineMs int `json:"deadline_ms"`
	// Inflight is the maximum simultaneously in-flight module.* requests
	// the host will issue. Default 32. Over-cap is a clean call-local
	// error, not a protocol fault.
	Inflight int `json:"inflight"`
}

Limits is the per-child resource envelope the host sets at handshake (design §4.4 module.handshake params). All zeros means "host defaults apply."

type OvercapError ¶

type OvercapError struct {
	Size int // bytes observed; -1 if unknown (e.g. bufio.Scanner ErrTooLong)
	Cap  int // negotiated cap in bytes
}

OvercapError is returned by the codec when a frame exceeds the negotiated max_frame_bytes on read or write. It is terminal: by design §4.2 the peer never truncates, so the connection is unusable.

func (e *OvercapError) Error() string

func (e *OvercapError) Is(target error) bool

type Peer ¶

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

Peer is a full-duplex endpoint over a Codec. Both the host and the child construct one; each Peer serves inbound requests AND originates outbound requests concurrently over the SAME connection. This is the load-bearing break from mcpclient, which could originate but not serve.

Per-direction ID correlation (design §4.3 — the most-tested property):

• Each Peer owns an independent id counter ([Peer.nextID], atomic, starts at 0; the first Peer.Call uses id=1).
• Each Peer owns its own pending map.
• The read loop consults its local pending map ONLY for frames that are responses (method == "" && id present). A request with the same numeric id is handled by the request branch, which echoes the id back without touching the map.

Therefore host-originated id:7 and child-originated id:7 NEVER collide. See peer_test.go's interleaved bidirectional test, which pins this property.

Cancellation (design §4.4 module.cancel):

• The Peer installs a built-in handler for MethodCancel. When a module.cancel notification arrives with a given request_id, the Peer cancels the context of the inbound request currently serving that id (the request_id is the inbound frame's id, encoded as a string). The child's handlers observe ctx.Done and abort.
• Origination-side cancellation (the host sending module.cancel when ITS Call's ctx expires) is policy, NOT codec behavior. The supervisor wires it by calling Peer.Notify from a goroutine that watches ctx.Done.

func NewPeer(codec *Codec, role Role, opts ...PeerOption) *Peer

func (p *Peer) Call(ctx context.Context, method string, params any) (json.RawMessage, error)

func (p *Peer) Close() error

func (p *Peer) Done() <-chan struct{}

func (p *Peer) FatalDone() <-chan struct{}

func (p *Peer) FatalError() error

func (p *Peer) Handle(method string, h Handler) error

func (p *Peer) Notify(ctx context.Context, method string, params any) error

func (p *Peer) Role() Role

func (p *Peer) Start()

type PeerOption ¶

type PeerOption func(*Peer)

PeerOption configures a Peer at construction.

func WithHandler(method string, h Handler) PeerOption

func WithMaxInflight(n int) PeerOption

func WithMaxServeInflight(n int) PeerOption

type ProtoRange ¶

type ProtoRange struct {
	Min int `json:"min"`
	Max int `json:"max"`
}

ProtoRange is the integer protocol-version window a peer advertises in module.handshake (design §4.5). Versions are plain integers — there is no MCP-style "YYYY-MM-DD" string and no semver. [Min, Max] is inclusive.

A peer that speaks exactly one version sets Min == Max. The floor for v1 of this package is [ProtoV1Min, ProtoV1Max].

func (r ProtoRange) Contains(v int) bool

func (r ProtoRange) Validate() error

type ReadyParams ¶

type ReadyParams struct{}

ReadyParams is empty — module.ready takes no params (design §4.4).

type ReadyResult ¶

type ReadyResult struct {
	Ready  bool   `json:"ready"`
	Detail string `json:"detail,omitempty"`
}

ReadyResult is the result of module.ready. ready:true means the child has completed warmup and may serve proxied traffic.

type RingSink ¶

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

RingSink is a bounded, non-blocking byte sink that retains the last N bytes written to it (design §4.2). It wraps the child's stderr so the host can observe recent child log output without allowing an unbounded log to exhaust memory. It replaces mcpclient's drainStderr's `io.Copy(io.Discard, …)`.

Properties:

• NEVER blocks the writer (the child's stderr drain goroutine). Write always succeeds immediately and returns len(p), regardless of how full the ring is.
• Retains at most cap bytes. When the ring would overflow, the OLDEST bytes are evicted. [Tail] returns the retained slice in write order.
• Safe for concurrent Write and Tail.

Implementation: a single growable []byte guarded by a mutex, trimmed to the last cap bytes on each write. The trim is O(remaining) but stderr is low-volume relative to the protocol path, so a proper circular buffer would add complexity without measurable benefit. If the stderr path ever carries high volume, swap in a circular buffer keeping the same API.

func NewRingSink(capBytes int) *RingSink

func (r *RingSink) Cap() int

func (r *RingSink) Drain(src io.Reader) error

func (r *RingSink) Len() int

func (r *RingSink) Reset()

func (r *RingSink) Tail() []byte

func (r *RingSink) Write(p []byte) (int, error)

type Role ¶

type Role int

diagnostic/policy only: the codec and Frame type are symmetric, and a Peer of either role can both originate and serve requests. The supervisor uses Role to decide policy (e.g. only the host role sends module.cancel; the child role's handlers are subject to it).

const (
	// RoleHost is the host-side endpoint: originates module.* requests and
	// serves host.* reverse requests.
	RoleHost Role = iota
	// RoleChild is the module-side endpoint: serves module.* requests and
	// originates host.* reverse requests.
	RoleChild
)

func (r Role) String() string

type SearchQueryParams ¶

type SearchQueryParams struct {
	Query  string          `json:"query"`
	Filter json.RawMessage `json:"filter,omitempty"`
	Limit  int             `json:"limit,omitempty"`
	Caller Caller          `json:"caller"`
}

SearchQueryParams is the module→host reverse call host.search.query.

type SearchQueryResult ¶

type SearchQueryResult struct {
	Results json.RawMessage `json:"results"`
	Total   int             `json:"total,omitempty"`
}

SearchQueryResult is the result of host.search.query.

type Tool ¶

type Tool struct {
	ID          string          `json:"id"`
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"input_schema,omitempty"`
}

Tool is one entry in the module.tool.list result. The host registers these into its existing core/mcp.Server under a per-module prefix (design §5.1). At handshake the host verifies byte-equality with the descriptor's tool digests — the child cannot add, rename, or reshape at runtime.

type ToolCallParams ¶

type ToolCallParams struct {
	ToolID         string          `json:"tool_id"`
	Arguments      json.RawMessage `json:"arguments,omitempty"`
	Caller         Caller          `json:"caller"`
	DeadlineUnixMs int64           `json:"deadline_unix_ms"`
}

ToolCallParams invokes one tool by id (design §4.4 module.tool.call).

type ToolCallResult ¶

type ToolCallResult struct {
	Result json.RawMessage `json:"result"`
}

ToolCallResult is the result of module.tool.call. The host re-validates any ui.node.v1 content in Result exactly as it would for module.http.

type ToolListResult ¶

type ToolListResult struct {
	Tools []Tool `json:"tools"`
}

ToolListResult is the result of module.tool.list.