anil.recoil.org
A batteries included HTTP/1.1 client in OCaml
metadata
+19
-1
.gitignore
+19
-1
.gitignore
···
1
-
_build
1
+
# OCaml build artifacts
2
+
_build/
3
+
*.install
4
+
*.merlin
5
+
6
+
# Third-party sources (fetch locally with opam source)
7
+
third_party/
8
+
9
+
# Editor and OS files
10
+
.DS_Store
11
+
*.swp
12
+
*~
13
+
.vscode/
14
+
.idea/
15
+
16
+
# Opam local switch
17
+
_opam/
18
+
19
+
# Symlinks to local dependencies (development only)
2
20
conpool
3
21
cookeio
+1
.ocamlformat
+1
.ocamlformat
···
1
+
version=0.28.1
+53
.tangled/workflows/build.yml
+53
.tangled/workflows/build.yml
···
1
+
when:
2
+
- event: ["push", "pull_request"]
3
+
branch: ["main"]
4
+
5
+
engine: nixery
6
+
7
+
dependencies:
8
+
nixpkgs:
9
+
- shell
10
+
- stdenv
11
+
- findutils
12
+
- binutils
13
+
- libunwind
14
+
- ncurses
15
+
- opam
16
+
- git
17
+
- gawk
18
+
- gnupatch
19
+
- gnum4
20
+
- gnumake
21
+
- gnutar
22
+
- gnused
23
+
- gnugrep
24
+
- diffutils
25
+
- gzip
26
+
- bzip2
27
+
- gcc
28
+
- ocaml
29
+
- pkg-config
30
+
31
+
steps:
32
+
- name: opam
33
+
command: |
34
+
opam init --disable-sandboxing -a -y
35
+
- name: repo
36
+
command: |
37
+
opam repo add aoah https://tangled.org/anil.recoil.org/aoah-opam-repo.git
38
+
- name: switch
39
+
command: |
40
+
opam install . --confirm-level=unsafe-yes --deps-only
41
+
- name: build
42
+
command: |
43
+
opam exec -- dune build
44
+
- name: switch-test
45
+
command: |
46
+
opam install . --confirm-level=unsafe-yes --deps-only --with-test
47
+
- name: test
48
+
command: |
49
+
opam exec -- dune runtest --verbose
50
+
- name: doc
51
+
command: |
52
+
opam install -y odoc
53
+
opam exec -- dune build @doc
+15
LICENSE.md
+15
LICENSE.md
···
1
+
ISC License
2
+
3
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>
4
+
5
+
Permission to use, copy, modify, and distribute this software for any
6
+
purpose with or without fee is hereby granted, provided that the above
7
+
copyright notice and this permission notice appear in all copies.
8
+
9
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
+
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
+
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12
+
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
+
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
+
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
+
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+70
README.md
+70
README.md
···
1
+
# requests - HTTP Client Library for OCaml
2
+
3
+
A modern HTTP(S) client library for OCaml with Eio support, providing a clean API for making web requests with automatic TLS/CA certificate handling. Inspired by Python's requests library.
4
+
5
+
## Key Features
6
+
7
+
- **Clean Eio-style API**: Async I/O using OCaml 5's Eio library
8
+
- **Automatic TLS**: Built-in TLS support with automatic CA certificate handling
9
+
- **Simple Interface**: Intuitive API similar to Python's requests library
10
+
- **Type-safe**: Leverages OCaml's type system for safer HTTP operations
11
+
- **Comprehensive**: Support for common HTTP methods, headers, authentication, retries, and timeouts
12
+
13
+
## Usage
14
+
15
+
Basic GET request:
16
+
17
+
```ocaml
18
+
let () =
19
+
Eio_main.run @@ fun env ->
20
+
let response = Requests.get ~env (Uri.of_string "https://example.com") in
21
+
print_endline (Requests.Response.body_string response)
22
+
```
23
+
24
+
POST request with JSON body:
25
+
26
+
```ocaml
27
+
let () =
28
+
Eio_main.run @@ fun env ->
29
+
let uri = Uri.of_string "https://api.example.com/data" in
30
+
let body = {|{"key": "value"}|} in
31
+
let headers = Requests.Headers.of_list [
32
+
("content-type", "application/json")
33
+
] in
34
+
let response = Requests.post ~env ~headers ~body uri in
35
+
Printf.printf "Status: %d\n" (Requests.Response.status_code response)
36
+
```
37
+
38
+
Using authentication and custom headers:
39
+
40
+
```ocaml
41
+
let () =
42
+
Eio_main.run @@ fun env ->
43
+
let auth = Requests.Auth.basic ~username:"user" ~password:"pass" in
44
+
let headers = Requests.Headers.add
45
+
(Requests.Headers.init ())
46
+
"user-agent" "my-app/1.0" in
47
+
let response = Requests.get ~env ~auth ~headers
48
+
(Uri.of_string "https://api.example.com") in
49
+
(* Process response *)
50
+
()
51
+
```
52
+
53
+
## Installation
54
+
55
+
```
56
+
opam install requests
57
+
```
58
+
59
+
## Documentation
60
+
61
+
API documentation is available at https://tangled.org/@anil.recoil.org/ocaml-requests or via:
62
+
63
+
```
64
+
opam install requests
65
+
odig doc requests
66
+
```
67
+
68
+
## License
69
+
70
+
ISC
+5
bin/ocurl.ml
+5
bin/ocurl.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
open Eio
2
7
open Cmdliner
3
8
+4
dune
+4
dune
+21
-12
dune-project
+21
-12
dune-project
···
1
-
(lang dune 3.0)
1
+
(lang dune 3.20)
2
+
2
3
(name requests)
3
4
4
5
(generate_opam_files true)
5
6
6
-
(source
7
-
(github username/requests))
8
-
9
-
(authors "Your Name")
7
+
(license ISC)
8
+
(authors "Anil Madhavapeddy")
9
+
(homepage "https://tangled.org/@anil.recoil.org/ocaml-requests")
10
+
(maintainers "Anil Madhavapeddy <anil@recoil.org>")
11
+
(bug_reports "https://tangled.org/@anil.recoil.org/ocaml-requests/issues")
12
+
(maintenance_intent "(latest)")
10
13
11
-
(maintainers "Your Name")
12
-
13
-
(license MIT)
14
+
; NOTE: Do NOT add a (source ...) field for Tangled projects
15
+
; Tangled uses the homepage/bug_reports URLs to determine the source repository
14
16
15
17
(package
16
18
(name requests)
17
19
(synopsis "Clean Eio-style HTTPS client library for OCaml")
18
-
(description "A modern HTTP(S) client library for OCaml with Eio support, providing a clean API for making web requests with automatic TLS/CA certificate handling")
20
+
(description
21
+
"A modern HTTP(S) client library for OCaml with Eio support, providing \
22
+
a clean API for making web requests with automatic TLS/CA certificate handling. \
23
+
Inspired by Python's requests library, this provides a simple, intuitive \
24
+
interface for HTTP operations.")
19
25
(depends
20
-
ocaml
21
-
(dune (>= 3.0))
26
+
(ocaml (>= 5.1.0))
27
+
(dune (>= 3.20))
22
28
eio
23
29
cohttp-eio
24
30
tls-eio
···
27
33
uri
28
34
digestif
29
35
base64
30
-
logs))
36
+
logs
37
+
(odoc :with-doc)
38
+
(alcotest (and :with-test (>= 1.7.0)))
39
+
(eio_main :with-test)))
+5
examples/session_example.ml
+5
examples/session_example.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
open Eio
2
7
3
8
let () =
+5
lib/auth.ml
+5
lib/auth.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
let src = Logs.Src.create "requests.auth" ~doc:"HTTP Authentication"
2
7
module Log = (val Logs.src_log src : Logs.LOG)
3
8
+5
lib/auth.mli
+5
lib/auth.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** Authentication mechanisms *)
2
7
3
8
(** Log source for authentication operations *)
+6
-1
lib/body.ml
+6
-1
lib/body.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
let src = Logs.Src.create "requests.body" ~doc:"HTTP Request/Response Body"
2
7
module Log = (val Logs.src_log src : Logs.LOG)
3
8
···
63
68
(* JSON streaming using jsont - we encode the value to string and stream it *)
64
69
module Json_stream_source = struct
65
70
type t = {
66
-
mutable content : string;
71
+
content : string;
67
72
mutable offset : int;
68
73
}
69
74
+5
lib/body.mli
+5
lib/body.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** HTTP request body construction
2
7
3
8
This module provides various ways to construct HTTP request bodies,
+5
lib/error.ml
+5
lib/error.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** Centralized error handling for the Requests library *)
2
7
3
8
let src = Logs.Src.create "requests.error" ~doc:"HTTP Request Errors"
+5
lib/error.mli
+5
lib/error.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** Centralized error handling for the Requests library *)
2
7
3
8
(** Log source for error reporting *)
+5
lib/headers.ml
+5
lib/headers.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
let src = Logs.Src.create "requests.headers" ~doc:"HTTP Headers"
2
7
module Log = (val Logs.src_log src : Logs.LOG)
3
8
+5
lib/headers.mli
+5
lib/headers.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** HTTP headers management with case-insensitive keys
2
7
3
8
This module provides an efficient implementation of HTTP headers with
+5
lib/http_client.ml
+5
lib/http_client.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** Low-level HTTP/1.1 client over raw TCP connections for connection pooling *)
2
7
3
8
let src = Logs.Src.create "requests.http_client" ~doc:"Low-level HTTP client"
+5
lib/method.ml
+5
lib/method.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
let src = Logs.Src.create "requests.method" ~doc:"HTTP Methods"
2
7
module Log = (val Logs.src_log src : Logs.LOG)
3
8
+5
lib/method.mli
+5
lib/method.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** HTTP methods following RFC 7231 *)
2
7
3
8
(** Log source for method operations *)
+5
lib/mime.ml
+5
lib/mime.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
let src = Logs.Src.create "requests.mime" ~doc:"MIME Type Handling"
2
7
module Log = (val Logs.src_log src : Logs.LOG)
3
8
+5
lib/mime.mli
+5
lib/mime.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** MIME type handling *)
2
7
3
8
(** Log source for MIME type operations *)
+5
lib/one.ml
+5
lib/one.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
let src = Logs.Src.create "requests.one" ~doc:"One-shot HTTP Requests"
2
7
module Log = (val Logs.src_log src : Logs.LOG)
3
8
+5
lib/one.mli
+5
lib/one.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** One-shot HTTP client for stateless requests
2
7
3
8
The One module provides a stateless HTTP client for single requests without
+5
lib/requests.ml
+5
lib/requests.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** OCaml HTTP client library with streaming support *)
2
7
3
8
let src = Logs.Src.create "requests" ~doc:"HTTP Client Library"
+5
lib/requests.mli
+5
lib/requests.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** Requests - A modern HTTP client library for OCaml
2
7
3
8
Requests is an HTTP client library for OCaml inspired by Python's requests
+5
lib/response.ml
+5
lib/response.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
let src = Logs.Src.create "requests.response" ~doc:"HTTP Response"
2
7
module Log = (val Logs.src_log src : Logs.LOG)
3
8
+5
lib/response.mli
+5
lib/response.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** HTTP response handling
2
7
3
8
This module represents HTTP responses and provides functions to access
+5
lib/retry.ml
+5
lib/retry.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
let src = Logs.Src.create "requests.retry" ~doc:"HTTP Request Retry Logic"
2
7
module Log = (val Logs.src_log src : Logs.LOG)
3
8
+5
lib/retry.mli
+5
lib/retry.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** HTTP request retry logic with exponential backoff *)
2
7
3
8
open Eio
+5
lib/status.ml
+5
lib/status.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** HTTP status codes following RFC 7231 and extensions *)
2
7
3
8
let src = Logs.Src.create "requests.status" ~doc:"HTTP Status Codes"
+5
lib/status.mli
+5
lib/status.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** HTTP status codes following RFC 7231 and extensions *)
2
7
3
8
(** Log source for status code operations *)
+5
lib/timeout.ml
+5
lib/timeout.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
let src = Logs.Src.create "requests.timeout" ~doc:"HTTP Request Timeouts"
2
7
module Log = (val Logs.src_log src : Logs.LOG)
3
8
+5
lib/timeout.mli
+5
lib/timeout.mli
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(** Timeout configuration *)
2
7
3
8
(** Log source for timeout operations *)
+11
-9
requests.opam
+11
-9
requests.opam
···
2
2
opam-version: "2.0"
3
3
synopsis: "Clean Eio-style HTTPS client library for OCaml"
4
4
description:
5
-
"A modern HTTP(S) client library for OCaml with Eio support, providing a clean API for making web requests with automatic TLS/CA certificate handling"
6
-
maintainer: ["Your Name"]
7
-
authors: ["Your Name"]
8
-
license: "MIT"
9
-
homepage: "https://github.com/username/requests"
10
-
bug-reports: "https://github.com/username/requests/issues"
5
+
"A modern HTTP(S) client library for OCaml with Eio support, providing a clean API for making web requests with automatic TLS/CA certificate handling. Inspired by Python's requests library, this provides a simple, intuitive interface for HTTP operations."
6
+
maintainer: ["Anil Madhavapeddy <anil@recoil.org>"]
7
+
authors: ["Anil Madhavapeddy"]
8
+
license: "ISC"
9
+
homepage: "https://tangled.org/@anil.recoil.org/ocaml-requests"
10
+
bug-reports: "https://tangled.org/@anil.recoil.org/ocaml-requests/issues"
11
11
depends: [
12
-
"ocaml"
13
-
"dune" {>= "3.0" & >= "3.0"}
12
+
"ocaml" {>= "5.1.0"}
13
+
"dune" {>= "3.20" & >= "3.20"}
14
14
"eio"
15
15
"cohttp-eio"
16
16
"tls-eio"
···
21
21
"base64"
22
22
"logs"
23
23
"odoc" {with-doc}
24
+
"alcotest" {with-test & >= "1.7.0"}
25
+
"eio_main" {with-test}
24
26
]
25
27
build: [
26
28
["dune" "subst"] {dev}
···
36
38
"@doc" {with-doc}
37
39
]
38
40
]
39
-
dev-repo: "git+https://github.com/username/requests.git"
41
+
x-maintenance-intent: ["(latest)"]
+5
test/test_localhost.ml
+5
test/test_localhost.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(* Test conpool with 16 localhost servers on different 127.0.* addresses *)
2
7
3
8
open Eio.Std
+5
test/test_localhost.mli
+5
test/test_localhost.mli
+5
test/test_simple.ml
+5
test/test_simple.ml
···
1
+
(*---------------------------------------------------------------------------
2
+
Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3
+
SPDX-License-Identifier: ISC
4
+
---------------------------------------------------------------------------*)
5
+
1
6
(* Simple test to debug connection issues *)
2
7
3
8
open Eio.Std
+5
test/test_simple.mli
+5
test/test_simple.mli