H3 - Zig HTTP Framework

⚡️ A minimal, fast, and composable HTTP server framework for Zig, inspired by H3.js.

Features

• Minimal & Fast: Small core with low latency and minimal memory footprint
• Composable: Modular design with tree-shakeable utilities
• Type Safe: Leverages Zig's compile-time type safety
• Zero Dependencies: Only uses Zig standard library
• Memory Safe: Built with Zig's memory safety guarantees

Quick Start

Installation

Add H3 to your build.zig.zon:

.dependencies = .{
    .h3 = .{
        .url = "https://github.com/dg0230/h3z/archive/main.tar.gz",
        .hash = "...",
    },
},

Basic Usage

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

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Create H3 app
    var app = h3.createApp(allocator);
    defer app.deinit();

    // Add routes
    _ = app.get("/", helloHandler);
    _ = app.get("/api/users/:id", getUserHandler);
    _ = app.post("/api/users", createUserHandler);

    // Start server
    try h3.serve(&app, .{ .port = 3000 });
}

fn helloHandler(event: *h3.Event) !void {
    try h3.sendText(event, "⚡️ Hello from H3!");
}

fn getUserHandler(event: *h3.Event) !void {
    const user_id = h3.getParam(event, "id") orelse {
        try h3.utils.response.badRequest(event, "Missing user ID");
        return;
    };

    const user = .{ .id = user_id, .name = "John Doe" };
    try h3.sendJson(event, user);
}

fn createUserHandler(event: *h3.Event) !void {
    const User = struct { name: []const u8 };
    const user_data = try h3.readJson(event, User);

    event.setStatus(.created);
    try h3.sendJson(event, .{ .id = 123, .name = user_data.name });
}

API Reference

H3 Application

// Create app
var app = h3.createApp(allocator);
defer app.deinit();

// HTTP methods
_ = app.get("/path", handler);
_ = app.post("/path", handler);
_ = app.put("/path", handler);
_ = app.delete("/path", handler);
_ = app.patch("/path", handler);
_ = app.head("/path", handler);
_ = app.options("/path", handler);
_ = app.all("/path", handler); // All methods

// Middleware
_ = app.use(middleware);

H3Event

The H3Event is the central context object that carries request and response data:

fn handler(event: *h3.Event) !void {
    // Request info
    const method = event.getMethod();
    const path = event.getPath();
    const url = event.getUrl();

    // Headers
    const auth = event.getHeader("authorization");
    try event.setHeader("x-custom", "value");

    // Parameters and query
    const id = h3.getParam(event, "id");
    const page = h3.getQuery(event, "page");

    // Body
    const body = h3.readBody(event);
    const json_data = try h3.readJson(event, MyStruct);

    // Response
    event.setStatus(.ok);
    try h3.sendText(event, "Hello");
    try h3.sendJson(event, "{\"message\": \"Hello\"}");
    try h3.sendJson(event, .{ .message = "Hello" });
    try h3.response.redirect(event, "/new-path", .moved_permanently);
}

Utilities

// Response helpers
try h3.sendText(event, "text");
try h3.sendJson(event, json_string);
try h3.sendJson(event, struct_or_value);
try h3.utils.response.redirect(event, "/path", .found);

// Error responses
try h3.utils.response.notFound(event, "Custom message");
try h3.utils.response.badRequest(event, "Invalid input");
try h3.utils.response.unauthorized(event, null);
try h3.utils.response.forbidden(event, null);
try h3.utils.response.internalServerError(event, null);

// Request helpers
const header = event.getHeader("content-type");
const param = h3.getParam(event, "id");
const query = h3.getQuery(event, "page");
const body = h3.readBody(event);
const json = try h3.readJson(event, MyStruct);

// Security and CORS
try h3.utils.response.setCors(event, "*");
try h3.utils.response.setSecurity(event);
try h3.utils.response.setNoCache(event);

Middleware

fn loggerMiddleware(event: *h3.Event, context: h3.MiddlewareContext, index: usize, final_handler: h3.Handler) !void {
    std.log.info("{s} {s}", .{ event.getMethod().toString(), event.getPath() });
    try context.next(event, index, final_handler);
}

fn corsMiddleware(event: *h3.Event, context: h3.MiddlewareContext, index: usize, final_handler: h3.Handler) !void {
    try h3.utils.response.setCors(event, "*");
    if (event.getMethod() == .OPTIONS) {
        event.setStatus(.no_content);
        return;
    }
    try context.next(event, index, final_handler);
}

// Built-in middleware
_ = app.use(h3.middleware.logger);
_ = app.use(h3.middleware.cors("*"));
_ = app.use(h3.middleware.security);

Server

// Start server with options
try h3.serve(&app, .{
    .port = 3000,
    .host = "127.0.0.1",
    .backlog = 128,
});

// Start with defaults (port 3000)
try h3.serve(&app, .{});

Route Patterns

H3 supports simple route patterns:

• Exact match: /api/users
• Parameters: /api/users/:id (accessible via event.getParam("id"))
• Wildcards: /static/* (matches any path starting with /static/)

Building and Testing

# Build the project
zig build

# Run tests
zig build test

# Run the example
zig build run

# Build in release mode
zig build -Doptimize=ReleaseFast

Requirements

• Zig 0.14.0 or later

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Roadmap

• Advanced routing (regex patterns, route groups)
• WebSocket support
• Static file serving
• Template engine integration
• Database integration helpers
• Session management
• Rate limiting
• Compression middleware
• File upload handling
• Testing utilities

Inspiration

This project is inspired by H3.js, bringing similar concepts and ergonomics to the Zig ecosystem while leveraging Zig's unique strengths in performance and safety.