Documentation
¶
Overview ¶
Package aggregate presents many downstream servers as one tool catalog.
It is the gateway's pure topology layer. Given the raw tool listings reported by each downstream a client may use, it namespaces every tool name to keep it collision-safe (downstream__tool), merges the listings into one deterministic domain.Catalog, cursor-paginates that catalog with an opaque, name-stable token, and resolves a namespaced call back to the downstream that owns it.
This package never talks to a downstream session; it operates only on the listings handed to it, so it is deterministic and trivially testable. Routing of the resolved call to a live session belongs to the registry layer.
Validation fails fast (design §7): a downstream or tool name that contains the namespace separator, an empty name, a duplicate downstream, or a duplicate tool within a downstream is rejected at Build rather than risking silent mis-routing later.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Build ¶
Build namespaces every tool as "downstream__tool" and merges all listings into a single, deterministically ordered domain.Catalog.
It fails fast, returning an error and an empty catalog, if any downstream name or tool name is empty or contains the namespace separator domain.NamespaceSeparator, if two listings share a downstream name, or if a downstream reports the same tool twice. Rejecting these at aggregation time prevents an ambiguous namespaced name from ever mis-routing a later call (design §7).
The returned catalog is sorted by namespaced name, so the same input always yields the same output.
func Page ¶
func Page(catalog domain.Catalog, cursor string, size int) (page domain.Catalog, next string, err error)
Page returns one page of catalog, sized at most size, plus an opaque cursor for the next page ("" when the returned page is the last one).
Pagination is name-based and stateless: the catalog is read in sorted namespaced-name order, and the page is the first size tools whose name is strictly greater than the name encoded in cursor. An empty cursor starts at the beginning. Because the cursor encodes a name rather than an index, a page stays correct even if tools are added or removed between requests: the next page always resumes strictly after the last name already returned, never skipping or repeating a surviving tool.
The cursor is an opaque base64url token; a cursor that is not valid base64url is rejected with an error. size must be positive; a non-positive size is rejected with an error rather than silently defaulted, so a caller's mistake surfaces immediately.
func Resolve ¶
Resolve parses a client-facing namespaced tool name and returns the downstream and tool it routes to.
It rejects a malformed name (delegating the shape rules to domain.ParseToolRef) and rejects a well-formed name whose downstream is not present-and-true in knownDownstreams, so a call to an unknown or removed downstream is a clean error rather than a panic or a misroute (design §7). A nil knownDownstreams map treats every downstream as unknown.
Types ¶
type Listing ¶
type Listing struct {
// Downstream is the configured downstream server name (for example "github").
Downstream string
// Tools is every tool that downstream reported, un-namespaced.
Tools []Tool
}
Listing is one downstream's complete set of reported tools.
type Tool ¶
type Tool struct {
// Name is the tool's own name on its downstream (for example "create_issue").
Name string
// Title is the tool's optional human-readable display name.
Title string
// Description is the human-readable description the downstream provides.
Description string
// InputSchema is the tool's JSON Schema for its arguments.
InputSchema json.RawMessage
// OutputSchema is the tool's optional structured-result JSON Schema, or nil.
OutputSchema json.RawMessage
// Annotations is the tool's optional annotations as raw JSON, or nil.
Annotations json.RawMessage
// Icons is the tool's optional icon set as raw JSON, or nil.
Icons json.RawMessage
}
Tool is a single tool exactly as a downstream reports it, before namespacing. Every field other than Name is carried through verbatim to the namespaced domain.Tool; the raw-JSON fields are treated as immutable, so callers must not mutate the bytes.
Source Files