Release 0.7.0

Author: KingMob

CHANGES.md

@@ -1,27 +1,20 @@
-### 0.7.0-rc2
+### 0.7.0
 
-* Include Brotli and zstd deps by default, remove code treating them as optional
-
-Contribution by Matthew Davidson. 
-
-### 0.7.0-rc1
-
-* Added HTTP/2 server support
+* HTTP/2 server support, including ALPN and h2c
+* HTTP/2 client support
 * Support more compression codecs (Brotli, Zstd, and Snappy)
-
-Contributions by Matthew Davidson, Moritz Heidkamp, and Arnaud Geiser.
-
-### 0.7.0-alpha2
-
-* Enable SSL/TLS certificate hostname verification by default in the client. (Warning: This is a BREAKING change for those with misconfigured server certificat~es.)
-
-Contribution by Moritz Heidkamp.
-
-### 0.7.0-alpha1
-
-* Add support for HTTP/2 in the client.
-
-Contributions by Matthew Davidson and Arnaud Geiser.
+* Enable SSL/TLS certificate hostname verification by default in the client for 
+  security purposes. (Warning: This is a BREAKING change for those with 
+  misconfigured server certificates.)
+* Bump Manifold dep to 0.4.1, which means Aleph/Manifold deferreds now support 
+  CompletionStage for better Java interop
+* Bump Netty to 4.1.00.Final
+* Improved error logging
+
+Contributions by Matthew Davidson, Moritz Heidkamp, and Arnaud Geiser. 
+
+Manifold contributions by Renan Ribeiro, Ryan Smith, Arnaud Geiser, and Matthew 
+Davidson.
 
 ### 0.6.3
 

README.md

@@ -8,11 +8,11 @@ Aleph exposes data from the network as a [Manifold](https://github.com/clj-commo
 
 Leiningen:
 ```clojure
-[aleph "0.7.0-rc2"]
+[aleph "0.7.0"]
 ```
 deps.edn:
 ```clojure
-aleph/aleph {:mvn/version "0.7.0-rc2"}
+aleph/aleph {:mvn/version "0.7.0"}
 ;; alternatively
 io.github.clj-commons/aleph {:git/sha "..."}
 ```
@@ -30,17 +30,26 @@ Aleph follows the [Ring](https://github.com/ring-clojure) spec fully, and can be
    :headers {"content-type" "text/plain"}
    :body "hello!"})
 
-(http/start-server handler {:port 8080})
+(http/start-server handler {:port 8080}) ; HTTP/1-only
+
+;; To support HTTP/2, do the following:
+;; (def my-ssl-context ...)
+(http/start-server handler {:port 443
+                            :http-versions [:http2 :http1]
+                            :ssl-context my-ssl-context})
+;; See aleph.examples.http2 for more details
 ```
 
 The body of the response may also be a Manifold stream, where each message from the stream is sent as a chunk, allowing for precise control over streamed responses for [server-sent events](http://en.wikipedia.org/wiki/Server-sent_events) and other purposes.
 
+
 #### Client
 
 For HTTP client requests, Aleph models itself after [clj-http](https://github.com/dakrone/clj-http), except that every request immediately returns a Manifold deferred representing the response.
 
 ```clojure
 (require
+  '[aleph.http :as http]
   '[manifold.deferred :as d]
   '[clj-commons.byte-streams :as bs])
 
@@ -53,6 +62,12 @@ For HTTP client requests, Aleph models itself after [clj-http](https://github.co
          :body
          bs/to-string
          prn)
+
+;; To support HTTP/2, do the following:
+(def conn-pool
+  (http/connection-pool {:connection-options {:http-versions [:http2 :http1]}}))
+@(http/get "https://google.com" {:pool conn-pool})
+;; See aleph.examples.http2 for more details
 ```
 
 Aleph attempts to mimic the clj-http API and capabilities fully. It supports multipart/form-data requests, cookie stores, proxy servers and requests inspection with a few notable differences:
@@ -77,6 +92,22 @@ Aleph client also supports fully async and [highly customizable](https://github.
 
 To learn more, [read the example code](https://github.com/clj-commons/aleph/blob/master/examples/src/aleph/examples/http.clj).
 
+#### HTTP/2
+
+As of 0.7.0, Aleph supports HTTP/2 in both the client and the server.
+
+For the most part, Aleph's HTTP/2 support is a drop-in replacement for HTTP/1. For backwards compatibility, though, Aleph defaults to HTTP/1-only. See the [the example HTTP/2 code](https://github.com/clj-commons/aleph/blob/master/examples/src/aleph/examples/http2.clj) for a good overview on getting started with HTTP/2.
+
+Things to be aware of:
+
+1. Multipart uploads are not yet supported under HTTP/2, because Netty doesn't support them under HTTP/2. For new development, open a new H2 stream/request for each file instead. (HTTP/2 generally doesn't need multipart, since it doesn't have the same limitations on the number of connections as HTTP/1.) For existing multipart code, stick with HTTP/1. Ideally, this will be added in a future release.
+2. Aleph does not currently support the CONNECT method under HTTP/2. Stick with HTTP/1 if you're using CONNECT.
+3. Aleph will not support HTTP/2 server push, since it's deprecated, and effectively disabled by Chrome.
+4. Aleph does not currently support HTTP/2 trailers (headers arriving after the body).
+5. Aleph does nothing with priority information. We would like to expose an API to support user use of prioritization, but the browsers never agreed on how to interpret them, and some (e.g., Safari) effectively never used them. We think back-porting the HTTP/3 priority headers to HTTP/2 is a better aim.
+6. Aleph currently uses Netty's default flow control. This is a 64 kb window, which with bytes acknowledged as soon they're received. We plan to add support for adjusting the default window size and flow control strategy in a future release.
+7. If you were using `pipeline-transform` to alter the underlying Netty pipeline, you will need to check your usage of it for HTTP/2. Under the hood, the new HTTP/2 code uses Netty's multiplexed pipeline setup, with a shared connection-level pipeline that feeds stream-specific frames to N pipelines created for N individual streams. (A standard HTTP request/response pair maps to a single H2 stream.)
+
 ### WebSockets
 
 On any HTTP request which has the proper `Upgrade` headers, you may call `(aleph.http/websocket-connection req)`, which returns a deferred which yields a **duplex stream**, which uses a single stream to represent bidirectional communication.  Messages from the client can be received via `take!`, and sent to the client via `put!`.  An echo WebSocket handler, then, would just consist of:
@@ -136,6 +167,6 @@ Minimal [`tools.deps`](https://github.com/clojure/tools.deps.alpha) support is a
 
 ### License
 
-Copyright © 2010-2023 Zachary Tellman
+Copyright © 2010-2024 Zachary Tellman
 
 Distributed under the MIT License

adr/adr-001-http2.adoc

@@ -5,7 +5,7 @@ Date: 2023-04-10
 
 == Status
 
-#Proposed#
+#Accepted#
 
 A decision may be "proposed" if the project stakeholders haven't agreed with it
 yet, or "accepted" once it is agreed. If a later ADR changes or reverses a
@@ -94,15 +94,11 @@ HTTP/2 supports CONNECT proxying, but over a single HTTP/2 stream, not a whole T
 === Backwards-compatibility mode
 
 We will maintain a backwards-compatible API for the majority of users, where
-their existing handlers will work as is. All streams will have equal priority,
-and flow control will ...
-
-NOTE: What should the default flow control strategy be? An infinitely large
-window? The default 64kb window, that auto-replenishes as soon as bytes are read
-off? Netty offers both of the previous as default strategies available for use.
-
-NOTE: What should a raw stream look like? A sequence of ByteBufs? Or a sequence
-of Frames, which is Netty's "raw" level for HTTP/2?
+their existing Ring handlers will work as is. All streams will have equal
+priority, and flow control will use the default Netty policy of a 64 kb window,
+that auto-replenishes as soon as bytes are read off. Users will be able to
+adjust the initial window size. Ring maps will still be used in the normal mode,
+and ByteBufs will still be used in raw mode.
 
 === HTTP/2 connection mode
 We will NOT support server push, as our resources are too limited relative to

examples/project.clj

@@ -1,5 +1,5 @@
-(defproject aleph.examples "0.7.0-rc2"
-  :dependencies [[aleph "0.7.0-rc2"]
+(defproject aleph.examples "0.7.0"
+  :dependencies [[aleph "0.7.0"]
                  [gloss "0.2.6"]
                  [metosin/reitit "0.5.18"]
                  [org.clojure/clojure "1.11.1"]

project.clj

@@ -3,7 +3,7 @@
 (def brotli-version "1.12.0")
 
 
-(defproject aleph (or (System/getenv "PROJECT_VERSION") "0.7.0-rc2")
+(defproject aleph (or (System/getenv "PROJECT_VERSION") "0.7.0")
   :description "A framework for asynchronous communication"
   :url "https://github.com/clj-commons/aleph"
   :license {:name "MIT License"}

src/aleph/http/common.clj

@@ -27,7 +27,7 @@
 
 (set! *warn-on-reflection* true)
 
-(def aleph-server-header "Aleph value for the Server header" (AsciiString. "Aleph/0.7.0-rc2"))
+(def aleph-server-header "Aleph value for the Server header" (AsciiString. "Aleph/0.7.0"))
 
 (defprotocol HeaderMap
   (get-header-values [m ^String k]))