gazagnaire.org
forked from
anil.recoil.org/ocaml-requests
A batteries included HTTP/1.1 client in OCaml
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** HTTP methods following RFC 7231 *)
7
8(** Log source for method operations *)
9val src : Logs.Src.t
10
11(** HTTP method type using polymorphic variants for better composability *)
12type t = [
13 | `GET (** Retrieve a resource *)
14 | `POST (** Submit data to be processed *)
15 | `PUT (** Replace a resource *)
16 | `DELETE (** Delete a resource *)
17 | `HEAD (** Retrieve headers only *)
18 | `OPTIONS (** Retrieve allowed methods *)
19 | `PATCH (** Partial resource modification *)
20 | `CONNECT (** Establish tunnel to server *)
21 | `TRACE (** Echo received request *)
22 | `Other of string (** Non-standard or extension method *)
23]
24
25(** {1 Conversion Functions} *)
26
27val to_string : t -> string
28(** Convert method to uppercase string representation *)
29
30val of_string : string -> t
31(** Parse method from string (case-insensitive).
32 Returns [`Other s] for unrecognized methods. *)
33
34val pp : Format.formatter -> t -> unit
35(** Pretty printer for methods *)
36
37(** {1 Method Properties} *)
38
39val is_safe : t -> bool
40(** Returns true for safe methods (GET, HEAD, OPTIONS, TRACE).
41 Safe methods should not have side effects. *)
42
43val is_idempotent : t -> bool
44(** Returns true for idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS, TRACE).
45 Idempotent methods can be called multiple times with the same result. *)
46
47val has_request_body : t -> bool
48(** Returns true for methods that typically have a request body (POST, PUT, PATCH) *)
49
50val is_cacheable : t -> bool
51(** Returns true for methods whose responses are cacheable by default (GET, HEAD, POST).
52 Note: POST is only cacheable with explicit cache headers. *)
53
54(** {1 Comparison} *)
55
56val equal : t -> t -> bool
57(** Compare two methods for equality *)
58
59val compare : t -> t -> int
60(** Compare two methods for ordering *)