Webs v0.0.0-135-g93c0715

Manuals

These manuals are available:

• The HTTP service howto explains how to define, compile and run a service behind an HTTP gateway and let it serve files and webpages efficiently.
• The HTTP request handling cookbook has a few conventions and recipes to handle HTTP requests.
• 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

The examples 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.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

Fetch an URL with this fetch.ml file:

open Webs

let main () =
  let httpc = Webs_spawn_client.make () in
  let url = Sys.argv.(1) in
  match Http_client.get httpc ~follow:true ~url with
  | Error e -> prerr_endline e; 1
  | Ok page -> print_endline page; 0

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

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 that with

ocamlfind ocamlopt -pkg webs,webs.unix -o fetch fetch.ml
ocamlfind ocamlopt -pkg webs,webs.http11,webs.cli -o serve serve.ml

Let them talk (you will need curl in your PATH):

./serve &
./fetch http://localhost:8000/hey
./fetch http://localhost:8000/ho
pkill serve
serve --help

See also the samples in the repo.

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 HTTP 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.

Finally note that while Webs is unlikely to change drastically, making some breaking changes in the future is not excluded.