(** ETag parsing and comparison per RFC 7232. *)

(** Entity tag. Record pointing into the parse buffer.
    The [off] and [len] fields reference the opaque-tag content without quotes. *)
type t =
  { weak : bool   (** [true] if prefixed with W/ *)
  ; off : int     (** Offset of tag content (after opening quote) *)
  ; len : int     (** Length of tag content (excluding quotes) *)
  }

(** Parse status. *)
type status =
  | Valid    (** Successfully parsed *)
  | Invalid  (** Invalid ETag syntax *)

(** Parse a single ETag value from a span.
    Accepts formats: ["xyzzy"], [W/"xyzzy"], [""]
    Returns (status, tag) - tag is only valid if status = Valid. *)
val parse : Base_bigstring.t -> Span.t -> status * t

(** Empty/invalid ETag constant. *)
val empty : t

(** Parse ETag to string (allocates). Useful for storage/comparison. *)
val to_string : Base_bigstring.t -> t -> string

(** {2 If-Match / If-None-Match Parsing} *)

(** Result of parsing If-Match or If-None-Match header. *)
type match_condition =
  | Any           (** "*" - matches any entity *)
  | Tags          (** List of entity tags - use [get_tags] to retrieve *)
  | Empty         (** No valid tags found *)

(** Maximum number of ETags that can be parsed from a header. *)
val max_tags : int

(** Parse If-Match or If-None-Match header value.
    Handles "*" and comma-separated lists of entity tags.
    Tags are stored in the provided array (up to [max_tags]).
    Returns (condition, count) where count is number of tags if Tags. *)
val parse_match_header
  :  Base_bigstring.t
  -> Span.t
  -> t array
  -> match_condition * int

(** {2 Comparison Functions} *)

(** Strong comparison per RFC 7232 Section 2.3.2. *)
val strong_match : Base_bigstring.t -> t -> t -> bool

(** Weak comparison per RFC 7232 Section 2.3.2. *)
val weak_match : Base_bigstring.t -> t -> t -> bool

(** Check if an etag matches any in array (weak comparison). *)
val matches_any_weak : Base_bigstring.t -> t -> t array -> count:int -> bool

(** Check if an etag matches any in array (strong comparison). *)
val matches_any_strong : Base_bigstring.t -> t -> t array -> count:int -> bool

(** {2 Response Writing} *)

(** Write ETag header: [ETag: "tag"\r\n] or [ETag: W/"tag"\r\n]. *)
val write_etag : Base_bigstring.t -> off:int -> t -> Base_bigstring.t -> int

(** Write ETag header from string value. *)
val write_etag_string : Base_bigstring.t -> off:int -> weak:bool -> string -> int

(** Pretty-print etag. *)
val pp : Base_bigstring.t -> Stdlib.Format.formatter -> t -> unit