karlseguin/http.zig

This is for Zig 0.17.0. See the various branches for versions pinned to older versions.

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

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

  // More advanced cases will use a custom "Handler" instead of "void".
  // The last parameter is our handler instance; since we have a "void"
  // handler, we passed a void ({}) value.
  var server = try httpz.Server(void).init(init.io, allocator, .{
    // use .all(5882) to bind to all interfaces, i.e. 0.0.0.0
    .address = .localhost(5882),
  }, {});
  defer {
    // clean shutdown, finishes serving any live requests
    server.stop();
    server.deinit();
  }

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

  // blocks
  try server.listen();
}

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

• Examples
• Installation
• Alternatives
• Handler
  • Custom Dispatch
  • Per-Request Context
  • Custom Not Found
  • Custom Error Handler
  • Dispatch Takeover
• Memory And Arenas
• httpz.Request
• httpz.Response
• Router
• Middlewares
• Configuration
• Metrics
• Testing
• HTTP Compliance
• Server Side Events
• Websocket

The master branch targets the latest stable release of Zig; the dev branch targets the latest version of Zig. If you're looking for an older version, look for zig-X.YY branches.

See the examples folder for examples. If you clone this repository, you can run zig build example_# to run a specific example:

$ zig build example_1
listening http://localhost:8800/

1. Add http.zig as a dependency in your build.zig.zon:

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

   The master branch tracks the latest stable release of Zig. If you're using a different version of Zig, use the appropriate branch.

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

   const httpz = b.dependency("httpz", .{
       .target = target,
       .optimize = optimize,
   });
   
   // the executable from your call to b.addExecutable(...)
   exe.root_module.addImport("httpz", httpz.module("httpz"));

If you're looking for a higher level web framework with more included functionality, consider JetZig or Tokamak which are built on top of httpz.

std.http.Server is very slow and assumes well-behaved clients.

There are many Zig HTTP server implementations. Most wrap std.http.Server and tend to be slow. Benchmark it, you'll see. A few wrap C libraries and are faster (though some of these are slow too!).

http.zig is written in Zig, without using std.http.Server. On an M2, a basic request can hit 140K requests per seconds.

When a non-void Handler is used, the value given to Server(H).init is passed to every action. This is how application-specific data can be passed into your actions.

For example, using pg.zig, we can make a database connection pool available to each action:

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

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

  var db = try pg.Pool.init(init.io, allocator, .{
    .connect = .{ .port = 5432, .host = "localhost"},
    .auth = .{.username = "user", .database = "db", .password = "pass"}
  });
  defer db.deinit();

  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, .{});
  try server.listen();
}

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

fn getUser(app: *App, req: *httpz.Request, res: *httpz.Response) !void {
  const user_id = req.param("id").?;

  var row = try app.db.row("select name from users where id = $1", .{user_id}) orelse {
    res.status = 404;
    res.body = "Not found";
    return;
  };
  defer row.deinit() catch {};

  try res.json(.{
    .id = user_id,
    .name = row.get([]u8, 0),
  }, .{});
}

Beyond sharing state, your custom handler can be used to control how httpz behaves. By defining a public dispatch method you can control how (or even if) actions are executed. For example, to log timing, you could do:

const App = struct {
  io: std.Io,

  pub fn dispatch(self: *App, action: httpz.Action(*App), req: *httpz.Request, res: *httpz.Response) !void {
    const start = std.Io.Timestamp.now(self.io, .awake);

    // your `dispatch` doesn't _have_ to call the action
    try action(self, req, res);

    const elapsed = start.untilNow(self.io, .awake);
    std.log.info("{} {s} {d}", .{req.method, req.url.path, elapsed.toMicroseconds()});
  }
};

The 2nd parameter, action, is of type httpz.Action(*App). This is a function pointer to the function you specified when setting up the routes. As we've seen, this works well to share global data. But, in many cases, you'll want to have request-specific data.

Consider the case where you want your dispatch method to conditionally load a user (maybe from the Authorization header of the request). How would you pass this User to the action? You can't use the *App directly, as this is shared concurrently across all requests.

To achieve this, we'll add another structure called RequestContext. You can call this whatever you want, and it can contain any fields of methods you want.

const RequestContext = struct {
  // You don't have to put a reference to your global data.
  // But chances are you'll want.
  app: *App,
  user: ?User,
};

We can now change the definition of our actions and dispatch method:

fn getUser(ctx: *RequestContext, req: *httpz.Request, res: *httpz.Response) !void {
   // can check if ctx.user is != null
}

const App = struct {
  pub fn dispatch(self: *App, action: httpz.Action(*RequestContext), req: *httpz.Request, res: *httpz.Response) !void {
    var ctx = RequestContext{
      .app = self,
      .user = self.loadUser(req),
    }
    return action(&ctx, req, res);
  }

  fn loadUser(self: *App, req: *httpz.Request) ?User {
    // todo, maybe using req.header("authorizaation")
  }
};

httpz infers the type of the action based on the 2nd parameter of your handler's dispatch method. If you use a void handler or your handler doesn't have a dispatch method, then you won't interact with httpz.Action(H) directly.

If your handler has a public notFound method, it will be called whenever a path doesn't match a found route:

const App = struct {
  pub fn notFound(_: *App, req: *httpz.Request, res: *httpz.Response) !void {
    std.log.info("404 {} {s}", .{req.method, req.url.path});
    res.status = 404;
    res.body = "Not Found";
  }
};

If your handler has a public uncaughtError method, it will be called whenever there's an unhandled error. This could be due to some internal httpz bug, or because your action returns an error.

const App = struct {
  pub fn uncaughtError(_: *App, req: *httpz.Request, res: *httpz.Response, err: anyerror) void {
    std.log.info("500 {} {s} {}", .{req.method, req.url.path, err});
    res.status = 500;
    res.body = "sorry";
  }
};

Notice that, unlike notFound and other normal actions, the uncaughtError method cannot return an error itself.

For the most control, you can define a handle method. This circumvents most of Httpz's dispatching, including routing. Frameworks like JetZig hook handle in order to provide their own routing and dispatching. When you define a handle method, then any dispatch, notFound and uncaughtError methods are ignored by httpz.

const App = struct {
  pub fn handle(app: *App, req: *httpz.Request, res: *httpz.Response) void {
    // todo
  }
};

The library supports both simple and complex use cases. A simple use case is shown below. It's initiated by the call to httpz.Server():

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)}, {});

    // overwrite the default notFound handler
    server.notFound(notFound);

    // overwrite the default error handler
    server.errorHandler(errorHandler);

    var router = try server.router(.{});

    // use get/post/put/head/patch/options/delete
    // you can also use "all" to attach to all methods
    router.get("/api/user/:id", getUser, .{});

    // start the server in the current thread, blocking.
    try server.listen();
}

fn getUser(req: *httpz.Request, res: *httpz.Response) !void {
    // status code 200 is implicit.

    // The json helper will automatically set the res.content_type = httpz.ContentType.JSON;
    // Here we're passing an inferred anonymous structure, but you can pass anytype
    // (so long as it can be serialized using std.json.Stringify)

    try res.json(.{.id = req.param("id").?, .name = "Teg"}, .{});
}

fn notFound(_: *httpz.Request, res: *httpz.Response) !void {
    res.status = 404;

    // you can set the body directly to a []u8, but note that the memory
    // must be valid beyond your handler. Use the res.arena if you need to allocate
    // memory for the body.
    res.body = "Not Found";
}

// note that the error handler return `void` and not `!void`
fn errorHandler(req: *httpz.Request, res: *httpz.Response, err: anyerror) void {
    res.status = 500;
    res.body = "Internal Server Error";
    std.log.warn("httpz: unhandled exception for request: {s}\nErr: {}", .{req.url.raw, err});
}

Any allocations made for the response, such as the body or a header, must remain valid until after the action returns. To achieve this, use res.arena or the res.writer():

fn arenaExample(req: *httpz.Request, res: *httpz.Response) !void {
    const query = try req.query();
    const name = query.get("name") orelse "stranger";
    res.body = try std.fmt.allocPrint(res.arena, "Hello {s}", .{name});
}

fn writerExample(req: *httpz.Request, res: *httpz.Response) !void {
    const query = try req.query();
    const name = query.get("name") orelse "stranger";
    try res.writer().print("Hello {s}", .{name});
}

Alternatively, you can explicitly call res.write(). Once res.write() returns, the response is sent and your action can cleanup/release any resources.

res.arena is actually a configurable-sized thread-local buffer that falls back to an std.heap.ArenaAllocator. In other words, it's fast so it should be your first option for data that needs to live only until your action exits.

res.writer() returns a *std.Io.Writer which writes into httpz's own buffered response body.

The following fields are the most useful:

• method - httpz.Method enum
• method_string - Only set if method == .OTHER, else empty. Used when using custom methods.
• arena - A fast thread-local buffer that falls back to an ArenaAllocator, same as res.arena.
• url.path - the path of the request ([]const u8)
• address - the std.Io.net.IpAddress of the client

If you give your route a data configuration, the value can be retrieved from the optional route_data field of the request.

The param method of *Request returns an ?[]const u8. For example, given the following path:

router.get("/api/users/:user_id/favorite/:id", user.getFavorite, .{});

Then we could access the user_id and id via:

pub fn getFavorite(req *http.Request, res: *http.Response) !void {
    const user_id = req.param("user_id").?;
    const favorite_id = req.param("id").?;
    ...

In the above, passing any other value to param would return a null object (since the route associated with getFavorite only defines these 2 parameters). Given that routes are generally statically defined, it should not be possible for req.param to return an unexpected null. However, it is possible to define two routes to the same action:

router.put("/api/users/:user_id/favorite/:id", user.updateFavorite, .{});

// currently logged in user, maybe?
router.put("/api/use/favorite/:id", user.updateFavorite, .{});

In which case the optional return value of param might be useful.

Similar to param, header values can be fetched via the header function, which also returns a ?[]const u8:

if (req.header("authorization")) |auth| {

} else {
    // not logged in?:
}

Header names are lowercase. Values maintain their original casing.

To iterate over all headers, use:

var it = req.headers.iterator();
while (it.next()) |kv| {
  // kv.key
  // kv.value
}

The framework does not automatically parse the query string. Therefore, its API is slightly different.

const query = try req.query();
if (query.get("search")) |search| {

} else {
    // no search parameter
};

On first call, the query function attempts to parse the query string. This requires memory allocations to unescape encoded values. The parsed value is internally cached, so subsequent calls to query() are fast and cannot fail.

The original casing of both the key and the name are preserved.

To iterate over all query parameters, use:

var it = req.query().iterator();
while (it.next()) |kv| {
  // kv.key
  // kv.value
}

A key can appear multiple times (e.g. ?tag=a&tag=b). get returns the first value. To get every value for a key, use getAll:

var it = (try req.query()).getAll("tag");
while (it.next()) |tag| {
  // tag is []const u8
}

getAll is available on headers, the query string, form data and multipart form data.

The body of the request, if any, can be accessed using req.body(). This returns a ?[]const u8.

The req.json(TYPE) function is a wrapper around the body() function which will call std.json.parse on the body. This function does not consider the content-type of the request and will try to parse any body.

if (try req.json(User)) |user| {

}

The req.jsonValue() function is a wrapper around the body() function which will parse the body into a std.json.Value, returning a !?std.json.Value. This function does not consider the content-type of the request and will try to parse any body.

if (try req.jsonValue()) |v| {
    // probably want to be more defensive than this
    const product_type = v.object.get("type").?.string;
    //...
}

The even more specific jsonObject() function will return an std.json.ObjectMap provided the body is a map

if (try req.jsonObject()) |t| {
    // probably want to be more defensive than this
    const product_type = t.get("type").?.string;
    //...
}

The body of the request, if any, can be parsed as a x-www-form-urlencoded value using req.formData(). The request.max_form_count configuration value must be set to the maximum number of form fields to support. This defaults to 0.

This behaves similarly to query().

On first call, the formData function attempts to parse the body. This can require memory allocations to unescape encoded values. The parsed value is internally cached, so subsequent calls to formData() are fast and cannot fail.

The original casing of both the key and the name are preserved.

To iterate over all fields, use:

var it = (try req.formData()).iterator();
while (it.next()) |kv| {
  // kv.key
  // kv.value
}

Once this function is called, req.multiFormData() will no longer work (because the body is assumed parsed).

Similar to the above, req.multiFormData() can be called to parse requests with a multipart/form-data content type. The request.max_multiform_count configuration value must be set to the maximum number of form fields to support. This defaults to 0.

This is a different API than formData because the return type is different. Rather than a simple string=>value type, the multi part form data value consists of a value: []const u8 and a filename: ?[]const u8.

On first call, the multiFormData function attempts to parse the body. The parsed value is internally cached, so subsequent calls to multiFormData() are fast and cannot fail.

The original casing of both the key and the name are preserved.

To iterate over all fields, use:

var it = (try req.multiFormData()).iterator();
while (it.next()) |kv| {
  // kv.key
  // kv.value.value
  // kv.value.filename (optional)
}

When the same field name appears multiple times, such as from an <input type=file name=files multiple>, get only returns the first. Use getAll to iterate through every value for the field:

var it = (try req.multiFormData()).getAll("files");
while (it.next()) |file| {
  // file.value
  // file.filename (optional)
}

Note that each uploaded file counts towards request.max_multiform_count.

Once this function is called, req.formData() will no longer work (because the body is assumed parsed).

Advance warning: This is one of the few methods that can modify the request in-place. For most people this won't be an issue, but if you use req.body() and req.multiFormData(), say to log the raw body, the content-disposition field names are escaped in-place. It's still safe to use req.body() but any content-disposition name that was escaped will be a little off.

By default, httpz reads the full request body into memory. Depending on httpz configuration and the request size, the body will be stored in the static request buffer, a large buffer pool, or dynamically allocated.

As an alternative, when config.request.lazy_read_size is set, bodies larger than the configured bytes will not be read into memory. Instead, applications can create a io.Reader by calling req.reader(timeout_in_ms).

// 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
}

req.reader can safely be used whether or not the full body was already in-memory - the API abstracts reading from already-loaded bytes and bytes still waiting to be received on the socket. You can check req.unread_body > 0 to know whether lazy loading is in effect.

A few notes about the implementation.

If if the body is larger than the configured lazy_read_size, part of the body might still be read into the request's static buffer. The io.Reader returned by req.reader() will abstract this detail away and return the full body.

Also, if the body isn't fully read, but the connection is marked for keepalive (which is generally the default), httpz will still read the full body, but will do so in 4K chunks.

While the io.Reader can be used for non-lazy loaded bodies, there's overhead to this. It is better to use it only when you know that the body is large (i.e., a file upload).

Use the req.cookies method to get a Request.Cookie object. Use get to get an optional cookie value for a given cookie name. The cookie name is case sensitive.

var cookies = req.cookies();
if (cookies.get("auth")) |auth| {
  /// ...
}

The following fields are the most useful:

• status - set the status code, by default, each response starts off with a 200 status code
• content_type - an httpz.ContentType enum value. This is a convenience and optimization over using the res.header function.
• arena - A fast thread-local buffer that falls back to an ArenaAllocator, same as req.arena.

The status field is a u16. You can alternatively use res.setStatus(.ok) if you prefer to use the std.http.Status enum.

The simplest way to set a body is to set res.body to a []const u8. However the provided value must remain valid until the body is written, which happens after the function exists or when res.write() is explicitly called.

You can use the res.arena allocator to create dynamic content:

const query = try req.query();
const name = query.get("name") orelse "stranger";
res.body = try std.fmt.allocPrint(res.arena, "Hello {s}", .{name});

Memory allocated with res.arena will exist until the response is sent.

res.writer() returns a *std.Io.Writer. Various types support writing to an std.Io.Writer. For example, the built-in JSON stream writer can use this writer:

var ws: std.json.Stringify = .{ .writer = res.writer() };
try ws.beginObject();
try ws.objectField("name");
try ws.write(req.param("name").?);
try ws.endObject();

The res.json function will set the content_type to httpz.ContentType.JSON and serialize the provided value using std.json.Stringify. The 2nd argument to the json function is the std.json.Stringify.Options to use.

This function uses res.writer() explained above.

Set header values using the res.header(NAME, VALUE) function:

res.header("Location", "/");

The header name and value are sent as provided. Both the name and value must remain valid until the response is sent, which will happen outside of the action. Dynamic names and/or values should be created and or dupe'd with res.arena.

res.headerOpts(NAME, VALUE, OPTS) can be used to dupe the name and/or value:

try res.headerOpts("Location", location, .{.dupe_value = true});

HeaderOpts currently supports dupe_name: bool and dupe_value: bool, both default to false.

You can use the res.setCookie(name, value, opts) to set the "Set-Cookie" header.

try res.setCookie("cookie_name3", "cookie value 3", .{
    .path = "/auth/",
    .domain = "www.openmymind.net",
    .max_age = 9001,
    .secure = true,
    .http_only = true,
    .partitioned = true,
    .same_site = .lax,  // or .none, or .strict (or null to leave out)
});

setCookie does not validate the name, value, path or domain - it assumes you're setting proper values. It will double-quote values which contain spaces or commas (as required).

If, for whatever reason, res.setCookie doesn't work for you, you always have full control over the cookie value via res.header("Set-Cookie", value).

var cookies = req.cookies();
if (cookies.get("auth")) |auth| {
  /// ...
}

By default, httpz will automatically flush your response. In more advanced cases, you can use res.write() to explicitly flush it. This is useful in cases where you have resources that need to be freed/released only after the response is written. For example, my LRU cache uses atomic referencing counting to safely allow concurrent access to cached data. This requires callers to "release" the cached entry:

pub fn info(app: *MyApp, _: *httpz.Request, res: *httpz.Response) !void {
    const cached = app.cache.get("info") orelse {
        // load the info
    };
    defer cached.release();

    res.body = cached.value;
    return res.write();
}

You get an instance of the router by calling server.router(.{}). Currently, the configuration takes a single parameter:

• middlewares - A list of middlewares to apply to each request. These middleware will be executed even for requests with no matching route (i.e. not found). An individual route can opt-out of these middleware, see the middleware_strategy route configuration.

You can use the get, put, post, head, patch, trace, delete, options or connect method of the router to define a router. You can also use the special all method to add a route for all methods.

These functions can all @panic as they allocate memory. Each function has an equivalent tryXYZ variant which will return an error rather than panicking:

// this can panic if it fails to create the route
router.get("/", index, .{});

// this returns a !void (which you can try/catch)
router.tryGet("/", index, .{});

The 3rd parameter is a route configuration. It allows you to specify a different handler and/or dispatch method and/or middleware.

// this can panic if it fails to create the route
router.get("/", index, .{
  .dispatcher = Handler.dispatchAuth,
  .handler = &auth_handler,
  .middlewares = &.{cors_middleware},
});

The last parameter to the various router methods is a route configuration. In many cases, you'll probably use an empty configuration (.{}). The route configuration has three fields:

• dispatcher - The dispatch method to use. This overrides the default dispatcher, which is either httpz built-in dispatcher or your handler's dispatch method.
• handler - The handler instance to use. The default handler is the 3rd parameter passed to Server(H).init but you can override this on a route-per-route basis.
• middlewares - A list of middlewares to run. By default, no middlewares are run. By default, this list of middleware is appended to the list given to server.router(.{.middlewares = .{....}).
• middleware_strategy - How the given middleware should be merged with the global middlewares. Defaults to .append, can also be .replace.
• data - Arbitrary data (*const anyopaque) to make available to req.route_data. This must be a const.

You can specify a separate configuration for each route. To change the configuration for a group of routes, you have two options. The first, is to directly change the router's handler, dispatcher and middlewares field. Any subsequent routes will use these values:

var server = try httpz.Server(Handler).init(io, allocator, .{.address = .localhost(5882)}, &handler);

var router = try server.router(.{});

// Will use Handler.dispatch on the &handler instance passed to init
// No middleware
router.get("/route1", route1, .{});

router.dispatcher = Handler.dispatchAuth;
// uses the new dispatcher
router.get("/route2", route2, .{});

router.handler = &Handler{.public = true};
// uses the new dispatcher + new handler
router.get("/route3", route3, .{.handler = Handler.dispatchAuth});

This approach is error prone though. New routes need to be carefully added in the correct order so that the desired handler, dispatcher and middlewares are used.

A more scalable option is to use route groups.

Defining a custom dispatcher or custom global data on each route can be tedious. Instead, consider using a router group:

var admin_routes = router.group("/admin", .{
  .handler = &auth_handler,
  .dispatcher = Handler.dispatchAuth,
  .middlewares = &.{cors_middleware},
});
admin_routes.get("/users", listUsers, .{});
admin_routs.delete("/users/:id", deleteUsers, .{});

The first parameter to group is a prefix to prepend to each route in the group. An empty prefix is acceptable. Thus, route groups can be used to configure either a common prefix and/or a common configuration across multiple routes.

You must use a lowercase route. You can use any casing with parameter names, as long as you use that same casing when getting the parameter.

Routing supports parameters, via :CAPTURE_NAME. The captured values are available via req.params.get(name: []const u8) ?[]const u8.

You can glob an individual path segment, or the entire path suffix. For a suffix glob, it is important that no trailing slash is present.

// prefer using a custom `notFound` handler than a global glob.
router.all("/*", not_found, .{});
router.get("/api/*/debug", .{})

When multiple globs are used, the most specific will be selected. E.g., give the following two routes:

router.get("/*", not_found, .{});
router.get("/info/*", any_info, .{})

A request for "/info/debug/all" will be routed to any_info, whereas a request for "/over/9000" will be routed to not_found.

You can use the method function to route a custom method:

router.method("TEA", "/", teaList, .{});

In such cases, request.method will be .OTHER and you can use the request.method_string for the string value. The method name, TEA above, is cloned by the router and does not need to exist beyond the function call. The method name should only be uppercase ASCII letters.

The router.all method does not route to custom methods.

The router has several limitations which might not get fixed. These specifically resolve around the interaction of globs, parameters and static path segments.

Given the following routes:

router.get("/:any/users", route1, .{});
router.get("/hello/users/test", route2, .{});

You would expect a request to "/hello/users" to be routed to route1. However, no route will be found.

Globs interact similarly poorly with parameters and static path segments.

Resolving this issue requires keeping a stack (or visiting the routes recursively), in order to back-out of a dead-end and trying a different path. This seems like an unnecessarily expensive thing to do, on each request, when, in my opinion, such route hierarchies are uncommon.

In general, use a custom dispatch function to apply custom logic, such as logging, authentication and authorization. If you have complex route-specific logic, middleware can also be leveraged.

A middleware is a struct which exposes a nested Config type, a public init function and a public execute method. It can optionally define a deinit method. See the built-in CORS middleware or the sample logger middleware for examples.

A middleware instance is created using server.middleware() and can then be used with the router:

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

// the middleware method takes the struct name and its configuration
const cors = try server.middleware(httpz.middleware.Cors, .{
  .origin = "https://www.openmymind.net/",
});

// apply this middleware to all routes (unless the route
// explicitly opts out)
var router = try server.router(.{.middlewares = &.{cors}});

// or we could add middleware on a route-per-route basis
router.get("/v1/users", user, .{.middlewares = &.{cors}});

// by default, middlewares on a route are appended to the global middlewares
// we can replace them instead by specifying a middleware_strategy
router.get("/v1/metrics", metrics, .{.middlewares = &.{cors}, .middleware_strategy = .replace});

httpz comes with a built-in CORS middleware: httpz.middleware.Cors. Its configuration is:

• origin: []const u8 - The allowed origin(s)
• headers: ?[]const u8 = null - Allowed headers for preflight requests
• methods: ?[]const u8 = null - Allowed methods for preflight requests
• max_age: ?[]const u8 = null - Max age for preflight cache
• credentials: ?[]const u8 = null - Allow credentials (set to "true" to enable)

The origin configuration supports three formats:

Allow all origins with *:

const cors = try server.middleware(httpz.middleware.Cors, .{
    .origin = "*",
    .methods = "GET,POST",
    .headers = "content-type",
});

Allow a single specific origin:

const cors = try server.middleware(httpz.middleware.Cors, .{
    .origin = "https://www.openmymind.net",
    .methods = "GET,POST",
    .max_age = "300",
});

Allow multiple specific origins by separating them with commas:

const cors = try server.middleware(httpz.middleware.Cors, .{
    .origin = "https://www.openmymind.net, https://api.example.com, https://app.example.com",
    .methods = "GET,POST,DELETE",
    .headers = "authorization,content-type",
});

To allow credentials (cookies, authorization headers, etc.), set the credentials field:

const cors = try server.middleware(httpz.middleware.Cors, .{
    .origin = "https://www.openmymind.net",
    .credentials = "true",
    .methods = "GET,POST",
});

Note that when using credentials, origin cannot be * (wildcard) - you must specify explicit origin(s).

The CORS middleware includes an Access-Control-Allow-Origin header in responses when:

• The request includes an Origin header
• The origin matches the configured allowed origin(s)

For wildcard origins (*), the middleware returns Access-Control-Allow-Origin: *. For specific origins, it echoes back the request's origin if it's in the allowed list.

For OPTIONS requests where sec-fetch-mode is set to cors (preflight requests), the middleware will also set:

• Access-Control-Allow-Headers (if configured)
• Access-Control-Allow-Methods (if configured)
• Access-Control-Max-Age (if configured)
• Access-Control-Allow-Credentials (if configured)

And return a 204 No Content status.

The origin parsing and validation happens once at middleware initialization, not on every request, ensuring optimal performance.

The second parameter given to Server(H).init is an httpz.Config. When running in blocking mode (e.g. on Windows) a few of these behave slightly, but not drastically, different.

There are many configuration options.

thread_pool.buffer_size is the single most important value to tweak. Usage of req.arena, res.arena, res.writer() and res.json() all use a fallback allocator which first uses a fast thread-local buffer and then an underlying arena. The total memory this will require is thread_pool.count * thread_pool.buffer_size. Since thread_pool.count is usually small, a large buffer_size is reasonable.

request.buffer_size must be large enough to fit the request header. Any extra space might be used to read the body. However, there can be up to workers.count * workers.max_conn pending requests, so a large request.buffer_size can take up a lot of memory. Instead, consider keeping request.buffer_size only large enough for the header (plus a bit of overhead for decoding URL-escape values) and set workers.large_buffer_size to a reasonable size for your incoming request bodies. This will take workers.count * workers.large_buffer_count * workers.large_buffer_size memory.

Buffers for request bodies larger than workers.large_buffer_size but smaller than request.max_body_size will be dynamically allocated.

In addition to a bit of overhead, at a minimum, httpz will use:

(thread_pool.count * thread_pool.buffer_size) +
(workers.count * workers.large_buffer_count * workers.large_buffer_size) +
(workers.count * workers.min_conn * request.buffer_size)

Possible values, along with their default, are:

var server = try httpz.Server(void).init(io, allocator, .{
    // Listen on a localhost port.
    .address = .localhost(5882),

    // Listen on all addresses.
    // .address = .all(5882),

    // unix socket to listen on (mutually exclusive with host&port)
    // .address = .{ .unix = "http.sock" },

    // Listen on a std.Io.net.IpAddress.
    // .address = .{ .ip = .{ .ip4 = .{ .bytes = .{ 0, 0, 0, 0 }, .port = 5882 } } },

    // configure the workers which are responsible for:
    // 1 - accepting connections
    // 2 - reading and parsing requests
    // 3 - passing requests to the thread pool
    .workers = .{
        // Number of worker threads
        // (blocking mode: handled differently)
        .count = 1,

        // Maximum number of concurrent connection each worker can handle
        // (blocking mode: currently ignored)
        .max_conn = 8_192,

        // Minimum number of connection states each worker should maintain
        // (blocking mode: currently ignored)
        .min_conn = 64,

        // A pool of larger buffers that can be used for any data larger than configured
        // static buffers. For example, if response headers don't fit in in
        // $response.header_buffer_size, a buffer will be pulled from here.
        // This is per-worker.
        .large_buffer_count = 16,

        // The size of each large buffer.
        .large_buffer_size = 65536,

        // Size of bytes retained for the connection arena between use. This will
        // result in up to `count * min_conn * retain_allocated_bytes` of memory usage.
        .retain_allocated_bytes = 4096,
    },

    // configures the threadpool which processes requests. The threadpool is
    // where your application code runs.
    .thread_pool = .{
        // Number threads. If your handlers are doing a lot of i/o, a higher
        // number might provide better throughput
        // (blocking mode: handled differently)
        .count = 32,

        // The maximum number of pending requests that the thread pool will accept
        // This applies back pressure to the above workers and ensures that, under load,
        // pending requests get precedence over processing new requests.
        .backlog = 500,

        // Size of the static buffer to give each thread. Memory usage will be
        // `count * buffer_size`. If you're making heavy use of either `req.arena` or
        // `res.arena`, this is likely the single easiest way to gain performance.
        .buffer_size = 8192,
    },

    // options for tweaking request processing
    .request = .{
        // Maximum request body size that we'll process. We can allocate up
        // to this much memory per request for the body. Internally, we might
        // keep this memory around for a number of requests as an optimization.
        .max_body_size = 1_048_576,

        // When set, if request body is larger than this value, the body won't be
        // eagerly read. The application can use `req.reader()` to create a reader
        // to read the body. Prevents loading large bodies completely in memory.
        // When set, max_body_size is ignored.
        .lazy_read_size = null,

        // This memory is allocated upfront. The request header _must_ fit into
        // this space, else the request will be rejected.
        .buffer_size = 4_096,

        // Maximum number of headers to accept.
        // Additional headers will be silently ignored.
        .max_header_count = 32,

        // Maximum number of URL parameters to accept.
        // Additional parameters will be silently ignored.
        .max_param_count = 10,

        // Maximum number of query string parameters to accept.
        // Additional parameters will be silently ignored.
        .max_query_count = 32,

        // Maximum number of x-www-form-urlencoded fields to support.
        // Additional parameters will be silently ignored. This must be
        // set to a value greater than 0 (the default) if you're going
        // to use the req.formData() method.
        .max_form_count = 0,

        // Maximum number of multipart/form-data fields to support.
        // Additional parameters will be silently ignored. This must be
        // set to a value greater than 0 (the default) if you're going
        // to use the req.multiFormData() method.
        .max_multiform_count = 0,
    },

    // options for tweaking response object
    .response = .{
        // The maximum number of headers to accept.
        // Additional headers will be silently ignored.
        .max_header_count = 16,
    },

    .timeout = .{
        // Time in seconds that keepalive connections will be kept alive while inactive
        .keepalive = null,

        // Time in seconds that a connection has to send a complete request
        .request = null,

        // Maximum number of a requests allowed on a single keepalive connection
        .request_count = null,
    },
    .websocket = .{
        // refer to https://github.com/karlseguin/websocket.zig#config
        .max_message_size = null,
        .small_buffer_size = null,
        .small_buffer_pool = null,
        .large_buffer_size = null,
        .large_buffer_pool = null,
        .compression = false,
        .compression_retain_writer = true,
        // if compression is true, and this is null, then
        // we accept compressed messaged from the client, but never send
        // compressed messages
        .compression_write_treshold = null,
    },
}, {});

kqueue (BSD, MacOS) or epoll (Linux) are used on supported platforms. On all other platforms (most notably Windows), a more naive thread-per-connection with blocking sockets is used.

The comptime-safe, httpz.blockingMode() bool function can be called to determine which mode httpz is running in (when it returns true, then you're running the simpler blocking mode).

While you should always run httpz behind a reverse proxy, it's particularly important to do so in blocking mode due to the ease with which external connections can DOS the server.

In blocking mode, config.workers.count is hard-coded to 1. (This worker does considerably less work than the non-blocking workers). If config.workers.count is > 1, than those extra workers will go towards config.thread_pool.count. In other words:

In non-blocking mode, if config.workers.count = 2 and config.thread_pool.count = 4, then you'll have 6 threads: 2 threads that read+parse requests and send replies, and 4 threads to execute application code.

In blocking mode, the same config will also use 6 threads, but there will only be: 1 thread that accepts connections, and 5 threads to read+parse requests, send replies and execute application code.

The goal is for the same configuration to result in the same # of threads regardless of the mode, and to have more thread_pool threads in blocking mode since they do more work.

In blocking mode, config.workers.large_buffer_count defaults to the size of the thread pool.

In blocking mode, config.workers.max_conn and config.workers.min_conn are ignored. The maximum number of connections is simply the size of the thread_pool.

If you aren't using a reverse proxy, you should always set the config.timeout.request, config.timeout.keepalive and config.timeout.request_count settings. In blocking mode, consider using conservative values: say 5/5/5 (5 second request timeout, 5 second keepalive timeout, and 5 keepalive count). You can monitor the httpz_timeout_active metric to see if the request timeout is too low.

The configuration settings under the timeouts section are designed to help protect the system against basic DOS attacks (say, by connecting and not sending data). However it is recommended that you leave these null (disabled) and use the appropriate timeout in your reverse proxy (e.g. NGINX).

The timeout.request is the time, in seconds, that a connection has to send a complete request. The timeout.keepalive is the time, in second, that a connection can stay connected without sending a request (after the initial request has been sent).

The connection alternates between these two timeouts. It starts with a timeout of timeout.request and after the response is sent and the connection is placed in the "keepalive list", switches to the timeout.keepalive. When new data is received, it switches back to timeout.request. When null, both timeouts default to 2_147_483_647 seconds (so not completely disabled, but close enough).

The timeout.request_count is the number of individual requests allowed within a single keepalive session. This protects against a client consuming the connection by sending unlimited meaningless but valid HTTP requests.

When the three are combined, it should be difficult for a problematic client to stay connected indefinitely.

If you're running httpz on Windows (or, more generally, where httpz.blockingMode() returns true), please read the section as this mode of operation is more susceptible to DOS.

A few basic metrics are collected using metrics.zig, a prometheus-compatible library. These can be written to an std.Io.Writer using try httpz.writeMetrics(writer). As an example:

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

    // if we were also using pg.zig
    // try pg.writeMetrics(writer);
}

Since httpz does not provide any authorization, care should be taken before exposing this.

The metrics are:

• httpz_connections - counts each TCP connection
• httpz_requests - counts each request (should be >= httpz_connections due to keepalive)
• httpz_timeout_active - counts each time an "active" connection is timed out. An "active" connection is one that has (a) just connected or (b) started to send bytes. The timeout is controlled by the timeout.request configuration.
• httpz_timeout_keepalive - counts each time an "keepalive" connection is timed out. A "keepalive" connection has already received at least 1 response and the server is waiting for a new request. The timeout is controlled by the timeout.keepalive configuration.
• httpz_alloc_buffer_empty - counts number of bytes allocated due to the large buffer pool being empty. This may indicate that workers.large_buffer_count should be larger.
• httpz_alloc_buffer_large - counts number of bytes allocated due to the large buffer pool being too small. This may indicate that workers.large_buffer_size should be larger.
• httpz_alloc_unescape - counts number of bytes allocated due to unescaping query or form parameters. This may indicate that request.buffer_size should be larger.
• httpz_internal_error - counts number of unexpected errors within httpz. Such errors normally result in the connection being abruptly closed. For example, a failing syscall to epoll/kqueue would increment this counter.
• httpz_invalid_request - counts number of requests which httpz could not parse (where the request is invalid).
• httpz_header_too_big - counts the number of requests which httpz rejects due to a header being too big (does not fit in request.buffer_size config).
• httpz_body_too_big - counts the number of requests which httpz rejects due to a body being too big (is larger than request.max_body_size config).

The httpz.testing namespace exists to help application developers setup an *httpz.Request and assert an *httpz.Response.

Imagine we have the following partial action:

fn search(req: *httpz.Request, res: *httpz.Response) !void {
    const query = try req.query();
    const search = query.get("search") orelse return missingParameter(res, "search");

    // TODO ...
}

fn missingParameter(res: *httpz.Response, parameter: []const u8) !void {
    res.status = 400;
    return res.json(.{.@"error" = "missing parameter", .parameter = parameter}, .{});
}

We can test the above error case like so:

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

test "search: missing parameter" {
    // init takes the same Configuration used when creating the real server
    // but only the config.request and config.response settings have any impact
    var web_test = ht.init(.{});
    defer web_test.deinit();

    try search(web_test.req, web_test.res);
    try web_test.expectStatus(400);
    try web_test.expectJson(.{.@"error" = "missing parameter", .parameter = "search"});
}

The testing structure returned from httpz.testing.init exposes helper functions to set param, query and header values as well as the body:

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

web_test.param("id", "99382");
web_test.query("search", "tea");
web_test.header("Authorization", "admin");

web_test.body("over 9000!");
// OR
web_test.json(.{.over = 9000});
// OR
// This requires ht.init(.{.request = .{.max_form_count = 10}})
web_test.form(.{.over = "9000"});

// at this point, web_test.req has a param value, a query string value, a header value and a body.

As an alternative to the query function, the full URL can also be set. If you use query AND url, the query parameters of the URL will be ignored:

web_test.url("/power?over=9000");

There are various methods to assert the response:

try web_test.expectStatus(200);
try web_test.expectHeader("Location", "/");
try web_test.expectHeader("Location", "/");
try web_test.expectBody("{\"over\":9000}");

If the expected body is in JSON, there are two helpers available. First, to assert the entire JSON body, you can use expectJson:

try web_test.expectJson(.{.over = 9000});

Or, you can retrieve a std.json.Value object by calling getJson:

const json = try web_test.getJson();
try std.testing.expectEqual(@as(i64, 9000), json.object.get("over").?.integer);

For more advanced validation, use the parseResponse function to return a structure representing the parsed response:

const res = try web_test.parseResponse();
try std.testing.expectEqual(@as(u16, 200), res.status);
// use res.body for a []const u8
// use res.headers for a std.StringHashMap([]const u8)
// use res.raw for the full raw response

This implementation may never be fully HTTP/1.1 compliant, as it is built with the assumption that it will sit behind a reverse proxy that is tolerant of non-compliant upstreams (e.g. nginx). (One example I know of is that the server doesn't include the mandatory Date header in the response.)

Server Side Events can be enabled by calling res.startEventStream(). This method takes an arbitrary context and a function pointer. The provided function will be executed in a new thread, receiving the provided context and an std.Io.net.Stream. Headers can be added (via res.headers.add) before calling startEventStream(). res.body must not be set (directly or indirectly).

Calling startEventStream() automatically sets the Content-Type, Cache-Control and Connection header.

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

const StreamContext = struct {
    io: std.Io,

    fn handle(self: StreamContext, stream: std.Io.net.Stream) void {
        var w = stream.writer(self.io, &.{});
        while (true) {
            // some event loop
            w.interface.writeAll("event: ....") catch return;
        }
    }
};

http.zig integrates with https://github.com/karlseguin/websocket.zig by calling httpz.upgradeWebsocket(). First, your handler must have a WebsocketHandler declaration which is the WebSocket handler type used by websocket.Server(H).

const websocket = httpz.websocket;

const Handler = struct {
  // App-specific data you want to pass when initializing
  // your WebSocketHandler
  const WebsocketContext = struct {

  };

  // See the websocket.zig documentation. But essentially this is your
  // Application's wrapper around 1 websocket connection
  pub const WebsocketHandler = struct {
    conn: *websocket.Conn,

    // ctx is arbitrary data you pass to httpz.upgradeWebsocket
    pub fn init(conn: *websocket.Conn, _: WebsocketContext) {
      return .{
        .conn =  conn,
      }
    }

    // echo back
    pub fn clientMessage(self: *WebsocketHandler, data: []const u8) !void {
        try self.conn.write(data);
    }
  }
};

With this in place, you can call httpz.upgradeWebsocket() within an action:

fn ws(req: *httpz.Request, res: *httpz.Response) !void {
  if (try httpz.upgradeWebsocket(WebsocketHandler, req, res, WebsocketContext{}) == false) {
  // this was not a valid websocket handshake request
  // you should probably return with an error
  res.status = 400;
  res.body = "invalid websocket handshake";
  return;
  }
  // Do not use `res` from this point on
}

In websocket.zig, init is passed a websocket.Handshake. This is not the case with the httpz integration - you are expected to do any necessary validation of the request in the action.

It is an undefined behavior if Handler.WebsocketHandler is not the same type passed to httpz.upgradeWebsocket.

For GraphQL support, you might want to consider yousif-wali/grapzig which can been integrated with http.zig.