Dream

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

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

• Easy HTTPS and HTTP/2 support — Dream runs without a proxy.
• WebSockets and GraphQL for your modern Web apps.
• HTML templates with embedded OCaml or Reason — use existing skills!
• Composable middleware and routes.
• Easy-to-use functions for secure cookies and CSRF-safe forms.
• Sessions with pluggable storage back ends.
• Unified, internationalization-friendly error handling.
• Cryptography helpers, key rotation, and a chosen cipher.
• A neat logger, and attention to configuring the OCaml runtime nicely.

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. 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 takes care of horridness like ALPN.

Getting started

TODO opam release, esy instructions, quick-start script.

opam install dream

Documentation

• Tutorial — Threads together the first several examples of Dream, touching all the basic topics, including security. See the full list and start wherever you like, or begin at 1-hello, the Dream version of Hello, world!
• Reason syntax — Several of the examples are available in Reason syntax, with more to come over time!
• Examples — These cover various HTTP scenarios.
• API reference

Contact

Apart from the issues, good places to discuss Dream are...

• The OCaml and/or Reason Discord servers.
• The OCaml Discuss forum.

Highlight @antron to poke @aantron specifically.

Contributing

Dream uses several submodules, so be sure to clone with

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:

• Templates are inspired by ECaml from Alexander Markov and Embedded OCaml Templates from Emile Trotignon.
• Dream's handler and middleware types are simplified from Opium by Rudi Grinberg and contributors.
• The lower-level HTTP and WebSocket servers are vendored copies of Antonio Nuno Monteiro's forks and original works, with credit also due to their contributors, and Spiros Eliopoulos in particular, as the original author of two of the projects.
• The API docs are instantiated by Soupault from Daniil Baturin.
• The name was inspired by Morph from Ulrik Strid, which was itself partially inspired by Opium.
• Raphael Rafatpanah and El-Hassan Wanas provided important early feedback.

Roadmap

1.0.0~alpha1:

• Finish more of the examples, cross-link everything.
• Correct the cipher rotation envelope scheme.
• Quick start script.

Then:

• Optimizations: router, logger, microparsers (form data, etc.), fully zero-allocation streaming.
• WebSocket and stream backpressure.
• HTTP3/QUIC.
• Review JSON.
• Review SQL prepared statements.
• Switch to AEAD_AES_256_GCM_SIV for the cipher.
• WebSocket streaming (frames).
• Factor out internal sub-libraries to port Dream to MirageOS, etc.
• Token rotation-based session management.
• Lots of helpers for decoupling defaults, e.g. forms without CSRF checking, SQL sessions with a different database.
• Bundle GraphiQL into a single HTML file that does not access any external CDN.
• Maybe a logo.
• i18n helper, URL templates.
• Auth library.
• Maybe REST helpers.
• Maybe Async support.
• Multicore.
• Effects.
• Proxy headers support.
• Introspection.
• Dependency reduction, especially system dependencies.
• And lots, lots more.