dream

Tidy, feature-complete Web framework
README

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

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.

Getting started

Dream is not yet announced or released! Before release, Dream will get a
quick-start script, and some other help for getting started quickly. However,
if you want to try Dream now, you can add:

"dependencies": {
  "@opam/dream": "aantron/dream:dream.opam"
}

to your esy.json. See example w-esy for a minimal
project.

Alternatively, if you are using opam:

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

Note: the clone must be --recursive, because Dream vendors several
packages
as git submodules. Also, if you have gluten, httpaf, h2,
or websocketaf, or their gluten-*, etc., subpackages independently
installed in your switch, you may have to remove them with opam remove to
avoid conflicts. However, they should not be pulled into a basic build of Dream
and most programs that use it.

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

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

If you prefer Reason syntax, try example r-hello instead.

You should be able to copy the example out to a completely separate directory,
if you didn't use a local _opam switch scoped to Dream's clone directory. If
you did, you can pin Dream to your clone in a different opam switch with

opam pin add dream /path/to/your/clone

Documentation

Contact

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

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:

Roadmap

  • [x] GraphQL subscriptions.

  • [ ] 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 optionals for decoupling defaults, e.g. forms without CSRF
    checking, SQL sessions with a different database.

  • [x] 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.