From 9a0c9a69a7796b9ae77665dfbb151b3c6fdf31f1 Mon Sep 17 00:00:00 2001 From: Stefan Majewsky Date: Sun, 18 Oct 2026 20:13:21 +0200 Subject: tmp: add Sinatra-style API for package pathrouter 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. --- pathrouter/builder.go | 298 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) create mode 100644 pathrouter/builder.go 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 +// 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 +} -- cgit v1.3.1