Server Management

/**
 * Server that opens server sockets and handles requests through routing.
 */
interface WebServer extends RuntimeType.Api<WebServerConfig> {
    /**
     * Create a new web server from its configuration.
     * @param serverConfig configuration
     * @return a new web server
     */
    static WebServer create(WebServerConfig serverConfig);
    
    /**
     * Create a new webserver customizing its configuration.
     * @param builderConsumer consumer of configuration builder
     * @return a new web server
     */
    static WebServer create(Consumer<WebServerConfig.Builder> builderConsumer);
    
    /**
     * A new builder to set up server.
     * @return builder
     */
    static WebServerConfig.Builder builder();
    
    /**
     * Starts the server. Has no effect if server is running.
     * @return a started server
     * @throws IllegalStateException when startup fails
     */
    WebServer start();
    
    /**
     * Attempt to gracefully shutdown the server.
     * @return a stopped server
     */
    WebServer stop();
    
    /**
     * Returns true if the server is currently running.
     * @return true if server is running
     */
    boolean isRunning();
    
    /**
     * Returns a port number the default server socket is bound to.
     * @return a listen port; or -1 if unknown or not active
     */
    default int port();
    
    /**
     * Returns a port number an additional named server socket is bound to.
     * @param socketName the name of an additional named server socket
     * @return a listen port; or -1 if socket name is unknown or not active
     */
    int port(String socketName);
    
    /**
     * Returns true if TLS is configured for the default socket.
     * @return whether TLS is enabled for the default socket
     */
    default boolean hasTls();
    
    /**
     * Returns true if TLS is configured for the named socket.
     * @param socketName the name of a socket
     * @return whether TLS is enabled for the socket
     */
    boolean hasTls(String socketName);
    
    /**
     * Context associated with the WebServer, used as a parent for listener contexts.
     * @return a server context
     */
    Context context();
    
    /**
     * Reload TLS keystore and truststore configuration for the default socket.
     * @param tls new TLS configuration
     */
    default void reloadTls(Tls tls);
    
    /**
     * Reload TLS keystore and truststore configuration for the named socket.
     * @param socketName socket name to reload TLS configuration on
     * @param tls new TLS configuration
     */
    void reloadTls(String socketName, Tls tls);
}

/**
 * The default server socket configuration name.
 * Value: "@default"
 */
String DEFAULT_SOCKET_NAME = "@default";

import io.helidon.webserver.WebServer;
import io.helidon.webserver.http.HttpRouting;

// Create server with builder pattern
WebServer server = WebServer.builder()
    .port(8080)
    .routing(HttpRouting.builder()
        .get("/health", (req, res) -> res.send("OK"))
        .build())
    .build()
    .start();

// Create server with configuration consumer
WebServer server2 = WebServer.create(config -> 
    config.port(8081)
          .addNamedRouting("admin", HttpRouting.builder()
              .get("/metrics", (req, res) -> res.send("metrics"))
              .build())
);

// Server lifecycle management
if (!server.isRunning()) {
    server.start();
}

int port = server.port(); // Get default port
int adminPort = server.port("admin"); // Get named socket port

boolean tlsEnabled = server.hasTls(); // Check TLS status

// Graceful shutdown
server.stop();

/**
 * Router for server. Contains routings of various types.
 */
interface Router {
    /**
     * Builder for router.
     * @return a new builder
     */
    static Builder builder();
    
    /**
     * Empty router.
     * @return new empty router
     */
    static Router empty();
    
    /**
     * Get routing of a specific type.
     * @param routingType type of the routing
     * @param defaultValue default value to use if routing not defined
     * @param <T> type of routing
     * @return routing defined or default value if not found
     */
    <T extends Routing> T routing(Class<T> routingType, T defaultValue);
    
    /**
     * This is called after server closes ports.
     */
    void afterStop();
    
    /**
     * This is called before server opens ports.
     */
    void beforeStart();
    
    /**
     * This is called after the server's listeners have successfully started.
     * @param webServer the WebServer that has successfully started
     */
    default void afterStart(WebServer webServer);
    
    /**
     * List of all configured routings.
     * @return all routings
     */
    List<? extends Routing> routings();
}

interface Router.Builder extends RouterBuilder<Builder>, io.helidon.common.Builder<Builder, Router> {
}

interface Router.RouterBuilder<B extends RouterBuilder<B>> {
    /**
     * Add a new routing to this router.
     * @param routing routing to add, such as HttpRouting
     * @return updated builder
     */
    B addRouting(io.helidon.common.Builder<?, ? extends Routing> routing);
    
    /**
     * List of all routing builders registered with this router builder.
     * @return routing builder list
     */
    List<io.helidon.common.Builder<?, ? extends Routing>> routings();
}

import io.helidon.webserver.Router;
import io.helidon.webserver.http.HttpRouting;

// Create router with multiple routing types
Router router = Router.builder()
    .addRouting(HttpRouting.builder()
        .get("/api/*", (req, res) -> res.send("API"))
        .build())
    // Add other protocol routings here
    .build();

// Use router in server
WebServer server = WebServer.builder()
    .router(router)
    .build();

/**
 * Interface for server listeners that handle connections.
 */
interface ServerListener {
    // Server listener methods
}

/**
 * Context for a connection to the server.
 */
interface ConnectionContext {
    // Connection context methods
}

/**
 * Context for a server listener.
 */
interface ListenerContext {
    // Listener context methods
}

/**
 * Lifecycle management for server components.
 */
interface ServerLifecycle {
    // Lifecycle methods
}

/**
 * Handler for server connections.
 */
interface ConnectionHandler {
    // Connection handler methods
}

/**
 * Utility for managing protocol configurations.
 */
class ProtocolConfigs {
    // Protocol configuration utilities
}

/**
 * Providers for server connections.
 */
class ConnectionProviders {
    // Connection provider utilities
}

/**
 * Executor implementation using virtual threads.
 */
class ThreadPerTaskExecutor {
    // Virtual thread executor implementation
}

/**
 * Factory for creating executors.
 */
class ExecutorsFactory {
    // Executor factory methods
}

/**
 * Exception to close a connection.
 */
class CloseConnectionException extends RuntimeException {
    public CloseConnectionException();
    public CloseConnectionException(String message);
    public CloseConnectionException(String message, Throwable cause);
}

/**
 * Exception related to server connections.
 */
class ServerConnectionException extends RuntimeException {
    public ServerConnectionException();
    public ServerConnectionException(String message);
    public ServerConnectionException(String message, Throwable cause);
}

/**
 * Support for key performance indicators.
 */
class KeyPerformanceIndicatorSupport {
    // KPI support methods
}

/**
 * Data for proxy protocol handling.
 */
class ProxyProtocolData {
    // Proxy protocol data handling
}

/**
 * Handler for proxy protocol.
 */
class ProxyProtocolHandler {
    // Proxy protocol handling methods
}

WebServer server = WebServer.builder()
    .port(8080) // Default socket
    .addNamedSocket("admin", SocketConfig.builder()
        .port(8081)
        .tls(tlsConfig)
        .build())
    .routing(HttpRouting.builder()
        .get("/", (req, res) -> res.send("Main"))
        .build())
    .addNamedRouting("admin", HttpRouting.builder()
        .get("/health", (req, res) -> res.send("Healthy"))
        .build())
    .build();

server.start();

// Access different ports
int mainPort = server.port(); // 8080
int adminPort = server.port("admin"); // 8081

import io.helidon.common.tls.Tls;

// Server with TLS
Tls tlsConfig = Tls.builder()
    .keystore(keystoreConfig)
    .truststore(truststoreConfig)
    .build();

WebServer server = WebServer.builder()
    .port(8443)
    .tls(tlsConfig)
    .routing(routing)
    .build()
    .start();

// Runtime TLS reload
Tls newTlsConfig = Tls.builder()
    .keystore(updatedKeystoreConfig)
    .build();

server.reloadTls(newTlsConfig); // Reload default socket TLS
server.reloadTls("admin", newTlsConfig); // Reload named socket TLS

// Access server context
Context serverContext = server.context();

// Custom lifecycle handling
Router customRouter = Router.builder()
    .addRouting(httpRouting)
    .build();

// Lifecycle callbacks are automatically called
WebServer server = WebServer.builder()
    .router(customRouter)
    .build();

server.start(); // Calls beforeStart(), then afterStart()
server.stop();  // Calls afterStop()