1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
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
}
|