FusionAuth java-http

The HTTPOutputStream acts as the bridge between the Worker thread and the Server. It manages data buffering and optional compression.

Compression Logic

To support compressed responses, the HTTPOutputStream must inspect the HTTPRequest. If the request allows it via the Accept-Encoding header, the HTTPOutputStream is wrapped with a GzipOutputStream. This ensures that as the Worker thread writes bytes, they are compressed inline before being handed to the Server.

Buffering and Chunking Mechanism

The HTTPOutputStream uses a synchronized chunking mechanism to pass data to the Server:

• Chunk Size: Data is managed using ByteBuffers of a fixed chunk size (e.g., 1024 bytes).
• Transfer Process: When a chunk is full, it is moved from the 'write side' to the 'read side' and returned to the Server. If the chunk is not yet full, the method returns null.
• Closing: When close() is called, any remaining bytes in the write buffer are immediately transferred to the read side so the Server can finish the transmission.

The server processes incoming HTTP requests in two distinct phases: the head section (start-line and headers) and the body section.

1. Head Section Processing: The server reads bytes from the client and processes them sequentially until the end of the head section is reached. This phase uses a single ByteBuffer for efficiency, as it is managed by a single server thread and does not require thread safety. The request parser handles characters inline during this phase.
2. Body Section Processing: Once the head section is complete, the server transitions into body piping mode. The remaining bytes in the buffer are handed off to a thread-safe pipe. A Worker thread then begins executing the request by reading from this pipe in a streaming fashion.

To ensure high performance and non-blocking behavior, the pipe used for the body must block on the read side (the Worker thread) rather than the write side (the server thread). This allows the server thread to continue reading from the network while the Worker thread processes the stream.

The HTTP response process is split between a Worker thread (which handles application logic) and the Server (which handles network I/O). This separation allows the worker to focus on generating data while the server manages the transmission of headers and body chunks.

The Lifecycle Steps:

1. Header & Status Preparation: The Worker thread runs a handler that writes headers and the status code to the HTTPResponse. The Server monitors this state (e.g., via isHeadReady() or state()) without participating in the logic.
2. Signaling Completion: The Worker thread signals it is finished by either calling close() on the OutputStream or by writing the first byte. This signal tells the Server to prepare the head section.
3. Head Writing: The Server converts the HTTPResponse into bytes (the head section) and writes it to the client.
4. Body Chunking & Compression: As the Worker thread writes bytes to the OutputStream, the Server reads these chunks and writes them to the client. If the client's HTTPRequest included an Accept-Encoding header that allows it, the Server performs inline compression (e.g., gzip).

The run-benchmarks.sh script is the main orchestrator for the benchmarking framework. It automates the process of building servers via Savant, starting them, executing benchmarks using specified tools, stopping the servers, and aggregating the results into JSON files.

To run the benchmarks, use the following command structure:

./run-benchmarks.sh [OPTIONS]

Available Options

The server supports TLS 1.0-1.3 via the Java SSLEngine. To enable TLS, pass a certificate string and a private key string to the HTTPListenerConfiguration constructor.

In development, you can use mkcert to generate self-signed certificates. In production, ensure your certificate file includes all intermediate CA certificates in the chain.

import java.nio.file.Files;
import java.nio.file.Paths;
import io.fusionauth.http.server.HTTPHandler;
import io.fusionauth.http.server.HTTPServer;
import io.fusionauth.http.server.HTTPListenerConfiguration;

public class Example {
  public static void main(String... args) throws Exception {
    String homeDir = System.getProperty("user.home");
    String certificate = Files.readString(Paths.get(homeDir + "/dev/certificates/example.org.pem"));
    String privateKey = Files.readString(Paths.get(homeDir + "/dev/certificates/example.org.key"));

    HTTPHandler handler = (req, res) -> {
      // Handler code goes here
    };

    try (HTTPServer server = new HTTPServer().withHandler(handler)
                                        .withListener(new HTTPListenerConfiguration(4242, certificate, privateKey))) {
      server.start();
    }
  }
}