Documentation
¶
Overview ¶
Package spec wraps the embedded Auth0 Management API skeleton. It exposes operation iteration, request validation, response validation, and registration-payload validation — everything the mgmtapi package needs to drive the Mgmt API.
Index ¶
- Constants
- func ConciseSchemaError(err error) string
- type Operation
- type Spec
- type Validator
- func (v *Validator) Resolve(method, path string) (Operation, error)
- func (v *Validator) ValidateEventStreamPayload(op Operation, status int, body []byte) error
- func (v *Validator) ValidateQueryMatcher(op Operation, query map[string]string) error
- func (v *Validator) ValidateRegistration(op Operation, status int, body json.RawMessage) error
- func (v *Validator) ValidateRegistrationDeferring(op Operation, status int, body json.RawMessage, skip, text []string) error
- func (v *Validator) ValidateRegistrationSkipping(op Operation, status int, body json.RawMessage, skip []string) error
- func (v *Validator) ValidateRequest(r *http.Request, _ Operation) error
- func (v *Validator) ValidateRequestMatcher(op Operation, body json.RawMessage) error
- func (v *Validator) ValidateResponse(op Operation, status int, headers map[string]string, body []byte) error
Constants ¶
const SubscribeEventsOperationID = "subscribe_events"
SubscribeEventsOperationID names GET /events, the one operation served by the SSE hub rather than the generic stub-driven handler.
Variables ¶
This section is empty.
Functions ¶
func ConciseSchemaError ¶ added in v0.228.0
ConciseSchemaError trims kin-openapi's verbose validation output to the actionable bits: a one-line `/json/pointer: reason` per failed field, joined with "; ". The raw error embeds a "Schema:\n {…}\n Value:\n …" block per failure, which gets relayed through JSON as `\n`-escaped soup and makes the wire response unreadable.
Walks MultiError → SchemaError leaves. Falls back to the first line of err.Error() when the structure isn't a shape we know how to walk.
Types ¶
type Operation ¶
type Operation struct {
Method string // Upper-case HTTP verb, e.g. "GET".
Template string // Full path including BasePath, e.g. "/api/v2/users/{id}".
Op *openapi3.Operation
}
Operation is one (method, path, openapi3.Operation) triple from the spec.
type Spec ¶
type Spec struct {
Doc *openapi3.T
BasePath string // E.g. "/api/v2" (derived from servers[0].url path component).
}
Spec wraps an openapi3.T plus a router for request matching.
type Validator ¶
type Validator struct {
// contains filtered or unexported fields
}
Validator wraps openapi3filter for request and registration-payload validation.
func NewValidator ¶
NewValidator constructs a Validator. The underlying router is built once. DisableSchemaPatternValidation is required because Auth0's spec contains Perl-syntax lookahead patterns (e.g. `(?=`) that Go's regexp engine does not support. Route matching is unaffected; only pattern constraints are skipped during router construction.
Returns an error if the embedded spec cannot be turned into a router; the caller (cmd/api boot) should surface that to the user instead of crashing.
func (*Validator) Resolve ¶
Resolve finds the spec Operation that a (method, path) pair routes to. The path may be concrete ("/api/v2/users/auth0|1") or a template ("/api/v2/users/{id}") — the router treats a literal "{id}" segment as just another path-parameter value, so both forms resolve to the same operation. Returns an error when no operation matches. Used by the /admin0/expectations handler, which receives method+path in a request body rather than from a routed URL.
func (*Validator) ValidateEventStreamPayload ¶ added in v0.228.0
ValidateEventStreamPayload validates a single SSE event payload against the text/event-stream schema declared for (op, status). Mirrors ValidateResponse but selects text/event-stream instead of application/json. Used by POST /admin0/events to reject misshapen CloudEvent payloads at push time (defence-in-depth, same pattern as ValidateRegistration).
func (*Validator) ValidateQueryMatcher ¶
ValidateQueryMatcher checks that every key in a query matcher names a query parameter declared by the operation.
func (*Validator) ValidateRegistration ¶
ValidateRegistration checks a registered response payload against the operation's response schema for the chosen status. Status must be present in op.Responses (or "default"); body is unmarshaled JSON.
func (*Validator) ValidateRegistrationDeferring ¶ added in v0.234.0
func (v *Validator) ValidateRegistrationDeferring(op Operation, status int, body json.RawMessage, skip, text []string) error
ValidateRegistrationDeferring is ValidateRegistrationSkipping that also defers the value checks (enum, format, pattern, length) at the JSON pointers in text to serve time, while still requiring a string there. It serves strings whose text is only known when served, such as a path parameter or an embedded placeholder in a template.
func (*Validator) ValidateRegistrationSkipping ¶ added in v0.234.0
func (v *Validator) ValidateRegistrationSkipping(op Operation, status int, body json.RawMessage, skip []string) error
ValidateRegistrationSkipping is ValidateRegistration that ignores schema errors at the JSON pointers in skip, or under them. It serves values whose type is only known at serve time, such as template placeholders.
func (*Validator) ValidateRequest ¶
ValidateRequest checks an incoming request against the operation it routed to. It returns nil on success or an error suitable for a 400 response body.
func (*Validator) ValidateRequestMatcher ¶
func (v *Validator) ValidateRequestMatcher(op Operation, body json.RawMessage) error
ValidateRequestMatcher checks a request-body matcher against the operation's request body schema, with `required` constraints relaxed — a matcher is intentionally partial, so absent required fields are fine, but unknown fields (the request schema is typically additionalProperties:false) and mistyped known fields are still rejected. An empty matcher body is a no-op; an operation that declares no JSON request body rejects any non-empty body.
func (*Validator) ValidateResponse ¶
func (v *Validator) ValidateResponse(op Operation, status int, headers map[string]string, body []byte) error
ValidateResponse checks an outgoing response. Used as defense-in-depth at serve time. Errors here mean a registered match was somehow stored despite failing ValidateRegistration; in strict mode the caller returns 500.