112 lines
3.6 KiB
Markdown
112 lines
3.6 KiB
Markdown
<p align="center">
|
|
<a href="https://code.zeptotech.net/zedd/zouter">
|
|
<picture>
|
|
<img alt="Zouter logo" width="150" src="https://code.zeptotech.net/zedd/zouter/raw/branch/main/logo.svg" />
|
|
</picture>
|
|
</a>
|
|
</p>
|
|
|
|
<h1 align="center">
|
|
Zouter
|
|
</h1>
|
|
|
|
<h4 align="center">
|
|
<a href="https://code.zeptotech.net/zedd/zouter">Documentation</a>
|
|
|
|
|
<a href="https://zedd.zeptotech.net/zouter/api">API</a>
|
|
</h4>
|
|
|
|
<p align="center">
|
|
Zig HTTP router library
|
|
</p>
|
|
|
|
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.1.2 is made for zig 0.13.0 and tested with zap 0.9.1.
|
|
|
|
## How to use
|
|
|
|
### Install
|
|
|
|
In your project directory:
|
|
|
|
```shell
|
|
$ zig fetch --save https://code.zeptotech.net/zedd/zouter/archive/v0.1.2.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).
|