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

Interface Configurable<T extends Configurable<T>>

Type Parameters:
T - The type of configurable for casting.
All Known Implementing Classes:
HTTPServer, HTTPServerConfiguration
public interface Configurable<T extends Configurable<T>>
An interface that identifies something that is configurable. Mainly, this allows the HTTPServer to be configured or to be passed a configuration.

  • Method Details

    • configuration

      HTTPServerConfiguration configuration()
      Returns:
      The configuration object.

    • withBaseDir

      default T 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.
      Parameters:
      baseDir - The base dir.
      Returns:
      This.

    • withChunkedBufferSize

      default T withChunkedBufferSize(int chunkedBufferSize)
      Sets the buffer size for the chunked input stream. Defaults to 4 Kilobytes.
      Parameters:
      chunkedBufferSize - the buffer size used to read a request body that was encoded using 'chunked' transfer-encoding.
      Returns:
      This.

    • withCompressByDefault

      default T 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.

      Parameters:
      compressByDefault - true if you want to compress by default, or false to not compress by default.
      Returns:
      This.

    • withContextPath

      default T 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.
      Parameters:
      contextPath - The context path for the server.
      Returns:
      This.

    • withExpectValidator

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

      Must not be null.

      Parameters:
      validator - The validator.
      Returns:
      This.

    • withHandler

      default T withHandler(HTTPHandler handler)
      Sets the handler that will process the requests.

      Must not be null.

      Parameters:
      handler - The handler that processes the requests.
      Returns:
      This.

    • withInitialReadTimeout

      default T 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.
      Parameters:
      duration - The duration.
      Returns:
      This.

    • withInstrumenter

      default T withInstrumenter(Instrumenter instrumenter)
      Sets an instrumenter that the server will notify when events and conditions happen.
      Parameters:
      instrumenter - The instrumenter.
      Returns:
      This.

    • withKeepAliveTimeoutDuration

      default T 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.
      Parameters:
      duration - The duration.
      Returns:
      This.

    • withListener

      default T 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.
      Parameters:
      listener - The listener.
      Returns:
      This.

    • withLoggerFactory

      default T withLoggerFactory(LoggerFactory loggerFactory)
      Sets the logger factory that all the HTTP server classes use to retrieve specific loggers. Defaults to the SystemOutLoggerFactory.
      Parameters:
      loggerFactory - The factory.
      Returns:
      This.

    • withMaxPendingSocketConnections

      default T 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.

      Returns:
      This.

    • withMaxRequestBodySize

      default T 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".

      Parameters:
      maxRequestBodySize - a map specifying the maximum size in bytes for the HTTP request body by Content-Type
      Returns:
      This.

    • withMaxRequestHeaderSize

      default T 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.

      Parameters:
      maxRequestHeaderSize - the maximum size in bytes for the HTTP request header
      Returns:
      This.

    • withMaxRequestsPerConnection

      default T 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.
      Parameters:
      maxRequestsPerConnection - The maximum number of requests that can be handled by a single persistent connection.
      Returns:
      This.

    • withMaxResponseChunkSize

      default T withMaxResponseChunkSize(int size)
      This configures the maximum size of a chunk in the response when the server is using chunked response encoding. Defaults to 16 Kilobytes.
      Parameters:
      size - The size in bytes.
      Returns:
      This.

    • withMaximumBytesToDrain

      default T 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.
      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

      default T 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.
      Parameters:
      bytesPerSecond - The bytes per second throughput.
      Returns:
      This.

    • withMinimumWriteThroughput

      default T 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.
      Parameters:
      bytesPerSecond - The bytes per second throughput.
      Returns:
      This.

    • withMultipartBufferSize

      @Deprecated default T withMultipartBufferSize(int multipartBufferSize)
      Deprecated.
      use the configuration found in MultipartConfiguration instead.
      Sets the size of the buffer that is used to process the multipart request body. This defaults to 16 Kilobytes.
      Parameters:
      multipartBufferSize - The size of the buffer.
      Returns:
      This.

    • withMultipartConfiguration

      default T withMultipartConfiguration(MultipartConfiguration multipartStreamConfiguration)
      Sets the multipart processor configuration.

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

      Parameters:
      multipartStreamConfiguration - The configuration.
      Returns:
      This

    • withProcessingTimeoutDuration

      default T 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.
      Parameters:
      duration - The duration.
      Returns:
      This.

    • withReadThroughputCalculationDelayDuration

      default T 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.

      Parameters:
      duration - The duration to delay the enforcement of the minimum read throughput.
      Returns:
      This.

    • withRequestBufferSize

      default T withRequestBufferSize(int requestBufferSize)
      Sets the size of the buffer that is used to process the HTTP request. This defaults to 16 Kilobytes.
      Parameters:
      requestBufferSize - The size of the buffer.
      Returns:
      This.

    • withResponseBufferSize

      default T 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.

      Parameters:
      responseBufferSize - The size of the buffer.
      Returns:
      This.

    • withShutdownDuration

      default T withShutdownDuration(Duration duration)
      Sets the duration the server will wait for running requests to be completed. Defaults to 10 seconds.
      Parameters:
      duration - The duration the server will wait for all running request processing threads to complete their work.
      Returns:
      This.

    • withUnexpectedExceptionHandler

      default T 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.

      Parameters:
      unexpectedExceptionHandler - The unexpected exception handler.
      Returns:
      This.

    • withWriteThroughputCalculationDelayDuration

      default T 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.

      Parameters:
      duration - The duration to delay the enforcement of the minimum write throughput.
      Returns:
      This.