// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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); }