Something went wrong. Try again.
An HTTP library for Zig 0.17, server and client, HTTP/1.0 through HTTP/3, with the protocol in a module that owns no socket.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! A request method.//!//! A string rather than an enumeration, because that is what the method//! actually is: RFC 9110 §9 defines a registry that anyone may add to, and//! WebDAV, CalDAV and every other extension have. A server that models the//! method as a closed set cannot tell `PROPFIND` from nonsense, and so cannot//! answer the first with `405 Method Not Allowed` and the second with `501//! Not Implemented`, which are different answers to different questions.//!//! `known` narrows one to an enumeration when there is something to switch//! on. The constants below — `.get`, `.post` and the rest — are the methods//! RFC 9110 defines, spelled the way they go on the wire.//!//! Methods are case-sensitive: `get` is not `GET`, and RFC 9110 §9.1 says so//! explicitly. `eql` compares exactly, which means a server will answer a//! lower-case `get` with `501` rather than serving it — deliberately, because//! the alternative is a cache that stores under one spelling what it was//! asked for under another.
const std = @import("std");
const token = @import("token.zig");
const Method = @This();
/// The method as it appeared, always a valid `token`.name: []const u8,
/// The methods RFC 9110 §9.3 defines, for when there is something to switch/// on. `Method.known` is how one is reached.pub const Known = enum { GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, /// RFC 5789. PATCH,};
pub const get: Method = .{ .name = "GET" };pub const head: Method = .{ .name = "HEAD" };pub const post: Method = .{ .name = "POST" };pub const put: Method = .{ .name = "PUT" };pub const delete: Method = .{ .name = "DELETE" };pub const connect: Method = .{ .name = "CONNECT" };pub const options: Method = .{ .name = "OPTIONS" };pub const trace: Method = .{ .name = "TRACE" };pub const patch: Method = .{ .name = "PATCH" };
pub const ParseError = error{ /// Not a `token`: empty, or carrying an octet a method may not contain. InvalidMethod,};
/// Checks that `name` could be a method and wraps it. Borrows `name`.pub fn parse(name: []const u8) ParseError!Method { if (!token.isToken(name)) return error.InvalidMethod; return .{ .name = name };}
/// Which of the standard methods this is, or null for anything else —/// `PROPFIND`, `QUERY`, a private extension, or a lower-case `get`.pub fn known(m: Method) ?Known { return std.meta.stringToEnum(Known, m.name);}
/// Exact comparison, because methods are case-sensitive.pub fn eql(a: Method, b: Method) bool { return std.mem.eql(u8, a.name, b.name);}
/// Whether a request with this method is understood to leave the server as it/// found it (RFC 9110 §9.2.1). An unknown method is not assumed safe.pub fn isSafe(m: Method) bool { const k = m.known() orelse return false; return switch (k) { .GET, .HEAD, .OPTIONS, .TRACE => true, .POST, .PUT, .DELETE, .CONNECT, .PATCH => false, };}
/// Whether repeating the request has the same effect as making it once (RFC/// 9110 §9.2.2). An unknown method is not assumed idempotent.pub fn isIdempotent(m: Method) bool { const k = m.known() orelse return false; return switch (k) { .GET, .HEAD, .PUT, .DELETE, .OPTIONS, .TRACE => true, .POST, .CONNECT, .PATCH => false, };}
/// Whether a response to this method may be stored by a cache, absent any/// explicit cache directive (RFC 9110 §9.2.3).pub fn isCacheable(m: Method) bool { const k = m.known() orelse return false; return switch (k) { .GET, .HEAD => true, else => false, };}
/// Whether a response to this method carries a body.////// This is not about whether the resource has one. A `HEAD` response carries/// the `Content-Length` the matching `GET` would have had and then stops, so/// that a client can learn the length without the bytes; the server must/// frame the response as though a body were coming and send none of it. That/// asymmetry is the whole reason this predicate exists and is checked at the/// point the body is written rather than where the handler runs.pub fn responseHasBody(m: Method) bool { const k = m.known() orelse return true; return switch (k) { .HEAD => false, else => true, };}
/// Writes the method as it goes on the wire, so that one can be printed with/// `{f}`.pub fn format(m: Method, w: *std.Io.Writer) std.Io.Writer.Error!void { try w.writeAll(m.name);}
test known { try std.testing.expectEqual(Known.GET, get.known().?); try std.testing.expect((try parse("PROPFIND")).known() == null); // Case-sensitive: a lower-case spelling is an extension method, not GET. try std.testing.expect((try parse("get")).known() == null);}
test parse { try std.testing.expectError(error.InvalidMethod, parse("")); try std.testing.expectError(error.InvalidMethod, parse("GET ")); try std.testing.expectError(error.InvalidMethod, parse("G\x00T")); try std.testing.expectEqualStrings("QUERY", (try parse("QUERY")).name);}
test responseHasBody { try std.testing.expect(!head.responseHasBody()); try std.testing.expect(get.responseHasBody()); // An unknown method is assumed to want a body, since the alternative is // silently dropping one the handler meant to send. try std.testing.expect((try parse("PROPFIND")).responseHasBody());}
test eql { try std.testing.expect(get.eql(try parse("GET"))); // Methods are case-sensitive, so this is a different method. try std.testing.expect(!get.eql(try parse("get")));}
test isSafe { try std.testing.expect(get.isSafe()); try std.testing.expect(options.isSafe()); try std.testing.expect(!post.isSafe()); // An extension method is not trusted to be harmless. try std.testing.expect(!(try parse("PROPFIND")).isSafe());}
test isIdempotent { try std.testing.expect(put.isIdempotent()); try std.testing.expect(delete.isIdempotent()); try std.testing.expect(!post.isIdempotent()); try std.testing.expect(!patch.isIdempotent());}
test isCacheable { try std.testing.expect(get.isCacheable()); try std.testing.expect(head.isCacheable()); try std.testing.expect(!post.isCacheable());}
test format { var buf: [32]u8 = undefined; const line = try std.fmt.bufPrint(&buf, "{f} /index.html", .{post}); try std.testing.expectEqualStrings("POST /index.html", line);}