Documentation
¶
Overview ¶
Package ir defines the Forge Intermediate Representation: a language- and target-agnostic model of an API. Every Forge generator (tool-pack, MCP server, docs, SDKs) reads only the IR, so adding a new source format (OpenAPI, GraphQL, gRPC) means writing one ingester, and adding a new output means writing one generator — never an N×M matrix.
Index ¶
Constants ¶
const ( SkipClientStreaming = "client-streaming" // gRPC client-streaming method SkipServerStreaming = "server-streaming" // gRPC server-streaming method SkipBidiStreaming = "bidi-streaming" // gRPC bidirectional-streaming method SkipSubscription = "subscription" // GraphQL subscription field )
SkippedOperation.Kind values. SkipServerStreaming and SkipSubscription are retained for backward compatibility with stored IR JSON, but current ingesters place server-streaming methods and subscription fields in API.Streams (exposed as streaming sessions) rather than in Skipped.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type API ¶
type API struct {
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description,omitempty"`
SourceType string `json:"source_type"` // "openapi" | "graphql" | "grpc"
Servers []Server `json:"servers,omitempty"`
Auth []AuthScheme `json:"auth,omitempty"`
Operations []Operation `json:"operations"`
Schemas map[string]*Schema `json:"schemas,omitempty"` // named component schemas
// Streams lists source operations that are PUSH STREAMS — gRPC
// server-streaming methods and GraphQL subscription fields — exposed at
// runtime as background streaming sessions (start / poll / stop over a
// bounded ring buffer, mirroring the bash_background pattern) instead of
// unary tools. They are kept out of Operations on purpose: every unary
// generator (SDKs, docs, static tool registration) would otherwise emit a
// one-shot request/response wrapper that hangs or truncates at call time.
// Only the live tool layer (toolpack stream tools) reads this list.
Streams []Operation `json:"streams,omitempty"`
// Skipped lists operations the ingester found in the source spec but
// deliberately did NOT expose at all (gRPC client-streaming and
// bidi-streaming methods, which cannot ride a JSON-over-HTTP bridge).
// Generators ignore it; the CLI reports it at add time so exclusions are
// specific instead of silent.
Skipped []SkippedOperation `json:"skipped,omitempty"`
}
API is the normalized description of an API.
func (*API) OperationByID ¶
OperationByID returns the operation with the given ID, or nil.
func (*API) Resolve ¶
Resolve dereferences a schema one level against the API's named schemas. It returns the input unchanged when it is not a reference.
func (*API) SortedOperations ¶
SortedOperations returns operations sorted by ID for deterministic output.
func (*API) StreamByID ¶
StreamByID returns the stream operation with the given ID, or nil.
type AuthScheme ¶
type AuthScheme struct {
Name string `json:"name"` // security scheme name (key)
Type string `json:"type"` // "apiKey" | "http" | "oauth2"
In string `json:"in,omitempty"` // apiKey: "header" | "query" | "cookie"
KeyName string `json:"key_name,omitempty"` // apiKey: the header/query parameter name
Scheme string `json:"scheme,omitempty"` // http: "bearer" | "basic"
}
AuthScheme describes one authentication mechanism.
type Operation ¶
type Operation struct {
ID string `json:"id"` // operationId → tool/method name (sanitized)
Method string `json:"method"` // GET/POST/PUT/PATCH/DELETE
Path string `json:"path"` // /v1/customers/{id}
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
Params []Param `json:"params,omitempty"`
RequestBody *Schema `json:"request_body,omitempty"`
Responses map[string]*Schema `json:"responses,omitempty"`
Auth []string `json:"auth,omitempty"`
Pagination *PaginationHint `json:"pagination,omitempty"`
Mutating bool `json:"mutating"` // non-GET ⇒ approval candidate
Tags []string `json:"tags,omitempty"`
}
Operation is a single callable endpoint.
func (*Operation) ToolInputSchema ¶
func (op *Operation) ToolInputSchema(api *API) json.RawMessage
ToolInputSchema builds a single flat JSON-Schema object for an operation by merging its path/query/header parameters and request body into one object — the convention agent tool callers expect (one flat input object per tool). A non-object body is wrapped under a "body" property.
type PaginationHint ¶
type PaginationHint struct {
Style string `json:"style"` // "cursor" | "page" | "offset"
Param string `json:"param"` // request param that drives paging
NextField string `json:"next_field,omitempty"` // response field holding the next token
}
PaginationHint records detected pagination so generators can emit iterators.
type Param ¶
type Param struct {
Name string `json:"name"`
In string `json:"in"` // path | query | header | cookie
Required bool `json:"required"`
Description string `json:"description,omitempty"`
Schema *Schema `json:"schema,omitempty"`
}
Param is a path / query / header / cookie parameter.
type Schema ¶
type Schema struct {
Name string `json:"name,omitempty"` // component name, if a named schema
Ref string `json:"ref,omitempty"` // referenced component name
Type string `json:"type,omitempty"` // object|array|string|number|integer|boolean
Format string `json:"format,omitempty"`
Description string `json:"description,omitempty"`
Properties map[string]*Schema `json:"properties,omitempty"`
Required []string `json:"required,omitempty"`
Items *Schema `json:"items,omitempty"`
Enum []string `json:"enum,omitempty"`
Nullable bool `json:"nullable,omitempty"`
AdditionalProperties *Schema `json:"additional_properties,omitempty"`
}
Schema is a normalized JSON-Schema node. A reference is represented by Ref (the component name); generators resolve it via API.Schemas when needed.
func (*Schema) JSONSchema ¶
func (s *Schema) JSONSchema(api *API) json.RawMessage
JSONSchema renders a Schema as a draft-07-ish JSON Schema document (the shape tools.ToolSpec.Parameters and MCP inputSchema expect). References are inlined one level to keep the schema self-contained for the model.
type SkippedOperation ¶
type SkippedOperation struct {
ID string `json:"id"`
Kind string `json:"kind"` // one of the Skip* constants below
}
SkippedOperation records one deliberately-unexposed source operation.
Source Files