CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-helidon-webserver--helidon-webserver

High-performance HTTP server implementation built on Java 21 Virtual Threads for Helidon microservices framework

—

Pending
Overview
Eval results
Files

configuration.mddocs/

Configuration

Type-safe configuration system using builder patterns and Blueprint annotations for all server components, providing comprehensive control over server behavior, connections, and protocols.

Capabilities

WebServerConfig Interface

Main configuration interface for WebServer instances with comprehensive server settings.

/**
 * Configuration for WebServer instances.
 */
interface WebServerConfig extends Prototype.Api {
    /**
     * Create builder for WebServer configuration.
     * @return configuration builder
     */
    static Builder builder();
    
    /**
     * Get server port configuration.
     * @return server port
     */
    int port();
    
    /**
     * Get bind address configuration.
     * @return bind address
     */
    String bindAddress();
    
    /**
     * Get backlog configuration for server socket.
     * @return backlog size
     */
    int backlog();
    
    /**
     * Get receive buffer size.
     * @return receive buffer size
     */
    int receiveBufferSize();
    
    /**
     * Get socket options.
     * @return socket options
     */
    Map<SocketOption<?>, Object> socketOptions();
    
    /**
     * Get TLS configuration.
     * @return TLS configuration if enabled
     */
    Optional<Tls> tls();
    
    /**
     * Get connection configuration.
     * @return connection configuration
     */
    ConnectionConfig connection();
    
    /**
     * Get listener configurations.
     * @return map of listener configurations by name
     */
    Map<String, ListenerConfig> listeners();
    
    /**
     * Get routing configuration.
     * @return routing configuration
     */
    Optional<Router> router();
    
    /**
     * Get protocol configurations.
     * @return protocol configurations
     */
    List<ProtocolConfig> protocols();
}

WebServerConfig Builder

Builder for creating WebServer configurations with fluent API.

/**
 * Builder for WebServer configuration.
 */
interface WebServerConfig.Builder extends io.helidon.common.Builder<Builder, WebServerConfig> {
    /**
     * Set server port.
     * @param port server port
     * @return updated builder
     */
    Builder port(int port);
    
    /**
     * Set bind address.
     * @param bindAddress bind address
     * @return updated builder
     */
    Builder bindAddress(String bindAddress);
    
    /**
     * Set socket backlog.
     * @param backlog backlog size
     * @return updated builder
     */
    Builder backlog(int backlog);
    
    /**
     * Set receive buffer size.
     * @param receiveBufferSize buffer size
     * @return updated builder
     */
    Builder receiveBufferSize(int receiveBufferSize);
    
    /**
     * Add socket option.
     * @param option socket option
     * @param value option value
     * @param <T> option type
     * @return updated builder
     */
    <T> Builder socketOption(SocketOption<T> option, T value);
    
    /**
     * Set TLS configuration.
     * @param tls TLS configuration
     * @return updated builder
     */
    Builder tls(Tls tls);
    
    /**
     * Set TLS configuration using builder.
     * @param tlsBuilder TLS builder consumer
     * @return updated builder
     */
    Builder tls(Consumer<Tls.Builder> tlsBuilder);
    
    /**
     * Set connection configuration.
     * @param connection connection configuration
     * @return updated builder
     */
    Builder connection(ConnectionConfig connection);
    
    /**
     * Set connection configuration using builder.
     * @param connectionBuilder connection builder consumer
     * @return updated builder
     */
    Builder connection(Consumer<ConnectionConfig.Builder> connectionBuilder);
    
    /**
     * Add named listener configuration.
     * @param name listener name
     * @param listener listener configuration
     * @return updated builder
     */
    Builder addListener(String name, ListenerConfig listener);
    
    /**
     * Add named listener using builder.
     * @param name listener name
     * @param listenerBuilder listener builder consumer
     * @return updated builder
     */
    Builder addListener(String name, Consumer<ListenerConfig.Builder> listenerBuilder);
    
    /**
     * Set router configuration.
     * @param router router configuration
     * @return updated builder
     */
    Builder router(Router router);
    
    /**
     * Set router using builder.
     * @param routerBuilder router builder consumer
     * @return updated builder
     */
    Builder router(Consumer<Router.Builder> routerBuilder);
    
    /**
     * Add routing configuration.
     * @param routing routing to add
     * @return updated builder
     */
    Builder routing(io.helidon.common.Builder<?, ? extends Routing> routing);
    
    /**
     * Add named routing configuration.
     * @param name routing name
     * @param routing routing to add
     * @return updated builder
     */
    Builder addNamedRouting(String name, io.helidon.common.Builder<?, ? extends Routing> routing);
    
    /**
     * Add protocol configuration.
     * @param protocol protocol configuration
     * @return updated builder
     */
    Builder addProtocol(ProtocolConfig protocol);
}

Usage Examples:

import io.helidon.webserver.WebServerConfig;
import io.helidon.common.tls.Tls;
import java.net.StandardSocketOptions;

// Basic server configuration
WebServerConfig basicConfig = WebServerConfig.builder()
    .port(8080)
    .bindAddress("0.0.0.0")
    .backlog(1024)
    .build();

// Advanced server configuration
WebServerConfig advancedConfig = WebServerConfig.builder()
    .port(8443)
    .bindAddress("localhost")
    .backlog(2048)
    .receiveBufferSize(8192)
    
    // Socket options
    .socketOption(StandardSocketOptions.SO_KEEPALIVE, true)
    .socketOption(StandardSocketOptions.SO_REUSEADDR, true)
    .socketOption(StandardSocketOptions.TCP_NODELAY, true)
    
    // TLS configuration
    .tls(tls -> tls
        .keystore(keystore -> keystore
            .keystore(Paths.get("keystore.p12"))
            .keystorePassphrase("password"))
        .truststore(truststore -> truststore
            .truststore(Paths.get("truststore.p12"))
            .truststorePassphrase("password")))
    
    // Connection configuration
    .connection(conn -> conn
        .connectTimeout(Duration.ofSeconds(10))
        .readTimeout(Duration.ofSeconds(30))
        .maxConcurrentRequests(100))
    
    // Routing configuration
    .routing(HttpRouting.builder()
        .get("/health", (req, res) -> res.send("OK"))
        .get("/api/*", (req, res) -> res.send("API")))
    
    .build();

// Multi-listener configuration
WebServerConfig multiListenerConfig = WebServerConfig.builder()
    .port(8080) // Default listener
    
    // Admin listener on different port
    .addListener("admin", listener -> listener
        .port(8081)
        .bindAddress("127.0.0.1"))
    
    // Secure listener with TLS
    .addListener("secure", listener -> listener
        .port(8443)
        .tls(tlsConfig))
    
    // Default routing
    .routing(HttpRouting.builder()
        .get("/", (req, res) -> res.send("Main")))
    
    // Admin routing
    .addNamedRouting("admin", HttpRouting.builder()
        .get("/health", (req, res) -> res.send("Healthy"))
        .get("/metrics", (req, res) -> res.send("Metrics")))
    
    // Secure routing
    .addNamedRouting("secure", HttpRouting.builder()
        .get("/secure", (req, res) -> res.send("Secure content")))
    
    .build();

ListenerConfig Interface

Configuration for individual server listeners with port and protocol settings.

/**
 * Configuration for server listeners.
 */
interface ListenerConfig extends Prototype.Api {
    /**
     * Create builder for listener configuration.
     * @return configuration builder
     */
    static Builder builder();
    
    /**
     * Get listener port.
     * @return port number
     */
    int port();
    
    /**
     * Get listener bind address.
     * @return bind address
     */
    String bindAddress();
    
    /**
     * Get listener backlog.
     * @return backlog size
     */
    int backlog();
    
    /**
     * Get TLS configuration for this listener.
     * @return TLS configuration if enabled
     */
    Optional<Tls> tls();
    
    /**
     * Get connection configuration for this listener.
     * @return connection configuration
     */
    ConnectionConfig connection();
    
    /**
     * Get protocol configurations for this listener.
     * @return protocol configurations
     */
    List<ProtocolConfig> protocols();
    
    /**
     * Get socket options for this listener.
     * @return socket options
     */
    Map<SocketOption<?>, Object> socketOptions();
}

ConnectionConfig Interface

Configuration for connection handling and timeouts.

/**
 * Configuration for connections.
 */
interface ConnectionConfig extends Prototype.Api {
    /**
     * Create builder for connection configuration.
     * @return configuration builder
     */
    static Builder builder();
    
    /**
     * Get connect timeout.
     * @return connect timeout duration
     */
    Duration connectTimeout();
    
    /**
     * Get read timeout.
     * @return read timeout duration
     */
    Duration readTimeout();
    
    /**
     * Get connection idle timeout.
     * @return idle timeout duration
     */
    Duration idleTimeout();
    
    /**
     * Get maximum concurrent requests per connection.
     * @return max concurrent requests
     */
    int maxConcurrentRequests();
    
    /**
     * Get initial buffer size for connections.
     * @return initial buffer size
     */
    int initialBufferSize();
    
    /**
     * Get maximum buffer size for connections.
     * @return maximum buffer size
     */
    int maxBufferSize();
    
    /**
     * Get connection backpressure buffer size.
     * @return backpressure buffer size
     */
    int backpressureBufferSize();
    
    /**
     * Check if connection pooling is enabled.
     * @return true if connection pooling enabled
     */
    boolean connectionPooling();
}

Usage Examples:

import io.helidon.webserver.ConnectionConfig;
import java.time.Duration;

// Basic connection configuration
ConnectionConfig basicConnection = ConnectionConfig.builder()
    .connectTimeout(Duration.ofSeconds(10))
    .readTimeout(Duration.ofSeconds(30))
    .idleTimeout(Duration.ofMinutes(5))
    .build();

// High-performance connection configuration
ConnectionConfig highPerfConnection = ConnectionConfig.builder()
    .connectTimeout(Duration.ofSeconds(5))
    .readTimeout(Duration.ofSeconds(60))
    .idleTimeout(Duration.ofMinutes(10))
    .maxConcurrentRequests(1000)
    .initialBufferSize(16384)
    .maxBufferSize(1048576) // 1MB
    .backpressureBufferSize(65536)
    .connectionPooling(true)
    .build();

// Use in server configuration
WebServerConfig serverConfig = WebServerConfig.builder()
    .port(8080)
    .connection(highPerfConnection)
    .build();

ErrorHandling Interface

Configuration for error handling behavior.

/**
 * Configuration for error handling.
 */
interface ErrorHandling extends Prototype.Api {
    /**
     * Create builder for error handling configuration.
     * @return configuration builder
     */
    static Builder builder();
    
    /**
     * Check if stack traces should be sent in error responses.
     * @return true if stack traces should be sent
     */
    boolean sendStackTrace();
    
    /**
     * Check if debugging information should be included.
     * @return true if debug info should be included
     */
    boolean debug();
    
    /**
     * Get custom error page mappings.
     * @return map of status codes to error page paths
     */
    Map<Integer, String> errorPages();
    
    /**
     * Get default error content type.
     * @return default content type for error responses
     */
    MediaType defaultErrorContentType();
}

Usage Examples:

import io.helidon.webserver.ErrorHandling;
import io.helidon.http.MediaType;

// Development error handling (includes stack traces)
ErrorHandling devErrorHandling = ErrorHandling.builder()
    .sendStackTrace(true)
    .debug(true)
    .defaultErrorContentType(MediaType.APPLICATION_JSON)
    .build();

// Production error handling (no stack traces)
ErrorHandling prodErrorHandling = ErrorHandling.builder()
    .sendStackTrace(false)
    .debug(false)
    .errorPages(Map.of(
        404, "/errors/404.html",
        500, "/errors/500.html"
    ))
    .defaultErrorContentType(MediaType.TEXT_HTML)
    .build();

Configuration Patterns

Environment-Based Configuration

import io.helidon.config.Config;

// Load configuration from environment and config files
Config config = Config.create();

WebServerConfig serverConfig = WebServerConfig.builder()
    .port(config.get("server.port").asInt().orElse(8080))
    .bindAddress(config.get("server.host").asString().orElse("0.0.0.0"))
    .connection(conn -> conn
        .connectTimeout(config.get("server.connect-timeout")
                             .as(Duration.class)
                             .orElse(Duration.ofSeconds(10)))
        .readTimeout(config.get("server.read-timeout")
                           .as(Duration.class)
                           .orElse(Duration.ofSeconds(30)))
        .maxConcurrentRequests(config.get("server.max-concurrent-requests")
                                    .asInt()
                                    .orElse(100)))
    .build();

Profile-Based Configuration

public class ServerConfigFactory {
    
    public static WebServerConfig createDevelopmentConfig() {
        return WebServerConfig.builder()
            .port(8080)
            .bindAddress("localhost")
            .connection(conn -> conn
                .connectTimeout(Duration.ofSeconds(30))
                .readTimeout(Duration.ofMinutes(5))
                .maxConcurrentRequests(10))
            .build();
    }
    
    public static WebServerConfig createProductionConfig() {
        return WebServerConfig.builder()
            .port(80)
            .bindAddress("0.0.0.0")
            .backlog(8192)
            .receiveBufferSize(32768)
            .connection(conn -> conn
                .connectTimeout(Duration.ofSeconds(5))
                .readTimeout(Duration.ofSeconds(30))
                .idleTimeout(Duration.ofMinutes(2))
                .maxConcurrentRequests(1000)
                .initialBufferSize(16384)
                .maxBufferSize(2097152)
                .connectionPooling(true))
            .tls(tls -> tls
                .keystore(keystore -> keystore
                    .keystore(Paths.get("/etc/ssl/server.p12"))
                    .keystorePassphrase(System.getenv("KEYSTORE_PASSWORD")))
                .protocols("TLSv1.3", "TLSv1.2")
                .cipherSuites("TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256"))
            .build();
    }
}

Dynamic Configuration

public class DynamicServerConfig {
    private final AtomicReference<WebServerConfig> currentConfig;
    private final ConfigWatcher configWatcher;
    
    public DynamicServerConfig(Config initialConfig) {
        this.currentConfig = new AtomicReference<>(buildConfig(initialConfig));
        this.configWatcher = ConfigWatcher.create(initialConfig);
        
        configWatcher.onChange(this::updateConfiguration);
    }
    
    private void updateConfiguration(Config newConfig) {
        WebServerConfig newServerConfig = buildConfig(newConfig);
        WebServerConfig oldConfig = currentConfig.getAndSet(newServerConfig);
        
        // Apply configuration changes
        applyConfigurationChanges(oldConfig, newServerConfig);
    }
    
    private WebServerConfig buildConfig(Config config) {
        return WebServerConfig.builder()
            .port(config.get("server.port").asInt().orElse(8080))
            .connection(conn -> conn
                .connectTimeout(config.get("server.timeouts.connect")
                                     .as(Duration.class)
                                     .orElse(Duration.ofSeconds(10)))
                .readTimeout(config.get("server.timeouts.read")
                                   .as(Duration.class)
                                   .orElse(Duration.ofSeconds(30)))
                .maxConcurrentRequests(config.get("server.limits.concurrent-requests")
                                            .asInt()
                                            .orElse(100)))
            .build();
    }
}

Configuration Validation

public class ConfigurationValidator {
    
    public static void validateServerConfig(WebServerConfig config) {
        // Validate port range
        if (config.port() < 1 || config.port() > 65535) {
            throw new IllegalArgumentException("Port must be between 1 and 65535");
        }
        
        // Validate connection settings
        ConnectionConfig conn = config.connection();
        if (conn.connectTimeout().isNegative()) {
            throw new IllegalArgumentException("Connect timeout cannot be negative");
        }
        
        if (conn.maxConcurrentRequests() < 1) {
            throw new IllegalArgumentException("Max concurrent requests must be at least 1");
        }
        
        // Validate buffer sizes
        if (conn.initialBufferSize() > conn.maxBufferSize()) {
            throw new IllegalArgumentException("Initial buffer size cannot exceed max buffer size");
        }
        
        // Validate listeners
        config.listeners().forEach((name, listener) -> {
            if (listener.port() == config.port() && 
                listener.bindAddress().equals(config.bindAddress())) {
                throw new IllegalArgumentException(
                    "Listener '" + name + "' conflicts with default listener");
            }
        });
    }
    
    public static WebServerConfig createValidatedConfig(
            Consumer<WebServerConfig.Builder> configurer) {
        WebServerConfig.Builder builder = WebServerConfig.builder();
        configurer.accept(builder);
        WebServerConfig config = builder.build();
        
        validateServerConfig(config);
        return config;
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-io-helidon-webserver--helidon-webserver

docs

configuration.md

http-routing.md

http-services.md

http1-protocol.md

index.md

request-response.md

server-management.md

spi.md

tile.json