router

README

Router

A radix-tree based no-allocation router in Go. All credit to Eduard Urbach for his incredible work. This router sports a fancy PATRICIA tree structure for efficient string lookups. It also has zero dependencies!

The router has a generic data structure, so any kind of handler can be used.

Installation

go get git.sharkk.net/Go/Router

Usage

router := router.New[string]()

// Static routes
router.Add("GET", "/hello", "...")
router.Add("GET", "/world", "...")

// Parameter routes
router.Add("GET", "/users/:id", "...")
router.Add("GET", "/users/:id/comments", "...")

// Wildcard routes
router.Add("GET", "/images/*path", "...")

// Simple lookup
data, params := router.Lookup("GET", "/users/42")
fmt.Println(data, params)

// Efficient lookup
data := router.LookupNoAlloc("GET", "/users/42", func(key string, value string) {
	fmt.Println(key, value)
})

Benchmarks

cpu: AMD Ryzen 9 7950X 16-Core Processor

BenchmarkBlog/Len1-Params0-32         	    268391120	      4.461 ns/op	       0 B/op	       0 allocs/op
BenchmarkBlog/Len1-Params0-NoAlloc-32 	    383737024	      3.123 ns/op	       0 B/op	       0 allocs/op
BenchmarkBlog/Len1-Param1-32          	    23690427	      47.85 ns/op	      32 B/op	       1 allocs/op
BenchmarkBlog/Len1-Param1-NoAlloc-32  	    248275540	      4.913 ns/op	       0 B/op	       0 allocs/op

BenchmarkGithub/Len7-Params0-32         	148926122	      8.043 ns/op	       0 B/op	       0 allocs/op
BenchmarkGithub/Len7-Params0-NoAlloc-32 	168011829	      7.153 ns/op	       0 B/op	       0 allocs/op
BenchmarkGithub/Len7-Params1-32         	22188592	      47.25 ns/op	      32 B/op	       1 allocs/op
BenchmarkGithub/Len7-Params1-NoAlloc-32 	100000000	      11.29 ns/op	       0 B/op	       0 allocs/op
BenchmarkGithub/Len7-Params3-32         	10181496	      111.3 ns/op	      96 B/op	       2 allocs/op
BenchmarkGithub/Len7-Params3-NoAlloc-32 	46369563	      25.54 ns/op	       0 B/op	       0 allocs/op

License

Licensed under MIT. Take a look!

Credit

All of the code here is built by Eduard Urbach.

Documentation

Index

• type Flow
• type Parameter
• type Router
  • func New[T any]() *Router[T]
  • func (router *Router[T]) Add(method string, path string, handler T)
  • func (router *Router[T]) Lookup(method string, path string) (T, []Parameter)
  • func (router *Router[T]) LookupNoAlloc(method string, path string, addParameter func(string, string)) T
  • func (router *Router[T]) Map(transform func(T) T)
• type Tree
  • func (tree *Tree[T]) Add(path string, data T)
  • func (tree *Tree[T]) Lookup(path string) (T, []Parameter)
  • func (tree *Tree[T]) LookupNoAlloc(path string, addParameter func(key string, value string)) T
  • func (tree *Tree[T]) Map(transform func(T) T)
• type TreeNode

Types

type Flow

type Flow int

type Parameter

type Parameter struct {
	Key   string
	Value string
}

type Router

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

func New

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

Create a new Router containing trees for every HTTP method.

func (*Router[T]) Add

func (router *Router[T]) Add(method string, path string, handler T)

Registers a new handler for the given method and path.

func (*Router[T]) Lookup

func (router *Router[T]) Lookup(method string, path string) (T, []Parameter)

Finds the handler and parameters for the given route.

func (*Router[T]) LookupNoAlloc

func (router *Router[T]) LookupNoAlloc(method string, path string, addParameter func(string, string)) T

Finds the handler and parameters for the given route without using any memory allocations.

func (*Router[T]) Map

func (router *Router[T]) Map(transform func(T) T)

Traverses all trees and calls the given function on every node.

type Tree

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

Super-fancy radix tree

func (*Tree[T]) Add

func (tree *Tree[T]) Add(path string, data T)

Adds a new element to the tree

func (*Tree[T]) Lookup

func (tree *Tree[T]) Lookup(path string) (T, []Parameter)

Lookup finds the data for the given path.

func (*Tree[T]) LookupNoAlloc

func (tree *Tree[T]) LookupNoAlloc(path string, addParameter func(key string, value string)) T

Finds the data for the given path without using any memory allocations.

func (*Tree[T]) Map

func (tree *Tree[T]) Map(transform func(T) T)

Binds all handlers to a new one provided by the callback.

type TreeNode

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

A node on our radix tree