http.zig (httpz)

httpz uses epoll (Linux) or kqueue (macOS/BSD) for non-blocking I/O. On other platforms (like Windows), it uses a blocking mode (thread-per-connection).

You can check the current mode using httpz.blockingMode().

Key differences in Blocking Mode:

• Worker Count: config.workers.count is hard-coded to 1. Any additional workers configured are added to the thread_pool.count instead.
• Connection Limits: config.workers.max_conn and config.workers.min_conn are ignored. The maximum number of connections is limited by the size of the thread_pool.
• Buffer Pooling: config.workers.large_buffer_count defaults to the size of the thread pool.
• Security: Blocking mode is more susceptible to DOS attacks. It is highly recommended to run httpz behind a reverse proxy (like NGINX) when in blocking mode.

Parameters

Use :CAPTURE_NAME in the path. Access them via req.params.get("name").

Globs

You can use * to match a single segment or /* to match a suffix. When multiple globs exist, the most specific route is selected.

Note: Routes must be lowercase. Parameter names can use any casing, but you must use the exact same casing when retrieving them.

Instead of using void as the generic type for httpz.Server, you can pass a custom struct (a "Handler") to init. This struct instance is then passed as the first argument to every action/route handler, allowing you to share resources like database connection pools across all requests.

const App = struct {
    db: *pg.Pool,
};

// The first argument is now *App instead of *httpz.Request
fn getUser(app: *App, req: *httpz.Request, res: *httpz.Response) !void {
  const user_id = req.param("id").?;
  // use app.db ...
}

// Initialization
var app = App{ .db = db };
var server = try httpz.Server(*App).init(init.io, allocator, .{.address = .localhost(5882)}, &app);
var router = try server.router(.{});
router.get("/api/user/:id", getUser, .{});

To start a basic server, initialize httpz.Server(void) and use a router to define routes. The server blocks on server.listen().

const std = @import("std");
const httpz = @import("httpz");

pub fn main(init: std.process.Init) !void {
  const allocator = init.gpa;

  var server = try httpz.Server(void).init(init.io, allocator, .{{
    .address = .localhost(5882),
  }}, {});
  defer {
    server.stop();
    server.deinit();
  }

  var router = try server.router(.{});
  router.get("/api/user/:id", getUser, .{});

  try server.listen();
}

fn getUser(req: *httpz.Request, res: *httpz.Response) !void {
  res.status = 200;
  try res.json(.{.id = req.param("id").?, .name = "Teg"}, .{});
}

To use httpz in your Zig project, follow these two steps:

1. Add the dependency to your build.zig.zon using zig fetch:

   zig fetch --save "git+https://github.com/karlseguin/http.zig#master"

   Note: Use the appropriate branch if you are not using Zig master (e.g., zig-0.15).

2. In your build.zig, add the httpz module as a dependency to your executable:

   const httpz = b.dependency("httpz", .{
       .target = target,
       .optimize = optimize,
   });
   
   exe.root_module.addImport("httpz", httpz.module("httpz"));

To enable Server-Side Events, call res.startEventStream(context, handler_function).

Requirements & Behavior:

• The handler_function is executed in a new thread.
• The function receives the provided context and an std.net.Stream.
• You must add any necessary headers (like Content-Type) via res.headers.add before calling startEventStream().
• Crucial: Do not set res.body (directly or indirectly) after starting the stream.
• startEventStream() automatically sets Content-Type, Cache-Control, and Connection headers.

fn handler(_: *Request, res: *Response) !void {
    try res.startEventStream(StreamContext{}, StreamContext.handle);
}

const StreamContext = struct {
    fn handle(self: StreamContext, stream: std.net.Stream) void {
        while (true) {
            stream.writeAll("event: ....") catch return;
        }
    }
}

The library collects basic operational metrics using metrics.zig. You can expose these metrics by writing them to an std.io.Writer (such as the response writer in a handler) using httpz.writeMetrics(writer).

Warning: httpz does not provide built-in authorization. Ensure you protect the endpoint exposing these metrics to prevent unauthorized access to server internals.

pub fn metrics(_: *httpz.Request, res: *httpz.Response) !void {
    const writer = res.writer();
    try httpz.writeMetrics(writer);
}

The httpz.testing namespace provides a testing utility to simulate requests and assert responses without running a full server.

Use ht.init(.{}) to create a test context. This returns a structure that provides access to a mock *httpz.Request and *httpz.Response.

const ht = @import("httpz").testing;

test "example test" {
    var web_test = ht.init(.{});
    defer web_test.deinit();

    // ... perform actions ...
}

By default, httpz reads the full request body into memory. If config.request.lazy_read_size is set, bodies larger than that size are not fully loaded.

Instead, you can stream the body using req.reader(timeout_in_ms). This returns an io.Reader that abstracts whether the data is already in memory or still arriving on the socket. You can check req.unread_body > 0 to determine if lazy loading is active.

// 5000 millisecond read timeout on a per-read basis
var reader = try req.reader(5000);
var buf: [4096]u8 = undefined;
while (true) {
    const n = try reader.read(&buf);
    if (n == 0) break
   // buf[0..n] is what was read
}