https://github.com/jnichols-git/matcha
Matcha is an efficient, fully-featured HTTP request router.
https://github.com/jnichols-git/matcha
golang golang-library golang-package http router routing
Last synced: 17 days ago
JSON representation
Matcha is an efficient, fully-featured HTTP request router.
- Host: GitHub
- URL: https://github.com/jnichols-git/matcha
- Owner: jnichols-git
- License: apache-2.0
- Created: 2023-02-06T01:45:24.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-12-24T22:08:30.000Z (over 2 years ago)
- Last Synced: 2026-01-15T07:04:14.722Z (2 months ago)
- Topics: golang, golang-library, golang-package, http, router, routing
- Language: Go
- Homepage:
- Size: 385 KB
- Stars: 10
- Watchers: 1
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# matcha
[](https://coveralls.io/github/decentplatforms/matcha?branch=main)
[](https://goreportcard.com/report/github.com/decentplatforms/matcha)
[](https://discord.gg/gCdJ6NPm)
Matcha is an HTTP router designed for ease of use, power, and extensibility.
## Features
- Flexible routing--handle your API specifications with ease
- Extensible components for edge cases and integration with 3rd-party tools
- High performance that scales to larger APIs
- Comprehensive and passing test coverage, and extensive benchmarks to track performance on key features
- Easy conversion from standard library; uses stdlib handler signatures and types
- Zero dependencies, zero dependency management
## Installation
`go get github.com/decentplatforms/matcha@v1.2.2`
## Basic Usage
Here's a "Hello, World" example to introduce you to Matcha's syntax! It serves requests to `http://localhost:8080/hello`.
```go
package examples
import (
"net/http"
"github.com/decentplatforms/matcha/pkg/router"
)
func sayHello(w http.ResponseWriter, req *http.Request) {
w.Write([]byte("Hello, World!"))
}
func HelloExample() {
rt := router.Default()
rt.HandleFunc(http.MethodGet, "/hello", sayHello)
// or:
// rt.Handle(http.MethodGet, "/hello", http.HandlerFunc(sayHello))
http.ListenAndServe(":3000", rt)
}
```
For a step-by-step guide through Matcha's features, see our [User Guide](docs/user-guide.md).
## Performance
Matcha has an extensive benchmark suite to help identify, document, and improve performance over time. Additionally, `/bench` contains a comprehensive benchmark API for "MockBoards", a fake website that just so happens to use all of the features of Matcha. The MockBoards API has the following:
- 18 distinct endpoints, including
- 4 endpoints requiring authorization using a "client_id" header
- 4 endpoints with an enumeration URI parameter (new/top posts, etc)
- 2 middleware components assigning a request ID and CORS headers
- 1 requirement for target host on all endpoints
The MockBoards benchmarks are run alongside an *offset benchmark* that measures the performance cost of setting up scaffolding
for each request sent to calculate their final score. The values below represent performance numbers that you might expect
to see in practice. Please keep in mind that performance varies by machine--you should run benchmarks on your own
hardware to get a proper idea of how well Matcha's performance suits your needs.
### MockBoards API Spec Benchmark
Benchmark | ns/request | B/request | allocs/request
--- | --- | --- | ---
Sequential | 2226 ns/request | 1909 bytes/request | 27 allocs/request
Concurrent | 1953 ns/request | 1943 bytes/request | 29 allocs/request
### MockBoards Mounted API (v2) Benchmark
This mounts a copy of the API at `/v2` and runs requests against both the v1 and v2 APIs.
Benchmark | ns/request | B/request | allocs/request
--- | --- | --- | ---
Sequential | 2797 ns/request | 2046 bytes/request | 29 allocs/request
Concurrent | 2097 ns/request | 2139 bytes/request | 30 allocs/request
### MockBoards API Routing-Only Benchmark
This is the v1 spec, but with the non-path features stripped out to give a better idea of pure routing costs.
Benchmark | ns/request | B/request | allocs/request
--- | --- | --- | ---
Sequential | 1054 ns/request | 1417 bytes/request | 12 allocs/request
Concurrent | 1353 ns/request | 1453 bytes/request | 14 allocs/request
## Maintainers
Name | Role | Pronouns | GitHub Username | Contact
---|---|---|---|---
Jake Nichols | Creator | they/them | jakenichols2719 |
## License
Copyright 2023 Decent Platforms LLC
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.