radix

Documentation

Overview

Package radix implements a generic radix tree for HTTP route matching.

• Nodes are static (byte-exact), param ("{name}", matches [^/]+), or catch-all ("{*name}", matches the rest of the path including slashes).
• A bare "*" segment is an unnamed catch-all (the "/*" wildcard); "/*" and "/static/*" are equivalent to "/{*}" and "/static/{*}" and expose the remainder under the key "*".
• Static nodes beat params, which beat catch-alls, at the same position — independent of registration order, so a static route is never shadowed.
• A catch-all matches the rest of the path, including an empty remainder: /files/{*path} matches /files (path="") and /* matches / (*=""). A single-segment param still requires a non-empty value.
• A catch-all must be the last segment of a pattern.
• Insert and Search both CleanPath-normalize; both must use the same rule.

Matching is case-sensitive. The tree is generic in the handler value T, so it stores whatever the caller needs (a handler in httpsrv, a string in tests). It never compares two T values, so T may be a func type.

Index

• func CleanPath(p string) string
• type Node
  • func New[T any]() *Node[T]
  • func (n *Node[T]) Insert(path string, handler T) error
  • func (n *Node[T]) Search(path string, params Params) (T, Params, bool)
• type Param
• type Params

Functions

func CleanPath

func CleanPath(p string) string

CleanPath normalizes a path: guarantees a leading '/', collapses duplicate slashes, and resolves '.'/'..'. Uses path (not path/filepath) for URL semantics on every platform. Insert and Search must use the same rule.

The common case — a path that is already canonical (which net/http guarantees for r.URL.Path, and which holds for every normalized route) — is returned as-is without allocating; only genuinely dirty input falls back to path.Clean.

Types

type Node

type Node[T any] struct {
	// contains filtered or unexported fields
}

Node is a radix tree node. The handler value has type T.

func New

func New[T any]() *Node[T]

New returns a new empty radix tree root of value type T.

func (*Node[T]) Insert

func (n *Node[T]) Insert(path string, handler T) error

Insert registers a route. The pattern is CleanPath-normalized, "*" wildcard segments are rewritten to "{*}", then validated; on error the tree is left unchanged.

func (*Node[T]) Search

func (n *Node[T]) Search(path string, params Params) (T, Params, bool)

Search looks up a route, returning the matching handler and any extracted params. The path is normalized once here; the recursion in search avoids re-cleaning already-consumed fragments (which would wrongly re-add a '/').

type Param

type Param struct {
	Key      string
	Value    string
	CatchAll bool // true for a {*name} catch-all match
}

Param is a single extracted path parameter.

type Params

type Params []Param

Params is a list of path parameters.