Build your first App

const Hello = struct {
    pub fn get(_: *Hello, ctx: *Context) !void {
        const query = try ctx.request.query();
        if (query.firstRaw("name")) |param| {
            var decoded: [1024]u8 = undefined;
            const name = try web.params.percentDecodeInto(param.value_raw, &decoded);
            return ctx.response.text(200, name); // copies before stack storage ends
        }
        return ctx.response.text(200, ctx.shared.greeting);
    }
};

This excerpt uses Context = web.App(Shared).Context. Register it with try app.endpoint("/hello", &hello). See the complete App example for initialization, stable state, and shutdown.

OWNERSHIPThis name is temporary, so response.text copies it. For retained input and immutable startup assets, borrowBody borrows the payload independently of staging capacity, within the total response limit. See the copy paths and limits → See a complete file-response handler →

Send the first bytes. Keep working.

Write a little. Flush it to the client. Pause, then send the next update—all inside the same handler.

fn progress(ctx: *Application.Context) !void {
    try ctx.response.header("Cache-Control", "no-cache");
    var stream = try ctx.response.stream(200, "text/plain; charset=utf-8", .{});
    const out = stream.writer();
    try out.writeAll("Starting…\n");
    try out.flush();
    try ctx.sleep(.fromMilliseconds(500));
    try out.print("Completed step {d} of {d}\n", .{ 1, 2 });
    try out.flush();
    try ctx.sleep(.fromMilliseconds(500));
    try out.writeAll("Done.\n");
    try stream.finish();
}

STREAMINGout is a standard std.Io.Writer. Each flush() sends the current bytes before the handler continues.

The complete example selects fixed workers. Headers are final after the first flush, and response size and request time remain bounded. Read the streaming guide → Native streaming evidence →

Many waiting streams. A small worker pool.

For higher concurrency, typed continuations return flush, wait, or finish. Waiting releases the executor while bounded typed state stays alive. Middleware runs once; completion, timeout, and disconnect clean up that state. Works inline or with fixed workers. Read the continuation guide →

Current limit: stream writes copy bytes. You cannot insert a borrowBody() call between flushes. See the response combination rules →

Send a file. Skip the body copy.

Already have a large image or file in memory? borrowBody() lets Baz send those existing bytes directly, avoiding a copy into its response buffer. A 5 MiB file stays in its original storage instead of being copied into another 5 MiB framework buffer.

This complete handler shows the API with an embedded HTML file: GET / returns the file’s contents as the entire response body. Use the same call with your image bytes and content type. Small bodies below the default 256-byte threshold—including this tiny HTML file—may still be copied.

const Shared = struct {};
const Application = web.App(Shared);

fn index(ctx: *Application.Context) !void {
    return ctx.response.borrowBody(200, "text/html; charset=utf-8", @embedFile("assets/serve_index.html"));
}

Here web = @import("baz"). The complete example registers try app.route("GET", "/", index). @embedFile includes the file at compile time, so this handler performs no filesystem I/O. Run it with zig build run-serve -Doptimize=ReleaseSafe -- --port 8080.

FEWER COPIESresponse.bytes() copies your body into bounded staging. borrowBody() avoids that payload copy for large retained bodies; a large file can use a small output arena. Headers and normal kernel transfers still have copying costs. See exactly where copies happen →

borrowBody() prepares one complete body. When this handler returns successfully, App publishes status 200, HTTP headers, and the file bytes. There is no body prefix or suffix. The embedded bytes stay alive for transmission.

Verified on native Linux, macOS, and Windows: the separate 5 MiB fixture sends the original payload with a 4 KiB arena and no framework payload copy. Read the copy-counter and ownership evidence → Read what can be combined →