mux

package
v0.85.0-pre.13 Latest Latest
Warning

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

 Go to latest Published: May 8, 2026 License: BSD-3-Clause Imports: 19 Imported by: 0

Documentation

Overview

Package mux provides typed HTTP routing with pattern matching, middleware composition, and nested route execution.

It supports two routing models:

  • Router: resolves one best-match route per request (traditional routing).
  • NestedRouter: resolves hierarchical ancestor matches (loader/layout routing).

Handlers may be standard http.Handlers or typed task handlers that return JSON-serializable data through a tasks.Cache execution context.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddNestedPatternWithoutHandler 

func AddNestedPatternWithoutHandler(router *NestedRouter, pattern string)

AddNestedPatternWithoutHandler registers a nested pattern with no handler.

func FindNestedMatches 

func FindNestedMatches(
	nr *NestedRouter, r *http.Request,
) (*matcher.FindNestedMatchesResults, bool)

FindNestedMatches resolves nested route matches for the request path.

func GetMatchedPattern 

func GetMatchedPattern(r *http.Request) string

GetMatchedPattern extracts the matched route pattern from a request.

func GetParam 

func GetParam(r *http.Request, key string) string

GetParam returns one route param by key.

func GetSplatValues 

func GetSplatValues(r *http.Request) []string

GetSplatValues returns all matched splat segments.

func GetTasksCache 

func GetTasksCache(r *http.Request) *tasks.Cache

GetTasksCache extracts the tasks cache from a request.

func InjectTasksCacheMiddleware 

func InjectTasksCacheMiddleware(next http.Handler) http.Handler

InjectTasksCacheMiddleware ensures requests carry a tasks cache.

func RequestWithTasksCache 

func RequestWithTasksCache(r *http.Request, ctx *tasks.Cache) *http.Request

RequestWithTasksCache returns a request carrying only a tasks cache.

func UseMiddleware 

func UseMiddleware(
	rt *Router,
	mw Middleware,
	opts ...*MiddlewareOptions,
)

func UseMiddlewareByMethod 

func UseMiddlewareByMethod(
	rt *Router,
	method string,
	mw Middleware,
	opts ...*MiddlewareOptions,
)

func UseMiddlewareByPattern 

func UseMiddlewareByPattern[I, O any](
	route *Route[I, O],
	mw Middleware,
	opts ...*MiddlewareOptions,
)

func UseTaskMiddleware 

func UseTaskMiddleware[O any](
	rt *Router,
	mw *TaskMiddleware[O],
	opts ...*MiddlewareOptions,
)

func UseTaskMiddlewareByMethod 

func UseTaskMiddlewareByMethod[O any](
	rt *Router,
	method string,
	mw *TaskMiddleware[O],
	opts ...*MiddlewareOptions,
)

func UseTaskMiddlewareByPattern 

func UseTaskMiddlewareByPattern[PI, PO, MWO any](
	route *Route[PI, PO],
	mw *TaskMiddleware[MWO],
	opts ...*MiddlewareOptions,
)

Types

type AnyNestedRoute 

type AnyNestedRoute interface {
	OriginalPattern() string
	genericsutil.AnyZeroHelper
	// contains filtered or unexported methods
}

AnyNestedRoute is the type-erased nested route interface.

type AnyRoute 

type AnyRoute interface {
	OriginalPattern() string
	Method() string
	genericsutil.AnyZeroHelper
	// contains filtered or unexported methods
}

AnyRoute is the type-erased route interface.

type Middleware 

type Middleware = func(http.Handler) http.Handler

type MiddlewareOptions 

type MiddlewareOptions struct {
	If func(r *http.Request) bool
}

MiddlewareOptions configures conditional middleware execution.

type NestedOptions 

type NestedOptions struct {
	DynamicParamPrefix             rune
	SplatSegmentIdentifier         rune
	ExplicitIndexSegmentIdentifier string
	ParseInput                     func(r *http.Request, inputPtr any) error
}

NestedOptions configures NestedRouter pattern matching.

type NestedRoute 

type NestedRoute[I, O any] struct {
	genericsutil.ZeroHelper[I, O]
	// contains filtered or unexported fields
}

NestedRoute stores metadata and an optional task handler for one nested pattern.

func AddNestedTaskHandler 

func AddNestedTaskHandler[I, O any](
	router *NestedRouter, pattern string, handler *TaskHandler[I, O],
) *NestedRoute[I, O]

AddNestedTaskHandler registers a nested pattern with a task handler.

func (*NestedRoute[I, O]) OriginalPattern 

func (r *NestedRoute[I, O]) OriginalPattern() string

type NestedRouter 

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

NestedRouter stores nested route patterns and optional task handlers.

func NewNestedRouter 

func NewNestedRouter(options ...NestedOptions) *NestedRouter

NewNestedRouter creates a NestedRouter.

func (*NestedRouter) AddPatternWithoutHandlerIfMissing 

func (nr *NestedRouter) AddPatternWithoutHandlerIfMissing(pattern string) bool

AddPatternWithoutHandlerIfMissing registers a pattern without a handler only when it is not already present. Returns true if a new route was added.

func (*NestedRouter) AllRoutes 

func (nr *NestedRouter) AllRoutes() map[string]AnyNestedRoute

AllRoutes returns a snapshot copy of registered routes.

func (*NestedRouter) DynamicParamPrefix 

func (nr *NestedRouter) DynamicParamPrefix() rune

func (*NestedRouter) ExplicitIndexSegmentIdentifier 

func (nr *NestedRouter) ExplicitIndexSegmentIdentifier() string

func (*NestedRouter) HasTaskHandler 

func (nr *NestedRouter) HasTaskHandler(pattern string) bool

HasTaskHandler reports whether a pattern is registered with a handler.

func (*NestedRouter) IsRegistered 

func (nr *NestedRouter) IsRegistered(pattern string) bool

IsRegistered reports whether a pattern is registered.

func (*NestedRouter) Matcher 

func (nr *NestedRouter) Matcher() *matcher.Matcher

Matcher returns a copy of the nested matcher.

func (*NestedRouter) RebuildPreservingHandlers 

func (nr *NestedRouter) RebuildPreservingHandlers(patterns []string)

RebuildPreservingHandlers atomically rebuilds the router, preserving routes that have task handlers and replacing handler-less routes with the provided patterns. Intended for dev-time hot rebuilds.

func (*NestedRouter) ReplaceRoutes 

func (nr *NestedRouter) ReplaceRoutes(new_routes map[string]AnyNestedRoute)

ReplaceRoutes atomically replaces all routes with a new set.

func (*NestedRouter) SplatSegmentIdentifier 

func (nr *NestedRouter) SplatSegmentIdentifier() rune

type NestedTasksResult 

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

NestedTasksResult stores execution output for one matched nested pattern.

func (*NestedTasksResult) Data 

func (r *NestedTasksResult) Data() any

func (*NestedTasksResult) Err 

func (r *NestedTasksResult) Err() error

func (*NestedTasksResult) OK 

func (r *NestedTasksResult) OK() bool

func (*NestedTasksResult) Pattern 

func (r *NestedTasksResult) Pattern() string

func (*NestedTasksResult) RanTask 

func (r *NestedTasksResult) RanTask() bool

type NestedTasksResults 

type NestedTasksResults struct {
	Params          Params
	SplatValues     []string
	Results         []*NestedTasksResult
	ResponseProxies []*response.Proxy
}

NestedTasksResults contains ordered task results for nested matches.

func FindNestedMatchesAndRunTasks 

func FindNestedMatchesAndRunTasks(
	nr *NestedRouter, r *http.Request,
) (*NestedTasksResults, bool)

FindNestedMatchesAndRunTasks finds matches and executes all matched handlers.

func RunNestedTasks 

func RunNestedTasks(
	nr *NestedRouter,
	r *http.Request,
	find_results *matcher.FindNestedMatchesResults,
) *NestedTasksResults

RunNestedTasks executes all task handlers for the matched routes in parallel.

This function uses object pooling for RequestCtx[None]. Safety depends on task execution completing before pooled objects are returned, which is guaranteed by the blocking WaitGroup/single-goroutine execution pattern below.

func (*NestedTasksResults) HasTaskHandlerAt 

func (r *NestedTasksResults) HasTaskHandlerAt(i int) bool

HasTaskHandlerAt reports whether the result at index i ran a task handler.

type None 

type None = genericsutil.None

type Options 

type Options struct {
	MountRoot              string
	DynamicParamPrefix     rune
	SplatSegmentIdentifier rune
	ParseInput             func(r *http.Request, inputPtr any) error
}

Options configures Router matching and input parsing.

type Params 

type Params = matcher.Params

func GetParams 

func GetParams(r *http.Request) Params

GetParams returns all route params for the request.

type RequestCtx 

type RequestCtx[I any] struct {
	// contains filtered or unexported fields
}

RequestCtx is request-scoped context passed to task handlers and middleware.

func (*RequestCtx[I]) AddResponseHeader 

func (rc *RequestCtx[I]) AddResponseHeader(
	k, v string,
)

func (*RequestCtx[I]) ClearForPool 

func (rc *RequestCtx[I]) ClearForPool()

ClearForPool zeroes fields before returning to a pool.

func (*RequestCtx[I]) HeadBuilder 

func (rc *RequestCtx[I]) HeadBuilder() *head.Builder

func (*RequestCtx[I]) Input 

func (rc *RequestCtx[I]) Input() I

func (*RequestCtx[I]) IsResponseError 

func (rc *RequestCtx[I]) IsResponseError() bool

func (*RequestCtx[I]) IsResponseRedirect 

func (rc *RequestCtx[I]) IsResponseRedirect() bool

func (*RequestCtx[I]) IsResponseSuccess 

func (rc *RequestCtx[I]) IsResponseSuccess() bool

func (*RequestCtx[I]) MatchedPattern 

func (rc *RequestCtx[I]) MatchedPattern() string

func (*RequestCtx[I]) Param 

func (rc *RequestCtx[I]) Param(key string) string

func (*RequestCtx[I]) Params 

func (rc *RequestCtx[I]) Params() Params

func (*RequestCtx[I]) Redirect 

func (rc *RequestCtx[I]) Redirect(url string, code ...int) (bool, error)

func (*RequestCtx[I]) Request 

func (rc *RequestCtx[I]) Request() *http.Request

func (*RequestCtx[I]) ResetForReuse 

func (rc *RequestCtx[I]) ResetForReuse(
	matched_pattern string,
	params Params,
	splat []string,
	input I,
	r *http.Request,
	proxy *response.Proxy,
)

ResetForReuse reinitializes fields for pooled reuse.

func (*RequestCtx[I]) ResponseCookies 

func (rc *RequestCtx[I]) ResponseCookies() []*http.Cookie

func (*RequestCtx[I]) ResponseHeader 

func (rc *RequestCtx[I]) ResponseHeader(
	k string,
) string

func (*RequestCtx[I]) ResponseHeaders 

func (rc *RequestCtx[I]) ResponseHeaders(
	k string,
) []string

func (*RequestCtx[I]) ResponseLocation 

func (rc *RequestCtx[I]) ResponseLocation() string

func (*RequestCtx[I]) ResponseProxy 

func (rc *RequestCtx[I]) ResponseProxy() *response.Proxy

func (*RequestCtx[I]) ResponseStatus 

func (rc *RequestCtx[I]) ResponseStatus() (int, string)

func (*RequestCtx[I]) SetRequest 

func (rc *RequestCtx[I]) SetRequest(req *http.Request)

func (*RequestCtx[I]) SetResponseCookie 

func (rc *RequestCtx[I]) SetResponseCookie(
	c *http.Cookie,
)

func (*RequestCtx[I]) SetResponseHeader 

func (rc *RequestCtx[I]) SetResponseHeader(
	k, v string,
)

func (*RequestCtx[I]) SetResponseStatus 

func (rc *RequestCtx[I]) SetResponseStatus(status int, text ...string)

func (*RequestCtx[I]) SetTasksCache 

func (rc *RequestCtx[I]) SetTasksCache(ctx *tasks.Cache)

func (*RequestCtx[I]) SplatValues 

func (rc *RequestCtx[I]) SplatValues() []string

func (*RequestCtx[I]) TasksCache 

func (rc *RequestCtx[I]) TasksCache() *tasks.Cache

type Route 

type Route[I, O any] struct {
	genericsutil.ZeroHelper[I, O]
	// contains filtered or unexported fields
}

Route stores registration metadata and handlers for a method+pattern pair.

func AddHTTPHandler 

func AddHTTPHandler(
	router *Router, method, pattern string, handler http.Handler,
) *Route[any, any]

AddHTTPHandler registers an http.Handler route.

func AddHTTPHandlerFunc 

func AddHTTPHandlerFunc(
	router *Router, method, pattern string, fn http.HandlerFunc,
) *Route[any, any]

AddHTTPHandlerFunc registers an http.HandlerFunc route.

func AddTaskHandler 

func AddTaskHandler[I, O any](
	router *Router, method, pattern string, handler *TaskHandler[I, O],
) *Route[I, O]

AddTaskHandler registers a task-based route handler.

func (*Route[I, O]) Method 

func (r *Route[I, O]) Method() string

func (*Route[I, O]) OriginalPattern 

func (r *Route[I, O]) OriginalPattern() string

func (*Route[I, O]) UseMiddlewareByPattern 

func (route *Route[I, O]) UseMiddlewareByPattern(
	mw Middleware,
	opts ...*MiddlewareOptions,
)

type Router 

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

Router matches one best route per request and executes its handler pipeline.

func NewRouter 

func NewRouter(options ...Options) *Router

NewRouter creates a Router.

func (*Router) AddHTTPHandler 

func (rt *Router) AddHTTPHandler(
	method, pattern string,
	h http.Handler,
) *Route[any, any]

func (*Router) AddHTTPHandlerFunc 

func (rt *Router) AddHTTPHandlerFunc(
	method, pattern string,
	fn http.HandlerFunc,
) *Route[any, any]

func (*Router) AllRoutes 

func (rt *Router) AllRoutes() []AnyRoute

AllRoutes returns a snapshot of all registered routes.

func (*Router) DynamicParamPrefix 

func (rt *Router) DynamicParamPrefix() rune

DynamicParamPrefix returns the configured dynamic param prefix.

func (*Router) MountRoot 

func (rt *Router) MountRoot(pattern ...string) string

MountRoot returns the mount root, optionally joined with a pattern. Panics if more than one argument is provided.

func (*Router) ServeHTTP 

func (rt *Router) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP matches the request and executes the resolved route pipeline.

func (*Router) SetGlobalNotFoundHTTPHandler added in v0.83.0 

func (rt *Router) SetGlobalNotFoundHTTPHandler(
	h http.Handler,
)

SetGlobalNotFoundHTTPHandler sets the fallback handler for unmatched requests.

func (*Router) SplatSegmentIdentifier 

func (rt *Router) SplatSegmentIdentifier() rune

SplatSegmentIdentifier returns the configured splat identifier.

func (*Router) UseMiddleware 

func (rt *Router) UseMiddleware(
	mw Middleware,
	opts ...*MiddlewareOptions,
)

func (*Router) UseMiddlewareByMethod 

func (rt *Router) UseMiddlewareByMethod(
	method string,
	mw Middleware,
	opts ...*MiddlewareOptions,
)

type TaskHandler 

type TaskHandler[I, O any] = tasks.Task[*RequestCtx[I], O]

func TaskHandlerFromFunc 

func TaskHandlerFromFunc[I, O any](
	fn TaskHandlerFunc[I, O],
) *TaskHandler[I, O]

TaskHandlerFromFunc creates a TaskHandler from a function.

type TaskHandlerFunc 

type TaskHandlerFunc[I, O any] func(*RequestCtx[I]) (O, error)

type TaskMiddleware 

type TaskMiddleware[O any] = tasks.Task[*RequestCtx[None], O]

func TaskMiddlewareFromFunc 

func TaskMiddlewareFromFunc[O any](
	fn TaskMiddlewareFunc[O],
) *TaskMiddleware[O]

TaskMiddlewareFromFunc creates TaskMiddleware from a function.

type TaskMiddlewareFunc 

type TaskMiddlewareFunc[O any] func(*RequestCtx[None]) (O, error)

type TasksCacheRequirer 

type TasksCacheRequirer interface {
	http.Handler
	NeedsTasksCache()
}

TasksCacheRequirer marks HTTP handlers that need a tasks cache injected.

type TasksCacheRequirerFunc 

type TasksCacheRequirerFunc func(http.ResponseWriter, *http.Request)

TasksCacheRequirerFunc adapts a function to a TasksCacheRequirer.

func (TasksCacheRequirerFunc) NeedsTasksCache 

func (h TasksCacheRequirerFunc) NeedsTasksCache()

func (TasksCacheRequirerFunc) ServeHTTP 

func (h TasksCacheRequirerFunc) ServeHTTP(
	w http.ResponseWriter,
	r *http.Request,
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.