Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ValidateAllowedHosts ¶
ValidateAllowedHosts accepts DNS names, IPv4 literals and bracketed IPv6 literals. An empty list adds no hosts; an invalid entry returns a user error naming that entry. It does not resolve DNS or accept ports or URL components.
Types ¶
type AuthHook ¶
type AuthHook interface {
// Authenticate returns the caller identity or an error without consuming the body.
Authenticate(*http.Request) (Principal, error)
}
AuthHook authenticates every route before its body is read. An error refuses the request with E426; a successful principal does not bypass invocation gates.
func BearerAuth ¶
BearerAuth checks a case-sensitive Bearer token using constant-time comparison of SHA-256 digests. An empty configured token rejects every request.
type Invoker ¶
type Invoker func(context.Context, *cmdregistry.Registry, string, invoke.Request, invoke.Options) (invoke.Result, error)
Invoker executes a registry command with the request context and server guard. Implementations must honor cancellation and the shared invocation contracts.
type Options ¶
type Options struct {
// Registry is the startup command snapshot; callers must not mutate it while serving.
Registry *cmdregistry.Registry
// Invoker executes commands; nil selects invoke.Invoke with the server's guard.
Invoker Invoker
// ProjectDir is the invocation working directory, not an HTTP-controlled value.
ProjectDir string
// Port is the required Host/Origin port; it must match the listener's actual port.
Port int
// AllowedHosts adds DNS names, IPv4 or bracketed IPv6 literals to the loopback
// defaults. Values must omit ports, schemes, paths and whitespace.
AllowedHosts []string
// Timeout limits document invocations; nonpositive values use invoke.DefaultTimeout.
// NDJSON invocations instead run until their request context ends.
Timeout time.Duration
// MaxInFlight caps command invocations; nonpositive values default to four.
MaxInFlight int
// Auth authenticates all routes before body reads and must not be nil.
Auth AuthHook
// DataSchema supplies committed data schemas by command path for OpenAPI.
// Nil or a missing schema produces an open data object.
DataSchema func(string) ([]byte, bool)
// Log receives serialized request metadata only; nil selects os.Stderr.
Log io.Writer
// ReadHeaderTimeout bounds header reads; nonpositive values default to ten seconds.
ReadHeaderTimeout time.Duration
// ReadTimeout bounds request reads; nonpositive values default to thirty seconds.
// The deadline is cleared after command request decoding to permit streams.
ReadTimeout time.Duration
// IdleTimeout bounds keep-alive idle time; nonpositive values default to sixty seconds.
IdleTimeout time.Duration
}
Options configures one server. Registry and Auth are required; New supplies documented defaults for optional limits without opening a listener.
type Principal ¶
type Principal struct {
// Subject is the caller's opaque identity, not a token or a permission list.
Subject string
}
Principal identifies an authenticated caller; it carries no authorization grants.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server owns one authenticated mux, startup registry snapshot and invocation guard. Configure mounts before serving; concurrent mount changes are unsupported.
func New ¶
New validates options and builds routes, OpenAPI and one shared invocation guard. It does not listen or execute commands; Registry and Auth are required.
func (*Server) Handler ¶
Handler returns the private mux behind Host, Origin and AuthHook checks and request logging. Command routes additionally enforce invocation validation.
func (*Server) ListenAndServe ¶
ListenAndServe listens on addr without TLS or a write timeout. Cancellation stops accepting requests and permits five seconds to drain before closing remaining connections and canceling their request contexts. It then waits up to eleven seconds for invocation child cleanup and audit writes. Context values are preserved; its deadline and cancellation do not interrupt the graceful drain. A completed shutdown returns nil; listener failures return their error.
Source Files