pm-mck / piaf

Client library for HTTP/1.X / HTTP/2 written entirely in OCaml.

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 url =
  let open Lwt_result.Syntax in

  Lwt_main.run begin
    print_endline("Sending request...");

    let* response = Client.Oneshot.get (Uri.of_string url) in

    if (Status.is_successful response.status) then
      Body.to_string response.body
    else
      let message = Status.to_string response.status in
      Lwt.return (Error (`Msg message))
  end

let () =
  match get_sync "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-shell --pure 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.