(** HTTP methods following RFC 7231 *)

(** Log source for method operations *)
val src : Logs.Src.t

(** HTTP method type using polymorphic variants for better composability *)
type t = [
  | `GET      (** Retrieve a resource *)
  | `POST     (** Submit data to be processed *)
  | `PUT      (** Replace a resource *)
  | `DELETE   (** Delete a resource *)
  | `HEAD     (** Retrieve headers only *)
  | `OPTIONS  (** Retrieve allowed methods *)
  | `PATCH    (** Partial resource modification *)
  | `CONNECT  (** Establish tunnel to server *)
  | `TRACE    (** Echo received request *)
  | `Other of string  (** Non-standard or extension method *)
]

(** {1 Conversion Functions} *)

val to_string : t -> string
(** Convert method to uppercase string representation *)

val of_string : string -> t
(** Parse method from string (case-insensitive).
    Returns [`Other s] for unrecognized methods. *)

val pp : Format.formatter -> t -> unit
(** Pretty printer for methods *)

(** {1 Method Properties} *)

val is_safe : t -> bool
(** Returns true for safe methods (GET, HEAD, OPTIONS, TRACE).
    Safe methods should not have side effects. *)

val is_idempotent : t -> bool
(** Returns true for idempotent methods (GET, HEAD, PUT, DELETE, OPTIONS, TRACE).
    Idempotent methods can be called multiple times with the same result. *)

val has_request_body : t -> bool
(** Returns true for methods that typically have a request body (POST, PUT, PATCH) *)

val is_cacheable : t -> bool
(** Returns true for methods whose responses are cacheable by default (GET, HEAD, POST).
    Note: POST is only cacheable with explicit cache headers. *)

(** {1 Comparison} *)

val equal : t -> t -> bool
(** Compare two methods for equality *)

val compare : t -> t -> int
(** Compare two methods for ordering *)