CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-eclipse-jetty--jetty-server

Core server component of Eclipse Jetty web server providing HTTP server functionality, request handling, and connection management

—

Pending
Overview
Eval results
Files

configuration.mddocs/

HTTP Configuration

HTTP configuration manages protocol settings, buffer sizes, security options, and request customization through the HttpConfiguration class and its customizers.

HttpConfiguration Class

The core class for configuring HTTP protocol behavior.

public class HttpConfiguration implements Dumpable {
    // Constructors
    public HttpConfiguration();
    public HttpConfiguration(HttpConfiguration config);
    
    // Buffer size configuration
    public int getOutputBufferSize();
    public void setOutputBufferSize(int outputBufferSize);
    public int getOutputAggregationSize();
    public void setOutputAggregationSize(int outputAggregationSize);
    public int getRequestHeaderSize();
    public void setRequestHeaderSize(int requestHeaderSize);
    public int getResponseHeaderSize();
    public void setResponseHeaderSize(int responseHeaderSize);
    public int getHeaderCacheSize();
    public void setHeaderCacheSize(int headerCacheSize);
    
    // Server identification
    public boolean getSendServerVersion();
    public void setSendServerVersion(boolean sendServerVersion);
    public boolean getSendDateHeader();
    public void setSendDateHeader(boolean sendDateHeader);
    public boolean getSendXPoweredBy();
    public void setSendXPoweredBy(boolean sendXPoweredBy);
    public String getServerAuthority();
    public void setServerAuthority(String serverAuthority);
    
    // URI and path configuration
    public int getSecurePort();
    public void setSecurePort(int securePort);
    public String getSecureScheme();
    public void setSecureScheme(String secureScheme);
    public long getIdleTimeout();
    public void setIdleTimeout(long idleTimeout);
    
    // HTTP compliance
    public HttpCompliance getRequestCookieCompliance();
    public void setRequestCookieCompliance(HttpCompliance requestCookieCompliance);
    public HttpCompliance getResponseCookieCompliance();
    public void setResponseCookieCompliance(HttpCompliance responseCookieCompliance);
    
    // Customizers
    public void addCustomizer(Customizer customizer);
    public List<Customizer> getCustomizers();
    public void removeCustomizer(Customizer customizer);
    
    // Nested interfaces
    interface Customizer {
        Request customize(Request request, HttpConfiguration configuration);
    }
    
    interface ConnectionFactory {
        HttpConfiguration getHttpConfiguration();
    }
}

Basic Configuration Example

// Create HTTP configuration
HttpConfiguration httpConfig = new HttpConfiguration();

// Buffer sizes
httpConfig.setOutputBufferSize(32768);        // 32KB output buffer
httpConfig.setOutputAggregationSize(8192);    // 8KB aggregation buffer
httpConfig.setRequestHeaderSize(8192);        // 8KB request headers
httpConfig.setResponseHeaderSize(8192);       // 8KB response headers
httpConfig.setHeaderCacheSize(512);           // 512 cached headers

// Server behavior
httpConfig.setSendServerVersion(false);       // Hide server version
httpConfig.setSendDateHeader(true);           // Include Date header
httpConfig.setSendXPoweredBy(false);          // Hide X-Powered-By

// Security configuration
httpConfig.setSecureScheme("https");
httpConfig.setSecurePort(8443);

// Timeout configuration
httpConfig.setIdleTimeout(30000);             // 30 second idle timeout

// Create connector with configuration
HttpConnectionFactory factory = new HttpConnectionFactory(httpConfig);
ServerConnector connector = new ServerConnector(server, factory);

HTTP Customizers

Customizers modify requests during processing to add security headers, handle forwarded headers, and implement protocol features.

SecureRequestCustomizer

Adds security features for HTTPS connections.

public class SecureRequestCustomizer implements HttpConfiguration.Customizer {
    // HSTS (HTTP Strict Transport Security)
    public long getStsMaxAge();
    public void setStsMaxAge(long stsMaxAge);
    public boolean isStsIncludeSubDomains();
    public void setStsIncludeSubDomains(boolean stsIncludeSubDomains);
    
    // SNI (Server Name Indication)
    public boolean isSniRequired();
    public void setSniRequired(boolean sniRequired);
    public boolean isSniHostCheck();
    public void setSniHostCheck(boolean sniHostCheck);
    
    // Client certificates
    public Request customize(Request request, HttpConfiguration configuration);
}

Usage Example

// Create HTTPS configuration
HttpConfiguration httpsConfig = new HttpConfiguration();
httpsConfig.setSecureScheme("https");
httpsConfig.setSecurePort(8443);

// Add secure request customizer
SecureRequestCustomizer secureCustomizer = new SecureRequestCustomizer();
secureCustomizer.setStsMaxAge(31536000);           // 1 year HSTS
secureCustomizer.setStsIncludeSubDomains(true);    // Include subdomains
secureCustomizer.setSniRequired(false);            // SNI optional
secureCustomizer.setSniHostCheck(true);            // Validate SNI hostname
httpsConfig.addCustomizer(secureCustomizer);

// SSL context factory
SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
sslContextFactory.setKeyStorePath("keystore.jks");
sslContextFactory.setKeyStorePassword("password");

// Create HTTPS connector
ServerConnector httpsConnector = new ServerConnector(server,
    new SslConnectionFactory(sslContextFactory, "http/1.1"),
    new HttpConnectionFactory(httpsConfig));
httpsConnector.setPort(8443);
server.addConnector(httpsConnector);

ForwardedRequestCustomizer

Handles X-Forwarded-* headers from reverse proxies.

public class ForwardedRequestCustomizer implements HttpConfiguration.Customizer {
    // Header names
    public String getForwardedHeader();
    public void setForwardedHeader(String forwardedHeader);
    public String getForwardedHostHeader();
    public void setForwardedHostHeader(String forwardedHostHeader);
    public String getForwardedServerHeader();  
    public void setForwardedServerHeader(String forwardedServerHeader);
    public String getForwardedProtoHeader();
    public void setForwardedProtoHeader(String forwardedProtoHeader);
    public String getForwardedForHeader();
    public void setForwardedForHeader(String forwardedForHeader);
    public String getForwardedHttpsHeader();
    public void setForwardedHttpsHeader(String forwardedHttpsHeader);
    public String getForwardedSslSessionIdHeader();
    public void setForwardedSslSessionIdHeader(String forwardedSslSessionIdHeader);
    public String getForwardedCipherSuiteHeader();
    public void setForwardedCipherSuiteHeader(String forwardedCipherSuiteHeader);
    
    // Processing options
    public boolean getProxyAsAuthority();
    public void setProxyAsAuthority(boolean proxyAsAuthority);
    
    // Request customization
    public Request customize(Request request, HttpConfiguration configuration);
}

Usage Example

// Create HTTP configuration for reverse proxy
HttpConfiguration proxyConfig = new HttpConfiguration();

// Add forwarded request customizer
ForwardedRequestCustomizer forwardedCustomizer = new ForwardedRequestCustomizer();

// Configure standard headers
forwardedCustomizer.setForwardedHostHeader("X-Forwarded-Host");
forwardedCustomizer.setForwardedServerHeader("X-Forwarded-Server");
forwardedCustomizer.setForwardedProtoHeader("X-Forwarded-Proto");
forwardedCustomizer.setForwardedForHeader("X-Forwarded-For");

// Handle HTTPS detection
forwardedCustomizer.setForwardedHttpsHeader("X-Forwarded-HTTPS");

// Trust proxy for authority
forwardedCustomizer.setProxyAsAuthority(true);

proxyConfig.addCustomizer(forwardedCustomizer);

// Create connector
ServerConnector connector = new ServerConnector(server, 
    new HttpConnectionFactory(proxyConfig));
connector.setPort(8080);

ProxyCustomizer

Handles HAProxy PROXY protocol for preserving client connection information.

public class ProxyCustomizer implements HttpConfiguration.Customizer {
    // Request customization for PROXY protocol
    public Request customize(Request request, HttpConfiguration configuration);
}

HostHeaderCustomizer

Validates and processes Host headers.

public class HostHeaderCustomizer implements HttpConfiguration.Customizer {
    // Authority validation
    public String getServerAuthority();
    public void setServerAuthority(String serverAuthority);
    
    // Request customization
    public Request customize(Request request, HttpConfiguration configuration);
}

Custom Customizer Implementation

// Custom security headers customizer
public class SecurityHeadersCustomizer implements HttpConfiguration.Customizer {
    private final Map<String, String> securityHeaders;
    
    public SecurityHeadersCustomizer() {
        this.securityHeaders = new HashMap<>();
        
        // Default security headers
        securityHeaders.put("X-Content-Type-Options", "nosniff");
        securityHeaders.put("X-Frame-Options", "DENY");
        securityHeaders.put("X-XSS-Protection", "1; mode=block");
        securityHeaders.put("Referrer-Policy", "strict-origin-when-cross-origin");
        securityHeaders.put("Content-Security-Policy", 
            "default-src 'self'; script-src 'self' 'unsafe-inline'");
    }
    
    public void addHeader(String name, String value) {
        securityHeaders.put(name, value);
    }
    
    public void removeHeader(String name) {
        securityHeaders.remove(name);
    }
    
    @Override
    public Request customize(Request request, HttpConfiguration configuration) {
        // Wrap request to add response headers
        return new SecurityHeaderRequest(request, securityHeaders);
    }
}

// Request wrapper that adds security headers to response
public class SecurityHeaderRequest extends Request.Wrapper {
    private final Map<String, String> securityHeaders;
    
    public SecurityHeaderRequest(Request wrapped, Map<String, String> securityHeaders) {
        super(wrapped);
        this.securityHeaders = securityHeaders;
    }
    
    // Could override response to add headers, or use a response wrapper
    // Implementation depends on how you want to inject the headers
}

// Usage
HttpConfiguration config = new HttpConfiguration();
SecurityHeadersCustomizer securityCustomizer = new SecurityHeadersCustomizer();
securityCustomizer.addHeader("Permissions-Policy", 
    "geolocation=(), microphone=(), camera=()");
config.addCustomizer(securityCustomizer);

Advanced Configuration

HTTP Compliance Configuration

// Configure HTTP compliance levels
HttpConfiguration config = new HttpConfiguration();

// Request cookie compliance
config.setRequestCookieCompliance(HttpCompliance.RFC6265);

// Response cookie compliance  
config.setResponseCookieCompliance(HttpCompliance.RFC6265);

// Create compliance violation listener
ComplianceViolation.Listener violationListener = new ComplianceViolation.Listener() {
    @Override
    public void onComplianceViolation(ComplianceViolation.Event event) {
        System.err.println("HTTP Compliance Violation: " + event.getDescription());
    }
};

config.addBean(violationListener);

Multi-Configuration Setup

public class MultiConfigurationServer {
    
    public void setupServer() {
        Server server = new Server();
        
        // Internal API configuration (relaxed)
        HttpConfiguration internalConfig = createInternalConfig();
        ServerConnector internalConnector = new ServerConnector(server,
            new HttpConnectionFactory(internalConfig));
        internalConnector.setHost("127.0.0.1");
        internalConnector.setPort(8081);
        
        // External API configuration (strict)
        HttpConfiguration externalConfig = createExternalConfig();
        ServerConnector externalConnector = new ServerConnector(server,
            new HttpConnectionFactory(externalConfig));
        externalConnector.setHost("0.0.0.0");
        externalConnector.setPort(8080);
        
        // HTTPS configuration
        HttpConfiguration httpsConfig = createHttpsConfig();
        SslContextFactory.Server sslContextFactory = createSslContextFactory();
        ServerConnector httpsConnector = new ServerConnector(server,
            new SslConnectionFactory(sslContextFactory, "http/1.1"),
            new HttpConnectionFactory(httpsConfig));
        httpsConnector.setPort(8443);
        
        server.setConnectors(new Connector[]{
            internalConnector, externalConnector, httpsConnector
        });
    }
    
    private HttpConfiguration createInternalConfig() {
        HttpConfiguration config = new HttpConfiguration();
        config.setOutputBufferSize(65536);    // Larger buffers for internal
        config.setRequestHeaderSize(16384);   // Allow larger headers
        config.setSendServerVersion(true);    // Include version for debugging
        return config;
    }
    
    private HttpConfiguration createExternalConfig() {
        HttpConfiguration config = new HttpConfiguration();
        config.setOutputBufferSize(32768);    // Standard buffers
        config.setRequestHeaderSize(8192);    // Standard header size
        config.setSendServerVersion(false);   // Hide version
        config.setSendXPoweredBy(false);      // Hide implementation
        
        // Add forwarded headers support for reverse proxy
        config.addCustomizer(new ForwardedRequestCustomizer());
        
        return config;
    }
    
    private HttpConfiguration createHttpsConfig() {
        HttpConfiguration config = new HttpConfiguration();
        config.setSecureScheme("https");
        config.setSecurePort(8443);
        
        // Add HTTPS security features
        SecureRequestCustomizer secureCustomizer = new SecureRequestCustomizer();
        secureCustomizer.setStsMaxAge(31536000);        // 1 year HSTS
        secureCustomizer.setStsIncludeSubDomains(true); // Include subdomains
        config.addCustomizer(secureCustomizer);
        
        return config;
    }
    
    private SslContextFactory.Server createSslContextFactory() {
        SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
        sslContextFactory.setKeyStorePath("keystore.jks");
        sslContextFactory.setKeyStorePassword("password");
        sslContextFactory.setIncludeProtocols("TLSv1.2", "TLSv1.3");
        return sslContextFactory;
    }
}

Configuration Monitoring and Debugging

Configuration Dumping

// Dump configuration for debugging
HttpConfiguration config = new HttpConfiguration();
// ... configure ...

// Dump configuration to string
StringWriter writer = new StringWriter();
config.dump(writer, "");
System.out.println("HTTP Configuration:");
System.out.println(writer.toString());

Dynamic Configuration Updates

public class DynamicConfigurationManager {
    private final HttpConfiguration config;
    private final List<HttpConfiguration.Customizer> customizers;
    
    public DynamicConfigurationManager(HttpConfiguration config) {
        this.config = config;
        this.customizers = new ArrayList<>(config.getCustomizers());
    }
    
    public void updateBufferSizes(int outputBuffer, int headerSize) {
        config.setOutputBufferSize(outputBuffer);
        config.setRequestHeaderSize(headerSize);
        config.setResponseHeaderSize(headerSize);
    }
    
    public void enableSecurityHeaders() {
        SecurityHeadersCustomizer securityCustomizer = new SecurityHeadersCustomizer();
        config.addCustomizer(securityCustomizer);
    }
    
    public void disableServerIdentification() {
        config.setSendServerVersion(false);
        config.setSendXPoweredBy(false);
    }
    
    public void resetCustomizers() {
        // Remove all customizers
        config.getCustomizers().clear();
        
        // Restore original customizers
        for (HttpConfiguration.Customizer customizer : customizers) {
            config.addCustomizer(customizer);
        }
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-org-eclipse-jetty--jetty-server

docs

configuration.md

connection-management.md

context-resources.md

handlers.md

index.md

request-logging.md

request-response.md

security-ssl.md

server-core.md

session-management.md

utility-handlers.md

tile.json