{"id":47944565,"url":"https://github.com/catatsuy/saruta","last_synced_at":"2026-04-04T08:22:13.573Z","repository":{"id":339901929,"uuid":"1163764668","full_name":"catatsuy/saruta","owner":"catatsuy","description":"Small radix-tree HTTP router for net/http with Go 1.22+ PathValue() params.","archived":false,"fork":false,"pushed_at":"2026-02-23T10:07:31.000Z","size":38,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T15:58:31.844Z","etag":null,"topics":["go","http","radix-tree","router"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/catatsuy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-22T05:22:38.000Z","updated_at":"2026-02-23T07:54:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/catatsuy/saruta","commit_stats":null,"previous_names":["catatsuy/saruta"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/catatsuy/saruta","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catatsuy%2Fsaruta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catatsuy%2Fsaruta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catatsuy%2Fsaruta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catatsuy%2Fsaruta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catatsuy","download_url":"https://codeload.github.com/catatsuy/saruta/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catatsuy%2Fsaruta/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31392853,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","http","radix-tree","router"],"created_at":"2026-04-04T08:22:10.622Z","updated_at":"2026-04-04T08:22:13.510Z","avatar_url":"https://github.com/catatsuy.png","language":"Go","readme":"# saruta\n\n`saruta` is a small radix-tree-based HTTP router for `net/http` with Go 1.22+ `PathValue()` support.\n\nIt is named after Sarutahiko, a guide deity in Japanese mythology associated with roads and directions.\n\n## Features\n\n- `net/http` compatible (`http.Handler`)\n- Path params via `req.PathValue(...)`\n- Static / param / catch-all routing (runtime radix tree)\n- Middleware: `func(http.Handler) http.Handler`\n- 404 / 405 (`Allow` header)\n- `Mount` for static prefixes (MVP: no path strip)\n\n## Install\n\n```bash\ngo get github.com/catatsuy/saruta\n```\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n\t\"log\"\n\t\"net/http\"\n\n\t\"github.com/catatsuy/saruta\"\n)\n\nfunc main() {\n\tr := saruta.New()\n\n\tr.Use(func(next http.Handler) http.Handler {\n\t\treturn http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {\n\t\t\tlog.Printf(\"%s %s\", req.Method, req.URL.Path)\n\t\t\tnext.ServeHTTP(w, req)\n\t\t})\n\t})\n\n\tr.Get(\"/health\", func(w http.ResponseWriter, req *http.Request) {\n\t\tw.Write([]byte(\"ok\"))\n\t})\n\n\tr.Get(\"/users/{id}\", func(w http.ResponseWriter, req *http.Request) {\n\t\tw.Write([]byte(\"user=\" + req.PathValue(\"id\")))\n\t})\n\n\tr.Get(\"/api/{name:[0-9]+}.json\", func(w http.ResponseWriter, req *http.Request) {\n\t\tw.Write([]byte(\"name=\" + req.PathValue(\"name\")))\n\t})\n\n\tr.Get(\"/image/{id:[a-z0-9]+}.{ext:[a-z]+}\", func(w http.ResponseWriter, req *http.Request) {\n\t\tw.Write([]byte(req.PathValue(\"id\") + \".\" + req.PathValue(\"ext\")))\n\t})\n\n\tr.Get(\"/files/{path...}\", func(w http.ResponseWriter, req *http.Request) {\n\t\tw.Write([]byte(\"file=\" + req.PathValue(\"path\")))\n\t})\n\n\tif err := r.Compile(); err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tlog.Fatal(http.ListenAndServe(\":8080\", r))\n}\n```\n\n## More Examples\n\n### Grouped middleware\n\n```go\nr := saruta.New()\n\nloggingMiddleware := func(next http.Handler) http.Handler {\n\treturn http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {\n\t\tlog.Printf(\"%s %s\", req.Method, req.URL.Path)\n\t\tnext.ServeHTTP(w, req)\n\t})\n}\n\nauthMiddleware := func(next http.Handler) http.Handler {\n\treturn http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {\n\t\tif req.Header.Get(\"Authorization\") == \"\" {\n\t\t\thttp.Error(w, \"unauthorized\", http.StatusUnauthorized)\n\t\t\treturn\n\t\t}\n\t\tnext.ServeHTTP(w, req)\n\t})\n}\n\nr.Use(loggingMiddleware)\n\nr.Group(func(api *saruta.Router) {\n\tapi.Use(authMiddleware)\n\n\tapi.Get(\"/me\", func(w http.ResponseWriter, req *http.Request) {\n\t\tw.Write([]byte(\"ok\"))\n\t})\n})\n\nr.MustCompile()\n```\n\n### Mount another handler\n\n```go\nfiles := http.FileServer(http.Dir(\"./public\"))\nr.Mount(\"/static\", files)\nr.MustCompile()\n```\n\n`Mount` matches a static prefix and forwards the original path (no stripping).\n\n### Custom 404 / 405 handlers\n\n```go\nr.NotFound(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {\n\thttp.Error(w, \"custom not found\", http.StatusNotFound)\n}))\n\nr.MethodNotAllowed(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {\n\thttp.Error(w, \"custom method not allowed\", http.StatusMethodNotAllowed)\n}))\n```\n\n### Startup panic mode\n\n```go\nr := saruta.New(saruta.WithPanicOnCompileError())\nr.Get(\"/users/{id}\", usersShow)\nr.Get(\"/users/{name}\", usersShow) // conflict\n\n// Panics instead of returning an error.\nr.Compile()\n```\n\nIf you prefer explicit error handling:\n\n```go\nif err := r.Compile(); err != nil {\n\tlog.Fatal(err)\n}\n```\n\n### Graceful shutdown\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"net/http\"\n\t\"os/signal\"\n\t\"syscall\"\n\t\"time\"\n\n\t\"github.com/catatsuy/saruta\"\n)\n\nfunc main() {\n\tr := saruta.New()\n\tr.Get(\"/health\", func(w http.ResponseWriter, req *http.Request) {\n\t\tw.Write([]byte(\"ok\"))\n\t})\n\tr.MustCompile()\n\n\tsrv := \u0026http.Server{\n\t\tAddr:    \":8080\",\n\t\tHandler: r,\n\t}\n\n\tctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)\n\tdefer stop()\n\n\tgo func() {\n\t\t\u003c-ctx.Done()\n\n\t\tshutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\t\tdefer cancel()\n\n\t\tif err := srv.Shutdown(shutdownCtx); err != nil {\n\t\t\tlog.Printf(\"shutdown error: %v\", err)\n\t\t}\n\t}()\n\n\tif err := srv.ListenAndServe(); err != nil \u0026\u0026 err != http.ErrServerClosed {\n\t\tlog.Fatal(err)\n\t}\n}\n```\n\n## Routing Rules (MVP)\n\n- Pattern must start with `/`\n- Trailing slash is significant (`/users` and `/users/` are different)\n- Params: `/{id}`\n- Constrained params (lightweight matcher, no `regexp`): `/{id:[0-9]+}`\n- Prefix/suffix constrained params: `/api/{name:[0-9]+}.json`\n- Multiple params in one segment: `/image/{id:[a-z0-9]+}.{ext:[a-z]+}`\n- Catch-all (last segment only): `/{path...}`\n- Priority: static \u003e param \u003e catch-all\n- No automatic path normalization or redirects\n\n## Registration API\n\n- Registration API: `Handle`, `Get`, `Post`, ...\n- Finalization API: `Compile() error`, `MustCompile()`\n- Optional panic mode for `Compile()`: `New(saruta.WithPanicOnCompileError())`\n\nRoutes are validated and compiled when `Compile()` runs.\nInvalid patterns/conflicts return an error from `Compile()` (or panic with `MustCompile()` / `WithPanicOnCompileError()`).\n\n### Supported Constraint Expressions (current)\n\n- `[0-9]+`, `[0-9]*`\n- `[a-z0-9-]+`\n- `\\d+`, `\\d*`\n\nThis is intentionally not full regular expression support for performance reasons.\n\n## Middleware\n\n- Type: `func(http.Handler) http.Handler`\n- `Use(A, B, C)` executes as `A -\u003e B -\u003e C -\u003e handler`\n- `With(...)` creates a derived router sharing the same routing tree\n- `Group(fn)` is a scoped `With(...)`\n\nMatched path params are set before middleware execution, so middleware can call `req.PathValue(...)`.\n\n## Thread Safety\n\n- Concurrent `ServeHTTP` after route registration is safe\n- Concurrent route registration and request handling is undefined\n- Register routes, then call `Compile()`, then start the server\n\n## Benchmark\n\nRun:\n\n```bash\ngo test -bench . -benchmem\n```\n\nFor cross-router comparisons, use the benchmark harness in `bench/`:\n\n```bash\ncd bench\ngo test -run '^$' -bench . -benchmem -tags 'chi httprouter'\n```\n\n### Benchmark Snapshot (2026-02-22, Apple M1)\n\nCommand:\n\n```bash\ncd bench\ngo test -run '^$' -bench . -benchmem -tags 'chi httprouter'\n```\n\nSelected results:\n\n| Benchmark | chi | httprouter | saruta | servemux |\n| --- | ---: | ---: | ---: | ---: |\n| Static lookup (ns/op) | 374.1 | 17.66 | 60.64 | 65.91 |\n| Static lookup (allocs/op) | 2 | 0 | 0 | 0 |\n| Param lookup (ns/op) | 259.7 | 39.22 | 87.74 | 133.8 |\n| Param lookup (allocs/op) | 4 | 1 | 0 | 1 |\n| Deep lookup (ns/op) | 190.7 | 18.03 | 62.91 | 229.2 |\n| Deep lookup (allocs/op) | 2 | 0 | 0 | 0 |\n| Scale 100 routes (ns/op) | 168.5 | 37.94 | 62.84 | 105.8 |\n| Scale 1,000 routes (ns/op) | 202.5 | 35.44 | 77.83 | 105.7 |\n| Scale 10,000 routes (ns/op) | 260.2 | 45.17 | 76.96 | 96.39 |\n\nNotes:\n\n- `saruta` now reaches `0 allocs/op` in the benchmarked lookup paths (static/param/deep/scale).\n- `saruta` uses a runtime radix tree and remains `0 allocs/op` in the benchmarked lookup paths.\n- In this benchmark run, `saruta` outperforms `ServeMux` across the listed static/param/deep/scale cases.\n- `httprouter` is still faster in these microbenchmarks, especially on static/deep lookups.\n- `httprouter` is significantly faster in these cases, but uses a different API/model.\n- Benchmark numbers depend on CPU, Go version, and benchmark flags. Re-run on your target machine for production decisions.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatatsuy%2Fsaruta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatatsuy%2Fsaruta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatatsuy%2Fsaruta/lists"}