My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** HTTP response handling
2
3 This module represents HTTP responses and provides functions to access
4 status codes, headers, and response bodies. Responses support streaming
5 to efficiently handle large payloads.
6
7 {2 Examples}
8
9 {[
10 (* Check response status *)
11 if Response.ok response then
12 Printf.printf "Success!\n"
13 else
14 Printf.printf "Error: %d\n" (Response.status_code response);
15
16 (* Access headers *)
17 match Response.content_type response with
18 | Some mime -> Printf.printf "Type: %s\n" (Mime.to_string mime)
19 | None -> ()
20
21 (* Stream response body *)
22 let body = Response.body response in
23 Eio.Flow.copy body (Eio.Flow.buffer_sink buffer)
24
25 (* Response automatically closes when the switch is released *)
26 ]}
27
28 {b Note}: Responses are automatically closed when the switch they were
29 created with is released. Manual cleanup is not necessary.
30*)
31
32open Eio
33
34(** Log source for response operations *)
35val src : Logs.Src.t
36
37type t
38(** Abstract response type representing an HTTP response. *)
39
40val make : sw:Eio.Switch.t -> status:int -> headers:Headers.t ->
41 body:Eio.Flow.source_ty Eio.Resource.t -> url:string -> elapsed:float -> t
42(** [make ~sw ~status ~headers ~body ~url ~elapsed] creates a response.
43 Internal function primarily used for caching. *)
44
45(** {1 Status Information} *)
46
47val status : t -> Status.t
48(** [status response] returns the HTTP status as a {!Status.t} value. *)
49
50val status_code : t -> int
51(** [status_code response] returns the HTTP status code as an integer (e.g., 200, 404). *)
52
53val ok : t -> bool
54(** [ok response] returns [true] if the status code is in the 2xx success range.
55 This is an alias for {!Status.is_success}. *)
56
57(** {1 Header Access} *)
58
59val headers : t -> Headers.t
60(** [headers response] returns all response headers. *)
61
62val header : string -> t -> string option
63(** [header name response] returns the value of a specific header, or [None] if not present.
64 Header names are case-insensitive. *)
65
66val content_type : t -> Mime.t option
67(** [content_type response] returns the parsed Content-Type header as a MIME type,
68 or [None] if the header is not present or cannot be parsed. *)
69
70val content_length : t -> int64 option
71(** [content_length response] returns the Content-Length in bytes,
72 or [None] if not specified or chunked encoding is used. *)
73
74val location : t -> string option
75(** [location response] returns the Location header value, typically used in redirects.
76 Returns [None] if the header is not present. *)
77
78(** {1 Response Metadata} *)
79
80val url : t -> string
81(** [url response] returns the final URL after following any redirects.
82 This may differ from the originally requested URL. *)
83
84val elapsed : t -> float
85(** [elapsed response] returns the time taken for the request in seconds,
86 including connection establishment, sending the request, and receiving headers. *)
87
88(** {1 Response Body} *)
89
90val body : t -> Flow.source_ty Resource.t
91(** [body response] returns the response body as an Eio flow for streaming.
92 This allows efficient processing of large responses without loading them
93 entirely into memory.
94
95 Example:
96 {[
97 let body = Response.body response in
98 let buffer = Buffer.create 4096 in
99 Eio.Flow.copy body (Eio.Flow.buffer_sink buffer);
100 Buffer.contents buffer
101 ]}
102*)
103
104
105(** {1 Pretty Printing} *)
106
107val pp : Format.formatter -> t -> unit
108(** Pretty print a response summary *)
109
110val pp_detailed : Format.formatter -> t -> unit
111(** Pretty print a response with full headers *)
112
113(** {1 Private API} *)
114
115(** Internal functions exposed for use by other modules in the library.
116 These are not part of the public API and may change between versions. *)
117module Private : sig
118 val make :
119 sw:Eio.Switch.t ->
120 status:int ->
121 headers:Headers.t ->
122 body:Flow.source_ty Resource.t ->
123 url:string ->
124 elapsed:float ->
125 t
126 (** [make ~sw ~status ~headers ~body ~url ~elapsed] constructs a response.
127 The response will be automatically closed when the switch is released.
128 This function is used internally by the Client module. *)
129end