Webs v0.0.0-148-g65ff953

Manuals

These manuals are available:

• The quick start should do so.
• The Webs cookbook has a few convention and HTTP client and service recipes.
• The service howto explains how to define, compile and run a service behind an HTTP gateway and let it serve files and webpages efficiently.
• The connector conventions explain how service and client connectors construct and interpret request and response values. It's a good idea to read it to understand how connectors behave in certain edge cases.
• The tutorial is a more involved example to get you started.
• The TODO is a few things that are todo
• There are a few limitations

The test directory of the repository has a few simple examples that use the APIs.

Library webs

• Webs HTTP interactions. Open to use it.

• Webs.Http HTTP datatypes.
• Webs.Http.Request HTTP requests.
• Webs.Http.Response HTTP responses.
• Webs.Http_client HTTP clients.
• Webs.Media_type Media type constants and file extensions.
• Webs.Url Sloppy URL processing.

Library webs.kit

• Webs_authenticatable Authenticatable data.
• Webs_authenticated_cookie Authenticated cookies.
• Webs_base64 base64 and base64url codecs.
• Webs_basic_auth HTTP basic authentication.
• Webs_bazaar Unstable service tools.
• Webs_cryptorand Cryptographically secure pseudorandom bytes and entropy.
• Webs_gateway Gateway interaction.
• Webs_hash Hashing tools.
• Webs_session Session handling.

Library webs.unix

Provides tools to send files and simple connectors. Depends on OCaml's unix library.

• Webs_unix Webs Unix tooling.
• Webs_thread_pool Thread pools.
• Webs_listener Socket connection listeners.
• Webs_fs File system responses.

Service connectors

• Webs_cgi CGI gateway connector.
• Webs_http11_gateway HTTP/1.1 gateway connector.

Client connectors

• Webs_spawn_client Client request by spawning.

Library webs.cli

Standard command line options and quick service setup.

• Webs_cli Command line interface support.
• Webs_quick Quick serves and fetches.

Quick start

See also the samples in the dev repo.

Fetch

Fetch an URL with this fetch.ml file:

open Webs
open Result.Syntax

let main () =
  Result.retract @@ Result.map_error (fun e -> prerr_endline e; 1) @@
  let url = Sys.argv.(1) in
  let* httpc = Webs_spawn_client.make () in
  let* page = Http_client.get httpc ~follow:true ~url in
  print_endline page;
  Ok 0

let () = if !Sys.interactive then () else exit (main ())

Compile and run with:

ocamlfind ocamlopt -linkpkg -package webs,webs.unix -o fetch fetch.ml
./fetch https://example.org   # needs curl in your PATH

Serve

Make a minimal server with this serve.ml file:

open Webs

let service = Http.Request.echo
let main () = Webs_quick.serve service
let () = if !Sys.interactive then () else exit (main ())

Compile and run with:

ocamlfind ocamlopt -linkpkg -package webs,webs.unix,webs.cli -o serve serve.ml
./serve &
curl http://localhost:8000/hey
./fetch http://localhost:8000/hey
pkill serve
./serve --help

Limitations

Before using Webs for your project you should be aware of these current limitations, some of which will be lifted in the future.

• All available service connectors do not talk directly to the internet and do not talk https. You need to pair your service with an HTTP gateway like Apache, nginx, etc. See the service howto for more details. Alternatively you can develop your own connector with your own concurrency model.
• TODO chunked encoding
• Webs supports the application/x-www-form-urlencoded content type for form posting but it's missing an implementation of the multipart/form body content type (e.g. to upload files). This will be added in the future so that Webs.Http.Request.to_query eventually abstracts over all forms of queries.
• The architecture of the Webs_http11_gateway connector will not fare well if you need to support WebSockets or SSE at scale.
• For now the only client connector is Webs_spawn_client which is only ok for scripting or lightweight needs.