diff --git a/app-server/cli.md b/app-server/cli.md index f51faf6..f90e0d2 100644 --- a/app-server/cli.md +++ b/app-server/cli.md @@ -104,7 +104,7 @@ debug mode, which starts the pprof server and listens for incoming requests on p ## Experimental features -RoadRunner also supports experimental features. +RoadRunner can run with experimental features enabled. There are no experimental features at the moment, so the option has no effect. See [Experimental Features](../experimental/experimental.md). To enable experimental features, use the `--enable-experimental` or `-e` option: {% code %} @@ -132,8 +132,7 @@ To enable experimental features, use the `--enable-experimental` or `-e` option: - `-s` - suppresses command status messages. Configure plugin logs through the `logs` section. - `-o` - overrides a configuration key, such as `-o http.address=127.0.0.1:8080`. Included files can override these values. - `-p` - creates a `.pid` file for `rr stop`. -- `-e` or `--enable-experimental` - enables experimental features. This option is useful when you want to test new - features that are not yet available in the stable release. +- `-e` or `--enable-experimental` - enables experimental features. There are no experimental features at the moment. ## Stopping the Server diff --git a/experimental/experimental.md b/experimental/experimental.md index f45523d..5d536cb 100644 --- a/experimental/experimental.md +++ b/experimental/experimental.md @@ -2,7 +2,14 @@ ## Introduction -Starting with RR `v2023.3.4`, we introduced a new capability called **Experimental Features**. This allows you to try out features that are not yet ready for production use. +Starting with RR `v2023.3.4`, RoadRunner can run with experimental features enabled. These are features that are not yet ready for production use. + +RoadRunner has no experimental features at the moment. The `-e` flag is accepted and has no effect. + +These features were experimental in earlier releases and are stable now: + +- HTTP/3 server. See [HTTP/3](../http/http.md#http3). +- `envfile` and `include` configuration settings. See [Configuration](../plugins/config.md). ## How to enable experimental features @@ -25,77 +32,3 @@ Or: ``` {% endcode %} - -## Configuration Files - -The `envfile` and `include` settings work without the experimental flag. See [Configuration](../plugins/config.md) for these settings. - -## HTTP/3 Server - -Set `http.http3.cert` and `http.http3.key` to existing certificate and private key files. The HTTP/3 listener requires these files at startup. Start RoadRunner with `-e` to enable this listener. - -Sample `.rr.yaml` file: - -{% code title=".rr.yaml" %} - -```yaml -version: "3" - -server: - command: "php worker.php" - relay: pipes - -http: - address: 127.0.0.1:15389 - pool: - num_workers: 2 - http3: - address: 127.0.0.1:34555 - key: "localhost+2-key.pem" - cert: "localhost+2.pem" -``` - -{% endcode %} - -You can also generate test certificates manually and use them in the configuration file. To do that, use [mkcert](https://github.com/FiloSottile/mkcert) or [certbot](https://certbot.eff.org/): - -{% code %} - -```bash -mkcert -install && mkcert -client localhost 127.0.0.1 ::1 && mkcert localhost 127.0.0.1 ::1 -``` - -{% endcode %} - -This command generates the client and server certificates for the `localhost` domain. You can use them in the configuration file: - -{% code title=".rr.yaml" %} - -```yaml .rr.yaml -version: "3" - -server: - command: "php worker.php" - relay: pipes - -http: - address: 127.0.0.1:15389 - pool: - num_workers: 2 - http3: - address: 127.0.0.1:34555 - key: "localhost+2-key.pem" # <- generated by mkcert: "localhost+2-key.pem" - cert: "localhost+2.pem" # <- generated by mkcert: "localhost+2.pem" -``` - -{% endcode %} - -You can use client certificates in your preferred HTTP/3 client. For example, use [curl3](https://curl.se/docs/http3.html) to test the HTTP/3 server: - -{% code %} - -```bash -curl3 --http3 -k --cert localhost+2.pem --key localhost+2-key.pem https://127.0.0.1:34555/ -``` - -{% endcode %} diff --git a/http/http.md b/http/http.md index d16b9e4..5a84322 100644 --- a/http/http.md +++ b/http/http.md @@ -346,6 +346,17 @@ http: # # Default: 128 max_concurrent_streams: 128 + + # HTTP/3 settings. Enable QUIC + HTTP/3 on a separate address. + http3: + # Host and port to listen on for HTTP/3. + # + # Default: disabled (section absent) + address: 127.0.0.1:8443 + # Path to the certificate. Required together with the key when the section is present. + cert: "/ssl/cert.crt" + # Path to the private key. + key: "/ssl/key.pem" ``` {% endcode %} @@ -638,7 +649,50 @@ The parser can reject fragmented v1 headers. It limits the v2 address and metada ## HTTP/3 -HTTP/3 support is experimental and might change in the future. Docs are available in the [experimental](../experimental/experimental.md) section. +Add the `http3` section to the `http` config to start an HTTP/3 listener. QUIC uses UDP, so the listener has its own address. Set `cert` and `key` to existing certificate and private key files. The listener loads these files at startup. + +{% code title=".rr.yaml" %} + +```yaml +version: "3" + +server: + command: "php worker.php" + relay: pipes + +http: + address: 127.0.0.1:15389 + pool: + num_workers: 2 + http3: + address: 127.0.0.1:34555 + key: "localhost+2-key.pem" + cert: "localhost+2.pem" +``` + +{% endcode %} + +To generate test certificates, use [mkcert](https://github.com/FiloSottile/mkcert) or [certbot](https://certbot.eff.org/): + +{% code %} + +```bash +mkcert -install && mkcert localhost 127.0.0.1 ::1 +``` + +{% endcode %} + +This command installs a local CA and writes `localhost+2.pem` and `localhost+2-key.pem` for the `localhost` domain. Use them in the configuration above. + +To test the server, use a client with HTTP/3 support, such as [curl](https://curl.se/docs/http3.html): + +{% code %} + +```bash +curl --http3 -k https://127.0.0.1:34555/ +``` + +{% endcode %} ## Overriding HTTP default error code