Ring 2.0 feedback

[weavejester]

This is an issue for gathering feedback on the Ring 2.0 design.

The code and documentation will be held in the 2.0 branch of the repository.

The first draft specification for Ring 2.0 is now available to read, and accompanying it is an architecture design record that attempts to explain the decision-making behind the design.

New features for Ring 2.0 include:

• Namespaced request and response maps
• Request body changed from Java InputStream to protocol
• Websockets
• HTTP/2 push promises

Note that Ring does not use semantic versioning. Ring 2.0 will be backward compatible with Ring 1.0, as described in the ADR.

As of writing this design has not yet been implemented in code. The next step is to create an alpha release that implements the draft spec, allowing the community to try the design out. I anticipate Ring 2.0 will remain in alpha for a while, in a similar fashion to Clojure spec, to allow plenty of time for community feedback and testing.

[iku000888]

🎉

Did you mean :ring.request/body -> :ring.response/body etc in the table?

[souenzzo]

0. Why not use core.async protocols to async responses?
1. ring.request keys and ring.push keys has identical specs. Why not reuse ring.request in push maps?
2. Let's use clojure.core predicates in "types"? I mean, use string? where was String

[weavejester]

Why not use core.async protocols to async responses?

It adds a dependency on core.async.

ring.request keys and ring.push keys has identical specs. Why not reuse ring.request in push maps?

So that we can distinguish between a push map and a request map. A push map also has different mandatory keys to a request map.

Let's use clojure.core predicates in "types"? I mean, use string? where was String

That doesn't work for protocols, and I'd rather be precise and use a type over a predicate. There are some predicates that don't map 1-to-1 with types.

[weavejester]

Did you mean :ring.request/body -> :ring.response/body etc in the table?

Yes, good catch. Let me fix that.

[souenzzo]

Why not use core.async protocols to async responses?

It adds a dependency on core.async.

So can we consider a new protocol for async API? Then we can easily bridge any async lib into ring protocol.

ring.request keys and ring.push keys has identical specs. Why not reuse ring.request in push maps?

So that we can distinguish between a push map and a request map. A push map also has different mandatory keys to a request map.

Both clojure.spec and plumatic/schema has capabilities to say with keys are required in different contexts. In clojure.spec example:

(s/def ::request (s/keys :req [:ring.request/method]
                         :opt [:ring.request/path]))
(s/def ::push (s/keys :req [:ring.request/path]
                      :opt [:ring.request/method]))

Let's use clojure.core predicates in "types"? I mean, use string? where was String

That doesn't work for protocols, and I'd rather be precise and use a type over a predicate. There are some predicates that don't map 1-to-1 with types.

ring can define ring.response/streamable-response-body? next to the protocol.
Things like Integer don't make sense in some targets like clojurescript/JS, I think that :ring.response/status for example, can be a number?

[weavejester]

So can we consider a new protocol for async API? Then we can easily bridge any async lib into ring protocol.

Can you explain what you mean by "for async API"? Do you mean adding a protocol for non-blocking I/O on the request and response bodies?

Both clojure.spec and plumatic/schema has capabilities to say with keys are required in different contexts.

Sure, but that doesn't help if we want to differentiate between a push promise and a HTTP request dynamically. A push promise also has different semantic meaning to a HTTP request, even though they share fields of the same type.

Things like Integer don't make sense in some targets like clojurescript/JS, I think that :ring.response/status for example, can be a number?

The StreamableResponseBody protocol doesn't make sense for ClojureScript either. The specification is designed to target Clojure, rather than ClojureCLR or ClojureScript.

I have thought about what we'd do to adapt the specification to ClojureScript, and it goes a little deeper than just using predicates rather than type names.

[niquola]

How about async streaming API - if my handler wants to send chunks?

[niquola]

We use a lot a context map (with bunch of deps like db connection etc) as a first parameter to handlers - may it be useful for ring?

[dgr]

The spec obviously spends time describing the differences between the synchronous and asynchronous protocols. One thing it doesn’t seem to mention is the serialization of requests. For instance, can a server have multiple synchronous requests in flight at the same time, or does synchronous imply that requests are serialized, one after another? In particular, if a synchronous handler blocks, is it blocking all requests, or just the request that it’s servicing? Perhaps the omission is on purpose to allow for different server adapter implementations, but the silence is noticeable. If it’s purposeful, perhaps a statement to that effect would be good to include.

[weavejester]

How about async streaming API - if my handler wants to send chunks?

That was added back in Ring 1.6, with the caveat that I/O is blocking. In other words, while your handler is actively writing data to the client it's blocking the thread.

The problem with fully supporting non-blocking I/O in Ring 1 was that the request body was an InputStream, which is a blocking stream. In Ring 2, that's been changed, and in Ring 2.1 the plan is to have NIO protocols that the request body and response body can optionally satisfy.

For Ring 2.0 I thought that sort of performance optimisation was a little out of scope, as it's a fairly niche requirement.

We use a lot a context map (with bunch of deps like db connection etc) as a first parameter to handlers - may it be useful for ring?

In general I think it's generally better to use closures for that:

(fn [context]
  (fn [request]
    ...))

But I'd be interested in hearing about use-cases where closures are not as elegant. That said, I don't anticipate changing the request/response maps into context maps instead.

[weavejester]

For instance, can a server have multiple synchronous requests in flight at the same time, or does synchronous imply that requests are serialized, one after another? In particular, if a synchronous handler blocks, is it blocking all requests, or just the request that it’s servicing?

No, it's just blocking the thread for the current request. It's expected that an adapter that is running a synchronous handler will have a threadpool for handling multiple requests concurrently.

[dgr]

For instance, can a server have multiple synchronous requests in flight at the same time, or does synchronous imply that requests are serialized, one after another? In particular, if a synchronous handler blocks, is it blocking all requests, or just the request that it’s servicing?

No, it's just blocking the thread for the current request. It's expected that an adapter that is running a synchronous handler will have a threadpool for handling multiple requests concurrently.

OK. My suggestion would be to make that explicit so that nobody has to guess. I assume that the size of the thread pool is really in the domain of the server adapter and shouldn't be part of the Ring spec, but there's a big difference between one (serial) and more than one (non-serial). I'm sure that Ring 1.x behavior already works this way, but given the chance to document it explicitly, I would take the opportunity.

[tonsky]

This does make accessing request headers with single values slightly more laborious: (first (get-in request [:headers "content-type"]))

If you are already using get-in, it’s still simple:

(get-in request [:headers "content-type" 0])

[dgr]

The spec does a great job of considering HTTP/2 issues. Has it been checked against HTTP/3 proposals? I realize that's a moving target and still in flux, but it seems like 2020 is the year that HTTP/3 will start to happen. It's already included in stable versions of Chrome and Firefox, though not the default, per https://en.wikipedia.org/wiki/HTTP/3.

[tonsky]

Great spec, all changes very solid and timely!