Interface LifecycleObserver

public interface LifecycleObserver

Read-only hook methods for observing system and request lifecycle events.

Note: some of these methods are "fail-fast" - exceptions thrown will bubble out and stop execution - and for others, Soklet will catch exceptions and surface separately via didReceiveLogEvent(LogEvent).

A standard threadsafe implementation can be acquired via the defaultInstance() factory method.

Full documentation is available at https://www.soklet.com/docs/request-lifecycle.

Author:

Mark Allen

Method Summary

Modifier and Type	Method	Description
static @NonNull LifecycleObserver	defaultInstance()	Acquires a threadsafe LifecycleObserver instance with sensible defaults.
default void	didAcceptConnection(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress)	Called after a server accepts a new TCP connection.
default void	didAcceptRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget)	Called after a request is accepted for application-level handling.
default void	didCreateMcpSession(@NonNull Request request, @NonNull Class<? extends McpEndpoint> endpointClass, @NonNull String sessionId)	Called after an MCP session is durably created.
default void	didEstablishMcpSseStream(@NonNull Request request, @NonNull Class<? extends McpEndpoint> endpointClass, @NonNull String sessionId)	Called after an MCP GET stream is established.
default void	didEstablishSseConnection(@NonNull SseConnection sseConnection)	Called after an SSE connection is established.
default void	didFailToAcceptConnection(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @NonNull ConnectionRejectionReason reason, @Nullable Throwable throwable)	Called after a server fails to accept a new TCP connection.
default void	didFailToAcceptRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget, @NonNull RequestRejectionReason reason, @Nullable Throwable throwable)	Called when a request fails to be accepted before application-level handling begins.
default void	didFailToEstablishSseConnection(@NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull SseConnection.HandshakeFailureReason reason, @Nullable Throwable throwable)	Called if an SSE connection fails to establish.
default void	didFailToReadRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget, @NonNull RequestReadFailureReason reason, @Nullable Throwable throwable)	Called when a request could not be read or parsed into a valid Request.
default void	didFailToStartHttpServer(@NonNull HttpServer httpServer, @NonNull Throwable throwable)	Called after a HttpServer instance was asked to start, but failed due to an exception.
default void	didFailToStartMcpServer(@NonNull McpServer mcpServer, @NonNull Throwable throwable)	Called after an McpServer instance was asked to start, but failed due to an exception.
default void	didFailToStartSoklet(@NonNull Soklet soklet, @NonNull Throwable throwable)	Called after a Soklet instance was asked to start, but failed due to an exception.
default void	didFailToStartSseServer(@NonNull SseServer sseServer, @NonNull Throwable throwable)	Called after a SseServer instance was asked to start, but failed due to an exception.
default void	didFailToStopHttpServer(@NonNull HttpServer httpServer, @NonNull Throwable throwable)	Called after a HttpServer instance was asked to stop, but failed due to an exception.
default void	didFailToStopMcpServer(@NonNull McpServer mcpServer, @NonNull Throwable throwable)	Called after an McpServer instance was asked to stop, but failed due to an exception.
default void	didFailToStopSoklet(@NonNull Soklet soklet, @NonNull Throwable throwable)	Called after a Soklet instance was asked to stop, but failed due to an exception.
default void	didFailToStopSseServer(@NonNull SseServer sseServer, @NonNull Throwable throwable)	Called after a SseServer instance was asked to stop, but failed due to an exception.
default void	didFailToWriteResponse(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse, @NonNull Duration responseWriteDuration, @NonNull Throwable throwable)	Called after response data fails to write.
default void	didFailToWriteSseComment(@NonNull SseConnection sseConnection, @NonNull SseComment sseComment, @NonNull Duration writeDuration, @NonNull Throwable throwable)	Called after an SSE comment fails to write.
default void	didFailToWriteSseEvent(@NonNull SseConnection sseConnection, @NonNull SseEvent sseEvent, @NonNull Duration writeDuration, @NonNull Throwable throwable)	Called after an SSE event fails to write.
default void	didFinishMcpRequestHandling(@NonNull Request request, @NonNull Class<? extends McpEndpoint> endpointClass, @Nullable String sessionId, @NonNull String jsonRpcMethod, @Nullable McpJsonRpcRequestId jsonRpcRequestId, @NonNull McpRequestOutcome requestOutcome, @Nullable McpJsonRpcError jsonRpcError, @NonNull Duration duration, @NonNull List<@NonNull Throwable> throwables)	Called after MCP JSON-RPC request handling finishes.
default void	didFinishRequestHandling(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse, @NonNull Duration duration, @NonNull List<@NonNull Throwable> throwables)	Called after a request finishes processing.
default void	didReadRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget)	Called when a request was successfully read or parsed into a valid Request.
default void	didReceiveLogEvent(@NonNull LogEvent logEvent)	Called when Soklet emits a log event.
default void	didStartHttpServer(@NonNull HttpServer httpServer)	Called after the server starts.
default void	didStartMcpRequestHandling(@NonNull Request request, @NonNull Class<? extends McpEndpoint> endpointClass, @Nullable String sessionId, @NonNull String jsonRpcMethod, @Nullable McpJsonRpcRequestId jsonRpcRequestId)	Called after a valid MCP JSON-RPC request begins handling.
default void	didStartMcpServer(@NonNull McpServer mcpServer)	Called after the MCP server starts.
default void	didStartRequestHandling(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod)	Called as soon as a request is received and a Resource Method has been resolved to handle it.
default void	didStartSoklet(@NonNull Soklet soklet)	Called after a Soklet instance starts.
default void	didStartSseServer(@NonNull SseServer sseServer)	Called after the SSE server starts.
default void	didStopHttpServer(@NonNull HttpServer httpServer)	Called after the server stops.
default void	didStopMcpServer(@NonNull McpServer mcpServer)	Called after the MCP server stops.
default void	didStopSoklet(@NonNull Soklet soklet)	Called after a Soklet instance stops.
default void	didStopSseServer(@NonNull SseServer sseServer)	Called after the SSE server stops.
default void	didTerminateMcpSession(@NonNull Class<? extends McpEndpoint> endpointClass, @NonNull String sessionId, @NonNull Duration sessionDuration, @NonNull McpSessionTerminationReason terminationReason, @Nullable Throwable throwable)	Called after an MCP session is terminated.
default void	didTerminateMcpSseStream(@NonNull Request request, @NonNull Class<? extends McpEndpoint> endpointClass, @NonNull String sessionId, @NonNull Duration connectionDuration, @NonNull McpStreamTerminationReason terminationReason, @Nullable Throwable throwable)	Called after an MCP GET stream is terminated.
default void	didTerminateSseConnection(@NonNull SseConnection sseConnection, @NonNull Duration connectionDuration, @NonNull SseConnection.TerminationReason terminationReason, @Nullable Throwable throwable)	Called after an SSE connection is terminated.
default void	didWriteResponse(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse, @NonNull Duration responseWriteDuration)	Called after response data is written.
default void	didWriteSseComment(@NonNull SseConnection sseConnection, @NonNull SseComment sseComment, @NonNull Duration writeDuration)	Called after an SSE comment is written.
default void	didWriteSseEvent(@NonNull SseConnection sseConnection, @NonNull SseEvent sseEvent, @NonNull Duration writeDuration)	Called after an SSE event is written.
default void	willAcceptConnection(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress)	Called when a server is about to accept a new TCP connection.
default void	willAcceptRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget)	Called when a request is about to be accepted for application-level handling.
default void	willEstablishSseConnection(@NonNull Request request, @Nullable ResourceMethod resourceMethod)	Called before an SSE connection is established.
default void	willReadRequest(@NonNull ServerType serverType, @Nullable InetSocketAddress remoteAddress, @Nullable String requestTarget)	Called when Soklet is about to read or parse a request into a valid Request.
default void	willStartHttpServer(@NonNull HttpServer httpServer)	Called before the server starts.
default void	willStartMcpServer(@NonNull McpServer mcpServer)	Called before the MCP server starts.
default void	willStartSoklet(@NonNull Soklet soklet)	Called before a Soklet instance starts.
default void	willStartSseServer(@NonNull SseServer sseServer)	Called before the SSE server starts.
default void	willStopHttpServer(@NonNull HttpServer httpServer)	Called before the server stops.
default void	willStopMcpServer(@NonNull McpServer mcpServer)	Called before the MCP server stops.
default void	willStopSoklet(@NonNull Soklet soklet)	Called before a Soklet instance stops.
default void	willStopSseServer(@NonNull SseServer sseServer)	Called before the SSE server stops.
default void	willTerminateMcpSseStream(@NonNull Request request, @NonNull Class<? extends McpEndpoint> endpointClass, @NonNull String sessionId, @NonNull McpStreamTerminationReason terminationReason, @Nullable Throwable throwable)	Called before an MCP GET stream is terminated.
default void	willTerminateSseConnection(@NonNull SseConnection sseConnection, @NonNull SseConnection.TerminationReason terminationReason, @Nullable Throwable throwable)	Called before an SSE connection is terminated.
default void	willWriteResponse(@NonNull ServerType serverType, @NonNull Request request, @Nullable ResourceMethod resourceMethod, @NonNull MarshaledResponse marshaledResponse)	Called before response data is written.
default void	willWriteSseComment(@NonNull SseConnection sseConnection, @NonNull SseComment sseComment)	Called before an SSE comment is written.
default void	willWriteSseEvent(@NonNull SseConnection sseConnection, @NonNull SseEvent sseEvent)	Called before an SSE event is written.

Method Details

willStartSoklet

default void willStartSoklet(@NonNull Soklet soklet)

Called before a Soklet instance starts.

didStartSoklet

default void didStartSoklet(@NonNull Soklet soklet)

Called after a Soklet instance starts.

didFailToStartSoklet

default void didFailToStartSoklet(@NonNull Soklet soklet,
 @NonNull Throwable throwable)

Called after a Soklet instance was asked to start, but failed due to an exception.

willStopSoklet

default void willStopSoklet(@NonNull Soklet soklet)

Called before a Soklet instance stops.

didStopSoklet

default void didStopSoklet(@NonNull Soklet soklet)

Called after a Soklet instance stops.

didFailToStopSoklet

default void didFailToStopSoklet(@NonNull Soklet soklet,
 @NonNull Throwable throwable)

Called after a Soklet instance was asked to stop, but failed due to an exception.

willStartHttpServer

default void willStartHttpServer(@NonNull HttpServer httpServer)

Called before the server starts.

didStartHttpServer

default void didStartHttpServer(@NonNull HttpServer httpServer)

Called after the server starts.

didFailToStartHttpServer

default void didFailToStartHttpServer(@NonNull HttpServer httpServer,
 @NonNull Throwable throwable)

Called after a HttpServer instance was asked to start, but failed due to an exception.

willStopHttpServer

default void willStopHttpServer(@NonNull HttpServer httpServer)

Called before the server stops.

didStopHttpServer

default void didStopHttpServer(@NonNull HttpServer httpServer)

Called after the server stops.

didFailToStopHttpServer

default void didFailToStopHttpServer(@NonNull HttpServer httpServer,
 @NonNull Throwable throwable)

Called after a HttpServer instance was asked to stop, but failed due to an exception.

willAcceptConnection

default void willAcceptConnection(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress)

Called when a server is about to accept a new TCP connection.

Parameters:

serverType - the server type that is accepting the connection

remoteAddress - the best-effort remote address, or null if unavailable

didAcceptConnection

default void didAcceptConnection(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress)

Called after a server accepts a new TCP connection.

Parameters:

serverType - the server type that accepted the connection

remoteAddress - the best-effort remote address, or null if unavailable

didFailToAcceptConnection

default void didFailToAcceptConnection(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @NonNull ConnectionRejectionReason reason,
 @Nullable Throwable throwable)

Called after a server fails to accept a new TCP connection.

Parameters:

serverType - the server type that failed to accept the connection

remoteAddress - the best-effort remote address, or null if unavailable

reason - the failure reason

throwable - an optional underlying cause, or null if not applicable

willAcceptRequest

default void willAcceptRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget)

Called when a request is about to be accepted for application-level handling.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

didAcceptRequest

default void didAcceptRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget)

Called after a request is accepted for application-level handling.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

didFailToAcceptRequest

default void didFailToAcceptRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget,
 @NonNull RequestRejectionReason reason,
 @Nullable Throwable throwable)

Called when a request fails to be accepted before application-level handling begins.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

reason - the rejection reason

throwable - an optional underlying cause, or null if not applicable

willReadRequest

default void willReadRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget)

Called when Soklet is about to read or parse a request into a valid Request.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

didReadRequest

default void didReadRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget)

Called when a request was successfully read or parsed into a valid Request.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

didFailToReadRequest

default void didFailToReadRequest(@NonNull ServerType serverType,
 @Nullable InetSocketAddress remoteAddress,
 @Nullable String requestTarget,
 @NonNull RequestReadFailureReason reason,
 @Nullable Throwable throwable)

Called when a request could not be read or parsed into a valid Request.

Parameters:

serverType - the server type that received the request

remoteAddress - the best-effort remote address, or null if unavailable

requestTarget - the raw request target (path + query) if known, or null if unavailable

reason - the failure reason

throwable - an optional underlying cause, or null if not applicable

didStartRequestHandling

default void didStartRequestHandling(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod)

Called as soon as a request is received and a Resource Method has been resolved to handle it.

Parameters:

serverType - the server type that received the request

didFinishRequestHandling

default void didFinishRequestHandling(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse,
 @NonNull Duration duration,
 @NonNull List<@NonNull Throwable> throwables)

Called after a request finishes processing.

willWriteResponse

default void willWriteResponse(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse)

Called before response data is written.

didWriteResponse

default void didWriteResponse(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse,
 @NonNull Duration responseWriteDuration)

Called after response data is written.

didFailToWriteResponse

default void didFailToWriteResponse(@NonNull ServerType serverType,
 @NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull MarshaledResponse marshaledResponse,
 @NonNull Duration responseWriteDuration,
 @NonNull Throwable throwable)

Called after response data fails to write.

willStartMcpServer

default void willStartMcpServer(@NonNull McpServer mcpServer)

Called before the MCP server starts.

didStartMcpServer

default void didStartMcpServer(@NonNull McpServer mcpServer)

Called after the MCP server starts.

didFailToStartMcpServer

default void didFailToStartMcpServer(@NonNull McpServer mcpServer,
 @NonNull Throwable throwable)

Called after an McpServer instance was asked to start, but failed due to an exception.

willStopMcpServer

default void willStopMcpServer(@NonNull McpServer mcpServer)

Called before the MCP server stops.

didStopMcpServer

default void didStopMcpServer(@NonNull McpServer mcpServer)

Called after the MCP server stops.

didFailToStopMcpServer

default void didFailToStopMcpServer(@NonNull McpServer mcpServer,
 @NonNull Throwable throwable)

Called after an McpServer instance was asked to stop, but failed due to an exception.

didCreateMcpSession

default void didCreateMcpSession(@NonNull Request request,
 @NonNull Class<? extends McpEndpoint> endpointClass,
 @NonNull String sessionId)

Called after an MCP session is durably created.

didTerminateMcpSession

default void didTerminateMcpSession(@NonNull Class<? extends McpEndpoint> endpointClass,
 @NonNull String sessionId,
 @NonNull Duration sessionDuration,
 @NonNull McpSessionTerminationReason terminationReason,
 @Nullable Throwable throwable)

Called after an MCP session is terminated.

didStartMcpRequestHandling

default void didStartMcpRequestHandling(@NonNull Request request,
 @NonNull Class<? extends McpEndpoint> endpointClass,
 @Nullable String sessionId,
 @NonNull String jsonRpcMethod,
 @Nullable McpJsonRpcRequestId jsonRpcRequestId)

Called after a valid MCP JSON-RPC request begins handling.

didFinishMcpRequestHandling

default void didFinishMcpRequestHandling(@NonNull Request request,
 @NonNull Class<? extends McpEndpoint> endpointClass,
 @Nullable String sessionId,
 @NonNull String jsonRpcMethod,
 @Nullable McpJsonRpcRequestId jsonRpcRequestId,
 @NonNull McpRequestOutcome requestOutcome,
 @Nullable McpJsonRpcError jsonRpcError,
 @NonNull Duration duration,
 @NonNull List<@NonNull Throwable> throwables)

Called after MCP JSON-RPC request handling finishes.

didEstablishMcpSseStream

default void didEstablishMcpSseStream(@NonNull Request request,
 @NonNull Class<? extends McpEndpoint> endpointClass,
 @NonNull String sessionId)

Called after an MCP GET stream is established.

willTerminateMcpSseStream

default void willTerminateMcpSseStream(@NonNull Request request,
 @NonNull Class<? extends McpEndpoint> endpointClass,
 @NonNull String sessionId,
 @NonNull McpStreamTerminationReason terminationReason,
 @Nullable Throwable throwable)

Called before an MCP GET stream is terminated.

didTerminateMcpSseStream

default void didTerminateMcpSseStream(@NonNull Request request,
 @NonNull Class<? extends McpEndpoint> endpointClass,
 @NonNull String sessionId,
 @NonNull Duration connectionDuration,
 @NonNull McpStreamTerminationReason terminationReason,
 @Nullable Throwable throwable)

Called after an MCP GET stream is terminated.

willStartSseServer

default void willStartSseServer(@NonNull SseServer sseServer)

Called before the SSE server starts.

didStartSseServer

default void didStartSseServer(@NonNull SseServer sseServer)

Called after the SSE server starts.

didFailToStartSseServer

default void didFailToStartSseServer(@NonNull SseServer sseServer,
 @NonNull Throwable throwable)

Called after a SseServer instance was asked to start, but failed due to an exception.

willStopSseServer

default void willStopSseServer(@NonNull SseServer sseServer)

Called before the SSE server stops.

didStopSseServer

default void didStopSseServer(@NonNull SseServer sseServer)

Called after the SSE server stops.

didFailToStopSseServer

default void didFailToStopSseServer(@NonNull SseServer sseServer,
 @NonNull Throwable throwable)

Called after a SseServer instance was asked to stop, but failed due to an exception.

willEstablishSseConnection

default void willEstablishSseConnection(@NonNull Request request,
 @Nullable ResourceMethod resourceMethod)

Called before an SSE connection is established.

didEstablishSseConnection

default void didEstablishSseConnection(@NonNull SseConnection sseConnection)

Called after an SSE connection is established.

didFailToEstablishSseConnection

default void didFailToEstablishSseConnection(@NonNull Request request,
 @Nullable ResourceMethod resourceMethod,
 @NonNull SseConnection.HandshakeFailureReason reason,
 @Nullable Throwable throwable)

Called if an SSE connection fails to establish.

Parameters:

reason - the handshake failure reason

throwable - an optional underlying cause, or null if not applicable

willTerminateSseConnection

default void willTerminateSseConnection(@NonNull SseConnection sseConnection,
 @NonNull SseConnection.TerminationReason terminationReason,
 @Nullable Throwable throwable)

Called before an SSE connection is terminated.

didTerminateSseConnection

default void didTerminateSseConnection(@NonNull SseConnection sseConnection,
 @NonNull Duration connectionDuration,
 @NonNull SseConnection.TerminationReason terminationReason,
 @Nullable Throwable throwable)

Called after an SSE connection is terminated.

willWriteSseEvent

default void willWriteSseEvent(@NonNull SseConnection sseConnection,
 @NonNull SseEvent sseEvent)

Called before an SSE event is written.

didWriteSseEvent

default void didWriteSseEvent(@NonNull SseConnection sseConnection,
 @NonNull SseEvent sseEvent,
 @NonNull Duration writeDuration)

Called after an SSE event is written.

didFailToWriteSseEvent

default void didFailToWriteSseEvent(@NonNull SseConnection sseConnection,
 @NonNull SseEvent sseEvent,
 @NonNull Duration writeDuration,
 @NonNull Throwable throwable)

Called after an SSE event fails to write.

willWriteSseComment

default void willWriteSseComment(@NonNull SseConnection sseConnection,
 @NonNull SseComment sseComment)

Called before an SSE comment is written.

didWriteSseComment

default void didWriteSseComment(@NonNull SseConnection sseConnection,
 @NonNull SseComment sseComment,
 @NonNull Duration writeDuration)

Called after an SSE comment is written.

didFailToWriteSseComment

default void didFailToWriteSseComment(@NonNull SseConnection sseConnection,
 @NonNull SseComment sseComment,
 @NonNull Duration writeDuration,
 @NonNull Throwable throwable)

Called after an SSE comment fails to write.

didReceiveLogEvent

default void didReceiveLogEvent(@NonNull LogEvent logEvent)

Called when Soklet emits a log event.

defaultInstance

static @NonNull LifecycleObserver defaultInstance()

Acquires a threadsafe LifecycleObserver instance with sensible defaults.

Returns:

a LifecycleObserver with default settings