allancalix / piaf

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

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 via esy or by running opam install piaf.

Note: make sure to mirror Piaf's own resolutions located in the opam file.

Usage & Examples

TODO, read the mli file for now.

Examples

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, 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 installed, the repository includes scripts to set up a sandbox. Otherwise you can use opam to install the necessary dependencies globally.

Option 1) Setting up the sandbox

Assuming nix has been installed 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 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.

The vendor/multipart_form directory contains a fork of multipart_form which is licensed under the MIT License. multipart_form.LICENSE reproduces the original license text.