diff --git a/docs/src/main/paradox/java/http/client-side/client-https-support.md b/docs/src/main/paradox/java/http/client-side/client-https-support.md deleted file mode 100644 index bad0cc0169e..00000000000 --- a/docs/src/main/paradox/java/http/client-side/client-https-support.md +++ /dev/null @@ -1,114 +0,0 @@ - -# Client-Side HTTPS Support - -Akka HTTP supports TLS encryption on the client-side as well as on the @ref[server-side](../server-side-https-support.md#serversidehttps-java). - -The central vehicle for configuring encryption is the `HttpsConnectionContext`, which can be created using -the static method `ConnectionContext.https` which is defined like this: - -@@snip [ConnectionContext.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/javadsl/ConnectionContext.scala) { #https-context-creation } - -In addition to the `outgoingConnection`, `newHostConnectionPool` and `cachedHostConnectionPool` methods the -@javadoc[akka.http.javadsl.Http](akka.http.javadsl.Http) extension also defines `outgoingConnectionHttps`, `newHostConnectionPoolHttps` and -`cachedHostConnectionPoolHttps`. These methods work identically to their counterparts without the `-Https` suffix, -with the exception that all connections will always be encrypted. - -The `singleRequest` and `superPool` methods determine the encryption state via the scheme of the incoming request, -i.e. requests to an "https" URI will be encrypted, while requests to an "http" URI won't. - -The encryption configuration for all HTTPS connections, i.e. the `HttpsContext` is determined according to the -following logic: - - 1. If the optional `httpsContext` method parameter is defined it contains the configuration to be used (and thus -takes precedence over any potentially set default client-side `HttpsContext`). - 2. If the optional `httpsContext` method parameter is undefined (which is the default) the default client-side -`HttpsContext` is used, which can be set via the `setDefaultClientHttpsContext` on the `Http` extension. - 3. If no default client-side `HttpsContext` has been set via the `setDefaultClientHttpsContext` on the `Http` -extension the default system configuration is used. - -Usually the process is, if the default system TLS configuration is not good enough for your application's needs, -that you configure a custom `HttpsContext` instance and set it via `Http.get(system).setDefaultClientHttpsContext`. -Afterwards you simply use `outgoingConnectionHttps`, `newHostConnectionPoolHttps`, `cachedHostConnectionPoolHttps`, -`superPool` or `singleRequest` without a specific `httpsContext` argument, which causes encrypted connections -to rely on the configured default client-side `HttpsContext`. - -If no custom `HttpsContext` is defined the default context uses Java's default TLS settings. Customizing the -`HttpsContext` can make the Https client less secure. Understand what you are doing! - -## SSL-Config - -Akka HTTP heavily relies on, and delegates most configuration of any SSL/TLS related options to -[Lightbend SSL-Config](http://typesafehub.github.io/ssl-config/), which is a library specialized in providing an secure-by-default SSLContext -and related options. - -Please refer to the [Lightbend SSL-Config](http://typesafehub.github.io/ssl-config/) documentation for detailed documentation of all available settings. - -SSL Config settings used by Akka HTTP (as well as Streaming TCP) are located under the *akka.ssl-config* namespace. - -## Detailed configuration and workarounds - -Akka HTTP relies on [Typesafe SSL-Config](http://typesafehub.github.io/ssl-config) which is a library maintained by Lightbend that makes configuring -things related to SSL/TLS much simpler than using the raw SSL APIs provided by the JDK. Please refer to its -documentation to learn more about it. - -All configuration options available to this library may be set under the `akka.ssl-config` configuration for Akka HTTP applications. - -@@@ note -When encountering problems connecting to HTTPS hosts we highly encourage to reading up on the excellent ssl-config -configuration. Especially the quick start sections about [adding certificates to the trust store](http://typesafehub.github.io/ssl-config/WSQuickStart.html#connecting-to-a-remote-server-over-https) should prove -very useful, for example to easily trust a self-signed certificate that applications might use in development mode. -@@@ - -@@@ warning - -While it is possible to disable certain checks using the so called "loose" settings in SSL Config, we **strongly recommend** -to instead attempt to solve these issues by properly configuring TLS–for example by adding trusted keys to the keystore. - -If however certain checks really need to be disabled because of misconfigured (or legacy) servers that your -application has to speak to, instead of disabling the checks globally (i.e. in `application.conf`) we suggest -configuring the loose settings for *specific connections* that are known to need them disabled (and trusted for some other reason). -The pattern of doing so is documented in the following sub-sections. - -@@@ - -### Hostname verification - -Hostname verification proves that the Akka HTTP client is actually communicating with the server it intended to -communicate with. Without this check a man-in-the-middle attack is possible. In the attack scenario, an alternative -certificate would be presented which was issued for another host name. Checking the host name in the certificate -against the host name the connection was opened against is therefore vital. - -The default `HttpsContext` enables hostname verification. Akka HTTP relies on the [Typesafe SSL-Config](http://typesafehub.github.io/ssl-config) library -to implement this and security options for SSL/TLS. Hostname verification is provided by the JDK -and used by Akka HTTP since Java 7, and on Java 6 the verification is implemented by ssl-config manually. - -For further recommended reading we would like to highlight the [fixing hostname verification blog post](https://tersesystems.com/2014/03/23/fixing-hostname-verification/) by blog post by Will Sargent. - -### Server Name Indication (SNI) - -SNI is an TLS extension which aims to guard against man-in-the-middle attacks. It does so by having the client send the -name of the virtual domain it is expecting to talk to as part of the TLS handshake. - -It is specified as part of [RFC 6066](https://tools.ietf.org/html/rfc6066#page-6). - -### Disabling TLS security features, at your own risk - -@@@ warning - -It is highly discouraged to disable any of the security features of TLS, however do acknowledge that workarounds may sometimes be needed. - -Before disabling any of the features one should consider if they may be solvable *within* the TLS world, -for example by [trusting a certificate](http://typesafehub.github.io/ssl-config/WSQuickStart.html), or [configuring the trusted cipher suites](http://typesafehub.github.io/ssl-config/CipherSuites.html). -There's also a very important section in the ssl-config docs titled [LooseSSL - Please read this before turning anything off!](http://typesafehub.github.io/ssl-config/LooseSSL.html#please-read-this-before-turning-anything-off). - -If disabling features is indeed desired, we recommend doing so for *specific connections*, -instead of globally configuring it via `application.conf`. - -@@@ - -The following shows an example of disabling SNI for a given connection: - -@@snip [HttpsExamplesDocTest.java](../../../../../test/java/docs/http/javadsl/HttpsExamplesDocTest.java) { #disable-sni-connection } - -The `badSslConfig` is a copy of the default `AkkaSSLConfig` with with the slightly changed configuration to disable SNI. -This value can be cached and used for connections which should indeed not use this feature. diff --git a/docs/src/main/paradox/java/http/client-side/client-https-support.md b/docs/src/main/paradox/java/http/client-side/client-https-support.md new file mode 120000 index 00000000000..ce5b52bb383 --- /dev/null +++ b/docs/src/main/paradox/java/http/client-side/client-https-support.md @@ -0,0 +1 @@ +../../../scala/http/client-side/client-https-support.md \ No newline at end of file diff --git a/docs/src/main/paradox/java/http/client-side/client-transport.md b/docs/src/main/paradox/java/http/client-side/client-transport.md deleted file mode 100644 index 8ac756bedd8..00000000000 --- a/docs/src/main/paradox/java/http/client-side/client-transport.md +++ /dev/null @@ -1,63 +0,0 @@ -# Pluggable Client Transports / HTTPS Proxy Support - -The client side infrastructure has (unstable) support to plug different transport mechanisms underneath. A client side -transport is represented by an instance of @javadoc[akka.http.javadsl.ClientTransport](akka.http.javadsl.ClientTransport): - -@@snip [ClientTransport.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/javadsl/ClientTransport.scala) { #client-transport-definition } - -A transport implementation defines how the client infrastructure should communicate with a given host. - -@@@note - -In our model, SSL/TLS runs on top of the client transport, even if you could theoretically see it as part of the -transport layer itself. - -@@@ - -## Configuring Client Transports - -A `ClientTransport` is configured slightly differently for the various layers of the HTTP client. -Right now, configuration is only possible with code (and not through config files). There's currently no -predefined way that would allow you to select different transports per target host (but you can easily define any kind -of strategy by implementing `ClientTransport` yourself). - -### Connection Pool Usage - -The `ConnectionPoolSettings` class allows setting a custom transport for any of the pool methods. Use -`ConnectionPoolSettings.withTransport` to configure a transport and pass those settings to one of the -pool methods like `Http.get(...).singleRequest`, `Http.get(...).superPool`, or `Http.get(...).cachedHostConnectionPool`. - -### Single Connection Usage - -You can configure a custom transport for a single HTTP connection by passing it to the `Http().outgoingConnectionUsingTransport` -method. - -## Predefined Transports - -### TCP - -The default transport is `ClientTransport.TCP` which simply opens a TCP connection to the target host. - -### HTTPS Proxy - -A transport that connects to target servers via an HTTPS proxy. An HTTPS proxy uses the HTTP `CONNECT` method (as -specified in [RFC 7231 Section 4.3.6](https://tools.ietf.org/html/rfc7231#section-4.3.6)) to create tunnels to target -servers. The proxy itself should transparently forward data to the target servers so that end-to-end encryption should -still work (if TLS breaks, then the proxy might be fussing with your data). - -Instantiate the HTTPS proxy transport using `ClientTransport.httpsProxy(proxyAddress)`. - -## Implementing Custom Transports - -Implement `ClientTransport.connectTo` to implement a custom client transport. - -Here are some ideas for custom (or future predefined) transports: - - * SSH tunnel transport: connects to the target host through an SSH tunnel - * Per-host configurable transport: allows choosing transports per target host - -## Usage Examples - -### Use HTTPS Proxy with `Http.get(...).singleRequest` - -@@snip [HttpClientExampleDocTest.java](../../../../../test/java/docs/http/javadsl/HttpClientExampleDocTest.java) { #https-proxy-example-single-request } diff --git a/docs/src/main/paradox/java/http/client-side/client-transport.md b/docs/src/main/paradox/java/http/client-side/client-transport.md new file mode 120000 index 00000000000..fc7d902869a --- /dev/null +++ b/docs/src/main/paradox/java/http/client-side/client-transport.md @@ -0,0 +1 @@ +../../../scala/http/client-side/client-transport.md \ No newline at end of file diff --git a/docs/src/main/paradox/java/http/client-side/connection-level.md b/docs/src/main/paradox/java/http/client-side/connection-level.md deleted file mode 100644 index 2e139a30bfe..00000000000 --- a/docs/src/main/paradox/java/http/client-side/connection-level.md +++ /dev/null @@ -1,68 +0,0 @@ - -# Connection-Level Client-Side API - -The connection-level API is the lowest-level client-side API Akka HTTP provides. It gives you full control over when -HTTP connections are opened and closed and how requests are to be send across which connection. As such it offers the -highest flexibility at the cost of providing the least convenience. - -## Opening HTTP Connections - -With the connection-level API you open a new HTTP connection to a target endpoint by materializing a `Flow` -returned by the `Http.get(system).outgoingConnection(...)` method. Here is an example: - -@@snip [HttpClientExampleDocTest.java](../../../../../test/java/docs/http/javadsl/HttpClientExampleDocTest.java) { #outgoing-connection-example } - -Apart from the host name and port the `Http.get(system).outgoingConnection(...)` method also allows you to specify socket options -and a number of configuration settings for the connection. - -Note that no connection is attempted until the returned flow is actually materialized! If the flow is materialized -several times then several independent connections will be opened (one per materialization). -If the connection attempt fails, for whatever reason, the materialized flow will be immediately terminated with a -respective exception. - -## Request-Response Cycle - -Once the connection flow has been materialized it is ready to consume `HttpRequest` instances from the source it is -attached to. Each request is sent across the connection and incoming responses dispatched to the downstream pipeline. -Of course and as always, back-pressure is adequately maintained across all parts of the -connection. This means that, if the downstream pipeline consuming the HTTP responses is slow, the request source will -eventually be slowed down in sending requests. - -Any errors occurring on the underlying connection are surfaced as exceptions terminating the response stream (and -canceling the request source). - -Note that, if the source produces subsequent requests before the prior responses have arrived, these requests will be -[pipelined](http://en.wikipedia.org/wiki/HTTP_pipelining) across the connection, which is something that is not supported by all HTTP servers. -Also, if the server closes the connection before responses to all requests have been received this will result in the -response stream being terminated with a truncation error. - -## Closing Connections - -Akka HTTP actively closes an established connection upon reception of a response containing `Connection: close` header. -The connection can also be closed by the server. - -An application can actively trigger the closing of the connection by completing the request stream. In this case the -underlying TCP connection will be closed when the last pending response has been received. - -The connection will also be closed if the response entity is cancelled (e.g. by attaching it to `Sink.cancelled()`) -or consumed only partially (e.g. by using `take` combinator). In order to prevent this behaviour the entity should be -explicitly drained by attaching it to `Sink.ignore()`. - -## Timeouts - -Timeouts are configured in the same way for Scala and Akka. See @ref[Akka HTTP Timeouts](../common/timeouts.md#http-timeouts-java) . - - -## Stand-Alone HTTP Layer Usage - -Due to its Reactive-Streams-based nature the Akka HTTP layer is fully detachable from the underlying TCP -interface. While in most applications this "feature" will not be crucial it can be useful in certain cases to be able -to "run" the HTTP layer (and, potentially, higher-layers) against data that do not come from the network but rather -some other source. Potential scenarios where this might be useful include tests, debugging or low-level event-sourcing -(e.g by replaying network traffic). - -On the client-side the stand-alone HTTP layer forms a `BidiFlow`, -that is a stage that "upgrades" a potentially encrypted raw connection to the HTTP level. - -You create an instance of the layer by calling one of the two overloads of the `Http.get(system).clientLayer` method, -which also allows for varying degrees of configuration. \ No newline at end of file diff --git a/docs/src/main/paradox/java/http/client-side/connection-level.md b/docs/src/main/paradox/java/http/client-side/connection-level.md new file mode 120000 index 00000000000..2b30d3b0f96 --- /dev/null +++ b/docs/src/main/paradox/java/http/client-side/connection-level.md @@ -0,0 +1 @@ +../../../scala/http/client-side/connection-level.md \ No newline at end of file diff --git a/docs/src/main/paradox/java/http/client-side/websocket-support.md b/docs/src/main/paradox/java/http/client-side/websocket-support.md index 13c02a3a3f4..a8e2e25b1ae 100644 --- a/docs/src/main/paradox/java/http/client-side/websocket-support.md +++ b/docs/src/main/paradox/java/http/client-side/websocket-support.md @@ -72,7 +72,7 @@ Simple example sending a message and printing any incoming message: ## webSocketClientLayer -Just like the @ref[Stand-Alone HTTP Layer Usage](connection-level.md#http-client-layer-java) for regular HTTP requests, the WebSocket layer can be used fully detached from the +Just like the @ref[Stand-Alone HTTP Layer Usage](connection-level.md#http-client-layer) for regular HTTP requests, the WebSocket layer can be used fully detached from the underlying TCP interface. The same scenarios as described for regular HTTP requests apply here. The returned layer forms a `BidiFlow>`. diff --git a/docs/src/main/paradox/java/http/common/timeouts.md b/docs/src/main/paradox/java/http/common/timeouts.md deleted file mode 100644 index cbaebc8054a..00000000000 --- a/docs/src/main/paradox/java/http/common/timeouts.md +++ /dev/null @@ -1,83 +0,0 @@ - -# Akka HTTP Timeouts - -Akka HTTP comes with a variety of built-in timeout mechanisms to protect your servers from malicious attacks or -programming mistakes. Some of these are simply configuration options (which may be overridden in code) while others -are left to the streaming APIs and are easily implementable as patterns in user-code directly. - -## Common timeouts - - -### Idle timeouts - -The `idle-timeout` is a global setting which sets the maximum inactivity time of a given connection. -In other words, if a connection is open but no request/response is being written to it for over `idle-timeout` time, -the connection will be automatically closed. - -The setting works the same way for all connections, be it server-side or client-side, and it's configurable -independently for each of those using the following keys: - -``` -akka.http.server.idle-timeout -akka.http.client.idle-timeout -akka.http.host-connection-pool.idle-timeout -akka.http.host-connection-pool.client.idle-timeout -``` - -@@@ note -For the connection pooled client side the idle period is counted only when the pool has no pending requests waiting. -@@@ - -## Server timeouts - - -### Request timeout - -Request timeouts are a mechanism that limits the maximum time it may take to produce an `HttpResponse` from a route. -If that deadline is not met the server will automatically inject a Service Unavailable HTTP response and close the connection -to prevent it from leaking and staying around indefinitely (for example if by programming error a Future would never complete, -never sending the real response otherwise). - -The default `HttpResponse` that is written when a request timeout is exceeded looks like this: - -@@snip [HttpServerBluePrint.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/impl/engine/server/HttpServerBluePrint.scala) { #default-request-timeout-httpresponse } - -A default request timeout is applied globally to all routes and can be configured using the -`akka.http.server.request-timeout` setting (which defaults to 20 seconds). - -@@@ note -Please note that if multiple requests (`R1,R2,R3,...`) were sent by a client (see "HTTP pipelining") -using the same connection and the `n-th` request triggers a request timeout the server will reply with an Http Response -and close the connection, leaving the `(n+1)-th` (and subsequent requests on the same connection) unhandled. -@@@ - -The request timeout can be configured at run-time for a given route using the any of the @ref[TimeoutDirectives](../routing-dsl/directives/timeout-directives/index.md#timeoutdirectives). - -### Bind timeout - -The bind timeout is the time period within which the TCP binding process must be completed (using any of the `Http().bind*` methods). -It can be configured using the `akka.http.server.bind-timeout` setting. - -### Linger timeout - -The linger timeout is the time period the HTTP server implementation will keep a connection open after -all data has been delivered to the network layer. This setting is similar to the SO_LINGER socket option -but does not only include the OS-level socket but also covers the Akka IO / Akka Streams network stack. -The setting is an extra precaution that prevents clients from keeping open a connection that is -already considered completed from the server side. - -If the network level buffers (including the Akka Stream / Akka IO networking stack buffers) -contains more data than can be transferred to the client in the given time when the server-side considers -to be finished with this connection, the client may encounter a connection reset. - -Set to `infinite` to disable automatic connection closure (which will risk to leak connections). - -## Client timeouts - -### Connecting timeout - -The connecting timeout is the time period within which the TCP connecting process must be completed. -Tweaking it should rarely be required, but it allows erroring out the connection in case a connection -is unable to be established for a given amount of time. - -it can be configured using the `akka.http.client.connecting-timeout` setting. diff --git a/docs/src/main/paradox/java/http/common/timeouts.md b/docs/src/main/paradox/java/http/common/timeouts.md new file mode 120000 index 00000000000..2be505d4f2a --- /dev/null +++ b/docs/src/main/paradox/java/http/common/timeouts.md @@ -0,0 +1 @@ +../../../scala/http/common/timeouts.md \ No newline at end of file diff --git a/docs/src/main/paradox/java/http/implications-of-streaming-http-entity.md b/docs/src/main/paradox/java/http/implications-of-streaming-http-entity.md index 0839955fcb9..e1a1c5f67df 100644 --- a/docs/src/main/paradox/java/http/implications-of-streaming-http-entity.md +++ b/docs/src/main/paradox/java/http/implications-of-streaming-http-entity.md @@ -1,4 +1,3 @@ - # Implications of the streaming nature of Request/Response Entities Akka HTTP is streaming *all the way through*, which means that the back-pressure mechanisms enabled by Akka Streams diff --git a/docs/src/main/paradox/java/http/routing-dsl/directives/alphabetically.md b/docs/src/main/paradox/java/http/routing-dsl/directives/alphabetically.md index afa37c1444b..15c6be8a932 100644 --- a/docs/src/main/paradox/java/http/routing-dsl/directives/alphabetically.md +++ b/docs/src/main/paradox/java/http/routing-dsl/directives/alphabetically.md @@ -146,9 +146,9 @@ |@ref[withMaterializer](basic-directives/withMaterializer.md#withmaterializer-java) | Runs its inner route with the given alternative `Materializer` | |@ref[withPrecompressedMediaTypeSupport](coding-directives/withPrecompressedMediaTypeSupport.md) | Adds a `Content-Encoding: gzip` response header if the entity's media-type is precompressed with gzip header | |@ref[withRangeSupport](range-directives/withRangeSupport.md#withrangesupport-java) | Adds `Accept-Ranges: bytes` to responses to GET requests, produces partial responses if the initial request contained a valid `Range` header | -|@ref[withRequestTimeout](timeout-directives/withRequestTimeout.md#withrequesttimeout-java) | Configures the @ref[request timeouts](../../common/timeouts.md#request-timeout-java) for a given route. | +|@ref[withRequestTimeout](timeout-directives/withRequestTimeout.md#withrequesttimeout-java) | Configures the @ref[request timeouts](../../common/timeouts.md#request-timeout) for a given route. | |@ref[withRequestTimeoutResponse](timeout-directives/withRequestTimeoutResponse.md#withrequesttimeoutresponse-java) | Prepares the `HttpResponse` that is emitted if a request timeout is triggered. `RequestContext => RequestContext` function | |@ref[withSettings](basic-directives/withSettings.md#withsettings-java) | Runs its inner route with the given alternative `RoutingSettings` | |@ref[withSizeLimit](misc-directives/withSizeLimit.md#withsizelimit-java) | Applies request entity size check | -|@ref[withoutRequestTimeout](timeout-directives/withoutRequestTimeout.md#withoutrequesttimeout-java) | Disables @ref[request timeouts](../../common/timeouts.md#request-timeout-java) for a given route. | +|@ref[withoutRequestTimeout](timeout-directives/withoutRequestTimeout.md#withoutrequesttimeout-java) | Disables @ref[request timeouts](../../common/timeouts.md#request-timeout) for a given route. | |@ref[withoutSizeLimit](misc-directives/withoutSizeLimit.md#withoutsizelimit-java) | Skips request entity size check | diff --git a/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withRequestTimeout.md b/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withRequestTimeout.md index 4e06adf547b..7327dbaac34 100644 --- a/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withRequestTimeout.md +++ b/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withRequestTimeout.md @@ -3,7 +3,7 @@ ## Description -This directive enables "late" (during request processing) control over the @ref[Request timeout](../../../common/timeouts.md#request-timeout-java) feature in Akka HTTP. +This directive enables "late" (during request processing) control over the @ref[Request timeout](../../../common/timeouts.md#request-timeout) feature in Akka HTTP. The timeout can be either loosened or made more tight using this directive, however one should be aware that it is inherently racy (which may especially show with very tight timeouts) since a timeout may already have been triggered @@ -29,7 +29,7 @@ or malicious attackers) and if needed tighten it using the directives – not th @@@ -For more information about various timeouts in Akka HTTP see @ref[Akka HTTP Timeouts](../../../common/timeouts.md#http-timeouts-java). +For more information about various timeouts in Akka HTTP see @ref[Akka HTTP Timeouts](../../../common/timeouts.md). ## Example diff --git a/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withRequestTimeoutResponse.md b/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withRequestTimeoutResponse.md index 29a4ba001fe..e37170e317e 100644 --- a/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withRequestTimeoutResponse.md +++ b/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withRequestTimeoutResponse.md @@ -3,7 +3,7 @@ ## Description -Allows customising the `HttpResponse` that will be sent to clients in case of a @ref[Request timeout](../../../common/timeouts.md#request-timeout-java). +Allows customising the `HttpResponse` that will be sent to clients in case of a @ref[Request timeout](../../../common/timeouts.md#request-timeout). See also @ref[withRequestTimeout](withRequestTimeout.md#withrequesttimeout-java) or @ref[withoutRequestTimeout](withoutRequestTimeout.md#withoutrequesttimeout-java) if interested in dynamically changing the timeout for a given route instead. @@ -19,7 +19,7 @@ of request timeouts being measured in seconds it shouldn't be a problem in reali @@@ -To learn more about various timeouts in Akka HTTP and how to configure them see @ref[Akka HTTP Timeouts](../../../common/timeouts.md#http-timeouts-java). +To learn more about various timeouts in Akka HTTP and how to configure them see @ref[Akka HTTP Timeouts](../../../common/timeouts.md). ## Example diff --git a/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withoutRequestTimeout.md b/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withoutRequestTimeout.md index 9cd46b942a9..6782d9d952a 100644 --- a/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withoutRequestTimeout.md +++ b/docs/src/main/paradox/java/http/routing-dsl/directives/timeout-directives/withoutRequestTimeout.md @@ -3,7 +3,7 @@ ## Description -This directive enables "late" (during request processing) control over the @ref[Request timeout](../../../common/timeouts.md#request-timeout-java) feature in Akka HTTP. +This directive enables "late" (during request processing) control over the @ref[Request timeout](../../../common/timeouts.md#request-timeout) feature in Akka HTTP. It is not recommended to turn off request timeouts using this method as it is inherently racy and disabling request timeouts basically turns off the safety net against programming mistakes that it provides. @@ -14,7 +14,7 @@ we're measuring the timeout" is already in the past (the moment we started handl timeout already was triggered before your directive had the chance to change it, an timeout may still be logged. @@@ -For more information about various timeouts in Akka HTTP see @ref[Akka HTTP Timeouts](../../../common/timeouts.md#http-timeouts-java). +For more information about various timeouts in Akka HTTP see @ref[Akka HTTP Timeouts](../../../common/timeouts.md). ## Example diff --git a/docs/src/main/paradox/java/http/server-side-https-support.md b/docs/src/main/paradox/java/http/server-side-https-support.md index e8a79593915..62eb99ed24f 100644 --- a/docs/src/main/paradox/java/http/server-side-https-support.md +++ b/docs/src/main/paradox/java/http/server-side-https-support.md @@ -1,4 +1,3 @@ - # Server-Side HTTPS Support Akka HTTP supports TLS encryption on the server-side as well as on the @ref[client-side](client-side/client-https-support.md). @@ -13,7 +12,7 @@ optional `httpsContext` parameter, which can receive the HTTPS configuration in instance. If defined encryption is enabled on all accepted connections. Otherwise it is disabled (which is the default). -For detailed documentation for client-side HTTPS support refer to @ref[Client-Side HTTPS Support](client-side/client-https-support.md#clientsidehttps). +For detailed documentation for client-side HTTPS support refer to @ref[Client-Side HTTPS Support](client-side/client-https-support.md). ## SSL-Config diff --git a/docs/src/main/paradox/java/http/server-side/websocket-support.md b/docs/src/main/paradox/java/http/server-side/websocket-support.md index b6789fd6999..ce1055818a7 100644 --- a/docs/src/main/paradox/java/http/server-side/websocket-support.md +++ b/docs/src/main/paradox/java/http/server-side/websocket-support.md @@ -94,7 +94,7 @@ and then responds with another text message that contains a greeting: @@snip [WebSocketCoreExample.java](../../../../../test/java/docs/http/javadsl/server/WebSocketCoreExample.java) { #websocket-handler } @@@ note -Inactive WebSocket connections will be dropped according to the @ref[idle-timeout settings](../common/timeouts.md#idle-timeouts-java). +Inactive WebSocket connections will be dropped according to the @ref[idle-timeout settings](../common/timeouts.md#idle-timeouts). In case you need to keep inactive connections alive, you can either tweak your idle-timeout or inject 'keep-alive' messages regularly. @@@ diff --git a/docs/src/main/paradox/scala/http/client-side/client-https-support.md b/docs/src/main/paradox/scala/http/client-side/client-https-support.md index 9a0ce0d5ebf..7e5b4dc9f70 100644 --- a/docs/src/main/paradox/scala/http/client-side/client-https-support.md +++ b/docs/src/main/paradox/scala/http/client-side/client-https-support.md @@ -1,15 +1,19 @@ - # Client-Side HTTPS Support -Akka HTTP supports TLS encryption on the client-side as well as on the @ref[server-side](../server-side-https-support.md#serversidehttps-scala). +Akka HTTP supports TLS encryption on the client-side as well as on the @ref[server-side](../server-side-https-support.md). The central vehicle for configuring encryption is the `HttpsConnectionContext`, which can be created using the static method `ConnectionContext.https` which is defined like this: -@@snip [ConnectionContext.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/scaladsl/ConnectionContext.scala) { #https-context-creation } +Scala +: @@snip[ConnectionContext.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/scaladsl/ConnectionContext.scala) { #https-context-creation } + +Java +: @@snip [ConnectionContext.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/javadsl/ConnectionContext.scala) { #https-context-creation } In addition to the `outgoingConnection`, `newHostConnectionPool` and `cachedHostConnectionPool` methods the -@scaladoc[akka.http.scaladsl.Http](akka.http.scaladsl.Http$) extension also defines `outgoingConnectionHttps`, `newHostConnectionPoolHttps` and +@scala[@scaladoc[akka.http.scaladsl.Http](akka.http.scaladsl.Http$)]@java[@javadoc[akka.http.javadsl.Http](akka.http.javadsl.Http)] +extension also defines `outgoingConnectionHttps`, `newHostConnectionPoolHttps` and `cachedHostConnectionPoolHttps`. These methods work identically to their counterparts without the `-Https` suffix, with the exception that all connections will always be encrypted. @@ -27,7 +31,8 @@ takes precedence over any potentially set default client-side `HttpsContext`). extension the default system configuration is used. Usually the process is, if the default system TLS configuration is not good enough for your application's needs, -that you configure a custom `HttpsContext` instance and set it via `Http().setDefaultClientHttpsContext`. +that you configure a custom `HttpsContext` instance and set it via +@scala[`Http().setDefaultClientHttpsContext`]@java[`Http.get(system).setDefaultClientHttpsContext`]. Afterwards you simply use `outgoingConnectionHttps`, `newHostConnectionPoolHttps`, `cachedHostConnectionPoolHttps`, `superPool` or `singleRequest` without a specific `httpsContext` argument, which causes encrypted connections to rely on the configured default client-side `HttpsContext`. @@ -60,6 +65,7 @@ very useful, for example to easily trust a self-signed certificate that applicat @@@ @@@ warning + While it is possible to disable certain checks using the so called "loose" settings in SSL Config, we **strongly recommend** to instead attempt to solve these issues by properly configuring TLS–for example by adding trusted keys to the keystore. @@ -67,6 +73,7 @@ If however certain checks really need to be disabled because of misconfigured (o application has to speak to, instead of disabling the checks globally (i.e. in `application.conf`) we suggest configuring the loose settings for *specific connections* that are known to need them disabled (and trusted for some other reason). The pattern of doing so is documented in the following sub-sections. + @@@ ### Hostname verification @@ -96,7 +103,8 @@ It is specified as part of [RFC 6066](https://tools.ietf.org/html/rfc6066#page-6 It is highly discouraged to disable any of the security features of TLS, however do acknowledge that workarounds may sometimes be needed. Before disabling any of the features one should consider if they may be solvable *within* the TLS world, -for example by [trusting a certificate](http://typesafehub.github.io/ssl-config/WSQuickStart.html), or [configuring the trusted cipher suites](http://typesafehub.github.io/ssl-config/CipherSuites.html) etc. +for example by [trusting a certificate](https://typesafehub.github.io/ssl-config/WSQuickStart.html), or [configuring the trusted cipher suites](https://typesafehub.github.io/ssl-config/CipherSuites.html). +There's also a very important section in the ssl-config docs titled [LooseSSL - Please read this before turning anything off!](https://typesafehub.github.io/ssl-config/LooseSSL.html#please-read-this-before-turning-anything-off). If disabling features is indeed desired, we recommend doing so for *specific connections*, instead of globally configuring it via `application.conf`. @@ -105,7 +113,11 @@ instead of globally configuring it via `application.conf`. The following shows an example of disabling SNI for a given connection: -@@snip [HttpsExamplesSpec.scala](../../../../../test/scala/docs/http/scaladsl/HttpsExamplesSpec.scala) { #disable-sni-connection } +Scala +: @@snip [HttpsExamplesSpec.scala](../../../../../test/scala/docs/http/scaladsl/HttpsExamplesSpec.scala) { #disable-sni-connection } + +Java +: @@snip [HttpsExamplesDocTest.java](../../../../../test/java/docs/http/javadsl/HttpsExamplesDocTest.java) { #disable-sni-connection } The `badSslConfig` is a copy of the default `AkkaSSLConfig` with with the slightly changed configuration to disable SNI. This value can be cached and used for connections which should indeed not use this feature. diff --git a/docs/src/main/paradox/scala/http/client-side/client-transport.md b/docs/src/main/paradox/scala/http/client-side/client-transport.md index 22574d8e9fc..0c672ba0c0a 100644 --- a/docs/src/main/paradox/scala/http/client-side/client-transport.md +++ b/docs/src/main/paradox/scala/http/client-side/client-transport.md @@ -1,9 +1,14 @@ # Pluggable Client Transports / HTTPS Proxy Support The client side infrastructure has (unstable) support to plug different transport mechanisms underneath. A client side -transport is represented by an instance of @scaladoc[akka.http.scaladsl.ClientTransport](akka.http.scaladsl.ClientTransport): +transport is represented by an instance of +@scala[@scaladoc[akka.http.scaladsl.ClientTransport](akka.http.scaladsl.ClientTransport)]@java[@javadoc[akka.http.javadsl.ClientTransport](akka.http.javadsl.ClientTransport)]: -@@snip [ClientTransport.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/scaladsl/ClientTransport.scala) { #client-transport-definition } +Scala +: @@snip [ClientTransport.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/scaladsl/ClientTransport.scala) { #client-transport-definition } + +Java +: @@snip [ClientTransport.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/javadsl/ClientTransport.scala) { #client-transport-definition } A transport implementation defines how the client infrastructure should communicate with a given host. @@ -25,7 +30,9 @@ of strategy by implementing `ClientTransport` yourself). The `ConnectionPoolSettings` class allows setting a custom transport for any of the pool methods. Use `ConnectionPoolSettings.withTransport` to configure a transport and pass those settings to one of the -pool methods like `Http().singleRequest`, `Http().superPool`, or `Http().cachedHostConnectionPool`. +pool methods like +@scala[`Http().singleRequest`, `Http().superPool`, or `Http().cachedHostConnectionPool`] +@java[`Http.get(...).singleRequest`, `Http.get(...).superPool`, or `Http.get(...).cachedHostConnectionPool`]. ### Single Connection Usage @@ -61,6 +68,10 @@ Here are some ideas for custom (or future predefined) transports: ## Usage Examples -### Use HTTPS Proxy with `Http().singleRequest` +### Use HTTPS Proxy with @scala[`Http().singleRequest`]@java[`Http.get(...).singleRequest`] + +Scala +: @@snip [HttpClientExampleSpec.scala](../../../../../test/scala/docs/http/scaladsl/HttpClientExampleSpec.scala) { #https-proxy-example-single-request } -@@snip [HttpClientExampleSpec.scala](../../../../../test/scala/docs/http/scaladsl/HttpClientExampleSpec.scala) { #https-proxy-example-single-request } +Java +: @@snip [HttpClientExampleDocTest.java](../../../../../test/java/docs/http/javadsl/HttpClientExampleDocTest.java) { #https-proxy-example-single-request } diff --git a/docs/src/main/paradox/scala/http/client-side/connection-level.md b/docs/src/main/paradox/scala/http/client-side/connection-level.md index 1a7bd3a1125..3c84af752e1 100644 --- a/docs/src/main/paradox/scala/http/client-side/connection-level.md +++ b/docs/src/main/paradox/scala/http/client-side/connection-level.md @@ -1,4 +1,3 @@ - # Connection-Level Client-Side API The connection-level API is the lowest-level client-side API Akka HTTP provides. It gives you full control over when @@ -6,7 +5,7 @@ HTTP connections are opened and closed and how requests are to be send across wh highest flexibility at the cost of providing the least convenience. @@@ note -It is recommended to first read the @ref[Implications of the streaming nature of Request/Response Entities](../implications-of-streaming-http-entity.md#implications-of-streaming-http-entities) section, +It is recommended to first read the @ref[Implications of the streaming nature of Request/Response Entities](../implications-of-streaming-http-entity.md) section, as it explains the underlying full-stack streaming concepts, which may be unexpected when coming from a background with non-"streaming first" HTTP Clients. @@@ @@ -14,12 +13,17 @@ from a background with non-"streaming first" HTTP Clients. ## Opening HTTP Connections With the connection-level API you open a new HTTP connection to a target endpoint by materializing a `Flow` -returned by the `Http().outgoingConnection(...)` method. Here is an example: +returned by the @scala[`Http().outgoingConnection(...)`]@java[`Http.get(system).outgoingConnection(...)`] method. +Here is an example: -@@snip [HttpClientExampleSpec.scala](../../../../../test/scala/docs/http/scaladsl/HttpClientExampleSpec.scala) { #outgoing-connection-example } +Scala +: @@snip [HttpClientExampleSpec.scala](../../../../../test/scala/docs/http/scaladsl/HttpClientExampleSpec.scala) { #outgoing-connection-example } -Apart from the host name and port the `Http().outgoingConnection(...)` method also allows you to specify socket options -and a number of configuration settings for the connection. +Java +: @@snip [HttpClientExampleDocTest.java](../../../../../test/java/docs/http/javadsl/HttpClientExampleDocTest.java) { #outgoing-connection-example } + +Apart from the host name and port the @scala[`Http().outgoingConnection(...)`]@java[`Http.get(system).outgoingConnection(...)`] +method also allows you to specify socket options and a number of configuration settings for the connection. Note that no connection is attempted until the returned flow is actually materialized! If the flow is materialized several times then several independent connections will be opened (one per materialization). @@ -50,9 +54,9 @@ The connection can also be closed by the server. An application can actively trigger the closing of the connection by completing the request stream. In this case the underlying TCP connection will be closed when the last pending response has been received. -The connection will also be closed if the response entity is cancelled (e.g. by attaching it to `Sink.cancelled`) +The connection will also be closed if the response entity is cancelled (e.g. by attaching it to `Sink.cancelled()`) or consumed only partially (e.g. by using `take` combinator). In order to prevent this behaviour the entity should be -explicitly drained by attaching it to `Sink.ignore`. +explicitly drained by attaching it to `Sink.ignore()`. ## Timeouts @@ -61,9 +65,9 @@ as a more general purpose streaming infrastructure feature. It should be noted that Akka Streams provide various timeout functionality so any API that uses streams can benefit from the stream stages such as `idleTimeout`, `backpressureTimeout`, `completionTimeout`, `initialTimeout` -and `throttle`. To learn more about these refer to their documentation in Akka Streams (and Scala Doc). +and `throttle`. To learn more about these refer to their documentation in Akka Streams. -For more details about timeout support in Akka HTTP in general refer to @ref[Akka HTTP Timeouts](../common/timeouts.md#http-timeouts-scala). +For more details about timeout support in Akka HTTP in general refer to @ref[Akka HTTP Timeouts](../common/timeouts.md). ## Stand-Alone HTTP Layer Usage @@ -74,9 +78,18 @@ to "run" the HTTP layer (and, potentially, higher-layers) against data that do n some other source. Potential scenarios where this might be useful include tests, debugging or low-level event-sourcing (e.g by replaying network traffic). -On the client-side the stand-alone HTTP layer forms a `BidiStage` that is defined like this: +On the client-side the stand-alone HTTP layer forms a `BidiStage` stage that "upgrades" a potentially encrypted raw connection to the HTTP level. +It is defined like this: +@@@ div { .group-scala } @@snip [Http.scala](../../../../../../../akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala) { #client-layer } +@@@ +@@@ div { .group-java } +```java +BidiFlow +``` +@@@ -You create an instance of `Http.ClientLayer` by calling one of the two overloads of the `Http().clientLayer` method, +You create an instance of @scala[`Http.ClientLayer`]@java[the layer] by calling one of the two overloads +of the @scala[`Http().clientLayer`]@java[`Http.get(system).clientLayer`] method, which also allows for varying degrees of configuration. diff --git a/docs/src/main/paradox/scala/http/client-side/host-level.md b/docs/src/main/paradox/scala/http/client-side/host-level.md index 120b1c820ff..b3617ead8cd 100644 --- a/docs/src/main/paradox/scala/http/client-side/host-level.md +++ b/docs/src/main/paradox/scala/http/client-side/host-level.md @@ -6,7 +6,7 @@ connections. It autonomously manages a configurable pool of connections to *one host/port combination). @@@ note -It is recommended to first read the @ref[Implications of the streaming nature of Request/Response Entities](../implications-of-streaming-http-entity.md#implications-of-streaming-http-entities) section, +It is recommended to first read the @ref[Implications of the streaming nature of Request/Response Entities](../implications-of-streaming-http-entity.md) section, as it explains the underlying full-stack streaming concepts, which may be unexpected when coming from a background with non-"streaming first" HTTP Clients. @@@ diff --git a/docs/src/main/paradox/scala/http/client-side/index.md b/docs/src/main/paradox/scala/http/client-side/index.md index 989fdf6799a..948591e0224 100644 --- a/docs/src/main/paradox/scala/http/client-side/index.md +++ b/docs/src/main/paradox/scala/http/client-side/index.md @@ -4,7 +4,7 @@ All client-side functionality of Akka HTTP, for consuming HTTP-based services offered by other endpoints, is currently provided by the `akka-http-core` module. -It is recommended to first read the @ref[Implications of the streaming nature of Request/Response Entities](../implications-of-streaming-http-entity.md#implications-of-streaming-http-entities) section, +It is recommended to first read the @ref[Implications of the streaming nature of Request/Response Entities](../implications-of-streaming-http-entity.md) section, as it explains the underlying full-stack streaming concepts, which may be unexpected when coming from a background with non-"streaming first" HTTP Clients. diff --git a/docs/src/main/paradox/scala/http/client-side/request-level.md b/docs/src/main/paradox/scala/http/client-side/request-level.md index 21da9ff0a46..1b96dcdb22e 100644 --- a/docs/src/main/paradox/scala/http/client-side/request-level.md +++ b/docs/src/main/paradox/scala/http/client-side/request-level.md @@ -6,7 +6,7 @@ The request-level API is the recommended and most convenient way of using Akka H Depending on your preference you can pick the flow-based or the future-based variant. @@@ note -It is recommended to first read the @ref[Implications of the streaming nature of Request/Response Entities](../implications-of-streaming-http-entity.md#implications-of-streaming-http-entities) section, +It is recommended to first read the @ref[Implications of the streaming nature of Request/Response Entities](../implications-of-streaming-http-entity.md) section, as it explains the underlying full-stack streaming concepts, which may be unexpected when coming from a background with non-"streaming first" HTTP Clients. @@@ diff --git a/docs/src/main/paradox/scala/http/common/timeouts.md b/docs/src/main/paradox/scala/http/common/timeouts.md index d4bf25a9842..8af4921eefc 100644 --- a/docs/src/main/paradox/scala/http/common/timeouts.md +++ b/docs/src/main/paradox/scala/http/common/timeouts.md @@ -1,4 +1,3 @@ - # Akka HTTP Timeouts Akka HTTP comes with a variety of built-in timeout mechanisms to protect your servers from malicious attacks or @@ -7,7 +6,7 @@ are left to the streaming APIs and are easily implementable as patterns in user- ## Common timeouts - + ### Idle timeouts The `idle-timeout` is a global setting which sets the maximum inactivity time of a given connection. @@ -30,7 +29,7 @@ For the client side connection pool, the idle period is counted only when the po ## Server timeouts - + ### Request timeout Request timeouts are a mechanism that limits the maximum time it may take to produce an `HttpResponse` from a route. diff --git a/docs/src/main/paradox/scala/http/implications-of-streaming-http-entity.md b/docs/src/main/paradox/scala/http/implications-of-streaming-http-entity.md index 1db762af67e..829483f307b 100644 --- a/docs/src/main/paradox/scala/http/implications-of-streaming-http-entity.md +++ b/docs/src/main/paradox/scala/http/implications-of-streaming-http-entity.md @@ -1,4 +1,3 @@ - # Implications of the streaming nature of Request/Response Entities Akka HTTP is streaming *all the way through*, which means that the back-pressure mechanisms enabled by Akka Streams diff --git a/docs/src/main/paradox/scala/http/low-level-server-side-api.md b/docs/src/main/paradox/scala/http/low-level-server-side-api.md index 971de79674e..e5137fbc6c4 100644 --- a/docs/src/main/paradox/scala/http/low-level-server-side-api.md +++ b/docs/src/main/paradox/scala/http/low-level-server-side-api.md @@ -34,7 +34,7 @@ Depending on your needs you can either use the low-level API directly or rely on easier. @@@ note -It is recommended to read the @ref[Implications of the streaming nature of Request/Response Entities](implications-of-streaming-http-entity.md#implications-of-streaming-http-entities) section, +It is recommended to read the @ref[Implications of the streaming nature of Request/Response Entities](implications-of-streaming-http-entity.md) section, as it explains the underlying full-stack streaming concepts, which may be unexpected when coming from a background with non-"streaming first" HTTP Servers. @@@ @@ -125,7 +125,7 @@ explicitly drained by attaching it to `Sink.ignore`. ## Configuring Server-side HTTPS -For detailed documentation about configuring and using HTTPS on the server-side refer to @ref[Server-Side HTTPS Support](server-side-https-support.md#serversidehttps-scala). +For detailed documentation about configuring and using HTTPS on the server-side refer to @ref[Server-Side HTTPS Support](server-side-https-support.md). ## Stand-Alone HTTP Layer Usage diff --git a/docs/src/main/paradox/scala/http/routing-dsl/directives/alphabetically.md b/docs/src/main/paradox/scala/http/routing-dsl/directives/alphabetically.md index 667f13bd7d2..040697c426d 100644 --- a/docs/src/main/paradox/scala/http/routing-dsl/directives/alphabetically.md +++ b/docs/src/main/paradox/scala/http/routing-dsl/directives/alphabetically.md @@ -147,14 +147,14 @@ |@ref[tprovide](basic-directives/tprovide.md#tprovide) | Injects a given tuple of values into a directive | |@ref[uploadedFile](file-upload-directives/uploadedFile.md#uploadedfile) | Streams one uploaded file from a multipart request to a file on disk | |@ref[validate](misc-directives/validate.md#validate) | Checks a given condition before running its inner route | -|@ref[withoutRequestTimeout](timeout-directives/withoutRequestTimeout.md#withoutrequesttimeout) | Disables @ref[request timeouts](../../common/timeouts.md#request-timeout-scala) for a given route. | +|@ref[withoutRequestTimeout](timeout-directives/withoutRequestTimeout.md#withoutrequesttimeout) | Disables @ref[request timeouts](../../common/timeouts.md#request-timeout) for a given route. | |@ref[withoutSizeLimit](misc-directives/withoutSizeLimit.md#withoutsizelimit) | Skips request entity size check | |@ref[withExecutionContext](basic-directives/withExecutionContext.md#withexecutioncontext) | Runs its inner route with the given alternative `ExecutionContext` | |@ref[withMaterializer](basic-directives/withMaterializer.md#withmaterializer) | Runs its inner route with the given alternative `Materializer` | |@ref[withLog](basic-directives/withLog.md#withlog) | Runs its inner route with the given alternative `LoggingAdapter` | |@ref[withPrecompressedMediaTypeSupport](coding-directives/withPrecompressedMediaTypeSupport.md) | Adds a `Content-Encoding: gzip` response header if the entity's media-type is precompressed with gzip header | |@ref[withRangeSupport](range-directives/withRangeSupport.md#withrangesupport) | Adds `Accept-Ranges: bytes` to responses to GET requests, produces partial responses if the initial request contained a valid `Range` header | -|@ref[withRequestTimeout](timeout-directives/withRequestTimeout.md#withrequesttimeout) | Configures the @ref[request timeouts](../../common/timeouts.md#request-timeout-scala) for a given route. | +|@ref[withRequestTimeout](timeout-directives/withRequestTimeout.md#withrequesttimeout) | Configures the @ref[request timeouts](../../common/timeouts.md#request-timeout) for a given route. | |@ref[withRequestTimeoutResponse](timeout-directives/withRequestTimeoutResponse.md#withrequesttimeoutresponse) | Prepares the `HttpResponse` that is emitted if a request timeout is triggered. `RequestContext => RequestContext` function | |@ref[withSettings](basic-directives/withSettings.md#withsettings) | Runs its inner route with the given alternative `RoutingSettings` | |@ref[withSizeLimit](misc-directives/withSizeLimit.md#withsizelimit) | Applies request entity size check | diff --git a/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeout.md b/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeout.md index abb57780060..a993e8e383c 100644 --- a/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeout.md +++ b/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeout.md @@ -7,7 +7,7 @@ ## Description -This directive enables "late" (during request processing) control over the @ref[Request timeout](../../../common/timeouts.md#request-timeout-scala) feature in Akka HTTP. +This directive enables "late" (during request processing) control over the @ref[Request timeout](../../../common/timeouts.md#request-timeout) feature in Akka HTTP. The timeout can be either loosened or made more tight using this directive, however one should be aware that it is inherently racy (which may especially show with very tight timeouts) since a timeout may already have been triggered @@ -33,7 +33,7 @@ or malicious attackers) and if needed tighten it using the directives – not th @@@ -For more information about various timeouts in Akka HTTP see @ref[Akka HTTP Timeouts](../../../common/timeouts.md#http-timeouts-scala). +For more information about various timeouts in Akka HTTP see @ref[Akka HTTP Timeouts](../../../common/timeouts.md). ## Example diff --git a/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeoutResponse.md b/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeoutResponse.md index a2dbfacf70f..16f142af677 100644 --- a/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeoutResponse.md +++ b/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withRequestTimeoutResponse.md @@ -7,7 +7,7 @@ ## Description -Allows customising the `HttpResponse` that will be sent to clients in case of a @ref[Request timeout](../../../common/timeouts.md#request-timeout-scala). +Allows customising the `HttpResponse` that will be sent to clients in case of a @ref[Request timeout](../../../common/timeouts.md#request-timeout). See also @ref[withRequestTimeout](withRequestTimeout.md#withrequesttimeout) or @ref[withoutRequestTimeout](withoutRequestTimeout.md#withoutrequesttimeout) if interested in dynamically changing the timeout for a given route instead. @@ -23,7 +23,7 @@ of request timeouts being measured in seconds it shouldn't be a problem in reali @@@ -To learn more about various timeouts in Akka HTTP and how to configure them see @ref[Akka HTTP Timeouts](../../../common/timeouts.md#http-timeouts-scala). +To learn more about various timeouts in Akka HTTP and how to configure them see @ref[Akka HTTP Timeouts](../../../common/timeouts.md). ## Example diff --git a/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withoutRequestTimeout.md b/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withoutRequestTimeout.md index d5a7dd41ef7..8bb36f241d3 100644 --- a/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withoutRequestTimeout.md +++ b/docs/src/main/paradox/scala/http/routing-dsl/directives/timeout-directives/withoutRequestTimeout.md @@ -7,7 +7,7 @@ ## Description -This directive enables "late" (during request processing) control over the @ref[Request timeout](../../../common/timeouts.md#request-timeout-scala) feature in Akka HTTP. +This directive enables "late" (during request processing) control over the @ref[Request timeout](../../../common/timeouts.md#request-timeout) feature in Akka HTTP. It is not recommended to turn off request timeouts using this method as it is inherently racy and disabling request timeouts basically turns off the safety net against programming mistakes that it provides. @@ -18,7 +18,7 @@ we're measuring the timeout" is already in the past (the moment we started handl timeout already was triggered before your directive had the chance to change it, an timeout may still be logged. @@@ -For more information about various timeouts in Akka HTTP see @ref[Akka HTTP Timeouts](../../../common/timeouts.md#http-timeouts-scala). +For more information about various timeouts in Akka HTTP see @ref[Akka HTTP Timeouts](../../../common/timeouts.md). ## Example diff --git a/docs/src/main/paradox/scala/http/routing-dsl/index.md b/docs/src/main/paradox/scala/http/routing-dsl/index.md index 20f260fe4d6..98075a464c4 100644 --- a/docs/src/main/paradox/scala/http/routing-dsl/index.md +++ b/docs/src/main/paradox/scala/http/routing-dsl/index.md @@ -7,7 +7,7 @@ functionality of typical web servers or frameworks, like deconstruction of URIs, static content serving. @@@ note -It is recommended to read the @ref[Implications of the streaming nature of Request/Response Entities](../implications-of-streaming-http-entity.md#implications-of-streaming-http-entities) section, +It is recommended to read the @ref[Implications of the streaming nature of Request/Response Entities](../implications-of-streaming-http-entity.md) section, as it explains the underlying full-stack streaming concepts, which may be unexpected when coming from a background with non-"streaming first" HTTP Servers. @@@ @@ -108,4 +108,4 @@ and split each line before we send it to an actor for further processing: ## Configuring Server-side HTTPS -For detailed documentation about configuring and using HTTPS on the server-side refer to @ref[Server-Side HTTPS Support](../server-side-https-support.md#serversidehttps-scala). +For detailed documentation about configuring and using HTTPS on the server-side refer to @ref[Server-Side HTTPS Support](../server-side-https-support.md). diff --git a/docs/src/main/paradox/scala/http/server-side-https-support.md b/docs/src/main/paradox/scala/http/server-side-https-support.md index 116d031a274..7258d03ea29 100644 --- a/docs/src/main/paradox/scala/http/server-side-https-support.md +++ b/docs/src/main/paradox/scala/http/server-side-https-support.md @@ -1,7 +1,7 @@ # Server-Side HTTPS Support -Akka HTTP supports TLS encryption on the server-side as well as on the @ref[client-side](client-side/client-https-support.md#clientsidehttps). +Akka HTTP supports TLS encryption on the server-side as well as on the @ref[client-side](client-side/client-https-support.md). The central vehicle for configuring encryption is the `HttpsConnectionContext`, which can be created using the static method `ConnectionContext.https` which is defined like this: @@ -13,7 +13,7 @@ optional `httpsContext` parameter, which can receive the HTTPS configuration in instance. If defined encryption is enabled on all accepted connections. Otherwise it is disabled (which is the default). -For detailed documentation for client-side HTTPS support refer to @ref[Client-Side HTTPS Support](client-side/client-https-support.md#clientsidehttps). +For detailed documentation for client-side HTTPS support refer to @ref[Client-Side HTTPS Support](client-side/client-https-support.md). ## SSL-Config @@ -97,4 +97,4 @@ Other excellent articles on the subject: * [Oracle Java SE 8: Creating a Keystore using JSSE](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html#CreateKeystore) * [Java PKI Programmer's Guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/certpath/CertPathProgGuide.html) - * [Fixing X.509 Certificates](https://tersesystems.com/2014/03/20/fixing-x509-certificates/) \ No newline at end of file + * [Fixing X.509 Certificates](https://tersesystems.com/2014/03/20/fixing-x509-certificates/)