route

Documentation

Overview

Package route provides immutable, pattern-indexed HTTP route values. Pattern identities are opt-in natural indices: Go+ checks them, generated Go retains IDs for erased-boundary guards, and ordinary net/http remains the wire API.

Index

• func Adapt(pattern Pattern, handler Handler) http.Handler
• func AddOutcomeFold[R any](a AddOutcome, cs AddOutcomeCases[R]) R
• func CapabilityEqual(a, b Capability) bool
• func CapabilityEqualWith(a, b Capability, ov CapabilityEqOverrides) bool
• func CapabilityFold[R any](v Capability, cs CapabilityCases[R]) R
• func MutateStateID() int
• func ObserveRequestID() int
• func ParamResultFold[T any, R any](p ParamResult[T], cs ParamResultCases[T, R]) R
• func ParseOutcomeFold[R any](p ParseOutcome, cs ParseOutcomeCases[R]) R
• func PatternID(pattern Pattern) int
• func Raw(request Request) *http.Request
• func ReadBodyID() int
• func RouteSetID(set int, route int) int
• func SegmentKindEqual(a, b SegmentKind) bool
• func SegmentKindEqualWith(a, b SegmentKind, ov SegmentKindEqOverrides) bool
• func SegmentKindFold[R any](s SegmentKind, cs SegmentKindCases[R]) R
• func Text(pattern Pattern) string
• func Wrap(middleware Middleware) func(http.Handler) http.Handler
• func WriteHeadersID() int
• func Writer(request Request) http.ResponseWriter
• type AddOutcome
  • func Add(routeID int, set RouteSet, route Registered) AddOutcome
• type AddOutcomeCases
• type Capability
  • func CapabilityOf(middleware Middleware) Capability
• type CapabilityCases
• type CapabilityEqOverrides
• type Handler
  • func NewHandler(pattern Pattern, run func(Request)) Handler
• type InvalidPattern
• type Metadata
  • func Routes(set RouteSet) []Metadata
• type Middleware
  • func BodyReader(wrap func(http.Handler) http.Handler) Middleware
  • func HeaderWriter(wrap func(http.Handler) http.Handler) Middleware
  • func NewMiddleware(id int, capability Capability, wrap func(http.Handler) http.Handler) Middleware
  • func Observer(wrap func(http.Handler) http.Handler) Middleware
  • func StateMutator(wrap func(http.Handler) http.Handler) Middleware
• type MutateState
• type ObserveRequest
• type ParamFound
• type ParamInvalid
• type ParamKey
  • func NewParamKey[T any](pattern Pattern, name string, decode func(string) (T, bool)) ParamKey[T]
• type ParamMissing
• type ParamResult
  • func Param[T any](request Request, key ParamKey[T]) ParamResult[T]
• type ParamResultCases
• type ParameterKind
• type ParseOutcome
  • func Parse(id int, text string) ParseOutcome
• type ParseOutcomeCases
• type Pattern
  • func MustPattern(id int, text string) Pattern
• type PatternParsed
• type ReadBody
• type Registered
  • func Register(method string, pattern Pattern) Registered
• type Request
• type RouteAdded
• type RouteConflict
• type RouteSet
  • func Empty() RouteSet
• type Segment
• type SegmentKind
• type SegmentKindCases
• type SegmentKindEqOverrides
• type StaticKind
• type WildcardKind
• type WriteHeaders

Functions

func Adapt

func Adapt(pattern Pattern, handler Handler) http.Handler

Adapt turns a pattern-indexed handler into ordinary net/http. It validates the path independently, making std/http/route useful without any router.

func AddOutcomeFold

func AddOutcomeFold[R any](a AddOutcome, cs AddOutcomeCases[R]) R

AddOutcomeFold reduces AddOutcome by one-level case analysis.

func CapabilityEqual

func CapabilityEqual(a, b Capability) bool

CapabilityEqual reports structural equality of a and b.

func CapabilityEqualWith

func CapabilityEqualWith(a, b Capability, ov CapabilityEqOverrides) bool

CapabilityEqualWith reports structural equality of a and b under ov.

func CapabilityFold

func CapabilityFold[R any](v Capability, cs CapabilityCases[R]) R

CapabilityFold reduces Capability by one-level case analysis.

func MutateStateID

func MutateStateID() int

func ObserveRequestID

func ObserveRequestID() int

func ParamResultFold

func ParamResultFold[T any, R any](p ParamResult[T], cs ParamResultCases[T, R]) R

ParamResultFold reduces ParamResult[T] by one-level case analysis.

func ParseOutcomeFold

func ParseOutcomeFold[R any](p ParseOutcome, cs ParseOutcomeCases[R]) R

ParseOutcomeFold reduces ParseOutcome by one-level case analysis.

func PatternID

func PatternID(pattern Pattern) int

func Raw

func Raw(request Request) *http.Request

func ReadBodyID

func ReadBodyID() int

func RouteSetID

func RouteSetID(set int, route int) int

func SegmentKindEqual

func SegmentKindEqual(a, b SegmentKind) bool

SegmentKindEqual reports structural equality of a and b.

func SegmentKindEqualWith

func SegmentKindEqualWith(a, b SegmentKind, ov SegmentKindEqOverrides) bool

SegmentKindEqualWith reports structural equality of a and b under ov.

func SegmentKindFold

func SegmentKindFold[R any](s SegmentKind, cs SegmentKindCases[R]) R

SegmentKindFold reduces SegmentKind by one-level case analysis.

func Text

func Text(pattern Pattern) string

func Wrap

func Wrap(middleware Middleware) func(http.Handler) http.Handler

func WriteHeadersID

func WriteHeadersID() int

func Writer

func Writer(request Request) http.ResponseWriter

Types

type AddOutcome

type AddOutcome interface {
	// contains filtered or unexported methods
}

func Add

func Add(routeID int, set RouteSet, route Registered) AddOutcome

type AddOutcomeCases

type AddOutcomeCases[R any] struct {
	RouteAdded    func(Set RouteSet) R
	RouteConflict func(Existing Metadata, Incoming Metadata) R
}

AddOutcomeCases selects one handler per AddOutcome variant for AddOutcomeFold.

type Capability

type Capability interface {
	// contains filtered or unexported methods
}

Capability makes middleware effects explicit instead of hiding them in an arbitrary handler wrapper.

func CapabilityOf

func CapabilityOf(middleware Middleware) Capability

type CapabilityCases

type CapabilityCases[R any] struct {
	ObserveRequest func() R
	WriteHeaders   func() R
	ReadBody       func() R
	MutateState    func() R
}

CapabilityCases selects one handler per Capability variant for CapabilityFold.

type CapabilityEqOverrides

type CapabilityEqOverrides struct {
	ObserveRequest func(x, y ObserveRequest) (eq, handled bool)
	WriteHeaders   func(x, y WriteHeaders) (eq, handled bool)
	ReadBody       func(x, y ReadBody) (eq, handled bool)
	MutateState    func(x, y MutateState) (eq, handled bool)
}

CapabilityEqOverrides carries optional per-variant hooks for CapabilityEqualWith. A hook returning handled=false falls through to the derived comparison.

type Handler

type Handler interface {
	// contains filtered or unexported methods
}

Handler[p] is sealed handler code for Pattern[p].

func NewHandler

func NewHandler(pattern Pattern, run func(Request)) Handler

type InvalidPattern

type InvalidPattern struct {
	Message string
}

type Metadata

type Metadata struct {
	Method     string
	Pattern    string
	PatternID  int
	ParamNames []string
}

func Routes

func Routes(set RouteSet) []Metadata

type Middleware

type Middleware interface {
	// contains filtered or unexported methods
}

Middleware[c] carries one declared capability c.

func BodyReader

func BodyReader(wrap func(http.Handler) http.Handler) Middleware

func HeaderWriter

func HeaderWriter(wrap func(http.Handler) http.Handler) Middleware

func NewMiddleware

func NewMiddleware(id int, capability Capability, wrap func(http.Handler) http.Handler) Middleware

func Observer

func Observer(wrap func(http.Handler) http.Handler) Middleware

func StateMutator

func StateMutator(wrap func(http.Handler) http.Handler) Middleware

type MutateState

type MutateState struct{}

type ObserveRequest

type ObserveRequest struct{}

type ParamFound

type ParamFound[T any] struct {
	Value T
}

type ParamInvalid

type ParamInvalid[T any] struct {
	Raw string
}

type ParamKey

type ParamKey[T any] interface {
	// contains filtered or unexported methods
}

ParamKey[T,p] decodes one named parameter belonging to Pattern[p].

func NewParamKey

func NewParamKey[T any](pattern Pattern, name string, decode func(string) (T, bool)) ParamKey[T]

type ParamMissing

type ParamMissing[T any] struct{}

type ParamResult

type ParamResult[T any] interface {
	// contains filtered or unexported methods
}

func Param

func Param[T any](request Request, key ParamKey[T]) ParamResult[T]

type ParamResultCases

type ParamResultCases[T any, R any] struct {
	ParamMissing func() R
	ParamInvalid func(Raw string) R
	ParamFound   func(Value T) R
}

ParamResultCases selects one handler per ParamResult variant for ParamResultFold.

type ParameterKind

type ParameterKind struct{}

type ParseOutcome

type ParseOutcome interface {
	// contains filtered or unexported methods
}

func Parse

func Parse(id int, text string) ParseOutcome

type ParseOutcomeCases

type ParseOutcomeCases[R any] struct {
	PatternParsed  func(Pattern Pattern) R
	InvalidPattern func(Message string) R
}

ParseOutcomeCases selects one handler per ParseOutcome variant for ParseOutcomeFold.

type Pattern

type Pattern interface {
	// contains filtered or unexported methods
}

Pattern[p] is a parsed route pattern with singleton identity p.

func MustPattern

func MustPattern(id int, text string) Pattern

type PatternParsed

type PatternParsed struct {
	Pattern Pattern
}

type ReadBody

type ReadBody struct{}

type Registered

type Registered interface {
	// contains filtered or unexported methods
}

Registered[p] ties handler metadata to Pattern[p].

func Register

func Register(method string, pattern Pattern) Registered

type Request

type Request interface {
	// contains filtered or unexported methods
}

Request[p] carries exactly the parameter environment produced by Pattern[p].

type RouteAdded

type RouteAdded struct {
	Set RouteSet
}

type RouteConflict

type RouteConflict struct {
	Existing Metadata
	Incoming Metadata
}

type RouteSet

type RouteSet interface {
	// contains filtered or unexported methods
}

RouteSet[s] is an immutable route-set fingerprint. Add changes s using a collision-free pairing function, so separately assembled sets cannot mix.

func Empty

func Empty() RouteSet

type Segment

type Segment struct {
	Kind SegmentKind
	Text string
	Name string
}

type SegmentKind

type SegmentKind interface {
	// contains filtered or unexported methods
}

type SegmentKindCases

type SegmentKindCases[R any] struct {
	StaticKind    func() R
	ParameterKind func() R
	WildcardKind  func() R
}

SegmentKindCases selects one handler per SegmentKind variant for SegmentKindFold.

type SegmentKindEqOverrides

type SegmentKindEqOverrides struct {
	StaticKind    func(x, y StaticKind) (eq, handled bool)
	ParameterKind func(x, y ParameterKind) (eq, handled bool)
	WildcardKind  func(x, y WildcardKind) (eq, handled bool)
}

SegmentKindEqOverrides carries optional per-variant hooks for SegmentKindEqualWith. A hook returning handled=false falls through to the derived comparison.

type StaticKind

type StaticKind struct{}

type WildcardKind

type WildcardKind struct{}

type WriteHeaders

type WriteHeaders struct{}