Documentation
¶
Overview ¶
Package ext is the public extension API for building custom gateway binaries on top of GoModel. External modules register request rewriters, HTTP middleware, and extra routes on a Registry (usually ext.Default) before starting the gateway; core consumes an immutable snapshot of the registry at server construction. An empty registry adds zero request overhead.
Index ¶
- Variables
- func AddPublicPaths(paths ...string)
- func RegisterRewriter(rw RequestRewriter)
- func RegisterRoutes(fn func(e *echo.Echo))
- func UseMiddleware(m echo.MiddlewareFunc)
- type Endpoint
- type Input
- type Registry
- func (r *Registry) AddPublicPaths(paths ...string)
- func (r *Registry) Middleware() []echo.MiddlewareFunc
- func (r *Registry) PublicPaths() []string
- func (r *Registry) RegisterRewriter(rw RequestRewriter)
- func (r *Registry) RegisterRoutes(fn func(e *echo.Echo))
- func (r *Registry) Rewriters() []RequestRewriter
- func (r *Registry) Routes() []func(*echo.Echo)
- func (r *Registry) UseMiddleware(m echo.MiddlewareFunc)
- type RejectionError
- type RequestRewriter
- type Result
Constants ¶
This section is empty.
Variables ¶
var Default = &Registry{}
Default is the process-wide registry used by package-level helpers and, by default, by run.Run.
Functions ¶
func AddPublicPaths ¶
func AddPublicPaths(paths ...string)
AddPublicPaths registers auth-skip paths on the Default registry.
func RegisterRewriter ¶
func RegisterRewriter(rw RequestRewriter)
RegisterRewriter registers a rewriter on the Default registry.
func RegisterRoutes ¶
RegisterRoutes registers a route callback on the Default registry.
func UseMiddleware ¶
func UseMiddleware(m echo.MiddlewareFunc)
UseMiddleware registers middleware on the Default registry.
Types ¶
type Endpoint ¶
type Endpoint string
Endpoint identifies an inference endpoint whose raw JSON body can be rewritten before core parses it.
type Input ¶
type Input struct {
Endpoint Endpoint
// Body is the raw JSON request body, already bounded by the server's
// body-size limit.
Body []byte
// Header is a clone of the inbound request headers with credential
// values (Authorization, cookies, API keys, ...) redacted. Rewriters
// run post-auth; use UserPath for identity.
Header http.Header
// UserPath is the canonical authenticated user path, when present.
UserPath string
// RequestID is the request correlation ID (X-Request-ID).
RequestID string
}
Input is the raw inbound request handed to a rewriter before core parses it. Body and Header are snapshots owned by the middleware; rewriters must treat them as read-only and return new values in Result when changing anything.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry collects extensions to be consumed by the gateway at startup. Register everything before the server is constructed (before run.Run or app.New); core snapshots the registry once and never consults it again.
func (*Registry) AddPublicPaths ¶
AddPublicPaths appends paths to the authentication skip list (for example OAuth callback endpoints). A trailing "/*" matches a prefix.
func (*Registry) Middleware ¶
func (r *Registry) Middleware() []echo.MiddlewareFunc
Middleware returns a defensive copy of the registered middleware.
func (*Registry) PublicPaths ¶
PublicPaths returns a defensive copy of the registered public paths.
func (*Registry) RegisterRewriter ¶
func (r *Registry) RegisterRewriter(rw RequestRewriter)
RegisterRewriter adds a request rewriter. Rewriters run in registration order, each receiving the previous rewriter's output.
func (*Registry) RegisterRoutes ¶
RegisterRoutes adds a callback that registers extra routes after all core routes. Paths are relative to the server base path.
func (*Registry) Rewriters ¶
func (r *Registry) Rewriters() []RequestRewriter
Rewriters returns a defensive copy of the registered rewriters.
func (*Registry) UseMiddleware ¶
func (r *Registry) UseMiddleware(m echo.MiddlewareFunc)
UseMiddleware adds an Echo middleware that runs after audit capture and before gateway authentication, so it can normalize credentials (for example an SSO session) before the gateway auth check.
type RejectionError ¶
RejectionError rejects the request with a client-visible status code and machine-readable error code, rendered in the endpoint's native error dialect (OpenAI or Anthropic envelope).
func (*RejectionError) Error ¶
func (e *RejectionError) Error() string
type RequestRewriter ¶
type RequestRewriter interface {
Name() string
Rewrite(ctx context.Context, in Input) (*Result, error)
}
RequestRewriter rewrites raw JSON request bodies at ingress, after authentication and before model resolution, so body changes (including the "model" field) affect routing, failover, guardrails, budgets, and caching.
Rewriters run once per request in registration order; each receives the previous rewriter's output. Implementations must be safe for concurrent use. Errors fail the request (fail-closed): return a *RejectionError for a client-visible status, any other error maps to HTTP 500.
type Result ¶
type Result struct {
Body []byte
// ResponseHeader entries are merged into the HTTP response so rewriters
// can annotate what they did (for example X-GoModel-Pro-Tokens-Saved).
ResponseHeader http.Header
// Detail optionally carries a JSON-serializable summary of what the
// rewriter changed. It is recorded in the audit trail's request-revision
// chain and never sent upstream; it must never contain secrets or
// request credentials.
Detail any
// TokensSaved is the rewriter's estimate of prompt tokens its body
// change removed from the request. When positive and the rewritten body
// is applied, core adds it to the request's usage record together with
// the input cost those tokens would have incurred, and the dashboard
// aggregates both as rewrite savings. Leave zero when the rewrite does
// not shrink the prompt.
TokensSaved int
}
Result carries a rewritten body and response-header annotations. A nil Result (or nil Body) means the request is unchanged.
Source Files