Documentation
¶
Overview ¶
Package module is the contract for controls compiled into the gateway binary. A module registers itself from init with Register, takes its settings from one member of a policy operation, compiles them once per published policy and then checks requests at one fixed phase of the request pipeline.
The order of phases is fixed in the gateway, never configured: a module cannot run before the checks its phase follows, cannot skip a later stage and never forwards anything. A refusal or failure ends the request. The gateway's five built-in controls (jwt, rbac, rate, body, validation) are registered under their own IDs in every build, which reserves those IDs.
A Check sees only a copy of the request's method, path, client address, headers and verified identity: no body, no token and no connection. It must not perform network or file I/O and must not keep mutable package-level state; per-key state belongs in a Table.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Control ¶
type Control interface {
Info() Info
// Compile runs inside the gateway's policy compiler, once per published
// policy and operation, never per request. raw is this module's member of
// the operation, nil when absent. A nil Check means the module is not
// configured for the operation. An error or a panic refuses the policy.
Compile(op Operation, raw json.RawMessage) (Check, error)
}
Control is a module.
func Extensions ¶
func Extensions() []Control
Extensions returns the registered modules that are not built in, sorted by phase and then ID: the ones whose checks the pipeline runs and whose policy members the gateway reads.
type Info ¶
type Info struct {
ID string // 1-32 of a-z, 0-9, '_'; unique; also the policy member name
Phase Phase
Version string // the module's own version
}
Info identifies a module.
func Registered ¶
func Registered() []Info
Registered lists every registered module, built-ins included, sorted by phase and then ID.
type Operation ¶
type Operation struct {
ID, API, Method, Target string
}
Operation is the policy operation a module's settings belong to.
type Phase ¶
type Phase int
Phase is the point of the request pipeline at which a module runs.
const ( Ingress Phase = iota + 1 // after the ingress checks, before a policy is captured; sees no policy settings Identity // after routing and access, following token verification Authorise // following roles and blocked accounts Traffic // following the rate limit Validate // following body and header validation )
type Request ¶
type Request struct {
Method, Path, ClientAddress string
Header http.Header // a copy: changing it changes nothing
Subject string // empty before or without a verified token
Roles []string
Operation, API string // empty in the Ingress phase
}
Request is the read-only view of a request a Check receives.
type Result ¶
type Result struct {
// contains filtered or unexported fields
}
Result is a Check's decision. Only Pass, Refuse and Fail build one; the zero Result is treated as a failure.
func Fail ¶
Fail ends the request with 503 gateway_unavailable; reason is recorded with the module's ID and must not contain request data.
func Refuse ¶
Refuse ends the request with status (400-499) and the error code code. A status outside that range or a malformed code becomes a failure.
func (Result) Passed ¶
Passed, Refused and Failed report the decision; Status and Code are the refusal's answer, and Reason a failure's reason.
type Table ¶
type Table[K comparable, V any] struct { // contains filtered or unexported fields }
Table holds per-key state for a module, bounded by a fixed number of keys. When it is full, Update refuses a new key instead of evicting one, so the module can fail closed. It is safe for concurrent use.
Source Files