On http4s, minimalism, and 1.0

[rossabaker]

On http4s, minimalism, and 1.0

http4s has been binary stable for 939 days, which warms my enterprise
staff engineer's heart. It has also been 0ver for 4,050 days, a more
dubious accomplishment.

How big is it, anyway?

The GitHub description for the project has long read:

A minimal, idiomatic Scala interface for HTTP

Let's check the cloc.

github.com/AlDanial/cloc v 1.94  T=0.70 s (946.0 files/s, 134834.2 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Scala                          613           8954          15192          58008
Markdown                        34           2624              0           9074
YAML                             4            122             22            721
Text                             7             39              0             50
Nix                              1              4              0             36
JSON                             1              0              0             32
XML                              3              6              6             30
CSS                              1              0              0              3
HTML                             1              0              0              1
Properties                       1              0              0              1
-------------------------------------------------------------------------------
SUM:                           666          11749          15220          67956
-------------------------------------------------------------------------------

This is after The Great Schism, which split off a significant number
of modules.

By way of comparison, this is bigger than cats-effect:

github.com/AlDanial/cloc v 1.94  T=0.30 s (1690.1 files/s, 231644.4 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Scala                          412           8661          16392          33996
Markdown                        52           1843              0           5501
YAML                             6            102             23            643
Java                             7             71            196            258
Bourne Shell                     7             66             13            219
Text                             5             33              0            168
JSON                             5              0              0            163
Nix                              1              4              0             35
Dockerfile                       1              1              0              2
Properties                       2              0              0              2
SVG                              1              0              0              1
-------------------------------------------------------------------------------
SUM:                           499          10781          16624          40988
-------------------------------------------------------------------------------

It's also bigger than fs2.

github.com/AlDanial/cloc v 1.94  T=0.51 s (1000.8 files/s, 175020.5 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
Scala                          470           9542          19835          52358
Text                             3             74              0           3940
Markdown                        29            801              0           2157
YAML                             3            129             28            598
HTML                             2              0              1             36
Nix                              1              1              0             28
JSON                             1              0              0              6
Properties                       3              0              0              3
-------------------------------------------------------------------------------
SUM:                           512          10547          19864          59126
-------------------------------------------------------------------------------

Why it matters

More code, more liability, more bikeshedding, more 0ver.

What is minimalism?

The original spirit of the project is neatly described by our Rack
cousins. Let's indulge our Scalatra roots, and substitute Scala for
Ruby:

Rack provides a minimal, modular, and adaptable interface for
developing web applications in Ruby. By wrapping HTTP requests and
responses in the simplest way possible, it unifies and distills the
bridge between web servers, web frameworks, and web application into a
single method call.

https://github.com/rack/rack

A revised strategy for 1.0

Let's extract a kernel from core. The kernel should be just enough to
serve as the sole dependency of a server and a client implementation.
It should also be enough to serve as a target for "front ends" like
Smithy, Endpoints4s, and our trusty old extractor-based DSL.

In scope

The base is a Request and Response in compliance with RFC9110.
This likely pulls into scope:

• Uri: a blight on http4s-0.23. This may be best manifested in
  cats-uri, though that project is not currently maintained and would
  add to the "import tax" that plagues http4s-0.x.
• Headers: called fields in the spec.
• Entity: called content in the spec. A minimal definition is
  an fs2.Stream[F, Byte], but one of the significant divergences
  between the main branch and series/0.23 today is the Entity
  sum type with strict and streamed implementations. There are
  performance benefits to this, and it represents some tension we'll
  need to resolve in the definition of "minimalism".
• Methods and Status: now, is it minimalist to imbue them with
  semantics like isIdempotent or isClientError?
• Version: there can only be 100 of them. At least this is solid!

Out of scope

These features are important parts of http4s, but they're also subject
to bikeshedding.

• HttpRoutes and HttpApp: as much as I will miss the demagoguery
  around monad transformers, up to and including being blamed for
  climate change, Request[F] =​> Resource[F, Response[F]] is enough
  to implement a server and a client. And Kleisli composition will
  always be available for those of us who understand that the network
  is their bottleneck.
• Middleware: they're great. They should probably be still be
  ported to MTL. They're also not kernel. This includes supporting
  features like auth and metrics algebrae.
• The DSL: borrowed from Finagle to serve as the first front end, it
  became the de facto backend. It's still quite useful, and
  eliminating it would be traumatic. But it's definitely not the
  kernel.
• Modeled headers: these can increase correctness, but the
  underlying model is already a (CIString, String) product. Leave
  these to the front ends.
• EntityEncoder and EntityDecoder: http4s was designed when
  typeclass codecs were en vogue, but implicits fall apart when
  there is no canonical instance. Is a String plain text or a JSON
  string?
• JSON support: these are based around the codecs. They of course
  need to exist, but HTTP != JSON.
• The staticcontent services: not core!

Open questions

1. Attributes

   I have long regretted the attributes. But how do we support extended
   functionality, like web sockets and servlet sessions, without a way to
   smuggle information through?

2. HTTP/2 and HTTP/3

   Perhaps related to the above, do we have everything we need to
   support HTTP/2 in full? HTTP/3? We have to get this right now. Our
   WAI cousins created an HTTP/2 application for push support.

3. An implementation versioned with the kernel

   There is a stated desire to make a default configuration part of the
   Typelevel toolkit. I think Ember is a fine starting point for that,
   and tactically it makes sense to compile it against the kernel as the
   kernel is defined. I see no reason it has to be versioned together
   with the kernel, or why a toolkit couldn't depend directly on it.

   One thing that could persuade me is that if the kernel model can be
   made safer if a codec appears in its companion objects, but this
   substantially increases the size of the kernel.

[hamnis]

I strongly agree with a minimal core kernel.

With regards to uri, this exists, and may be a way forward.
It will not help with the import tax, but may reduce bikeshedding time.

I would also express the need for the entity model such as it is in the main branch. This greatly improves the netty implementation and I think the perceived complexity is worth it. One might look at the entity model still as streams as a user, but will allow a more efficient implementation.

However, we might accomplish the same with only providing an interface for Request and Response and letting implementations implement these however they wish. The servlet spec has done this which works fine on the Java side.

[rossabaker]

I've wondered about a more abstract model. Instead of copying Netty codec types or servlet requests into a concrete Request, it could pass through to what the backends create, and perhaps increase performance, kind of like the JSON codecs that avoid an AST. But it complicates things that modify the request or response, particularly when the underlying types are mutable.

scala-uri is very well done, but is also of a Scala dialect that throws exceptions. It's close, but I wonder if it would ever quite fit right.

[hamnis]

One might wrap scala-uri with safe constructors and better error handling. Then we could just use it internally, but never expose it to users. This could help with the import tax. Of course, this could be done for any uri type we may want to use.

[armanbilge]

Thanks for getting this conversation started :)

Why it matters

More code, more liability, more bikeshedding, more 0ver.

💯

---

There is a stated desire to make a default configuration part of the Typelevel toolkit.

This is me! Among a few others. But let me clarify: the desire is not just to make it part of toolkit, but to generally reduce the friction for any user of http4s to hit the ground running. Having a default client available (and possibly a default server) on some top-level imports can take us a long way. See discussion in #6696.

I see no reason it has to be versioned together with the kernel

You could say the same thing about IO :) there's no reason that our effect implementation and runtime have to be versioned together with the CE kernel. But in practice, this turns out to be expedient.

In fact, if I know my history, didn't CE originally start as just a kernel? I'm curious what the path to a concrete IO implementation was. Nowadays we even discuss flattening the kernel/std/core modularization in a future CE4, since in practice nearly the entire ecosystem depends directly on core anyway.

My vision of a minimal http4s is very inspired by Cats Effect:

1. A kernel with well-defined APIs/laws/semantics/etc. that is (1) open to many implementations and (2) usable without relying on implementation details.
2. A core with a "blessed" implementation that is robust, observable, performant, maintainable. This implementation makes it easy for users to hit the ground running (think IOApp.Simple).
3. a stdlib of non-kernel but highly practical components. Ideally these are non-controversial, stable, and widely-useful, and often graduate to here from proven microlibs.

I think (1) and (2) are more-or-less straightforward (I agree with your scoping above). Admittedly what does or doesn't go into (3) and what it should look like is a much harder conversation that treads on a slippery path back to the http4s we have today. However, I think it's important to acknowledge there is stuff that does fall in this category and, when done well, a high-quality stdlib is a major asset.

(1) is essential for unblocking http4s 1.0. (2) isn't necessary but I think would be prudent. (3) trails further behind: many of the prospective candidates for an http4s stdlib have not had sufficient time to mature.

[SystemFw]

In fact, if I know my history, didn't CE originally start as just a kernel? I'm curious what the path to a concrete IO implementation was

Not really. Even before cats-effect existed, fs2 had both an effect typeclass hierarchy, with https://github.com/typelevel/fs2/blob/series/0.9/core/shared/src/main/scala/fs2/util/Async.scala at the bottom (you can navigate up from there if you want to see the others), and a concrete implementation https://github.com/typelevel/fs2/blob/series/0.9/core/shared/src/main/scala/fs2/Task.scala.

And those two were very much the foundation that led to the beginning of cats-effect, which was almost a port of that: https://github.com/typelevel/cats-effect/tree/series/0.x/core/shared/src/main/scala/cats/effect (and then if you really want the full history: a sketch for typeclasses was committed after IO: typelevel/cats-effect@f349984)

[rossabaker]

Should we keep doing 1.0 milestones as this takes shape? An 0.23 patch is imminent. I don't want to leave people high and dry, but the final product is going to look substantially different.

[danicheg]

Should we keep doing 1.0 milestones as this takes shape? An 0.23 patch is imminent. I don't want to leave people high and dry, but the final product is going to look substantially different.

I assume that we should. Because those bravehearts may also wish to get patches from 0.23.