Header_parsingHTTP Header Value Parsing
This module provides parsing and generation functions for complex HTTP header values that go beyond simple strings.
The Content-Range header indicates which part of a representation is enclosed when a 206 (Partial Content) response is returned.
val content_range_to_string : content_range -> stringcontent_range_to_string cr formats a content range as a header value.
Example: "bytes 0-499/1234"
val parse_content_range : string -> content_range optionparse_content_range s parses a Content-Range header value.
Returns None if the value cannot be parsed.
Examples:
"bytes 0-499/1234" -> Some \{unit="bytes"; range=Some(0,499); complete_length=Some 1234\}"bytes */1234" -> Some \{unit="bytes"; range=None; complete_length=Some 1234\}val make_content_range :
start:int64 ->
end_:int64 ->
complete_length:int64 ->
content_rangemake_content_range ~start ~end_ ~complete_length creates a Content-Range value for a byte range response.
val make_unsatisfied_range : complete_length:int64 -> content_rangemake_unsatisfied_range ~complete_length creates a Content-Range value for an unsatisfied range (416 response).
The If-Range header makes a Range request conditional. It can contain either an ETag or a Last-Modified date.
val if_range_to_string : if_range -> stringif_range_to_string ir converts an If-Range value to a string.
val parse_if_range : string -> if_range optionparse_if_range s parses an If-Range header value.
Distinguishes between ETags (contain quotes or start with W/) and HTTP-date values (start with a weekday abbreviation).
val if_range_of_etag : string -> if_rangeif_range_of_etag etag creates an If-Range value from an ETag.
val if_range_of_date : string -> if_rangeif_range_of_date date creates an If-Range value from a date string.
val if_range_is_etag : if_range -> boolif_range_is_etag ir returns true if ir is an ETag.
val if_range_is_date : if_range -> boolif_range_is_date ir returns true if ir is a date.
The Allow header lists the set of methods supported by the target resource.
val parse_allow : string -> Method.t listparse_allow s parses an Allow header value into a list of methods.
Example: "GET, HEAD, PUT" -> \`GET; \`HEAD; \`PUT
val allow_to_string : Method.t list -> stringallow_to_string methods formats a list of methods as an Allow header value.
Example: \`GET; \`HEAD -> "GET, HEAD"
val allow_contains : Method.t -> string -> boolallow_contains method_ allow_value checks if a method is in an Allow header value.
The Authentication-Info header is sent by the server after successful authentication. For Digest authentication, it provides:
type authentication_info = {nextnonce : string option;Next nonce to use for subsequent requests
*)qop : string option;Quality of protection that was used
*)rspauth : string option;Response authentication (server proves it knows the password)
*)cnonce : string option;Client nonce echoed back
*)nc : string option;Nonce count echoed back
*)}val parse_authentication_info : string -> authentication_infoparse_authentication_info s parses an Authentication-Info header value.
Example: "nextnonce=\"abc123\", qop=auth, rspauth=\"xyz789\""
val has_nextnonce : authentication_info -> boolhas_nextnonce info returns true if a new nonce is provided.
If present, the client should use this nonce for subsequent requests instead of waiting for a 401 response with a new challenge.
val get_nextnonce : authentication_info -> string optionget_nextnonce info returns the next nonce, if present.
The Retry-After header indicates how long to wait before retrying.
val parse_retry_after : string -> retry_after optionparse_retry_after s parses a Retry-After header value.
Examples:
"120" -> Some (Retry_after_seconds 120)"Fri, 31 Dec 1999 23:59:59 GMT" -> Some (Retry_after_date "...")val retry_after_to_seconds : ?now:float -> retry_after -> int optionretry_after_to_seconds ?now retry_after converts to seconds.
For Retry_after_seconds, returns the value directly. For Retry_after_date, parses the HTTP-date per RFC 9110 Section 5.6.7 and computes the difference from now. Returns 0 if the date is in the past. Returns None if the date cannot be parsed or now is not provided.
The Accept-Ranges header indicates whether the server supports range requests.
val parse_accept_ranges : string -> accept_rangesparse_accept_ranges s parses an Accept-Ranges header value.
Examples:
"bytes" -> Accept_ranges_bytes"none" -> Accept_ranges_noneval supports_byte_ranges : accept_ranges -> boolsupports_byte_ranges ar returns true if byte range requests are supported.
The Cache-Status header field indicates how caches have handled a request. It is a List structured field (RFC 8941) where each member is a cache identifier with optional parameters.
Example: Cache-Status: "Cloudflare"; hit, ExampleCDN; fwd=uri-miss; stored
type cache_status_fwd = | Fwd_uri_missThe cache did not contain any matching response
*)| Fwd_vary_missThe cache contained a response, but Vary header prevented match
*)| Fwd_missThe cache did not find a usable response (generic)
*)| Fwd_requestThe request semantics required forwarding (e.g., no-cache)
*)| Fwd_staleThe cache had a stale response that needed revalidation
*)| Fwd_partialThe cache had a partial response that needed completion
*)| Fwd_bypassThe cache was configured to bypass for this request
*)| Fwd_other of stringOther forward reason
*)Forward/stored response indicator for Cache-Status
type cache_status_entry = {cache_id : string;Identifier for the cache (e.g., "CDN", "proxy", "Cloudflare")
*)hit : bool option;True if served from cache without forwarding
*)fwd : cache_status_fwd option;Why the request was forwarded
*)fwd_status : int option;Status code from the forwarded response
*)stored : bool option;Whether the response was stored in cache
*)collapsed : bool option;Whether request was collapsed with others
*)ttl : int option;Time-to-live remaining in seconds
*)key : string option;Cache key used
*)detail : string option;Implementation-specific detail
*)}A single cache status entry from the Cache-Status header
val cache_status_fwd_of_string : string -> cache_status_fwdcache_status_fwd_of_string s parses a forward reason string.
val cache_status_fwd_to_string : cache_status_fwd -> stringcache_status_fwd_to_string fwd converts a forward reason to string.
val parse_cache_status_entry : string -> cache_status_entry optionparse_cache_status_entry s parses a single cache status entry. Format: cache-id; param1; param2=value
val parse_cache_status : string -> cache_status_entry listparse_cache_status s parses a complete Cache-Status header value.
Example: "Cloudflare; hit, CDN; fwd=uri-miss" -> list of entries
val cache_status_entry_to_string : cache_status_entry -> stringcache_status_entry_to_string entry formats a single entry.
val cache_status_to_string : cache_status_entry list -> stringcache_status_to_string entries formats entries as a header value.
val cache_status_is_hit : cache_status_entry list -> boolcache_status_is_hit entries returns true if any cache reported a hit.
val cache_status_is_stored : cache_status_entry list -> boolcache_status_is_stored entries returns true if any cache stored the response.
val cache_status_get_fwd : cache_status_entry list -> cache_status_fwd optioncache_status_get_fwd entries returns the forward reason from the first cache that forwarded the request, if any.
Content-Digest contains a digest of the content (after content coding). Repr-Digest contains a digest of the representation (before content coding).
These headers allow integrity verification of HTTP message bodies.
Example: Content-Digest: sha-256=:base64digest:
val digest_algorithm_of_string : string -> digest_algorithmdigest_algorithm_of_string s parses an algorithm name. Example: "sha-256" -> Sha256
val digest_algorithm_to_string : digest_algorithm -> stringdigest_algorithm_to_string algo converts to standard algorithm name.
type digest_value = {algorithm : digest_algorithm;The hash algorithm used
*)digest : string;The base64-encoded digest value
*)}A single digest value with its algorithm
val parse_digest_header : string -> digest_value listparse_digest_header s parses a Content-Digest or Repr-Digest header.
Example: "sha-256=:base64data:, sha-512=:base64data:" -> list of values
val digest_value_to_string : digest_value -> stringdigest_value_to_string dv formats a single digest value.
val digest_header_to_string : digest_value list -> stringdigest_header_to_string digests formats as a header value.
compute_sha256 content computes SHA-256 and returns base64-encoded result.
compute_sha512 content computes SHA-512 and returns base64-encoded result.
val compute_digest : algorithm:digest_algorithm -> string -> digest_valuecompute_digest ~algorithm content computes a digest using the specified algorithm.
val make_content_digest : ?algorithm:digest_algorithm -> string -> digest_valuemake_content_digest ?algorithm content creates a Content-Digest value. Defaults to SHA-256 which is recommended by RFC 9530.
val validate_digest : digests:digest_value list -> string -> boolvalidate_digest ~digests content validates content against provided digests. Returns true if any of the digests matches.
val get_strongest_digest : digest_value list -> digest_value optionget_strongest_digest digests returns the strongest available digest. Prefers SHA-512 over SHA-256 over others.
The Strict-Transport-Security (HSTS) header tells browsers to only access the site over HTTPS, protecting against protocol downgrade attacks and cookie hijacking.
Example: Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
type hsts = {max_age : int64;Required: Time in seconds the browser should remember HTTPS-only
*)include_subdomains : bool;If true, policy applies to all subdomains
*)preload : bool;If true, site requests inclusion in browser preload lists
*)}HSTS directive values
val parse_hsts : string -> hsts optionparse_hsts s parses a Strict-Transport-Security header value.
Returns None if the required max-age directive is missing.
Example: "max-age=31536000; includeSubDomains" -> Some \{max_age=31536000; include_subdomains=true; preload=false\}
val hsts_to_string : hsts -> stringhsts_to_string hsts formats an HSTS value as a header string.
Example: \{max_age=31536000; include_subdomains=true; preload=false\} -> "max-age=31536000; includeSubDomains"
val make_hsts :
?max_age:int64 ->
?include_subdomains:bool ->
?preload:bool ->
unit ->
hstsmake_hsts ?max_age ?include_subdomains ?preload () creates an HSTS value.
val hsts_is_enabled : hsts -> boolhsts_is_enabled hsts returns true if HSTS is effectively enabled (max-age > 0).
val hsts_one_year_subdomains : hstsOne year with subdomains - recommended for production
val hsts_preload : hstsTwo years with subdomains and preload - for HSTS preload submission
val hsts_disable : hstsDisable HSTS by setting max-age to 0