Configuration

###################################
# spray-can Reference Config File #
###################################

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

spray.can {

  server {
    # The value of the `Server` header to produce.
    # Set to the empty string to disable rendering of the server header.
    server-header = spray-can/${spray.version}

    # Enables/disables SSL encryption.
    # If enabled the server uses the implicit `ServerSSLEngineProvider` member
    # of the `Bind` command to create `SSLEngine` instances for the underlying
    # IO connection.
    ssl-encryption = off

    # 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.
    # Set to 'disabled' for completely disabling pipelining limits
    # (not recommended on public-facing servers due to risk of DoS attacks).
    # This value must be > 0 and <= 128.
    pipelining-limit = 1

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

    # If a request hasn't been responded to after the time period set here
    # a `spray.http.Timedout` message will be sent to the timeout handler.
    # Set to `infinite` to completely disable request timeouts.
    request-timeout = 20 s

    # After a `Timedout` message has been sent to the timeout handler and the
    # request still hasn't been completed after the time period set here
    # the server will complete the request itself with an error response.
    # Set to `infinite` to disable timeout timeouts.
    timeout-timeout = 2 s

    # The period during which a service must respond to a `ChunkedRequestStart` message
    # with a `RegisterChunkHandler` message. During the registration period reading from
    # the network is suspended. It is still possible that some chunks have already been
    # received which will be buffered until the registration is received or the timeout is
    # triggered. If the timeout is triggered the connection is immediately aborted.
    chunkhandler-registration-timeout = 500 ms

    # The path of the actor to send `spray.http.Timedout` messages to.
    # If empty all `Timedout` messages will go to the "regular" request
    # handling actor.
    timeout-handler = ""

    # The "granularity" of timeout checking for both idle connections timeouts
    # as well as request timeouts, should rarely be needed to modify.
    # If set to `infinite` request and connection timeout checking is disabled.
    reaping-cycle = 250 ms

    # Enables/disables support for statistics collection and querying.
    # Even though stats keeping overhead is small,
    # for maximum performance switch off when not needed.
    stats-support = on

    # 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 an alternative response streaming mode that doesn't
    # use `Transfer-Encoding: chunked` but rather renders the individual
    # MessageChunks coming in from the application as parts of the original
    # response entity.
    # Enabling this mode causes all connections to be closed after a streaming
    # response has been finished since there is no other way to signal the
    # response end to the client.
    # Note that chunkless-streaming is implicitly enabled when streaming
    # responses to HTTP/1.0 clients (since they don't support
    # `Transfer-Encoding: chunked`)
    chunkless-streaming = off

    # 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 spray will always produce log messages containing the full
    # error details.
    verbose-error-messages = off

    # Enables/disables the logging of the full (potentially multiple line)
    # error message to the server logs.
    # If disabled only a single line will be logged.
    verbose-error-logging = off

    # If this setting is non-zero the HTTP server automatically aggregates
    # incoming request chunks into full HttpRequests before dispatching them to
    # the application. If the size of the aggregated requests surpasses the
    # specified limit the server responds with a `413 Request Entity Too Large`
    # error response before closing the connection.
    # Set to zero to disable automatic request chunk aggregation and have
    # ChunkedRequestStart, MessageChunk and ChunkedMessageEnd messages be
    # dispatched to the handler.
    request-chunk-aggregation-limit = 1m

    # The initial size if 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

    # For HTTPS connections this setting specified the maximum number of
    # bytes that are encrypted in one go. Large responses are broken down in
    # chunks of this size so as to already begin sending before the response has
    # been encrypted entirely.
    max-encryption-chunk-size = 1m

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

    # The time period within which the TCP unbinding process must be completed.
    # Set to `infinite` to disable.
    unbind-timeout = 1s

    # The time period within which a connection handler must have been
    # registered after the bind handler has received a `Connected` event.
    # Set to `infinite` to disable.
    registration-timeout = 1s

    # The time after which a connection is aborted (RST) after a parsing error
    # occurred. The timeout prevents a connection which is already known to be
    # erroneous from receiving evermore data even if all of the data will be ignored.
    # However, in case of a connection abortion the client usually doesn't properly
    # receive the error response. This timeout is a trade-off which allows the client
    # some time to finish its request and receive a proper error response before the
    # connection is forcibly closed to free resources.
    parsing-error-abort-timeout = 2s

    # 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 = ""

    # Enables/disables automatic back-pressure handling by write buffering and
    # receive throttling
    automatic-back-pressure-handling = on

    back-pressure {
        # The reciprocal rate of requested Acks per NoAcks. E.g. the default value
        # '10' means that every 10th write request is acknowledged. This affects the
        # number of writes each connection has to buffer even in absence of back-pressure.
        noack-rate = 10

        # The lower limit the write queue size has to shrink to before reads are resumed.
        # Use 'infinite' to disable the low-watermark so that reading is resumed instantly
        # after the next successful write.
        reading-low-watermark = infinite
    }

    # Enables more verbose DEBUG logging for debugging SSL related issues.
    ssl-tracing = off

    # Modify to tweak parsing settings on the server-side only.
    parsing = ${spray.can.parsing}
  }

  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 = spray-can/${spray.version}

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

    # The max time period that a client connection will be waiting for a response
    # before triggering a request timeout. The timer for this logic is not started
    # until the connection is actually in a state to receive the response, which
    # may be quite some time after the request has been received from the
    # application!
    # There are two main reasons to delay the start of the request timeout timer:
    # 1. On the host-level API with pipelining disabled:
    #    If the request cannot be sent immediately because all connections are
    #    currently busy with earlier requests it has to be queued until a
    #    connection becomes available.
    # 2. With pipelining enabled:
    #    The request timeout timer starts only once the response for the
    #    preceding request on the connection has arrived.
    # Set to `infinite` to completely disable request timeouts.
    request-timeout = 20 s

    # the "granularity" of timeout checking for both idle connections timeouts
    # as well as request timeouts, should rarely be needed to modify.
    # If set to `infinite` request and connection timeout checking is disabled.
    reaping-cycle = 250 ms

    # If this setting is non-zero the HTTP client connections automatically
    # aggregate incoming response chunks into full HttpResponses before
    # dispatching them to the application.
    # If the size of the aggregated response surpasses the specified limit the
    # HTTP client connection is closed and an error returned.
    # Set to zero to disable automatic request chunk aggregation and have
    # ChunkedResponseStart, MessageChunk and ChunkedMessageEnd messages be
    # dispatched to the application.
    response-chunk-aggregation-limit = 1m

    # Enables/disables an alternative request streaming mode that doesn't
    # use `Transfer-Encoding: chunked` but rather renders the individual
    # MessageChunks coming in from the application as parts of the original
    # request entity.
    # Enabling this mode causes all requests to require an explicit `Content-Length`
    # header for streaming requests.
    # Note that chunkless-streaming is implicitly enabled when streaming
    # HTTP/1.0 requests since they don't support `Transfer-Encoding: chunked`.
    chunkless-streaming = off

    # The initial size if 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

    # For HTTPS connections this setting specified the maximum number of
    # bytes that are encrypted in one go. Large requests are broken down in
    # chunks of this size so as to already begin sending before the request has
    # been encrypted entirely.
    max-encryption-chunk-size = 1m

    # The time period within which the TCP connecting process must be completed.
    # Set to `infinite` to disable.
    connecting-timeout = 10s

    # The proxy configurations to be used for requests with the specified
    # scheme.
    proxy {
      # Proxy settings for unencrypted HTTP requests
      # Set to 'none' to always connect directly, 'default' to use the system
      # settings as described in http://docs.oracle.com/javase/6/docs/technotes/guides/net/proxies.html
      # or specify the proxy host, port and non proxy hosts as demonstrated
      # in the following example:
      # http {
      #   host = myproxy.com
      #   port = 8080
      #   non-proxy-hosts = ["*.direct-access.net"]
      # }
      http = default

      # Proxy settings for HTTPS requests (currently unsupported)
      https = default
    }

    # Enables more verbose DEBUG logging for debugging SSL related issues.
    ssl-tracing = off

    # Modify to tweak parsing settings on the client-side only.
    parsing = ${spray.can.parsing}
  }

  host-connector {
    # The maximum number of parallel connections that an `HttpHostConnector`
    # is allowed to establish to a host. Must be greater than zero.
    max-connections = 4

    # The maximum number of times an `HttpHostConnector` attempts to repeat
    # failed requests (if the request can be safely retried) before
    # giving up and returning an error.
    max-retries = 5

    # Configures redirection following.
    # If set to zero redirection responses will not be followed, i.e. they'll be returned to the user as is.
    # If set to a value > zero redirection responses will be followed up to the given number of times.
    # If the redirection chain is longer than the configured value the first redirection response that is
    # is not followed anymore is returned to the user as is.
    max-redirects = 0

    # If this setting is enabled, the `HttpHostConnector` pipelines requests
    # across connections, otherwise only one single request can be "open"
    # on a particular HTTP connection.
    pipelining = off

    # The time after which an idle `HttpHostConnector` (without open
    # connections) will automatically terminate itself.
    # Set to `infinite` to completely disable idle timeouts.
    idle-timeout = 30 s

    # Modify to tweak client settings for this host-connector only.
    client = ${spray.can.client}
  }

  # The (default) configuration of the HTTP message parser for the server and
  # the client.
  # IMPORTANT: These settings (i.e. children of `spray.can.parsing`) can't be directly
  # overridden in `application.conf` to change the parser settings for client and server
  # altogether (see https://github.com/spray/spray/issues/346). Instead, override the
  # concrete settings beneath `spray.can.server.parsing` and `spray.can.client.parsing`
  # where these settings are copied to.
  parsing {
    # The limits for the various parts of the HTTP message parser.
    max-uri-length             = 2k
    max-response-reason-length = 64
    max-header-name-length     = 64
    max-header-value-length    = 8k
    max-header-count           = 64
    max-content-length         = 8m
    max-chunk-ext-length       = 256
    max-chunk-size             = 1m

    # 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
    #
    # `relaxed-with-raw-query`: like `relaxed` but additionally
    #     the URI query is not parsed, but delivered as one raw string
    #     as the `key` value of a single Query structure element.
    #
    uri-parsing-mode = strict

    # 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, spray 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`.
    illegal-header-warnings = on

    # 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
    }

    # Sets the size starting from which incoming http-messages will be delivered
    # in chunks regardless of whether chunking is actually used on the wire.
    # Set to infinite to disable auto chunking.
    incoming-auto-chunking-threshold-size = infinite

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

  # Fully qualified config path which holds the dispatcher configuration
  # to be used for the HttpManager.
  manager-dispatcher = "akka.actor.default-dispatcher"

  # Fully qualified config path which holds the dispatcher configuration
  # to be used for the HttpClientSettingsGroup actors.
  settings-group-dispatcher = "akka.actor.default-dispatcher"

  # Fully qualified config path which holds the dispatcher configuration
  # to be used for the HttpHostConnector actors.
  host-connector-dispatcher = "akka.actor.default-dispatcher"

  # Fully qualified config path which holds the dispatcher configuration
  # to be used for HttpListener actors.
  listener-dispatcher = "akka.actor.default-dispatcher"

  # Fully qualified config path which holds the dispatcher configuration
  # to be used for HttpServerConnection and HttpClientConnection actors.
  connection-dispatcher = "akka.actor.default-dispatcher"
}