Appendix C. Error-Handling Patterns Cookbook

//! Demonstrates layering domain-specific error sets when loading configuration.
const std = @import("std");

pub const ParseError = error{
    MissingField,
    InvalidPort,
};

pub const SourceError = error{
    NotFound,
    PermissionDenied,
};

pub const LoadError = SourceError || ParseError;

const SimulatedSource = struct {
    payload: ?[]const u8 = null,
    failure: ?SourceError = null,

    fn fetch(self: SimulatedSource) SourceError![]const u8 {
        if (self.failure) |err| return err;
        return self.payload orelse SourceError.NotFound;
    }
};

fn parsePort(text: []const u8) ParseError!u16 {
    var iter = std.mem.splitScalar(u8, text, '=');
    const key = iter.next() orelse return ParseError.MissingField;
    const value = iter.next() orelse return ParseError.MissingField;
    if (!std.mem.eql(u8, key, "PORT")) return ParseError.MissingField;
    return std.fmt.parseInt(u16, value, 10) catch ParseError.InvalidPort;
}

pub fn loadPort(source: SimulatedSource) LoadError!u16 {
    const line = source.fetch() catch |err| switch (err) {
        SourceError.NotFound => return LoadError.NotFound,
        SourceError.PermissionDenied => return LoadError.PermissionDenied,
    };

    return parsePort(line) catch |err| switch (err) {
        ParseError.MissingField => return LoadError.MissingField,
        ParseError.InvalidPort => return LoadError.InvalidPort,
    };
}

test "successful load yields parsed port" {
    const source = SimulatedSource{ .payload = "PORT=8080" };
    try std.testing.expectEqual(@as(u16, 8080), try loadPort(source));
}

test "parse errors bubble through composed union" {
    const source = SimulatedSource{ .payload = "HOST=example" };
    try std.testing.expectError(LoadError.MissingField, loadPort(source));
}

test "source failures remain precise" {
    const source = SimulatedSource{ .failure = SourceError.PermissionDenied };
    try std.testing.expectError(LoadError.PermissionDenied, loadPort(source));
}

//! Shows how errdefer keeps allocations balanced when joining user snippets.
const std = @import("std");

pub const SnippetError = error{EmptyInput} || std.mem.Allocator.Error;

pub fn joinUpperSnippets(allocator: std.mem.Allocator, parts: []const []const u8) SnippetError![]u8 {
    if (parts.len == 0) return SnippetError.EmptyInput;

    var list = std.ArrayListUnmanaged(u8){};
    errdefer list.deinit(allocator);

    for (parts, 0..) |part, index| {
        if (index != 0) try list.append(allocator, ' ');
        for (part) |ch| try list.append(allocator, std.ascii.toUpper(ch));
    }

    return list.toOwnedSlice(allocator);
}

test "joinUpperSnippets capitalizes and joins input" {
    const allocator = std.testing.allocator;
    const result = try joinUpperSnippets(allocator, &[_][]const u8{ "zig", "cookbook" });
    defer allocator.free(result);

    try std.testing.expectEqualStrings("ZIG COOKBOOK", result);
}

test "joinUpperSnippets surfaces empty-input error" {
    const allocator = std.testing.allocator;
    try std.testing.expectError(SnippetError.EmptyInput, joinUpperSnippets(allocator, &[_][]const u8{}));
}

//! Bridges domain errors to user-facing log messages.
const std = @import("std");

pub const ApiError = error{
    NotFound,
    RateLimited,
    Backend,
};

fn describeApiError(err: ApiError, writer: anytype) !void {
    switch (err) {
        ApiError.NotFound => try writer.writeAll("resource not found; check identifier"),
        ApiError.RateLimited => try writer.writeAll("rate limit exceeded; retry later"),
        ApiError.Backend => try writer.writeAll("upstream dependency failed; escalate"),
    }
}

const Action = struct {
    outcomes: []const ?ApiError,
    index: usize = 0,

    fn invoke(self: *Action) ApiError!void {
        if (self.index >= self.outcomes.len) return;
        const outcome = self.outcomes[self.index];
        self.index += 1;
        if (outcome) |err| {
            return err;
        }
    }
};

pub fn runAndReport(action: *Action, writer: anytype) !void {
    action.invoke() catch |err| {
        try writer.writeAll("Request failed: ");
        try describeApiError(err, writer);
        return;
    };
    try writer.writeAll("Request succeeded");
}

test "runAndReport surfaces friendly error message" {
    var action = Action{ .outcomes = &[_]?ApiError{ApiError.NotFound} };
    var buffer: [128]u8 = undefined;
    var stream = std.io.fixedBufferStream(&buffer);

    try runAndReport(&action, stream.writer());
    const message = stream.getWritten();
    try std.testing.expectEqualStrings("Request failed: resource not found; check identifier", message);
}

test "runAndReport acknowledges success" {
    var action = Action{ .outcomes = &[_]?ApiError{null} };
    var buffer: [64]u8 = undefined;
    var stream = std.io.fixedBufferStream(&buffer);

    try runAndReport(&action, stream.writer());
    const message = stream.getWritten();
    try std.testing.expectEqualStrings("Request succeeded", message);
}