anil.recoil.org
A batteries included HTTP/1.1 client in OCaml
1{
2 "recommendations": [
3 {
4 "source_repo": "third_party/php/httplug",
5 "source_language": "PHP",
6 "criticality": "medium",
7 "change_type": "enhancement",
8 "title": "Add request context preservation in exceptions",
9 "description": "HTTPlug exceptions carry both the request and response objects via RequestAwareTrait, allowing users to inspect the original request that failed. The OCaml library error types contain URLs and status codes but lack access to the full request headers and body. Adding a request context to error variants would help with debugging and retry logic that needs to inspect what was sent.",
10 "affected_files": [
11 "lib/error.mli",
12 "lib/error.ml"
13 ],
14 "rationale": "HTTPlug RequestAwareTrait pattern allows exceptions to carry the full PSR-7 RequestInterface enabling detailed error analysis and retry strategies. The OCaml library currently only stores URLs in some error variants. Adding optional request metadata like method headers and sanitized body preview to error variants would improve debuggability without creating circular dependencies."
15 },
16 {
17 "source_repo": "third_party/php/httplug",
18 "source_language": "PHP",
19 "criticality": "medium",
20 "change_type": "enhancement",
21 "title": "Add response access in HTTP error exceptions",
22 "description": "HTTPlug HttpException provides getResponse to access the response object when HTTP errors occur. This allows users to examine response headers and body for error details. The OCaml library stores body_preview and headers in Http_error but Response.raise_for_status discards the response. Adding a variant that preserves response access would improve error handling.",
23 "affected_files": [
24 "lib/response.mli",
25 "lib/response.ml",
26 "lib/error.mli",
27 "lib/error.ml"
28 ],
29 "rationale": "HTTPlug HttpException.getResponse enables access to server error messages in response bodies and error-specific headers. While the OCaml library captures body_preview in Http_error Response.raise_for_status does not provide a way to access the full response after the exception is raised. Adding a result-based API or exception variant that preserves the response would enable better error message extraction."
30 },
31 {
32 "source_repo": "third_party/php/httplug",
33 "source_language": "PHP",
34 "criticality": "low",
35 "change_type": "enhancement",
36 "title": "Add standardized error message formatting",
37 "description": "HTTPlug HttpException.create provides a factory method that generates normalized error messages with a consistent format including URL HTTP method status code and reason phrase. The OCaml library to_string function could benefit from a similar standardized formatting approach for consistency across error types.",
38 "affected_files": [
39 "lib/error.ml"
40 ],
41 "rationale": "HTTPlug normalized error messages provide consistent parseable error output. The OCaml library Error.to_string already provides human-readable messages but adopting a more structured format with labeled fields would improve log parsing and error analysis tools."
42 },
43 {
44 "source_repo": "third_party/php/httplug",
45 "source_language": "PHP",
46 "criticality": "low",
47 "change_type": "enhancement",
48 "title": "Consider promise-based async API for advanced use cases",
49 "description": "HTTPlug provides HttpAsyncClient with promise-based asynchronous requests alongside synchronous APIs. While the OCaml library uses Eio fibers for concurrency which is idiomatic for OCaml 5, adding promise-like combinators for common async patterns like all race and timeout could improve ergonomics for complex concurrent request scenarios.",
50 "affected_files": [
51 "lib/requests.mli",
52 "lib/requests.ml"
53 ],
54 "rationale": "HTTPlug HttpAsyncClient with HttpFulfilledPromise and HttpRejectedPromise provides composable async operations. The OCaml library correctly uses Eio.Fiber for concurrency and documents Fiber.both and all patterns. However adding higher-level combinators like Requests.all and Requests.race could reduce boilerplate for common concurrent patterns while maintaining the Eio foundation."
55 },
56 {
57 "source_repo": "third_party/php/httplug",
58 "source_language": "PHP",
59 "criticality": "high",
60 "change_type": "security",
61 "title": "Ensure PSR-18 NetworkException compliance for network errors",
62 "description": "HTTPlug NetworkException implements PSR-18 NetworkExceptionInterface specifically for network failures where no response was received. The OCaml library should ensure clear distinction between connection errors like Dns_resolution_failed Tcp_connect_failed and Tls_handshake_failed versus HTTP protocol errors to align with this standard pattern.",
63 "affected_files": [
64 "lib/error.mli",
65 "lib/error.ml"
66 ],
67 "rationale": "PSR-18 NetworkExceptionInterface represents request cannot be completed because of network issues with no response available. The OCaml library already has granular connection error types and an is_connection query function. Documentation should emphasize this distinction to help users handle network versus HTTP errors appropriately matching the PSR-18 contract."
68 },
69 {
70 "source_repo": "third_party/php/httplug",
71 "source_language": "PHP",
72 "criticality": "medium",
73 "change_type": "enhancement",
74 "title": "Add exception chaining for wrapped errors",
75 "description": "HTTPlug exceptions accept an optional previous Exception parameter enabling exception chaining to preserve the underlying error cause. The OCaml library Eio.Io exceptions support backtraces but could benefit from explicit error chaining for wrapped network and TLS errors to preserve the full error context.",
76 "affected_files": [
77 "lib/error.mli",
78 "lib/error.ml",
79 "lib/http_client.ml"
80 ],
81 "rationale": "HTTPlug exception constructors include optional previous parameter for error chaining like wrapping socket errors in NetworkException. The OCaml library uses Eio.Io exceptions which capture backtraces but some error variants like Tls_handshake_failed and Tcp_connect_failed only store string reasons. Storing the underlying exn in a variant field would preserve full error context for debugging."
82 },
83 {
84 "source_repo": "third_party/php/httplug",
85 "source_language": "PHP",
86 "criticality": "low",
87 "change_type": "feature",
88 "title": "Add middleware plugin architecture for request response transformation",
89 "description": "HTTPlug ecosystem provides a plugin architecture for decorating HTTP clients with middleware like retry authentication and logging. While the OCaml library has built-in retry and auth adding a plugin middleware system would enable user extensions without modifying library code.",
90 "affected_files": [
91 "lib/requests.mli",
92 "lib/requests.ml",
93 "lib/one.mli",
94 "lib/one.ml"
95 ],
96 "rationale": "HTTPlug success partly comes from its plugin decorator pattern. The OCaml library has built-in retry auth and decompression but does not expose extension points for custom request response transformation. Adding optional middleware hooks like before_request and after_response callbacks would enable user extensions like custom logging request signing or metric collection."
97 },
98 {
99 "source_repo": "third_party/php/httplug",
100 "source_language": "PHP",
101 "criticality": "medium",
102 "change_type": "enhancement",
103 "title": "Improve testing support with mock stub utilities",
104 "description": "HTTPlug test suite uses phpspec with mock Request Response objects demonstrating good interface testability. The OCaml library could benefit from documented testing patterns or mock utilities to help users write tests without making real HTTP requests.",
105 "affected_files": [
106 "test/test_simple.ml",
107 "lib/requests.mli"
108 ],
109 "rationale": "HTTPlug test specs show how to test HTTP client code using mocks for RequestInterface and ResponseInterface. The OCaml library has Alcotest tests but primarily tests real HTTP behavior. Adding documented mock patterns like a Test module with mock responses or guidance on using Eio_mock.Backend would help library users write testable HTTP client code."
110 },
111 {
112 "source_repo": "third_party/php/httplug",
113 "source_language": "PHP",
114 "criticality": "low",
115 "change_type": "enhancement",
116 "title": "Add comprehensive error type documentation with usage examples",
117 "description": "HTTPlug exception hierarchy is well-documented with clear inheritance like TransferException extending to RequestException then HttpException and NetworkException. The OCaml library has excellent error documentation but could add more examples of how to pattern match on error types for different retry recovery strategies.",
118 "affected_files": [
119 "lib/error.mli"
120 ],
121 "rationale": "HTTPlug documentation clearly explains the exception hierarchy and when each type is raised. The OCaml library Error module has good query functions like is_retryable and is_connection but could expand documentation with concrete examples of error handling patterns such as retry on is_retryable different backoff for is_timeout versus is_connection and logging for is_security_error."
122 },
123 {
124 "source_repo": "third_party/php/httplug",
125 "source_language": "PHP",
126 "criticality": "medium",
127 "change_type": "enhancement",
128 "title": "Add builder pattern for complex request configuration",
129 "description": "While HTTPlug uses PSR-7 request objects that can be built separately from client invocation the OCaml library could benefit from a request builder pattern for complex requests with many optional parameters especially for the One module verbose signatures.",
130 "affected_files": [
131 "lib/one.mli",
132 "lib/one.ml",
133 "lib/requests.mli"
134 ],
135 "rationale": "HTTPlug separates request creation using PSR-7 RequestInterface from sending via sendRequest or sendAsyncRequest. The OCaml library One module functions have many optional parameters like 14 plus in one.request. Adding a Request.t builder type with a fluent API like Request.make url piped to with_headers with_body with_timeout would improve ergonomics for complex requests while maintaining backward compatibility."
136 }
137 ]
138}