Module io.fusionauth.http
Package io.fusionauth.http.server

Class HTTPServerConfiguration

java.lang.Object
io.fusionauth.http.server.HTTPServerConfiguration
All Implemented Interfaces:
Configurable<HTTPServerConfiguration>
public class HTTPServerConfiguration extends Object implements Configurable<HTTPServerConfiguration>
The HTTP Server configuration.
Author:
Brian Pontarelli

  • Field Details

    • DefaultMaxRequestSizes

      public static final Map<String,Integer> DefaultMaxRequestSizes

  • Constructor Details

    • HTTPServerConfiguration

      public HTTPServerConfiguration()

  • Method Details

    • configuration

      public HTTPServerConfiguration configuration()
      Specified by:
      configuration in interface Configurable<HTTPServerConfiguration>
      Returns:
      This.

    • getBaseDir

      public Path getBaseDir()
      Returns:
      The base dir for the entire server. This can be used to calculate files from as needed.

    • getChunkedBufferSize

      public int getChunkedBufferSize()
      Returns:
      the length of the buffer used to parse a chunked request.

    • getContextPath

      public String getContextPath()
      Returns:
      The context page that the entire server serves requests under or null.

    • getExpectValidator

      public ExpectValidator getExpectValidator()
      Returns:
      The expect validator. Cannot be null and is required.

    • getHandler

      public HTTPHandler getHandler()
      Returns:
      The HTTP handler for this server. Cannot be null and is required.

    • getInitialReadTimeoutDuration

      public Duration getInitialReadTimeoutDuration()
      Returns:
      The timeout between a socket being accepted by the server and the first byte being read. This is distinct and separate from the timeout for subsequent reads after the connection has been "kept alive".

    • getInstrumenter

      public Instrumenter getInstrumenter()
      Returns:
      The instrumenter or null.

    • getKeepAliveTimeoutDuration

      public Duration getKeepAliveTimeoutDuration()
      Returns:
      The timeout between requests when the server is in Keep-Alive mode. This is the maximum value to prevent DoS attacks that use the HTTP headers to set extremely long timeouts.

    • getListeners

      public List<HTTPListenerConfiguration> getListeners()
      Returns:
      All configured listeners (if any) or an empty list.

    • getLoggerFactory

      public LoggerFactory getLoggerFactory()
      Returns:
      The logger factory.

    • getMaxBytesToDrain

      public int getMaxBytesToDrain()
      When using keep-alive, this configuration represents the maximum number of bytes to drain from the InputStream when the request handler did not read all available bytes. This is done to drain the InputStream, attempting to reach the end of the request in order to prepare for the next request.

      If you are not using keep-alive, this configuration will not be utilized.

      When this configured limit is reached, the socket will be closed. This would be equivalent to adding Connection: close to the request. Setting this limit too low could cause connections not to be re-used, setting this limit too high simply means that the server will take more time to read more bytes from the client before being able to re-use the connection.

      Returns:
      The maximum number of bytes to drain from the InputStream when the request handler did not read all available bytes. Defaults to 256 Kilobytes.

    • getMaxPendingSocketConnections

      public int getMaxPendingSocketConnections()
      The maximum number of pending socket connections per HTTP listener.

      This number represents how many pending socket connections are allowed to queue before they are rejected. Once the connection is accepted by the server socket, a client socket is created and handed to an HTTP Worker. This queue length only needs to be large enough to buffer the incoming requests as fast as we can accept them and hand them to a worker.

      Returns:
      The maximum number of pending socket connections per HTTP listener. Defaults to 250.

    • getMaxRequestBodySize

      public Map<String,Integer> getMaxRequestBodySize()
      The map that specifies the maximum size in bytes of the HTTP request body by Content-Type. This configuration excludes the size of the HTTP request header.

      The returned map is keyed by Content-Type, and will contain a default value identified by '*', and may optionally contain a content type value with a wild card '*' as the subtype. For example, 'application/*' will match all subtypes of an application/ content type.

      Returns:
      the map keyed by Content-Type indicating the maximum size in bytes of the HTTP request body. Defaults to 128 Megabytes as a default, and 10 Megabytes for application/x-www-form-urlencoded.

    • getMaxRequestHeaderSize

      public int getMaxRequestHeaderSize()
      Returns:
      the maximum size of the HTTP request header in bytes. This configuration does not affect the HTTP response header. Defaults to 128 Kilobytes.

    • getMaxRequestsPerConnection

      public int getMaxRequestsPerConnection()
      This limit only applies when using a persistent connection. If this number is reached without hitting a Keep-Alive timeout the connection will be closed just as it would be if the Keep-Alive timeout was reached.
      Returns:
      The maximum number of requests that can be handled by a single persistent connection. Defaults to 100,000.

    • getMaxResponseChunkSize

      public int getMaxResponseChunkSize()
      Returns:
      The max chunk size in the response. Defaults to 16 Kilobytes.

    • getMinimumReadThroughput

      public long getMinimumReadThroughput()
      This configuration is the minimum number of bytes per second that a client must send a request to the server before the server closes the connection.

      A value of -1 indicates the minimum read throughput limitation has been disabled.

      Returns:
      The minimum throughput for any connection with the server in bytes per second.

    • getMinimumWriteThroughput

      public long getMinimumWriteThroughput()
      This configuration is the minimum number of bytes per second that a client must read the response from the server before the server closes the connection.

      A value of -1 indicates the minimum write throughput limitation has been disabled.

      Returns:
      The minimum throughput for any connection with the server in bytes per second.

    • getMultipartBufferSize

      @Deprecated public int getMultipartBufferSize()
      Deprecated.
      Returns:
      The multipart buffer size in bytes. This is primary used for parsing multipart requests by the HTTPRequest class. Defaults to 16 Kilobytes.

    • getMultipartConfiguration

      public MultipartConfiguration getMultipartConfiguration()
      Returns:
      the multipart configuration.

    • getProcessingTimeoutDuration

      public Duration getProcessingTimeoutDuration()
      Returns:
      The timeout between when the request has been fully read and the first byte is written. This provides the worker thread to perform work before it begins to write. This timeout should be relatively short depending on how long you want the browser/client to wait before the response comes back. Defaults to 10 seconds.

    • getReadThroughputCalculationDelay

      public Duration getReadThroughputCalculationDelay()
      Returns:
      the duration that will be used to delay the calculation and enforcement of the minimum read throughput.

    • getRequestBufferSize

      public int getRequestBufferSize()
      Returns:
      The size of the buffer used to read the request. Defaults to 16 Kilobytes

    • getResponseBufferSize

      public int getResponseBufferSize()
      Returns:
      The size of the buffer used to store the response. This allows the server to handle exceptions and errors without writing back a 200 response that is actually an error. Defaults to 64 Kilobytes.

    • getShutdownDuration

      public Duration getShutdownDuration()
      Returns:
      The duration that the server will wait while worker threads complete before forcibly shutting itself down. Defaults to 10 seconds.

    • getUnexpectedExceptionHandler

      public HTTPUnexpectedExceptionHandler getUnexpectedExceptionHandler()
      Returns:
      The HTTP unexpected exception handler for this server. Never null.

    • getWriteThroughputCalculationDelay

      public Duration getWriteThroughputCalculationDelay()
      Returns:
      the duration that will be used to delay the calculation and enforcement of the minimum write throughput.

    • isCompressByDefault

      public boolean isCompressByDefault()
      Returns:
      Whether all responses are compressed by default. Defaults to true.

    • withBaseDir

      public HTTPServerConfiguration withBaseDir(Path baseDir)
      Sets the base directory for this server. This is passed to the HTTPContext, which is available from this class. This defaults to the current working directory of the process.
      Specified by:
      withBaseDir in interface Configurable<HTTPServerConfiguration>
      Parameters:
      baseDir - The base dir.
      Returns:
      This.

    • withChunkedBufferSize

      public HTTPServerConfiguration withChunkedBufferSize(int chunkedBufferSize)
      Sets the buffer size for the chunked input stream. Defaults to 4 Kilobytes.
      Specified by:
      withChunkedBufferSize in interface Configurable<HTTPServerConfiguration>
      Parameters:
      chunkedBufferSize - the buffer size used to read a request body that was encoded using 'chunked' transfer-encoding.
      Returns:
      This.

    • withCompressByDefault

      public HTTPServerConfiguration withCompressByDefault(boolean compressByDefault)
      Sets the default compression behavior for the HTTP response. This behavior can be optionally set per response. See HTTPResponse.setCompress(boolean). Defaults to true.

      Set this configuration to true if you want to compress the response when the Accept-Encoding header is present. Set this configuration to false if you want to require the request handler to use HTTPResponse.setCompress(boolean) in order to compress the response.

      Regardless of this configuration, you always have the option to use HTTPResponse.setCompress(boolean) on a per-response basis as an override.

      When the request does not contain an Accept-Encoding the response will not be compressed regardless of this configuration.

      Specified by:
      withCompressByDefault in interface Configurable<HTTPServerConfiguration>
      Parameters:
      compressByDefault - true if you want to compress by default, or false to not compress by default.
      Returns:
      This.

    • withContextPath

      public HTTPServerConfiguration withContextPath(String contextPath)
      Sets the prefix of the URIs that this server handles. Technically, the server will accept all inbound connections, but if a context path is set, it can assist the application with building URIs (in HTML for example). This value will be accessible via the HTTPRequest.getContextPath() method.
      Specified by:
      withContextPath in interface Configurable<HTTPServerConfiguration>
      Parameters:
      contextPath - The context path for the server.
      Returns:
      This.

    • withExpectValidator

      public HTTPServerConfiguration withExpectValidator(ExpectValidator validator)
      Sets an ExpectValidator that is used if a client sends the server a Expect: 100-continue header.

      Must not be null.

      Specified by:
      withExpectValidator in interface Configurable<HTTPServerConfiguration>
      Parameters:
      validator - The validator.
      Returns:
      This.

    • withHandler

      public HTTPServerConfiguration withHandler(HTTPHandler handler)
      Sets the handler that will process the requests.

      Must not be null.

      Specified by:
      withHandler in interface Configurable<HTTPServerConfiguration>
      Parameters:
      handler - The handler that processes the requests.
      Returns:
      This.

    • withInitialReadTimeout

      public HTTPServerConfiguration withInitialReadTimeout(Duration duration)
      Sets the duration that the server will attempt to read the first byte from a client. This is the very first byte after the socket connection has been accepted by the server. Defaults to 2 seconds.
      Specified by:
      withInitialReadTimeout in interface Configurable<HTTPServerConfiguration>
      Parameters:
      duration - The duration.
      Returns:
      This.

    • withInstrumenter

      public HTTPServerConfiguration withInstrumenter(Instrumenter instrumenter)
      Sets an instrumenter that the server will notify when events and conditions happen.
      Specified by:
      withInstrumenter in interface Configurable<HTTPServerConfiguration>
      Parameters:
      instrumenter - The instrumenter.
      Returns:
      This.

    • withKeepAliveTimeoutDuration

      public HTTPServerConfiguration withKeepAliveTimeoutDuration(Duration duration)
      Sets the duration that the server will allow client connections to remain open and idle after each request has been processed. This is the Keep-Alive state before the first byte of the next request is read. Defaults to 20 seconds.
      Specified by:
      withKeepAliveTimeoutDuration in interface Configurable<HTTPServerConfiguration>
      Parameters:
      duration - The duration.
      Returns:
      This.

    • withListener

      public HTTPServerConfiguration withListener(HTTPListenerConfiguration listener)
      Adds a listener configuration for the server. This will listen on the address and port of the configuration but will share the thread pool of the server.
      Specified by:
      withListener in interface Configurable<HTTPServerConfiguration>
      Parameters:
      listener - The listener.
      Returns:
      This.

    • withLoggerFactory

      public HTTPServerConfiguration withLoggerFactory(LoggerFactory loggerFactory)
      Sets the logger factory that all the HTTP server classes use to retrieve specific loggers. Defaults to the SystemOutLoggerFactory.
      Specified by:
      withLoggerFactory in interface Configurable<HTTPServerConfiguration>
      Parameters:
      loggerFactory - The factory.
      Returns:
      This.

    • withMaxPendingSocketConnections

      public HTTPServerConfiguration withMaxPendingSocketConnections(int maxPendingSocketConnections)
      Sets the maximum number of pending socket connections per HTTP listener.

      This number represents how many pending socket connections are allowed to queue before they are rejected. Once the connection is accepted by the server socket, a client socket is created and handed to an HTTP Worker. This queue length only needs to be large enough to buffer the incoming requests as fast as we can accept them and hand them to a worker.

      Defaults to 200.

      Specified by:
      withMaxPendingSocketConnections in interface Configurable<HTTPServerConfiguration>
      Returns:
      This.

    • withMaxRequestBodySize

      public HTTPServerConfiguration withMaxRequestBodySize(Map<String,Integer> maxRequestBodySize)
      Sets the maximum size of the HTTP request body by Content-Type. If this limit is exceeded, the connection will be closed.

      The default size is identified by the "*" key. This default value will be used if a more specific value has not been configured for the requested Content-Type.

      You may also use wildcards to match one to many subtypes. For example, "application/*" will provide a max size for all content types beginning with application/ when an exact match has not been configured.

      An example lookup for the Content-Type "application/x-www-form-urlencoded" is:

      1. application/x-www-form-urlencoded
      2. application/*
      3. *

      If the provided configuration does not contain the initial default identified by the "*" key, the server default value will be retained. key.

      Set any value to -1 to disable this limitation.

      Defaults to 128 Megabytes for the default "*" and 10 Megabytes for "application/x-www-form-urlencoded".

      Specified by:
      withMaxRequestBodySize in interface Configurable<HTTPServerConfiguration>
      Parameters:
      maxRequestBodySize - a map specifying the maximum size in bytes for the HTTP request body by Content-Type
      Returns:
      This.

    • withMaxRequestHeaderSize

      public HTTPServerConfiguration withMaxRequestHeaderSize(int maxRequestHeaderSize)
      Sets the maximum size of the HTTP request header. The request header includes the HTTP request line, and all HTTP request headers, essentially everything except the request body. If this maximum limit is exceeded, the connection will be closed. Defaults to 128 Kilobytes.

      Set this to -1 to disable this limitation.

      Specified by:
      withMaxRequestHeaderSize in interface Configurable<HTTPServerConfiguration>
      Parameters:
      maxRequestHeaderSize - the maximum size in bytes for the HTTP request header
      Returns:
      This.

    • withMaxRequestsPerConnection

      public HTTPServerConfiguration withMaxRequestsPerConnection(int maxRequestsPerConnection)
      Sets the base directory for this server. This is passed to the HTTPContext, which is available from this class. This defaults to the current working directory of the process. Defaults to 100,000.
      Specified by:
      withMaxRequestsPerConnection in interface Configurable<HTTPServerConfiguration>
      Parameters:
      maxRequestsPerConnection - The maximum number of requests that can be handled by a single persistent connection.
      Returns:
      This.

    • withMaxResponseChunkSize

      public HTTPServerConfiguration withMaxResponseChunkSize(int maxResponseChunkSize)
      This configures the maximum size of a chunk in the response when the server is using chunked response encoding. Defaults to 16 Kilobytes.
      Specified by:
      withMaxResponseChunkSize in interface Configurable<HTTPServerConfiguration>
      Parameters:
      maxResponseChunkSize - The size in bytes.
      Returns:
      This.

    • withMaximumBytesToDrain

      public HTTPServerConfiguration withMaximumBytesToDrain(int maxBytesToDrain)
      Sets the maximum number of bytes the server will allow worker threads to drain after calling the request handler. If the request handler does not read all the bytes, and this limit is exceeded the connection will be closed. Defaults to 128 Kilobytes bytes.
      Specified by:
      withMaximumBytesToDrain in interface Configurable<HTTPServerConfiguration>
      Parameters:
      maxBytesToDrain - The maximum number of bytes to drain from the InputStream if the request handler did not read all the available bytes.
      Returns:
      This.

    • withMinimumReadThroughput

      public HTTPServerConfiguration withMinimumReadThroughput(long bytesPerSecond)
      This configures the minimum number of bytes per second that a client must send a request to the server before the server closes the connection. Set this to -1 to disable this check.
      Specified by:
      withMinimumReadThroughput in interface Configurable<HTTPServerConfiguration>
      Parameters:
      bytesPerSecond - The bytes per second throughput.
      Returns:
      This.

    • withMinimumWriteThroughput

      public HTTPServerConfiguration withMinimumWriteThroughput(long bytesPerSecond)
      This configures the minimum number of bytes per second that a client must read the response from the server before the server closes the connection. Set this to -1 to disable this check.
      Specified by:
      withMinimumWriteThroughput in interface Configurable<HTTPServerConfiguration>
      Parameters:
      bytesPerSecond - The bytes per second throughput.
      Returns:
      This.

    • withMultipartBufferSize

      public HTTPServerConfiguration withMultipartBufferSize(int multipartBufferSize)
      Sets the size of the buffer that is used to process the multipart request body. This defaults to 16 Kilobytes.
      Specified by:
      withMultipartBufferSize in interface Configurable<HTTPServerConfiguration>
      Parameters:
      multipartBufferSize - The size of the buffer.
      Returns:
      This.

    • withMultipartConfiguration

      public HTTPServerConfiguration withMultipartConfiguration(MultipartConfiguration multipartStreamConfiguration)
      Description copied from interface: Configurable
      Sets the multipart processor configuration.

      This configuration is used when parsing a multipart HTTP request that includes files.

      Specified by:
      withMultipartConfiguration in interface Configurable<HTTPServerConfiguration>
      Parameters:
      multipartStreamConfiguration - The configuration.
      Returns:
      This

    • withProcessingTimeoutDuration

      public HTTPServerConfiguration withProcessingTimeoutDuration(Duration duration)
      Sets the duration that the server will allow worker threads to run after the final request byte is read and before the first response byte is written. Defaults to 10 seconds.
      Specified by:
      withProcessingTimeoutDuration in interface Configurable<HTTPServerConfiguration>
      Parameters:
      duration - The duration.
      Returns:
      This.

    • withReadThroughputCalculationDelayDuration

      public HTTPServerConfiguration withReadThroughputCalculationDelayDuration(Duration duration)
      This configures the duration of the initial delay before calculating and enforcing the minimum read throughput. Defaults to 5 seconds.

      This accounts for some warm up period, and exempts short-lived connections that may have smaller payloads that are more difficult to calculate a reasonable minimum read throughput.

      Specified by:
      withReadThroughputCalculationDelayDuration in interface Configurable<HTTPServerConfiguration>
      Parameters:
      duration - The duration to delay the enforcement of the minimum read throughput.
      Returns:
      This.

    • withRequestBufferSize

      public HTTPServerConfiguration withRequestBufferSize(int requestBufferSize)
      Sets the size of the buffer that is used to process the HTTP request. This defaults to 16 Kilobytes.
      Specified by:
      withRequestBufferSize in interface Configurable<HTTPServerConfiguration>
      Parameters:
      requestBufferSize - The size of the buffer.
      Returns:
      This.

    • withResponseBufferSize

      public HTTPServerConfiguration withResponseBufferSize(int responseBufferSize)
      Sets the size of the buffer that is used to store the HTTP response before any bytes are written back to the client. This is useful when the server is generating the response but encounters an error. In this case, the server will throw out the response and change to a 500 error response. This defaults to 64 Kilobytes. Negative values disable the response buffer.

      Set to -1 do disable buffering completely.

      Specified by:
      withResponseBufferSize in interface Configurable<HTTPServerConfiguration>
      Parameters:
      responseBufferSize - The size of the buffer.
      Returns:
      This.

    • withShutdownDuration

      public HTTPServerConfiguration withShutdownDuration(Duration duration)
      Sets the duration the server will wait for running requests to be completed. Defaults to 10 seconds.
      Specified by:
      withShutdownDuration in interface Configurable<HTTPServerConfiguration>
      Parameters:
      duration - The duration the server will wait for all running request processing threads to complete their work.
      Returns:
      This.

    • withUnexpectedExceptionHandler

      public HTTPServerConfiguration withUnexpectedExceptionHandler(HTTPUnexpectedExceptionHandler unexpectedExceptionHandler)
      Sets the unexpected exception handler. This handler will be called when an unexpected exception is taken while processing the HTTP request by the HTTP worker.

      This allows you to customize the status code and logging behavior.

      Must not be null.

      Specified by:
      withUnexpectedExceptionHandler in interface Configurable<HTTPServerConfiguration>
      Parameters:
      unexpectedExceptionHandler - The unexpected exception handler.
      Returns:
      This.

    • withWriteThroughputCalculationDelayDuration

      public HTTPServerConfiguration withWriteThroughputCalculationDelayDuration(Duration duration)
      This configures the duration of the initial delay before calculating and enforcing the minimum write throughput. Defaults to 5 seconds.

      This accounts for some warm up period, and exempts short-lived connections that may have smaller payloads that are more difficult to calculate a reasonable minimum write throughput.

      Specified by:
      withWriteThroughputCalculationDelayDuration in interface Configurable<HTTPServerConfiguration>
      Parameters:
      duration - The duration to delay the enforcement of the minimum write throughput.
      Returns:
      This.