spec

package
v0.233.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 27, 2026 License: MIT Imports: 13 Imported by: 0

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

View Source
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

func ConciseSchemaError(err error) string

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.

func Load

func Load(jsonDoc []byte) (*Spec, error)

Load parses the given OpenAPI 3.1 JSON document.

func (*Spec) Operations

func (s *Spec) Operations() iter.Seq[Operation]

Operations yields every operation in the spec. The Template includes the spec's BasePath so callers don't have to recombine.

type Validator

type Validator struct {
	// contains filtered or unexported fields
}

Validator wraps openapi3filter for request and registration-payload validation.

func NewValidator

func NewValidator(s *Spec) (*Validator, error)

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

func (v *Validator) Resolve(method, path string) (Operation, error)

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

func (v *Validator) ValidateEventStreamPayload(op Operation, status int, body []byte) error

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

func (v *Validator) ValidateQueryMatcher(op Operation, query map[string]string) error

ValidateQueryMatcher checks that every key in a query matcher names a query parameter declared by the operation.

func (*Validator) ValidateRegistration

func (v *Validator) ValidateRegistration(op Operation, status int, body json.RawMessage) error

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) ValidateRequest

func (v *Validator) ValidateRequest(r *http.Request, _ Operation) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL