Merge branch 'master' into return-allow-header

.github/workflows/ci.yaml

@@ -4,11 +4,16 @@ name: Check Cowboy
 
 on:
   push:
+    branches:
+      - master
   pull_request:
   schedule:
       ## Every Monday at 2am.
       - cron: 0 2 * * 1
 
+env:
+  CI_ERLANG_MK: 1
+
 jobs:
   cleanup-master:
     name: Cleanup master build
@@ -29,3 +34,37 @@ jobs:
     name: Cowboy
     needs: cleanup-master
     uses: ninenines/ci.erlang.mk/.github/workflows/ci.yaml@master
+
+# The examples test suite is nice to run but typically not
+# important. So we run them after we are done with the other
+# test suites. At this point we know that Erlang was built
+# so we can just use the latest version.
+
+  examples:
+    name: Check examples
+    needs: check
+    runs-on: 'ubuntu-latest'
+    if: ${{ !cancelled() }}
+    steps:
+
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Output latest Erlang/OTP version
+      id: latest_version
+      run: |
+        {
+          echo "latest<<EOF"
+          make ci-list | grep -v rc | grep -v master | tail -n1
+          echo EOF
+        } >> "$GITHUB_OUTPUT"
+
+    - name: Restore CI cache
+      uses: actions/cache/restore@v4
+      with:
+        path: |
+          ~/erlang/
+        key: ${{ runner.os }}-${{ runner.arch }}-Erlang-${{ steps.latest_version.outputs.latest }}
+
+    - name: Run ct-examples
+      run: make ct-examples LATEST_ERLANG_OTP=1

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011-2022, Loïc Hoguin <[email protected]>
+Copyright (c) 2011-2024, Loïc Hoguin <[email protected]>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

Makefile

@@ -2,7 +2,7 @@
 
 PROJECT = cowboy
 PROJECT_DESCRIPTION = Small, fast, modern HTTP server.
-PROJECT_VERSION = 2.10.0
+PROJECT_VERSION = 2.12.0
 PROJECT_REGISTERED = cowboy_clock
 
 # Options.
@@ -15,9 +15,14 @@ CT_OPTS += -ct_hooks cowboy_ct_hook [] # -boot start_sasl
 LOCAL_DEPS = crypto
 
 DEPS = cowlib ranch
-dep_cowlib = git https://github.com/ninenines/cowlib 2.12.1
+dep_cowlib = git https://github.com/ninenines/cowlib master
 dep_ranch = git https://github.com/ninenines/ranch 1.8.0
 
+ifeq ($(COWBOY_QUICER),1)
+DEPS += quicer
+dep_quicer = git https://github.com/emqx/quic main
+endif
+
 DOC_DEPS = asciideck
 
 TEST_DEPS = $(if $(CI_ERLANG_MK),ci.erlang.mk) ct_helper gun
@@ -38,8 +43,8 @@ define HEX_TARBALL_EXTRA_METADATA
 #{
 	licenses => [<<"ISC">>],
 	links => #{
-		<<"User guide">> => <<"https://ninenines.eu/docs/en/cowboy/2.10/guide/">>,
-		<<"Function reference">> => <<"https://ninenines.eu/docs/en/cowboy/2.10/manual/">>,
+		<<"User guide">> => <<"https://ninenines.eu/docs/en/cowboy/2.12/guide/">>,
+		<<"Function reference">> => <<"https://ninenines.eu/docs/en/cowboy/2.12/manual/">>,
 		<<"GitHub">> => <<"https://github.com/ninenines/cowboy">>,
 		<<"Sponsor">> => <<"https://github.com/sponsors/essen">>
 	}
@@ -50,21 +55,37 @@ endef
 
 include erlang.mk
 
-# Don't run the examples test suite by default.
+# Don't run the examples/autobahn test suites by default.
 
 ifndef FULL
 CT_SUITES := $(filter-out examples ws_autobahn,$(CT_SUITES))
 endif
 
+# Don't run HTTP/3 test suites on Windows.
+
+ifeq ($(PLATFORM),msys2)
+CT_SUITES := $(filter-out rfc9114 rfc9204 rfc9220,$(CT_SUITES))
+endif
+
 # Compile options.
 
 ERLC_OPTS += +warn_missing_spec +warn_untyped_record # +bin_opt_info
 TEST_ERLC_OPTS += +'{parse_transform, eunit_autoexport}'
 
+ifeq ($(COWBOY_QUICER),1)
+ERLC_OPTS += -D COWBOY_QUICER=1
+TEST_ERLC_OPTS += -D COWBOY_QUICER=1
+endif
+
 # Generate rebar.config on build.
 
 app:: rebar.config
 
+# Fix quicer compilation for HTTP/3.
+
+autopatch-quicer::
+	$(verbose) printf "%s\n" "all: ;" > $(DEPS_DIR)/quicer/c_src/Makefile.erlang.mk
+
 # Dialyze the tests.
 
 #DIALYZER_OPTS += --src -r test
@@ -101,8 +122,11 @@ prepare_tag:
 	$(verbose) echo -n "GUIDE:  "
 	$(verbose) grep -h dep_$(PROJECT)_commit doc/src/guide/*.asciidoc || true
 	$(verbose) echo
+	$(verbose) echo "Links in the README:"
+	$(verbose) grep http.*:// README.asciidoc
+	$(verbose) echo
 	$(verbose) echo "Titles in most recent CHANGELOG:"
-	$(verbose) for f in `ls -r doc/src/guide/migrating_from_*.asciidoc | head -n1`; do \
+	$(verbose) for f in `ls -rv doc/src/guide/migrating_from_*.asciidoc | head -n1`; do \
 		echo $$f:; \
 		grep == $$f; \
 	done

README.asciidoc

@@ -18,8 +18,8 @@ Cowboy is *clean* and *well tested* Erlang code.
 
 == Online documentation
 
-* https://ninenines.eu/docs/en/cowboy/2.6/guide[User guide]
-* https://ninenines.eu/docs/en/cowboy/2.6/manual[Function reference]
+* https://ninenines.eu/docs/en/cowboy/2.12/guide[User guide]
+* https://ninenines.eu/docs/en/cowboy/2.12/manual[Function reference]
 
 == Offline documentation
 

doc/src/guide/book.asciidoc

@@ -75,6 +75,10 @@ include::performance.asciidoc[Performance]
 
 = Additional information
 
+include::migrating_from_2.11.asciidoc[Migrating from Cowboy 2.11 to 2.12]
+
+include::migrating_from_2.10.asciidoc[Migrating from Cowboy 2.10 to 2.11]
+
 include::migrating_from_2.9.asciidoc[Migrating from Cowboy 2.9 to 2.10]
 
 include::migrating_from_2.8.asciidoc[Migrating from Cowboy 2.8 to 2.9]

doc/src/guide/getting_started.asciidoc

@@ -62,14 +62,16 @@ handler.
 === Cowboy setup
 
 We will modify the 'Makefile' to tell the build system it needs to
-fetch and compile Cowboy:
+fetch and compile Cowboy, and that we will use releases:
 
 [source,makefile]
 ----
 PROJECT = hello_erlang
 
 DEPS = cowboy
-dep_cowboy_commit = 2.10.0
+dep_cowboy_commit = 2.11.0
+
+REL_DEPS = relx
 
 DEP_PLUGINS = cowboy
 
@@ -80,6 +82,9 @@ The `DEP_PLUGINS` line tells the build system to load the plugins
 Cowboy provides. These include predefined templates that we will
 use soon.
 
+The `REL_DEPS` line tells the build system to fetch and build
+`relx`, the library that will create the release.
+
 If you do `make run` now, Cowboy will be included in the release
 and started automatically. This is not enough however, as Cowboy
 doesn't do anything by default. We still need to tell Cowboy to

doc/src/guide/introduction.asciidoc

@@ -42,7 +42,7 @@ Cowboy is developed for Erlang/OTP 22.0 and newer.
 Cowboy uses the ISC License.
 
 ----
-Copyright (c) 2011-2019, Loïc Hoguin <[email protected]>
+Copyright (c) 2011-2024, Loïc Hoguin <[email protected]>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above

doc/src/guide/migrating_from_2.10.asciidoc

@@ -0,0 +1,139 @@
+[appendix]
+== Migrating from Cowboy 2.10 to 2.11
+
+Cowboy 2.11 contains a variety of new features and bug
+fixes. Nearly all previously experimental features are
+now marked as stable, including Websocket over HTTP/2.
+Included is a fix for an HTTP/2 protocol CVE.
+
+Cowboy 2.11 requires Erlang/OTP 24.0 or greater.
+
+Cowboy is now using GitHub Actions for CI. The main reason
+for the move is to reduce costs by no longer having to
+self-host CI runners. The downside is that GitHub runners
+are less reliable and timing dependent tests are now more
+likely to fail.
+
+=== Features added
+
+* A new HTTP/2 option `max_cancel_stream_rate` has been added
+  to control the rate of stream cancellation the server will
+  accept. By default Cowboy will accept 500 cancelled streams
+  every 10 seconds.
+
+* A new stream handler `cowboy_decompress_h` has been added.
+  It allows automatically decompressing incoming gzipped
+  request bodies. It includes options to protect against
+  zip bombs.
+
+* Websocket over HTTP/2 is no longer considered experimental.
+  Note that the `enable_connect_protocol` option must be set
+  to `true` in order to use Websocket over HTTP/2 for the
+  time being.
+
+* Automatic mode for reading request bodies has been
+  documented. In automatic mode, Cowboy waits indefinitely
+  for data and sends a `request_body` message when data
+  comes in. It mirrors `{active, once}` socket modes.
+  This is ideal for loop handlers and is also used
+  internally for HTTP/2 Websocket.
+
+* Ranged requests support is no longer considered
+  experimental. It was added in 2.6 to both `cowboy_static`
+  and `cowboy_rest`. Ranged responses can be produced
+  either automatically (for the `bytes` unit) or manually.
+  REST flowcharts have been updated with the new callbacks
+  and steps related to handling ranged requests.
+
+* A new HTTP/1.1 and HTTP/2 option `reset_idle_timeout_on_send`
+  has been added. When enabled, the `idle_timeout` will be
+  reset every time Cowboy sends data to the socket.
+
+* Loop handlers may now return a timeout value in the place
+  of `hibernate`. Timeouts behave the same as in `gen_server`.
+
+* The `generate_etag` callback of REST handlers now accepts
+  `undefined` as a return value to allow conditionally
+  generating etags.
+
+* The `cowboy_compress_h` options `compress_threshold` and
+  `compress_buffering` are no longer considered experimental.
+  They were de facto stable since 2.6 as they already were
+  documented.
+
+* Functions `cowboy:get_env/2,3` have been added.
+
+* Better error messages have been added when trying to send
+  a 204 or 304 response with a body; when attempting to
+  send two responses to a single request; when trying to
+  push a response after the final response; when trying
+  to send a `set-cookie` header without using
+  `cowboy_req:set_resp_cookie/3,4`.
+
+=== Features removed
+
+* Cowboy will no longer include the NPN extension when
+  starting a TLS listener. This extension has long been
+  deprecated and replaced with the ALPN extension. Cowboy
+  will continue using the ALPN extension for protocol
+  negotiation.
+
+=== Bugs fixed
+
+* A fix was made to address the HTTP/2 CVE CVE-2023-44487
+  via the new HTTP/2 option `max_cancel_stream_rate`.
+
+* HTTP/1.1 requests that contain both a content-length and
+  a transfer-encoding header will now be rejected to avoid
+  security risks. Previous behavior was to ignore the
+  content-length header as recommended by the HTTP RFC.
+
+* HTTP/1.1 connections would sometimes use the wrong timeout
+  value to determine whether the connection should be closed.
+  This resulted in connections staying up longer than
+  intended. This should no longer be the case.
+
+* Cowboy now reacts to socket errors immediately for HTTP/1.1
+  and HTTP/2 when possible. Cowboy will notice when connections
+  have been closed properly earlier than before. This also
+  means that the socket option `send_timeout_close` will work
+  as expected.
+
+* Shutting down HTTP/1.1 pipelined requests could lead to
+  the current request being terminated before the response
+  has been sent. This has been addressed.
+
+* When using HTTP/1.1 an invalid Connection header will now
+  be rejected with a 400 status code instead of crashing.
+
+* The documentation now recommends increasing the HTTP/2
+  option `max_frame_size_received`. Cowboy currently uses
+  the protocol default but will increase its default in a
+  future release. Until then users are recommended to set
+  the option to ensure larger requests are accepted and
+  processed with acceptable performance.
+
+* Cowboy could sometimes send HTTP/2 WINDOW_UPDATE frames
+  twice in a row. Now they should be consolidated.
+
+* Cowboy would sometimes send HTTP/2 WINDOW_UPDATE frames
+  for streams that have stopped internally. This should
+  no longer be the case.
+
+* The `cowboy_compress_h` stream handler will no longer
+  attempt to compress responses that have an `etag` header
+  to avoid caching issues.
+
+* The `cowboy_compress_h` will now always add `accept-encoding`
+  to the `vary` header as it indicates that responses may
+  be compressed.
+
+* Cowboy will now remove the `trap_exit` process flag when
+  HTTP/1.1 connections upgrade to Websocket.
+
+* Exit gracefully instead of crashing when the socket gets
+  closed when reading the PROXY header.
+
+* Missing `cowboy_stream` manual pages have been added.
+
+* A number of fixes were made to documentation and examples.

doc/src/guide/migrating_from_2.11.asciidoc

@@ -0,0 +1,15 @@
+[appendix]
+== Migrating from Cowboy 2.11 to 2.12
+
+Cowboy 2.12 contains a small security improvement for
+the HTTP/2 protocol.
+
+Cowboy 2.12 requires Erlang/OTP 24.0 or greater.
+
+=== Features added
+
+* A new HTTP/2 option `max_fragmented_header_block_size` has
+  been added to limit the size of header blocks that are
+  sent over multiple HEADERS and CONTINUATION frames.
+
+* Update Cowlib to 2.13.0.

doc/src/guide/resource_design.asciidoc

@@ -144,6 +144,16 @@ never be called.
 Implement the `languages_provided` or `charsets_provided`
 callbacks if applicable.
 
+Does the resource accept ranged requests? If it does,
+implement the `ranges_provided` callback. Resources that
+only accept `bytes` units can use the callback name
+`auto` and let Cowboy automatically do ranged responses.
+Other callbacks should have a name prefix of `ranged_`
+for clarity. For example, `ranged_bytes` or `ranged_pages`.
+If the resource needs to perform additional checks before
+accepting to do a ranged responses, implement the
+`range_satisfiable` callback.
+
 Is there any other header that may make the representation
 of the resource vary? Implement the `variances` callback.
 
@@ -191,10 +201,15 @@ the `options` method.
 === GET and HEAD methods
 
 If you implement the methods GET and/or HEAD, you must
-implement one `ProvideResource` callback for each
+implement one `ProvideCallback` callback for each
 content-type returned by the `content_types_provided`
 callback.
 
+When range requests are accepted, you must implement one
+`RangeCallback` for each range unit returned by
+`ranges_provided` (unless `auto` was used). This is
+in addition to the `ProvideCallback` callback.
+
 === PUT, POST and PATCH methods
 
 If you implement the methods PUT, POST and/or PATCH,