https://github.com/zigzedd/zouter
[MIRROR] Zig HTTP router library.
https://github.com/zigzedd/zouter
router routing routing-engine zap zig zig-library zig-package
Last synced: 4 months ago
JSON representation
[MIRROR] Zig HTTP router library.
- Host: GitHub
- URL: https://github.com/zigzedd/zouter
- Owner: zigzedd
- License: mit
- Created: 2024-10-10T22:11:55.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-11T22:15:37.000Z (9 months ago)
- Last Synced: 2025-04-11T22:35:20.251Z (9 months ago)
- Topics: router, routing, routing-engine, zap, zig, zig-library, zig-package
- Language: Zig
- Homepage: https://code.zeptotech.net/zedd/zouter
- Size: 22.5 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Zouter
Documentation
|
API
Zig HTTP router library
Zouter is part of [_zedd_](https://code.zeptotech.net/zedd), a collection of useful libraries for zig.
## Zouter for zap
_Zouter_ is an HTTP router library for Zig **zap** HTTP server. It's made to ease the use of **zap** to build REST APIs.
## Versions
Zouter 0.2.0 is made for zig 0.14.0 and tested with zap 0.10.1.
## How to use
### Install
In your project directory:
```shell
$ zig fetch --save https://code.zeptotech.net/zedd/zouter/archive/v0.2.0.tar.gz
```
In `build.zig`:
```zig
// Add zouter dependency.
const zouter = b.dependency("zouter", .{
.target = target,
.optimize = optimize,
});
exe.root_module.addImport("zouter", zouter.module("zouter"));
```
### Example
Here is a quick example of how to set up a router. It is an extract from the full test code at [`example.zig`](https://code.zeptotech.net/zedd/zouter/src/branch/main/tests/example.zig). You may want to have a look to [`simple_routes.zig`](https://code.zeptotech.net/zedd/zouter/src/branch/main/tests/simple_routes.zig) which shows more advanced features.
```zig
/// GET /foo/:arg/bar request handler.
fn get(route: zouter.MatchedRoute, request: zap.Request) !void {
var bodyBuffer: [512]u8 = undefined;
const body = try std.fmt.bufPrint(&bodyBuffer, "get: {s}", .{route.params.get("arg").?});
try request.sendBody(body);
}
/// POST /foo/:arg/bar request handler.
fn post(route: zouter.MatchedRoute, request: zap.Request) !void {
var bodyBuffer: [512]u8 = undefined;
const body = try std.fmt.bufPrint(&bodyBuffer, "post: {s}", .{route.params.get("arg").?});
try request.sendBody(body);
}
/// Setup an example router.
fn setupExampleRouter(allocator: std.mem.Allocator) !zouter.Router {
// Initialize an example router.
var exampleRouter = try zouter.Router.init(allocator, .{});
// Add a route to the example router.
try exampleRouter.route(.{
.path = "foo",
.children = &[_]zouter.RouteDefinition{
.{
.path = ":arg",
.children = &[_]zouter.RouteDefinition{
.{
.path = "bar",
.handle = .{
.get = &get,
.post = &post,
},
}
},
}
},
});
return exampleRouter;
}
```
### Route definition
A route only has one mandatory field: its path. If any part of a path starts with a `':'`, the value is taken as a dynamic variable, retrievable later with `Route.params` `HashMap`.
A route can have:
- **Children**: sub-routes definitions, with a `'/'` between the parent and the child. It's useful to prefix a list of routes with the same path / variable.
- **Handle object**: you can define a handle function for each HTTP basic request method. If you don't care about the request method, there is an `any` field which will be used for all undefined request methods.
- **Handle not found / error**: you can define a custom functions to handle errors or not found pages inside this path.
- **Pre-handle / post-handle**: these functions are started before and after the request handling in this path. It looks like middlewares and can assume the same role as most of them (e.g. a pre-handle function to check for authentication under a specific path).
Full details about route definition fields can be found in the [API reference](https://zedd.zeptotech.net/zouter/api).