package dream
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=b715cecf7e2b249335c8d1cd22c3e87017e40c0556774d209f338f9d78388c86
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 | Tutorial | Reference
Dream is one flat module in one package, documented on one page, but with many examples. It offers:
WebSockets and GraphQL for your modern Web apps.
HTML templates with embedded OCaml or Reason — use existing skills!
Easy HTTPS and HTTP/2 support — Dream runs without a proxy.
Helpers for secure cookies and CSRF-safe forms.
Full-stack ML with clients compiled by Melange, ReScript, or js_of_ocaml.
...all without sacrificing ease of use — Dream has:
A simple programming model — Web apps are just functions!
Composable middleware and routes.
Unified, internationalization-friendly error handling.
Cryptography helpers, key rotation, and a chosen cipher.
A neat logger, and attention to configuring the OCaml runtime nicely.
Deployment instructions for Digital Ocean, Heroku, and Fly.io, with sample CI scripts.
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
You can get one of the first tutorials and build it locally with:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/aantron/dream/master/example/quickstart.sh)"
opam
Create a project directory with an optional local switch:
mkdir project
cd project
opam switch create . 5.1.0
eval $(opam env)
Install Dream:
opam install dream
After that, go to any of the examples, such as 2-middleware
, re-create the files locally, and run it:
dune exec ./middleware.exe
esy
Visit any of the examples, such as 2-middleware
, and re-create the files locally. The file esy.json
shows how to depend on Dream. All of the examples are installed by running npx esy
, and started with npx esy start
.
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 written in Reason. See
r-hello
.Full-stack — See skeleton projects
r-fullstack-melange
,w-fullstack-rescript
, andw-fullstack-jsoo
.Deploying — Quick start instructions for small-to-medium deployments.
Examples — These cover various HTTP scenarios.
Watching and live reloading.
Recommended projects
dream-cli
— command-line interface for Dream applications.dream-encoding
— compression middleware.dream-livereload
— live reloading.emile
— email address syntax validation.letters
— SMTP client.
Example repositories
dream-mail-example
— sends email using RabbitMQ and Mailgun [blog post, discuss].dream-melange-tea-tailwind
— The Elm Architecture with a Dream server, client compiled by Melange.
Contact
Apart from the issues, good places to discuss Dream are...
#dream on the Reason Discord.
#webdev on the OCaml Discord
The OCaml Discuss forum.
The development stream on Twitch.
Highlight @antron
to poke @aantron specifically.
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:
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.
Dependencies (33)
- yojson
-
uri
>= "4.2.0"
-
ssl
>= "0.5.8"
-
ptime
>= "0.8.1"
-
ocaml
>= "4.08.0"
- multipart_form-lwt
-
multipart_form
>= "0.4.0"
- mirage-crypto-rng-lwt
-
mirage-crypto-rng
>= "1.0.0"
-
mirage-crypto
>= "1.0.0"
-
mirage-clock
>= "3.0.0"
-
markup
>= "1.0.2"
- magic-mime
-
logs
>= "0.5.0"
- lwt_ssl
-
lwt_ppx
>= "1.2.2"
- lwt
-
lambdasoup
>= "0.6.1"
- graphql-lwt
- graphql_parser
-
fmt
>= "0.8.7"
-
dune
>= "2.7.0"
-
dream-pure
>= "1.0.0~alpha2"
-
dream-httpaf
>= "1.0.0~alpha3"
-
digestif
>= "0.7"
-
cstruct
>= "6.0.0"
-
ocaml
os = "win32"
-
conf-libev
os != "win32"
-
caqti-lwt
>= "2.0.0"
-
caqti
>= "2.0.0"
- camlp-streams
- bigarray-compat
- base-unix
Dev Dependencies (13)
-
tyxml-jsx
with-test
-
tyxml
with-test & >= "4.5.0"
-
reason
with-test
-
ppx_yojson_conv
with-test
-
ppx_expect
with-test & >= "v0.15.0"
-
js_of_ocaml-ppx
with-test
-
js_of_ocaml
with-test
-
html_of_jsx
with-test
-
crunch
with-test
-
caqti-driver-sqlite3
with-test
-
caqti-driver-postgresql
with-test
-
bisect_ppx
with-test & >= "2.5.0"
-
alcotest
with-test
Used by (17)
- dream-accept
-
dream-cli
>= "0.2.0"
-
dream-encoding
>= "0.2.0"
- dream-html
- dream-htmx
-
dream-livereload
>= "0.2.0"
-
dream-serve
>= "1.0.1"
- FPauth
- FPauth-responses
- FPauth-strategies
- graphql_jsoo_client
- hyper
-
lambdapi
>= "2.4.0"
- ppx_dream_eml
- slipshow
- u2f
- universal-portal
Conflicts
None