···

       
5
       
 
       
successfully abstracts TLS configuration and CA certificate complexity while

     

       
6
       
 
       
providing a clean Eio-style API.

     

       
7
       
 
       


     

       
8
       
-
       
### Key Implementation Details

     

       
9
       
 
       


     

       
10
       
-
       
1. **Module Organization**:

     

       
11
       
-
       
   - Auth module must be defined before Config in both .mli and .ml files (Config references Auth.t)

     

       
12
       
-
       
   - ConnectionPool uses a GADT to hide the network type parameter

     

       
13
       
-
       
   - Session and PoolManager use internal type aliases to avoid naming conflicts

     

       
14
       
-
       


     

       
15
       
-
       
2. **Buffer Size Limitations**:

     

       
16
       
-
       
   - Cannot use `Int.max_int` for Eio buffer sizes (causes Bigarray creation errors)

     

       
17
       
-
       
   - Use reasonable sizes like `16 * 1024 * 1024` (16MB) for buffer creation

     

       
18
       
-
       
   - When converting Cohttp_eio body to Buf_read, always specify max_size

     

       
19
       
-
       


     

       
20
       
-
       
3. **Type Constraints**:

     

       
21
       
-
       
   - Network types use polymorphic variants: `[> \`Generic] Net.t`

     

       
22
       
-
       
   - Cannot use wildcard `_` in type declarations

     

       
23
       
-
       
   - Use GADTs or existential types when hiding type parameters in module signatures

     

       
24
       
-
       


     

       
25
       
-
       
4. **Build Commands**:

     

       
26
       
-
       
   - Development build: `opam exec -- dune build @check`

     

       
27
       
-
       
   - Release build (ignores warnings): `opam exec -- dune build @check --profile=release`

     

       
28
       
-
       
   - Documentation: `opam exec -- dune build @doc`

     

       
29
       
-
       


     

       
30
       
-
       
### Implemented Features

     

       
31
       
-
       


     

       
32
       
-
       
#### Core (urllib3-inspired):

     

       
33
       
-
       
- ✅ Per-host connection pooling with configurable limits

     

       
34
       
-
       
- ✅ Automatic retries with exponential backoff (default 10 retries)

     

       
35
       
-
       
- ✅ Advanced timeout handling (connect, read, total)

     

       
36
       
-
       
- ✅ HTTP caching with Cache-Control support

     

       
37
       
-
       
- ✅ Progress tracking via OCaml Logs

     

       
38
       
-
       
- ✅ Cookie handling in sessions

     

       
39
       
-
       


     

       
40
       
-
       
#### Authentication (requests-inspired):

     

       
41
       
-
       
- ✅ Basic authentication

     

       
42
       
-
       
- ✅ Digest authentication (RFC 2617)

     

       
43
       
-
       
- ✅ Bearer token (OAuth 2.0)

     

       
44
       
-
       
- ✅ OAuth 1.0a support

     

       
45
       
-
       
- ✅ OAuth 2.0 support

     

       
46
       
-
       
- ✅ Custom authentication handlers

     

       
47
       
-
       


     

       
48
       
-
       
#### Streaming:

     

       
49
       
-
       
- ✅ Upload streaming with Eio Flow sources

     

       
50
       
-
       
- ✅ Download streaming with Eio Flow sinks

     

       
51
       
-
       
- ✅ Response iteration (chunked/line-based)

     

       
52
       
-
       


     

       
53
       
-
       
### TODO - Future Work

     

       
54
       
-
       


     

       
55
       
-
       
1. **High Priority** (Core functionality):

     

       
56
       
-
       
   - [ ] Fix remaining build issues in lib/ruminant.ml (Github.Api.Https module)

     

       
57
       
-
       
   - [ ] Fix bin/main.ml (data.issues field issue)

     

       
58
       
-
       
   - [ ] Complete OAuth implementation (currently stubbed)

     

       
59
       
-
       
   - [ ] Implement actual HTTP caching storage (memory/file backends partially done)

     

       
60
       
-
       
   - [ ] Add proper connection pool lifecycle management

     

       
61
       
-
       


     

       
62
       
-
       
2. **Medium Priority** (Enhanced features from DESIGN.md):

     

       
63
       
-
       
   - [ ] Implement hooks system for request/response middleware

     

       
64
       
-
       
   - [ ] Add SOCKS proxy support (design in DESIGN.md)

     

       
65
       
-
       
   - [ ] Implement character encoding detection and conversion

     

       
66
       
-
       
   - [ ] Add compression support (gzip, deflate, brotli when available)

     

       
67
       
-
       
   - [ ] Implement proper multipart form data encoding

     

       
68
       
-
       


     

       
69
       
-
       
3. **Low Priority** (Advanced features):

     

       
70
       
-
       
   - [ ] WebSocket support

     

       
71
       
-
       
   - [ ] HTTP/2 support (when cohttp-eio adds it)

     

       
72
       
-
       
   - [ ] HTTP/3 support (future)

     

       
73
       
-
       
   - [ ] Connection persistence and keep-alive optimization

     

       
74
       
-
       
   - [ ] Advanced certificate pinning

     

       
75
       
-
       


     

       
76
       
-
       
4. **Testing & Documentation**:

     

       
77
       
-
       
   - [ ] Add comprehensive test suite for requests library

     

       
78
       
-
       
   - [ ] Create examples directory with common use cases

     

       
79
       
-
       
   - [ ] Write API documentation and usage guide

     

       
80
       
-
       
   - [ ] Add benchmarks comparing with Python requests

     

       
81
       
-
       


     

       
82
       
-
       
### Known Issues

     

       
83
       
-
       


     

       
84
       
-
       
2. **Type Shadowing**: Module-level type `t` can cause shadowing issues in nested modules. Use unique type names or GADTs to avoid conflicts.

     

       
85
       
-
       


     

       
86
       
-
       
3. **Module Dependencies**: Auth module must come before Config in the interface due to Config's create function taking an Auth.t parameter.

     

       
87
       
-
       


     

       
88
       
-
       
4. **Warnings**: Many unused variables in stub implementations need cleanup once features are fully implemented.

     

···

       
5
       
 
       
successfully abstracts TLS configuration and CA certificate complexity while

     

       
6
       
 
       
providing a clean Eio-style API.

     

       
7
       
 
       


     

       
8
       
+
       
As a matter of good hygeine, dont import Requests at the top of the test files but use it when needed or do a local open

     

       
9
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

···

       
1
       
 
       
(library

     

       
2
       
 
       
 (public_name requests)

     

       
3
       
 
       
 (name requests)

     

       
4
       
-
       
 (modules :standard \ digest_auth requests_cache requests_types)

     

       
5
       
 
       
 (libraries

     

       
6
       
 
       
  eio

     

       
7
       
 
       
  eio.unix

     

···

       
1
       
 
       
(library

     

       
2
       
 
       
 (public_name requests)

     

       
3
       
 
       
 (name requests)

     

       
4
       
+
       
 (modules :standard \ digest_auth)

     

       
5
       
 
       
 (libraries

     

       
6
       
 
       
  eio

     

       
7
       
 
       
  eio.unix

     

···

       
14
       
 
       
module Status = Status

     

       
15
       
 
       
module Error = Error

     

       
16
       
 
       
module Retry = Retry

     

       
0
       
 
       

     

       
17
       
 
       


     

       
18
       
 
       
(* Main API - Session functionality with concurrent fiber spawning *)

     

       
19
       
 
       


     

···

       
14
       
 
       
module Status = Status

     

       
15
       
 
       
module Error = Error

     

       
16
       
 
       
module Retry = Retry

     

       
17
       
+
       
module Cache = Requests_cache

     

       
18
       
 
       


     

       
19
       
 
       
(* Main API - Session functionality with concurrent fiber spawning *)

     

       
20
       
 
       


     

···

       
542
       
 
       
(** Timeout configuration for requests *)

     

       
543
       
 
       
module Timeout = Timeout

     

       
544
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
545
       
 
       
(** {2 Logging} *)

     

       
546
       
 
       


     

       
547
       
 
       
(** Log source for the requests library.

     

···

       
542
       
 
       
(** Timeout configuration for requests *)

     

       
543
       
 
       
module Timeout = Timeout

     

       
544
       
 
       


     

       
545
       
+
       
(** HTTP caching with cache control and range request support *)

     

       
546
       
+
       
module Cache = Requests_cache

     

       
547
       
+
       


     

       
548
       
 
       
(** {2 Logging} *)

     

       
549
       
 
       


     

       
550
       
 
       
(** Log source for the requests library.

     

···

       
282
       
 
       
        (* Store metadata *)

     

       
283
       
 
       
        let metadata_key = key ^ ".meta" in

     

       
284
       
 
       
        let metadata = serialize_metadata ~status ~headers in

     

       
285
       
-
       
        let metadata_source = Flow.string_source metadata in

     

       
286
       
 
       
        Cacheio.put cache ~key:metadata_key ~source:metadata_source ~ttl ();

     

       
287
       
 
       


     

       
288
       
 
       
        (* Store body directly from source *)

     
···

       
354
       
 
       
           let rec read_chunks () =

     

       
355
       
 
       
             let chunk = Cstruct.create 8192 in

     

       
356
       
 
       
             try

     

       
357
       
-
       
               let n = Flow.single_read source chunk in

     

       
358
       
 
       
               if n > 0 then begin

     

       
359
       
 
       
                 on_chunk (Cstruct.to_string ~off:0 ~len:n chunk);

     

       
360
       
 
       
                 read_chunks ()

     
···

       
369
       
 
       
             let rec read_chunk () =

     

       
370
       
 
       
               let chunk = Cstruct.create 8192 in

     

       
371
       
 
       
               try

     

       
372
       
-
       
                 let n = Flow.single_read source chunk in

     

       
373
       
 
       
                 if n > 0 then begin

     

       
374
       
 
       
                   on_chunk (Cstruct.to_string ~off:0 ~len:n chunk);

     

       
375
       
 
       
                   read_chunk ()

     

···

       
282
       
 
       
        (* Store metadata *)

     

       
283
       
 
       
        let metadata_key = key ^ ".meta" in

     

       
284
       
 
       
        let metadata = serialize_metadata ~status ~headers in

     

       
285
       
+
       
        let metadata_source = Eio.Flow.string_source metadata in

     

       
286
       
 
       
        Cacheio.put cache ~key:metadata_key ~source:metadata_source ~ttl ();

     

       
287
       
 
       


     

       
288
       
 
       
        (* Store body directly from source *)

     
···

       
354
       
 
       
           let rec read_chunks () =

     

       
355
       
 
       
             let chunk = Cstruct.create 8192 in

     

       
356
       
 
       
             try

     

       
357
       
+
       
               let n = Eio.Flow.single_read source chunk in

     

       
358
       
 
       
               if n > 0 then begin

     

       
359
       
 
       
                 on_chunk (Cstruct.to_string ~off:0 ~len:n chunk);

     

       
360
       
 
       
                 read_chunks ()

     
···

       
369
       
 
       
             let rec read_chunk () =

     

       
370
       
 
       
               let chunk = Cstruct.create 8192 in

     

       
371
       
 
       
               try

     

       
372
       
+
       
                 let n = Eio.Flow.single_read source chunk in

     

       
373
       
 
       
                 if n > 0 then begin

     

       
374
       
 
       
                   on_chunk (Cstruct.to_string ~off:0 ~len:n chunk);

     

       
375
       
 
       
                   read_chunk ()