Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Dream — tidy, feature-complete Web framework #18536

Merged
merged 1 commit into from
Apr 22, 2021
Merged

Dream — tidy, feature-complete Web framework #18536

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 128 additions & 0 deletions packages/dream/dream.1.0.0~alpha1/opam
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
opam-version: "2.0"

synopsis: "Tidy, feature-complete Web framework"
tags: ["http" "web" "framework" "websocket" "graphql" "server" "http2" "tls"]
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."""

license: "MIT"
homepage: "https://github.com/aantron/dream"
doc: "https://aantron.github.io/dream"
bug-reports: "https://github.com/aantron/dream/issues"
dev-repo: "git+https://github.com/aantron/dream.git"

author: "Anton Bachin <[email protected]>"
maintainer: "Anton Bachin <[email protected]>"

depends: [
"base-unix"
"base64" {>= "3.1.0"} # Base64.encode_string.
"bigarray-compat"
"caqti-lwt"
"conf-libev"
"cstruct"
"dune" {>= "2.7.0"} # --instrument-with.
"fmt" {>= "0.8.7"} # `Italic.
"graphql_parser"
"graphql-lwt"
"hmap"
"lwt"
"lwt_ppx"
"lwt_ssl"
"logs" {>= "0.5.0"}
"magic-mime"
"mirage-crypto" {>= "0.8.1"} # AES-256-GCM.
"mirage-crypto-rng" {>= "0.8.0"} # Signature of initialize.
"multipart-form-data" {>= "0.3.0"}
"ocaml" {>= "4.08.0"}
"opam-installer" {build}
"uri"
"yojson" # ...

# Currently vendored.
# "gluten"
# "gluten-lwt-unix"
# "httpaf"
# "httpaf-lwt-unix"
# "h2"
# "h2-lwt-unix"
# "websocketaf"

# Dependencies of vendored packages.
"angstrom" {>= "0.14.0"}
"bigstringaf" {>= "0.4.0"}
"digestif" {>= "0.7"} # websocket/af, sha1.
"faraday" {>= "0.6.1"}
"faraday-lwt-unix"
"psq" # h2.
"result" # http/af, websocket/af.

# Testing, development.
"alcotest" {with-test}
"bisect_ppx" {dev & >= "2.5.0"} # --instrument-with.
"ppx_expect" {with-test}
]

conflicts: [
"gluten"
"httpaf"
"h2"
"websocketaf"
]

build: [
["dune" "build" "-p"
"dream,gluten,gluten-lwt,gluten-lwt-unix,websocketaf,httpaf,httpaf-lwt,httpaf-lwt-unix,hpack,h2,h2-lwt,h2-lwt-unix"
"-j" jobs]
]

install: [
["opam-installer" "--prefix" prefix "dream.install"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
["opam-installer" "--prefix" prefix "dream.install"]

This should be unnecessary as opam already installs <pkg>.install by default (on top of the install section)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I just tested removing this line with esy, and esy does not install dream.install by default, causing a dependency error later if the line is removed. This may be a bug/oversight, but it's non-obvious and I think it's better not to rely on the repository client interpreting it correctly. So, I prefer to keep this line.

Hopefully, this whole install: section will become unnecessary relatively soon, and I'll remove it completely in a future Dream release.

Copy link
Member

@mseri mseri Apr 20, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One last question (from me) before merging. This may be a good opportunity to try how the vendoring behaves. Have you checked what happens if you install dream and then install the opam version of any of its vendored dependencies separately (or if you have some of the vendored dependencies preinstalled when you compile it)?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I just tested removing this line with esy, and esy does not install dream.install by default, causing a dependency error later if the line is removed.

Sorry, dumb question, have you tried removing the whole install section or just that line?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One last question (from me) before merging. This may be a good opportunity to try how the vendoring behaves. Have you checked what happens if you install dream and then install the opam version of any of its vendored dependencies separately (or if you have some of the vendored dependencies preinstalled when you compile it)?

Yes, assuming you are asking about opam as the client. Because of the conflicts: section, opam shows prompts like this:

The following actions will be performed:
  ⊘ remove  dream  ~dev* [conflicts with httpaf]
  ∗ install httpaf 0.7.1
===== ∗ 1   ⊘ 1 =====
Do you want to continue? [Y/n]

have you tried removing the whole install section or just that line?

I removed just that line during this PR. The section itself exists because depending on dream fails without it (when the vendored packages are missing), which I experienced when I first tried to install dream after vendoring these deps. I also tried variations of dune install -p ... (as suggested by @kit-ty-kate, thank you) and (vendored_dirs). However, dune install -p did not seem to be able to actually find the vendored packages' .install files when used on its own. (vendored_dirs) disallows passing -p options for selecting subpackages of vendored packages, which forces an overestimation of their deps that are needed for dream, since they are monorepos, pulling in e.g. async via httpaf-async.

So, AFAIK, opam-installer is the only thing that works right now (apart from hacky manual scripts). I've been implicitly testing with opam-installer for several weeks now.

Copy link
Contributor Author

@aantron aantron Apr 20, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(vendored_dirs) disallows passing -p options for selecting subpackages of vendored packages, which forces an overestimation of their deps that are needed for dream, since they are monorepos, pulling in e.g. async via httpaf-async.

And to clarify this, the failure is during the build of dream itself, since it picks up false transitive dependencies like async, which are not installed (and shouldn't be, on a request for dream only). So I don't know if dune install together with (vendored_dirs) would work, because (vendored_dirs) forces a failure during build, before the install step. EDIT: To the best of my knowledge.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW, since you made most of the Piaf dependency choices (my forks of http/af and websocket/af, lwt_ssl, etc), you could depend on Piaf and its vendored libs (piaf.httpaf, piaf.h2, etc).

Then you'd just need to vendor websocket/af and e.g. use a subdir stanza like I do in Piaf

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I may well do that eventually. However, I understand that then Dream will be "locked" to whatever exact commits Piaf is vendoring, is that right? At this early point, I still need the flexibility to choose other commits, but I hope to streamline that away soon.

Thanks for the subdir stanza tip.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the explanations, indeed one reason I was asking was due the presence of those conflicts. Thanks for clarifying the issue. It is a pity that it does not install cleanly due to the vendoring

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean in the context of a switch with those packages? It seems to install cleanly otherwise. The vendoring is a temporary situation. My goal is to eliminate it relatively quickly. I think it's fine for a first release — this isn't affecting any users of Dream, because it mostly doesn't have any. It will just be a temporary annoyance for early adopters.

["opam-installer" "--prefix" prefix "src/vendor/gluten/gluten.install"]
["opam-installer" "--prefix" prefix "src/vendor/gluten/gluten-lwt.install"]
["opam-installer" "--prefix" prefix "src/vendor/gluten/gluten-lwt-unix.install"]
["opam-installer" "--prefix" prefix "src/vendor/websocketaf/websocketaf.install"]
["opam-installer" "--prefix" prefix "src/vendor/httpaf/httpaf.install"]
["opam-installer" "--prefix" prefix "src/vendor/httpaf/httpaf-lwt.install"]
["opam-installer" "--prefix" prefix "src/vendor/httpaf/httpaf-lwt-unix.install"]
["opam-installer" "--prefix" prefix "src/vendor/h2/hpack.install"]
["opam-installer" "--prefix" prefix "src/vendor/h2/h2.install"]
["opam-installer" "--prefix" prefix "src/vendor/h2/h2-lwt.install"]
["opam-installer" "--prefix" prefix "src/vendor/h2/h2-lwt-unix.install"]
]

url {
src: "https://github.com/aantron/dream/releases/download/1.0.0-alpha1/dream-1.0.0-alpha1.tar.gz"
checksum: "md5=b8ad7f3e30f3e88e5451d92e42b49ce4"
}