package dream

  1. Overview
  2. Docs
Tidy, feature-complete Web framework

Install

Dune Dependency

Authors

Maintainers

Sources

dream-1.0.0-alpha2.tar.gz
md5=1220f17530522e488653eb91115867e3

Description

Dream is a feature-complete Web framework with a simple programming model and no boilerplate. It provides only two data types, request and response.

Almost everything else is either a built-in OCaml type, or an abbreviation for a bare function. For example, a Web app, known in Dream as a handler, is just an ordinary function from requests to responses. And a middleware is then just a function from handlers to handlers.

Within this model, Dream adds:

  • Session management with pluggable back ends.
  • A fully composable router.
  • Support for HTTP/1.1, HTTP/2, and HTTPS.
  • WebSockets.
  • GraphQL, including subscriptions and a built-in GraphiQL editor.
  • SQL connection pool helpers.
  • Server-side HTML templates.
  • Automatic secure handling of cookies and forms.
  • Unified, internationalization-friendly error handling.
  • A neat log, and OCaml runtime configuration.
  • Helpers for Web formats, such as Base64url, and a modern cipher.

Because of the simple programming model, everything is optional and composable. It is trivailly possible to strip Dream down to just a bare driver of the various HTTP protocols.

Dream is presented as a single module, whose API is documented on one page. In addition, Dream comes with a large number of examples. Security topics are introduced throughout, wherever they are applicable.

README

README.md

Dream

Easy-to-use, feature-complete Web framework without boilerplate.


Quick Start | Playground | Tutorial | Reference   



Dream is one flat module in one package, documented on one page, but with many examples. It offers:


...all without sacrificing ease of use — Dream has:


Every part of the API is arranged to be easy to understand, use, and remember. Dream sticks to base OCaml types like string and list, introducing only a few types of its own — and some of those are just abbreviations for bare functions!

The neat interface is not a limitation. Everything is still configurable by a large number of optional arguments, and very loose coupling. Where necessary, Dream exposes the lower-level machinery that it is composed from. For example, the basic body and WebSocket readers return strings, but you can also do zero-copy streaming.

You can even run Dream as a quite bare abstraction over its underlying set of HTTP libraries, where it acts only as minimal glue code between their slightly different interfaces.

And, even though Dream is presented as one package for ordinary usage, it is internally factored into several sub-libraries, according to the different dependencies of each, for fast porting to different environments.

Dream is a low-level and unopinionated framework, and you can swap out its conveniences. For example, you can use TyXML with server-side JSX instead of Dream's built-in templates. You can bundle assets into a single Dream binary, or use Dream in a subcommand. Dream tries to be as functional as possible, touching global runtime state only lazily, when called into.


Quick start


bash -c "$(curl -fsSL https://raw.githubusercontent.com/aantron/dream/master/example/quickstart.sh)"

This downloads and runs quickstart.sh, which does a sandboxed build of one of the first tutorials, 2-middleware. It's mostly the same as:

git clone https://github.com/aantron/dream.git --recursive
cd dream/example/2-middleware
npm install esy && npx esy
npx esy start

Knowing that, you can start from any other example. All of them include their own build commands. They don't have to be subdirectories of dream — you can copy them out to start your own project directory. Especially consider starting with the full-stack examples, which build both a Dream server and a JavaScript client.

opam

opam install dream

After that, go to one of the examples, such as 1-hello, and build it:

cd example/1-hello
dune exec --root . ./hello.exe

Playground

Most of the examples are loaded into the playground. For instance, 2-middleware is at http://dream.as/2-middleware.


Documentation


Contributing

All kinds of contributions are welcome, including examples, links to blogs, related libraries, and, of course, PRs! See CONTRIBUTING.md.

As an immediate note, if you'd like to clone the repo, be sure to use --recursive, because Dream uses several git submodules:

git clone https://github.com/aantron/dream.git --recursive

Acknowledgements

Dream is based on work by the authors and contributors of its many dependencies and their transitive dependencies. There are, however, several influences that cannot be discovered directly:

Dependencies (31)

  1. result
  2. psq
  3. faraday-lwt-unix
  4. faraday >= "0.6.1"
  5. digestif >= "0.7.2"
  6. bigstringaf >= "0.5.0"
  7. angstrom >= "0.14.0"
  8. yojson
  9. uri >= "4.2.0"
  10. ocaml >= "4.08.0" & < "5.0"
  11. multipart_form >= "0.3.0" & < "0.4.0"
  12. mirage-crypto-rng >= "0.8.0" & < "0.11.0"
  13. mirage-crypto >= "0.8.1"
  14. magic-mime
  15. logs >= "0.5.0"
  16. ssl >= "0.5.8"
  17. lwt_ssl
  18. lwt_ppx >= "1.2.2"
  19. lwt
  20. hmap
  21. graphql-lwt
  22. graphql_parser
  23. fmt >= "0.8.7"
  24. dune >= "2.7.0"
  25. cstruct >= "6.0.0"
  26. conf-libev os != "win32"
  27. caqti-lwt
  28. caqti >= "1.4.0" & < "2.0.0~"
  29. bigarray-compat
  30. base64 >= "3.1.0"
  31. base-unix

Dev Dependencies (11)

  1. tyxml-ppx with-test & >= "4.5.0"
  2. tyxml-jsx with-test & >= "4.5.0"
  3. tyxml with-test & >= "4.5.0"
  4. reason with-test
  5. ppx_yojson_conv with-test
  6. ppx_expect with-test
  7. lambdasoup with-test
  8. crunch with-test
  9. caqti-driver-sqlite3 with-test
  10. bisect_ppx with-test & >= "2.5.0"
  11. alcotest with-test

Conflicts (1)

  1. tls >= "0.15.0"