tokamak

# Tokamak

📚 **[Documentation](https://tomsik.cz/tokamak)**

Tokamak is a web application framework for Zig, built around
[http.zig](https://github.com/karlseguin/http.zig) and a simple dependency
injection container.

> **Note:** The main branch requires **Zig 0.17.1** or newer.

Note that it is **not designed to be used alone**, but with a reverse proxy in
front of it, like Nginx or Cloudfront, which will handle SSL, caching,
sanitization, etc.

> ### Recent changes
> - renamed few `bundle.addXxx()` methods to `bundle.provide()`,
>   `bundle.override()`, ...
> - renamed `inj.call0(fun)` → `inj.call(fun)`, `inj.call(fun, ...args)` →
>   `inj.callArgs(fun, ...args)`
> - opt dependencies were removed, ie. you can no longer inject `?Cfg` - it was
>   undocumented, incomplete, subtly broken, and not worth the extra complexity
> - multi-mod API has changed
>   [considerably](https://github.com/cztomsik/tokamak/pull/25)
> - new [cli module](https://github.com/cztomsik/tokamak/tree/master/src/cli.zig)
> - injecting `tk.Injector` is deprecated, use `*tk.Injector`
> - multi-module support (cross-module initializers, providers, overrides)
> - Switched to [http.zig](https://github.com/karlseguin/http.zig) for improved
>   performance over `std.http`.
> - Implemented hierarchical and introspectable routes.
> - Added basic Swagger support.
> - Added `tk.static.dir()` for serving entire directories.

## Installation

```bash
zig fetch --save "git+https://github.com/cztomsik/tokamak#main"
```

Then in your `build.zig`:

```zig
const tokamak = @import("tokamak");

pub fn build(b: *std.Build) void {
    ...
    const exe = b.addExecutable(.{ ... });
    ...

    // Add tokamak
    tokamak.setup(exe, .{});
}
```

## Getting Started

Simple things should be easy to do.

```zig
const std = @import("std");
const tk = @import("tokamak");

const routes: []const tk.Route = &.{
    .get("/", hello),
};

fn hello() ![]const u8 {
    return "Hello";
}

pub fn main(init: std.process.Init) !void {
    var server = try tk.Server.init(init.io, init.gpa, routes, .{ .listen = .{ .port = 8080 } });
    defer server.deinit();

    try server.start();
}
```

## Dependency Injection

The framework is built around the concept of dependency injection.
This means that your handler function can take any number of parameters, and the
framework will try to provide them for you.

Notable types you can inject are:

- `std.mem.Allocator` (request-scoped arena allocator)
- `*tk.Request` (current request, including headers, body reader, etc.)
- `*tk.Response` (current response, with methods to send data, set headers, etc.)
- `*tk.Injector` (the injector itself, see below)
- and everything you provide yourself

For example, you can easily write a handler function which will create a
string on the fly and return it to the client without any tight coupling to the
server or the request/response types.

```zig
fn hello(arena: std.mem.Allocator) ![]const u8 {
    return std.fmt.allocPrint(arena, "H