reference.conf

########################################
# akka-http-core Reference Config File #
########################################

# This is the reference config file that contains all the default settings.
# Make your edits/overrides in your application.conf.

# Akka HTTP version, checked against the runtime version of Akka HTTP.
# Loaded from generated conf file.
include "akka-http-version"

akka.http {

  server {
    # The default value of the `Server` header to produce if no
    # explicit `Server`-header was included in a response.
    # If this value is the empty string and no header was included in
    # the request, no `Server` header will be rendered at all.
    server-header = akka-http/${akka.http.version}

    # "PREVIEW" features that are not yet fully production ready.
    # These flags can can change or be removed between patch releases.
    preview {
      # ONLY WORKS WITH `bindAndHandleAsync` (currently)
      #
      # If this setting is enabled AND the akka-http2-support is found
      # on the classpath the usual Http().bind... method calls will bind
      # using HTTP/2. Please note that you must configure HTTPS while doing so.
      enable-http2 = off
    }

    # The time after which an idle connection will be automatically closed.
    # Set to `infinite` to completely disable idle connection timeouts.
    idle-timeout = 60 s

    # Defines the default time period within which the application has to
    # produce an HttpResponse for any given HttpRequest it received.
    # The timeout begins to run when the *end* of the request has been
    # received, so even potentially long uploads can have a short timeout.
    # Set to `infinite` to completely disable request timeout checking.
    #
    # Make sure this timeout is smaller than the idle-timeout, otherwise,
    # the idle-timeout will kick in first and reset the TCP connection
    # without a response.
    #
    # If this setting is not `infinite` the HTTP server layer attaches a
    # `Timeout-Access` header to the request, which enables programmatic
    # customization of the timeout period and timeout response for each
    # request individually.
    request-timeout = 20 s

    # The time period within which the TCP binding process must be completed.
    bind-timeout = 1s

    # Default port to bind HTTP server to when no port was explicitly given.
    default-http-port = 80

    # Default port to bind HTTPS server to when no port was explicitly given.
    default-https-port = 443

    # 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).
    linger-timeout = 1 min

    # The maximum number of concurrently accepted connections when using the
    # `Http().bindAndHandle` methods.
    #
    # This setting doesn't apply to the `Http().bind` method which will still
    # deliver an unlimited backpressured stream of incoming connections.
    #
    # Note, that this setting limits the number of the connections on a best-effort basis.
    # It does *not* strictly guarantee that the number of established TCP connections will never
    # exceed the limit (but it will be approximately correct) because connection termination happens
    # asynchronously. It also does *not* guarantee that the number of concurrently active handler
    # flow materializations will never exceed the limit for the reason that it is impossible to reliably
    # detect when a materialization has ended.
    max-connections = 1024

    # The maximum number of requests that are accepted (and dispatched to
    # the application) on one single connection before the first request
    # has to be completed.
    # Incoming requests that would cause the pipelining limit to be exceeded
    # are not read from the connections socket so as to build up "back-pressure"
    # to the client via TCP flow control.
    # A setting of 1 disables HTTP pipelining, since only one request per
    # connection can be "open" (i.e. being processed by the application) at any
    # time. Set to higher values to enable HTTP pipelining.
    # This value must be > 0 and <= 1024.
    pipelining-limit = 16

    # Enables/disables the addition of a `Remote-Address` header
    # holding the clients (remote) IP address.
    remote-address-header = off

    # Enables/disables the addition of a `Raw-Request-URI` header holding the
    # original raw request URI as the client has sent it.
    raw-request-uri-header = off

    # Enables/disables automatic handling of HEAD requests.
    # If this setting is enabled the server dispatches HEAD requests as GET
    # requests to the application and automatically strips off all message
    # bodies from outgoing responses.
    # Note that, even when this setting is off the server will never send
    # out message bodies on responses to HEAD requests.
    transparent-head-requests = on

    # Enables/disables the returning of more detailed error messages to
    # the client in the error response.
    # Should be disabled for browser-facing APIs due to the risk of XSS attacks
    # and (probably) enabled for internal or non-browser APIs.
    # Note that akka-http will always produce log messages containing the full
    # error details.
    verbose-error-messages = off

    # The initial size of the buffer to render the response headers in.
    # Can be used for fine-tuning response rendering performance but probably
    # doesn't have to be fiddled with in most applications.
    response-header-size-hint = 512

    # The requested maximum length of the queue of incoming connections.
    # If the server is busy and the backlog is full the OS will start dropping
    # SYN-packets and connection attempts may fail. Note, that the backlog
    # size is usually only a maximum size hint for the OS and the OS can
    # restrict the number further based on global limits.
    backlog = 100

    # If this setting is empty the server only accepts requests that carry a
    # non-empty `Host` header. Otherwise it responds with `400 Bad Request`.
    # Set to a non-empty value to be used in lieu of a missing or empty `Host`
    # header to make the server accept such requests.
    # Note that the server will never accept HTTP/1.1 request without a `Host`
    # header, i.e. this setting only affects HTTP/1.1 requests with an empty
    # `Host` header as well as HTTP/1.0 requests.
    # Examples: `www.spray.io` or `example.com:8080`
    default-host-header = ""

    # Socket options to set for the listening socket. If a setting is left
    # undefined, it will use whatever the default on the system is.
    socket-options {
      so-receive-buffer-size = undefined
      so-send-buffer-size = undefined
      so-reuse-address = undefined
      so-traffic-class = undefined
      tcp-keep-alive = undefined
      tcp-oob-inline = undefined
      tcp-no-delay = undefined
    }

    # Modify to tweak parsing settings on the server-side only.
    parsing {
      # no overrides by default, see `akka.http.parsing` for default values
    }

    # Enables/disables the logging of unencrypted HTTP traffic to and from the HTTP
    # server for debugging reasons.
    #
    # Note: Use with care. Logging of unencrypted data traffic may expose secret data.
    #
    # Incoming and outgoing traffic will be logged in hexdump format. To enable logging,
    # specify the number of bytes to log per chunk of data (the actual chunking depends
    # on implementation details and networking conditions and should be treated as
    # arbitrary).
    #
    # For logging on the client side, see akka.http.client.log-unencrypted-network-bytes.
    #
    # `off` : no log messages are produced
    # Int   : determines how many bytes should be logged per data chunk
    log-unencrypted-network-bytes = off

    http2 {
      # The maximum number of bytes to receive from a request entity in a single chunk.
      #
      # The reasoning to limit that amount (instead of delivering all buffered data for a stream) is that
      # the amount of data in the internal buffers will drive backpressure and flow control on the HTTP/2 level. Bigger
      # chunks would mean that the user-level entity reader will have to buffer all that data if it cannot read it in one
      # go. The implementation would not be able to backpressure further data in that case because it does not know about
      # this user-level buffer.
      request-entity-chunk-size = 65536 b

      # The number of request data bytes the HTTP/2 implementation is allowed to buffer internally per connection. Free
      # space in this buffer is communicated to the peer using HTTP/2 flow-control messages to backpressure data if it
      # isn't read fast enough.
      #
      # When there is no backpressure, this amount will limit the amount of in-flight data. It might need to be increased
      # for high bandwidth-delay-product connections.
      #
      # There is a relation between the `incoming-connection-level-buffer-size` and the `incoming-stream-level-buffer-size`:
      # If incoming-connection-level-buffer-size < incoming-stream-level-buffer-size * number_of_streams, then
      # head-of-line blocking is possible between different streams on the same connection.
      incoming-connection-level-buffer-size = 10 MB

      # The number of request data bytes the HTTP/2 implementation is allowed to buffer internally per stream. Free space
      # in this buffer is communicated to the peer using HTTP/2 flow-control messages to backpressure data if it isn't
      # read fast enough.
      #
      # When there is no backpressure, this amount will limit the amount of in-flight data per stream. It might need to
      # be increased for high bandwidth-delay-product connections.
      incoming-stream-level-buffer-size = 512kB
    }

    websocket {
      # periodic keep alive may be implemented using by sending Ping frames
      # upon which the other side is expected to reply with a Pong frame,
      # or by sending a Pong frame, which serves as unidirectional heartbeat.
      # Valid values:
      #   ping - default, for bi-directional ping/pong keep-alive heartbeating
      #   pong - for uni-directional pong keep-alive heartbeating
      #
      # It is also possible to provide a payload for each heartbeat message,
      # this setting can be configured programatically by modifying the websocket settings.
      # See: https://doc.akka.io/docs/akka-http/current/server-side/websocket-support.html
      periodic-keep-alive-mode = ping

      # Interval for sending periodic keep-alives
      # The frame sent will be the one configured in akka.http.server.websocket.periodic-keep-alive-mode
      # `infinite` by default, or a duration that is the max idle interval after which an keep-alive frame should be sent
      # The value `infinite` means that *no* keep-alive heartbeat will be sent, as: "the allowed idle time is infinite"
      periodic-keep-alive-max-idle = infinite
    }
  }

  client {
    # The default value of the `User-Agent` header to produce if no
    # explicit `User-Agent`-header was included in a request.
    # If this value is the empty string and no header was included in
    # the request, no `User-Agent` header will be rendered at all.
    user-agent-header = akka-http/${akka.http.version}

    # The time period within which the TCP connecting process must be completed.
    connecting-timeout = 10s

    # The time after which an idle connection will be automatically closed.
    # Set to `infinite` to completely disable idle timeouts.
    idle-timeout = 60 s

    # The initial size of the buffer to render the request headers in.
    # Can be used for fine-tuning request rendering performance but probably
    # doesn't have to be fiddled with in most applications.
    request-header-size-hint = 512

    # Socket options to set for the listening socket. If a setting is left
    # undefined, it will use whatever the default on the system is.
    socket-options {
      so-receive-buffer-size = undefined
      so-send-buffer-size = undefined
      so-reuse-address = undefined
      so-traffic-class = undefined
      tcp-keep-alive = undefined
      tcp-oob-inline = undefined
      tcp-no-delay = undefined
    }

    # Modify to tweak parsing settings on the client-side only.
    parsing {
      # no overrides by default, see `akka.http.parsing` for default values
    }

    # Enables/disables the logging of unencrypted HTTP traffic to and from the HTTP
    # client for debugging reasons.
    #
    # Note: Use with care. Logging of unencrypted data traffic may expose secret data.
    #
    # Incoming and outgoing traffic will be logged in hexdump format. To enable logging,
    # specify the number of bytes to log per chunk of data (the actual chunking depends
    # on implementation details and networking conditions and should be treated as
    # arbitrary).
    #
    # For logging on the server side, see akka.http.server.log-unencrypted-network-bytes.
    #
    # `off` : no log messages are produced
    # Int   : determines how many bytes should be logged per data chunk
    log-unencrypted-network-bytes = off

    websocket {
      # periodic keep alive may be implemented using by sending Ping frames
      # upon which the other side is expected to reply with a Pong frame,
      # or by sending a Pong frame, which serves as unidirectional heartbeat.
      # Valid values:
      #   ping - default, for bi-directional ping/pong keep-alive heartbeating
      #   pong - for uni-directional pong keep-alive heartbeating
      #
      # See https://tools.ietf.org/html/rfc6455#section-5.5.2
      # and https://tools.ietf.org/html/rfc6455#section-5.5.3 for more information
      periodic-keep-alive-mode = ping

      # Interval for sending periodic keep-alives
      # The frame sent will be the onne configured in akka.http.server.websocket.periodic-keep-alive-mode
      # `infinite` by default, or a duration that is the max idle interval after which an keep-alive frame should be sent
      periodic-keep-alive-max-idle = infinite
    }
  }

  host-connection-pool {
    # The maximum number of parallel connections that a connection pool to a
    # single host endpoint is allowed to establish. Must be greater than zero.
    max-connections = 4

    # The minimum number of parallel connections that a pool should keep alive ("hot").
    # If the number of connections is falling below the given threshold, new ones are being spawned.
    # You can use this setting to build a hot pool of "always on" connections.
    # Default is 0, meaning there might be no active connection at given moment.
    # Keep in mind that `min-connections` should be smaller than `max-connections` or equal
    min-connections = 0

    # The maximum number of times failed requests are attempted again,
    # (if the request can be safely retried) before giving up and returning an error.
    # Set to zero to completely disable request retries.
    max-retries = 5

    # The maximum number of open requests accepted into the pool across all
    # materializations of any of its client flows.
    # Protects against (accidentally) overloading a single pool with too many client flow materializations.
    # Note that with N concurrent materializations the max number of open request in the pool
    # will never exceed N * max-connections * pipelining-limit.
    # Must be a power of 2 and > 0!
    max-open-requests = 32

    # The maximum number of requests that are dispatched to the target host in
    # batch-mode across a single connection (HTTP pipelining).
    # A setting of 1 disables HTTP pipelining, since only one request per
    # connection can be "in flight" at any time.
    # Set to higher values to enable HTTP pipelining.
    # This value must be > 0.
    # (Note that, independently of this setting, pipelining will never be done
    # on a connection that still has a non-idempotent request in flight.
    #
    # Before increasing this value, make sure you understand the effects of head-of-line blocking.
    # Using a connection pool, a request may be issued on a connection where a previous
    # long-running request hasn't finished yet. The response to the pipelined requests may then be stuck
    # behind the response of the long-running previous requests on the server. This may introduce an
    # unwanted "coupling" of run time between otherwise unrelated requests.
    #
    # See http://tools.ietf.org/html/rfc7230#section-6.3.2 for more info.)
    pipelining-limit = 1

    # The time after which an idle connection pool (without pending requests)
    # will automatically terminate itself. Set to `infinite` to completely disable idle timeouts.
    idle-timeout = 30 s

    # The pool implementation to use. Currently supported are:
    #  - legacy: the original 10.0.x pool implementation
    #  - new: the pool implementation that became the default in 10.1.x and will receive fixes and new features
    pool-implementation = new

    # The "new" pool implementation will fail a connection early and clear the slot if a response entity was not
    # subscribed during the given time period after the response was dispatched. In busy systems the timeout might be
    # too tight if a response is not picked up quick enough after it was dispatched by the pool.
    response-entity-subscription-timeout = 1.second

    # Modify this section to tweak client settings only for host connection pools APIs like `Http().superPool` or
    # `Http().singleRequest`.
    client = {
      # no overrides by default, see `akka.http.client` for default values
    }
  }

  # Modify to tweak default parsing settings.
  #
  # IMPORTANT:
  # Please note that this sections settings can be overriden by the corresponding settings in:
  # `akka.http.server.parsing`, `akka.http.client.parsing` or `akka.http.host-connection-pool.client.parsing`.
  parsing {
    # The limits for the various parts of the HTTP message parser.
    max-uri-length             = 2k
    max-method-length          = 16
    max-response-reason-length = 64
    max-header-name-length     = 64
    max-header-value-length    = 8k
    max-header-count           = 64
    max-chunk-ext-length       = 256
    max-chunk-size             = 1m

    # Default maximum content length which should not be exceeded by incoming request entities.
    # Can be changed at runtime (to a higher or lower value) via the `HttpEntity::withSizeLimit` method.
    # Note that it is not necessarily a problem to set this to a high value as all stream operations
    # are always properly backpressured.
    # Nevertheless you might want to apply some limit in order to prevent a single client from consuming
    # an excessive amount of server resources.
    #
    # Set to `infinite` to completely disable entity length checks. (Even then you can still apply one
    # programmatically via `withSizeLimit`.)
    max-content-length = 8m

    # Sets the strictness mode for parsing request target URIs.
    # The following values are defined:
    #
    # `strict`: RFC3986-compliant URIs are required,
    #     a 400 response is triggered on violations
    #
    # `relaxed`: all visible 7-Bit ASCII chars are allowed
    #
    uri-parsing-mode = strict

    # Sets the parsing mode for parsing cookies.
    # The following value are defined:
    #
    # `rfc6265`: Only RFC6265-compliant cookies are parsed. Surrounding double-quotes are accepted and
    #   automatically removed. Non-compliant cookies are silently discarded.
    # `raw`: Raw parsing allows any non-control character but ';' to appear in a cookie value. There's no further
    #   post-processing applied, so that the resulting value string may contain any number of whitespace, unicode,
    #   double quotes, or '=' characters at any position.
    #   The rules for parsing the cookie name are the same ones from RFC 6265.
    #
    cookie-parsing-mode = rfc6265

    # Enables/disables the logging of warning messages in case an incoming
    # message (request or response) contains an HTTP header which cannot be
    # parsed into its high-level model class due to incompatible syntax.
    # Note that, independently of this settings, akka-http will accept messages
    # with such headers as long as the message as a whole would still be legal
    # under the HTTP specification even without this header.
    # If a header cannot be parsed into a high-level model instance it will be
    # provided as a `RawHeader`.
    # If logging is enabled it is performed with the configured
    # `error-logging-verbosity`.
    illegal-header-warnings = on

    # Parse headers into typed model classes in the Akka Http core layer.
    #
    # If set to `off`, only essential headers will be parsed into their model classes. All other ones will be provided
    # as instances of `RawHeader`. Currently, `Connection`, `Host`, and `Expect` headers will still be provided in their
    # typed model. The full list of headers still provided as modeled instances can be found in the source code of
    # `akka.http.impl.engine.parsing.HttpHeaderParser.alwaysParsedHeaders`. Note that (regardless of this setting)
    # some headers like `Content-Type` are treated specially and will never be provided in the list of headers.
    modeled-header-parsing = on

    # Configures the verbosity with which message (request or response) parsing
    # errors are written to the application log.
    #
    # Supported settings:
    # `off`   : no log messages are produced
    # `simple`: a condensed single-line message is logged
    # `full`  : the full error details (potentially spanning several lines) are logged
    error-logging-verbosity = full

    # Configures the processing mode when encountering illegal characters in
    # header value of response.
    #
    # Supported mode:
    # `error`  : default mode, throw an ParsingException and terminate the processing
    # `warn`   : ignore the illegal characters in response header value and log a warning message
    # `ignore` : just ignore the illegal characters in response header value
    illegal-response-header-value-processing-mode = error

    # limits for the number of different values per header type that the
    # header cache will hold
    header-cache {
      default = 12
      Content-MD5 = 0
      Date = 0
      If-Match = 0
      If-Modified-Since = 0
      If-None-Match = 0
      If-Range = 0
      If-Unmodified-Since = 0
      User-Agent = 32
    }

    # Enables/disables inclusion of an Tls-Session-Info header in parsed
    # messages over Tls transports (i.e., HttpRequest on server side and
    # HttpResponse on client side).
    tls-session-info-header = off
  }
}