jon.recoil.org
forked from
anil.recoil.org/monopam-myspace
My aggregated monorepo of OCaml code, automaintained
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** HTTP request methods per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-9}RFC 9110 Section 9}
7
8 HTTP methods indicate the desired action to be performed on a resource.
9 The method token is case-sensitive.
10
11 {2 Safe Methods}
12
13 Methods are considered "safe" if their semantics are read-only (GET, HEAD,
14 OPTIONS, TRACE). Per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.1}RFC 9110 Section 9.2.1}.
15
16 {2 Idempotent Methods}
17
18 A method is "idempotent" if multiple identical requests have the same effect
19 as a single request (GET, HEAD, PUT, DELETE, OPTIONS, TRACE).
20 Per {{:https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2}RFC 9110 Section 9.2.2}. *)
21
22(** Log source for method operations *)
23val src : Logs.Src.t
24
25(** HTTP method type using polymorphic variants for better composability *)
26type t = [
27 | `GET (** Retrieve a resource *)
28 | `POST (** Submit data to be processed *)
29 | `PUT (** Replace a resource *)
30 | `DELETE (** Delete a resource *)
31 | `HEAD (** Retrieve headers only *)
32 | `OPTIONS (** Retrieve allowed methods *)
33 | `PATCH (** Partial resource modification *)
34 | `CONNECT (** Establish tunnel to server *)
35 | `TRACE (** Echo received request *)
36 | `Other of string (** Non-standard or extension method *)
37]
38
39(** {1 Conversion Functions} *)
40
41val to_string : t -> string
42(** Convert method to uppercase string representation *)
43
44val of_string : string -> t
45(** Parse method from string (case-insensitive).
46 Returns [`Other s] for unrecognized methods. *)
47
48val pp : Format.formatter -> t -> unit
49(** Pretty printer for methods *)
50
51(** {1 Method Properties} *)
52
53val is_safe : t -> bool
54(** Returns true for safe methods (GET, HEAD, OPTIONS, TRACE).
55 Safe methods should not have side effects. *)
56
57val is_idempotent : t -> bool
58(** Returns true for idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS, TRACE).
59 Idempotent methods can be called multiple times with the same result. *)
60
61val has_request_body : t -> bool
62(** Returns true for methods that typically have a request body (POST, PUT, PATCH) *)
63
64val is_cacheable : t -> bool
65(** Returns true for methods whose responses are cacheable by default (GET, HEAD, POST).
66 Note: POST is only cacheable with explicit cache headers. *)
67
68(** {1 Comparison} *)
69
70val equal : t -> t -> bool
71(** Compare two methods for equality *)
72
73val compare : t -> t -> int
74(** Compare two methods for ordering *)