https://github.com/anmonteiro/piaf

Web library for OCaml with support for HTTP/1.X / HTTP/2
https://github.com/anmonteiro/piaf

http http-client http2 http2-client https https-client ocaml

Last synced: 15 days ago
JSON representation

Web library for OCaml with support for HTTP/1.X / HTTP/2

• Host: GitHub
• URL: https://github.com/anmonteiro/piaf
• Owner: anmonteiro
• License: bsd-3-clause
• Created: 2019-12-01T09:24:29.000Z (almost 5 years ago)
• Default Branch: master
• Last Pushed: 2024-03-03T05:26:29.000Z (8 months ago)
• Last Synced: 2024-05-22T21:32:10.889Z (6 months ago)
• Topics: http, http-client, http2, http2-client, https, https-client, ocaml
• Language: OCaml
• Homepage:
• Size: 945 KB
• Stars: 178
• Watchers: 8
• Forks: 20
• Open Issues: 9
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGES.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-list - piaf

README

        
# piaf

Piaf is a client library for the HTTP/1.X and HTTP/2 protocols written entirely

in OCaml.

## Installation

Piaf is released to OPAM.

You can depend on it by running `opam install piaf`.

_Note_: make sure to mirror Piaf's own resolutions located in the [opam

file](./piaf.opam).

# Usage & Examples

TODO, read the [mli](./lib/piaf.mli) file for now.

### Examples

```ml

open Piaf

let get_sync env ~sw url =

  print_endline "Sending request...";

  match Client.Oneshot.get ~sw env (Uri.of_string url) with

  | Ok response ->

    if Status.is_successful response.status

    then Body.to_string response.body

    else

      let message = Status.to_string response.status in

      Error (`Msg message)

  | Error e -> failwith (Error.to_string e)

let () =

  Eio_main.run (fun env ->

      Eio.Switch.run (fun sw ->

          match get_sync env ~sw "https://example.com" with

          | Ok body -> print_endline body

          | Error error ->

            let message = Error.to_string error in

            prerr_endline ("Error: " ^ message)))

```

There's a more substantive example of using Piaf's API in

[bin/carl.ml](./bin/carl.ml), an implementation of a subset of curl, in caml.

## Development

There's two ways to get a development environemnt up and running. If you have (or don't mind getting) [`nix`](https://nixos.org/nix/manual/) installed, the repository includes scripts to set up a sandbox. Otherwise you can use [`opam`](https://opam.ocaml.org/) to install the necessary dependencies globally.

### Option 1) Setting up the sandbox

Assuming [`nix` has been installed](https://nix.dev/tutorials/install-nix.html) and set up, run `nix develop -c $SHELL` in the repository root. Once it's done building, you should have the development environment set up!

### Option 2) Setting up opam

For this approach you'll need to [install `opam`](https://opam.ocaml.org/doc/Install.html)  and set it up with a switch using `ocaml` >= 4.08. Once that's done, run `opam pin . --deps-only` to install the dependencies.

Note that this installs the dependencies globally, and that the development environment is dependent on the switch used.

### Building

Run `dune build` to build, `dune build --watch` to run a watcher daemon that will build incrementally.

### Running examples

Run `dune exec examples/docs/readme.exe` to run the simple example above.

Run `dune exec bin/carl.exe` to run `carl`, the `curl`-like example.

## License & Copyright

Copyright (c) 2019 António Nuno Monteiro

piaf is distributed under the 3-Clause BSD License, see [LICENSE](./LICENSE).

The `vendor/multipart_form` directory contains a fork of

[`multipart_form`](https://github.com/dinosaure/multipart_form) which is

licensed under the MIT License.

[`multipart_form.LICENSE`](./multipart_form.LICENSE) reproduces the original

license text.