diff options
| author | Stefan Majewsky <majewsky@gmx.net> | 2026-10-18 20:13:21 +0200 |
|---|---|---|
| committer | Stefan Majewsky <majewsky@gmx.net> | 2026-11-09 23:39:31 +0100 |
| commit | 9a0c9a69a7796b9ae77665dfbb151b3c6fdf31f1 (patch) | |
| tree | e7f53e1cc370482bb04ea0b5e350501b6fa1655f /pathrouter | |
| parent | d2de069dd272447d0709beccd5afda7431a9021e (diff) | |
| download | go-gg-pathrouter-builder.tar.gz | |
tmp: add Sinatra-style API for package pathrouterpathrouter-builder
I'm not convinced this is really worth it because of how contrived this
implementation ends up being, relative to the internal beauty of the
explicit tree-shaped builder, and how having this API would constrain
future API extensions because they would all have to be able to exist in
a stringly-typed way.
Diffstat (limited to 'pathrouter')
| -rw-r--r-- | pathrouter/builder.go | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/pathrouter/builder.go b/pathrouter/builder.go new file mode 100644 index 0000000..931bfd7 --- /dev/null +++ b/pathrouter/builder.go @@ -0,0 +1,298 @@ +// SPDX-FileCopyrightText: 2026 Stefan Majewsky <majewsky@gmx.net> +// SPDX-License-Identifier: Apache-2.0 + +package pathrouter + +import ( + "errors" + "fmt" + "maps" + "net/http" + "slices" + "strings" + "unicode" + + . "go.xyrillian.de/gg/option" +) + +// Build offers a Sinatra-style interface for building [Matcher] interfaces. +// The routing table can be defined inside the supplied build function, using the methods on type [Builder]. +func Build(build func(Builder)) Matcher { + b := builder{Node: choiceNode{}} + build(&b) + if true { + panic("TODO: how would middlewares be encoded (see TODO in matcher.go)?") + } + return b.Node.Into(b.Predicates) +} + +// Builder is used inside [Build] calls to construct a routing table. +// +// The following rules apply to AddRoute calls: +// +// - Matching the semantics of [Handlers], a handler for [http.MethodGet] will also match [http.MethodHead] +// unless a handler for [http.MethodHead] is installed for the same path template. +// Said handler can be set to nil to explicitly forbid HEAD requests. +// - The path template must consist of a number of path elements separated by slashes, with a leading slash (e.g. "/v1/objects/:id"). +// Path elements must consist of alphanumeric ASCII characters, and otherwise use symbols only as detailed below. +// [Element], [Variable] and [CatchAllVariable] matchers using non-alphanumeric or non-ASCII characters cannot be represented +// and must use the tree-shaped constructor API instead. +// +// AddRoute accepts the following syntaxes for path elements: +// +// - Path elements without symbols will be translated into [Element] matchers with the path element as the value. +// - Path elements of the form ":name" will be translated into [Variable] matchers using the specified name. +// - Path elements of the form "*name" will be translated into [CatchAllVariable] matchers using the specified name. +// - Variable matchers can have a suffix of the form "?predicate" to restrict matches to values matching the predicate (as registered with AddPredicate). +// Those path elements will be translated into [VariableIf] and [CatchAllVariableIf] matchers. +// - Path templates that have a trailing slash or no trailing slash will match this property of the actual request path exactly. +// To match requests with trailing slash or no trailing slash using the same path template, write the trailing slash in parentheses, as "(/)". +// +// For example, a path template of "/objects/*path?isValidPath/comments/:id(/)" is equivalent to +// +// Element("objects", CatchAllVariableIf("path", isValidPath, +// Element("comments", Variable("id", +// Here(Handlers(...)), +// )), +// )) +type Builder interface { + // AddRoute adds an endpoint handler to the routing table. + // Refer to the type docstring for details. + AddRoute(method, pathTemplate string, handler http.HandlerFunc) + // AddPredicate registers a predicate that can be referenced in path templates of AddRoute(). + AddPredicate(name string, predicate func(string) bool) +} + +type builder struct { + Predicates map[string]func(string) bool + Node builderNode +} + +// AddRoute implements the [Builder] interface. +func (b *builder) AddRoute(method, pathTemplate string, handler http.HandlerFunc) { + // compile arguments into a sequence of path nodes leading to a handler node + node, err := b.buildRoute(method, pathTemplate, handler) + if err != nil { + panic(fmt.Sprintf("could not add route %q: %s", method+" "+pathTemplate, err.Error())) + } + + // merge new route into the existing routing table, spawning choice nodes as needed + b.Node = b.Node.TryMerge(node).UnwrapOrPanic("choiceNode.TryMerge() should never fail") +} + +func (b *builder) buildRoute(method, pathTemplate string, handler http.HandlerFunc) (node builderNode, err error) { + if handler == nil && method != http.MethodHead { + return nil, errors.New("handler must not be nil") + } + + // consume leading slash + var ok bool + pathTemplate, ok = strings.CutPrefix(pathTemplate, "/") + if !ok { + return nil, errors.New("path template does not have a leading slash") + } + + // consume required trailing slash + hn := handlerNode{ + Handlers: map[string]http.HandlerFunc{method: handler}, + } + pathTemplate, ok = strings.CutSuffix(pathTemplate, "(/)") + if ok { + hn.Attributes.IsHere = true + } + + // consume optional trailing slash if there was no required trailing slash + node = hn + if !ok { + pathTemplate, ok = strings.CutSuffix(pathTemplate, "/") + if ok { + node = pathNode{ + Inner: node, + Attributes: pathNodeAttributes{Element: "/"}, + } + } + } + + // now only the bare path remains in pathTemplate, e.g. `/v1/foo/bar(/)` -> `v1/foo/bar` + for _, elem := range slices.Backward(strings.Split(pathTemplate, "/")) { + node, err = b.buildPathNode(elem, node) + if err != nil { + return nil, fmt.Errorf("invalid path element %q in path %q: %w", elem, pathTemplate, err) + } + } + return node, nil +} + +func (b *builder) buildPathNode(template string, inner builderNode) (_ builderNode, err error) { + // try to parse a variable declaration + var ( + isVariable = false + isCatchAll = false + ok bool + ) + if template, ok = strings.CutPrefix(template, ":"); ok { + isVariable = true + } else if template, ok = strings.CutPrefix(template, ":"); ok { + isVariable = true + isCatchAll = true + } + if isVariable { + var ( + attrs = pathNodeAttributes{IsCatchAll: isCatchAll} + hasPredicate bool + ) + attrs.VariableName, attrs.PredicateName, hasPredicate = strings.Cut(template, "?") + if !isASCIIAlphanumeric(attrs.VariableName) { + return nil, fmt.Errorf("variable name %q contains invalid characters", attrs.VariableName) + } + if hasPredicate { + if attrs.PredicateName == "" { + return nil, errors.New("predicate name may not be empty") + } + if !isASCIIAlphanumeric(attrs.PredicateName) { + return nil, fmt.Errorf("predicate name %q contains invalid characters", attrs.PredicateName) + } + if _, ok := b.Predicates[attrs.PredicateName]; !ok { + return nil, fmt.Errorf("predicate %q is not defined", attrs.PredicateName) + } + } + return pathNode{inner, attrs}, nil + } + + // try to parse an element declaration + if !isASCIIAlphanumeric(template) { + return nil, fmt.Errorf("element %q contains invalid characters", template) + } + attrs := pathNodeAttributes{Element: template} + return pathNode{inner, attrs}, nil +} + +func isASCIIAlphanumeric(in string) bool { + for _, r := range in { + if r > unicode.MaxASCII { + return false + } + if !unicode.IsLetter(r) && !unicode.IsDigit(r) { + return false + } + } + return true +} + +// AddPredicate implements the [Builder] interface. +func (b *builder) AddPredicate(name string, predicate func(string) bool) { + _, ok := b.Predicates[name] + if ok { + panic(fmt.Sprintf("AddPredicate() called multiple times for name = %q", name)) + } + b.Predicates[name] = predicate +} + +// builderNode is an intermediate representation for the routing table that is being assembled by type builder. +type builderNode interface { + // Merge the given node into this one if the head nodes are compatible, + // returning the merged node on success or None on structural mismatch. + TryMerge(route builderNode) Option[builderNode] + // Convert this node into a real Matcher. + Into(predicates map[string]func(string) bool) Matcher +} + +type choiceNode []builderNode + +// TryMerge implements the [node] interface. +func (n choiceNode) TryMerge(other builderNode) Option[builderNode] { + for idx, node := range n { + if merged, ok := node.TryMerge(other).Unpack(); ok { + n[idx] = merged + return Some[builderNode](n) + } + } + return Some[builderNode](append(n, other)) +} + +// Into implements the [node] interface. +func (n choiceNode) Into(predicates map[string]func(string) bool) Matcher { + if len(n) == 1 { + return n[0].Into(predicates) + } + + matchers := make([]Matcher, len(n)) + for idx, node := range n { + matchers[idx] = node.Into(predicates) + } + return Choice(matchers...) +} + +type pathNode struct { + Inner builderNode + Attributes pathNodeAttributes +} + +type pathNodeAttributes struct { + // Element() + Element string + // Variable(), CatchAllVariable(), ...If() + VariableName string + IsCatchAll bool + PredicateName string +} + +// TryMerge implements the [node] interface. +func (n pathNode) TryMerge(other builderNode) Option[builderNode] { + rhs, ok := other.(pathNode) + if !ok || n.Attributes != rhs.Attributes { + return None[builderNode]() + } + + // if both sides have identical path nodes, we will always force a merge, + // possibly by spawning a choice node inside + merged, ok := n.Inner.TryMerge(rhs.Inner).Unpack() + if !ok { + merged = choiceNode{n.Inner, rhs.Inner} + } + return Some[builderNode](pathNode{merged, n.Attributes}) +} + +// Into implements the [node] interface. +func (n pathNode) Into(predicates map[string]func(string) bool) Matcher { + var ( + inner = n.Inner.Into(predicates) + attrs = n.Attributes + ) + switch { + case attrs.Element != "": + return Element(attrs.Element, inner) + case attrs.IsCatchAll: + return CatchAllVariableIf(attrs.VariableName, predicates[attrs.PredicateName], inner) + default: + return VariableIf(attrs.VariableName, predicates[attrs.PredicateName], inner) + } +} + +type handlerNode struct { + Handlers map[string]http.HandlerFunc + Attributes handlerNodeAttributes +} + +type handlerNodeAttributes struct { + IsHere bool +} + +// TryMerge implements the [node] interface. +func (n handlerNode) TryMerge(other builderNode) Option[builderNode] { + if rhs, ok := other.(handlerNode); ok && n.Attributes == rhs.Attributes { + maps.Copy(n.Handlers, rhs.Handlers) + return Some[builderNode](n) + } else { + return None[builderNode]() + } +} + +// Into implements the [node] interface. +func (n handlerNode) Into(predicates map[string]func(string) bool) Matcher { + result := Handlers(n.Handlers) + if n.Attributes.IsHere { + result = Here(result) + } + return result +} |
