Soklet Logo

Core Concepts

Production Readiness

Soklet is designed to be a small HTTP/1.1 application server that you run behind production edge infrastructure. It owns request routing, response writing, streaming, SSE, MCP transport, lifecycle hooks, and metrics. It intentionally does not own every platform concern.

Deployment Boundary

Run Soklet behind a load balancer, ingress, or reverse proxy that handles internet-facing transport policy:

  • Terminate TLS at the edge
  • Speak HTTP/2 or HTTP/3 to clients if you need those protocols
  • Forward HTTP/1.1 to Soklet
  • Enforce coarse connection, IP, WAF, and rate-limit policy before requests reach the JVM
  • Validate the public Host authority, and strip or overwrite forwarded metadata at the trusted edge before using effective-origin or effective-client-IP resolution

Soklet does not provide in-process TLS termination, HTTP/2, HTTP/3, or WebSockets. For server push, use Server-Sent Events. Modern MCP uses stateless POST requests; request-scoped SSE is negotiated on that response when an operation streams progress or subscription events. With HTTP transport admission, explicitly enabled 2025 sessions can also use leased GET notification streams and DELETE to close a session. See MCP for the transport contract.

For browser-facing SSE, prefer an edge that speaks HTTP/2 or HTTP/3 to clients even though it forwards HTTP/1.1 to Soklet. Browsers enforce low per-origin connection limits for HTTP/1.x, and long-lived SSE streams can consume those slots. HTTP/2 and HTTP/3 multiplex many browser-side streams over fewer client-to-edge connections, which avoids SSE starving ordinary page/API traffic while keeping Soklet's backend protocol simple.

If Soklet is directly reachable by untrusted clients, configure origin and forwarded-header handling defensively. Use TrustPolicy.TRUST_NONE unless the forwarding proxy is under your control, and use CORS allowlists rather than permissive origin reflection. For proxied client IPs, prefer EffectiveClientIpResolver with TrustPolicy.TRUST_PROXY_ALLOWLIST so client-supplied X-Forwarded-For values are only trusted through known proxy hops.

An effective origin describes the request; it is not a trusted application URL. TRUST_NONE excludes forwarded metadata, but an absolute-form request target still supplies a client-controlled scheme and authority. Construct password-reset links, OAuth callbacks, and other security-sensitive URLs from a configured canonical public base URL or an explicitly validated allowlist, rather than relying on resolve().orElse(configuredBaseUrl).

Forwarded Headers At The Edge

A proxy allowlist checks whether the physical socket peer is trusted; it does not validate the contents of headers that peer forwards. At the trusted edge, strip or overwrite all nine forwarded headers Soklet reads: Forwarded, X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Protocol, X-Url-Scheme, Front-End-Https, X-Forwarded-Ssl, X-Forwarded-Host, and X-Forwarded-Port. Soklet prefers usable Forwarded values, then fills missing scheme, host, or port fields from the other headers. Sanitizing only the family your proxy generates can leave client-supplied values effective.

Also validate the public Host against the application's accepted hostnames at the edge; use MCP's allowedHosts for its listener. A syntactically valid hostname is not necessarily an authorized hostname. Keep Origin for browser/CORS checks. It is an optional effective-origin fallback, disabled by default under TRUST_PROXY_ALLOWLIST; leave that fallback disabled for these proxy configurations.

These examples assume a single internet-facing edge that terminates TLS itself and forwards directly to a loopback Soklet HTTP listener. Reject requests for unrecognized public hostnames in the surrounding virtual-host configuration. Configure Soklet's proxy allowlist for the actual socket peer, and prevent clients from bypassing that edge.

For nginx, place this inside the HTTPS virtual host for app.example.com, with a separate default virtual host rejecting unknown authorities. This single-host example forwards a configured public authority rather than trusting the incoming Host or an absolute request target. For a non-default public port, include that port in both configured authority values.

location / {
  client_max_body_size 10m;
  proxy_pass http://127.0.0.1:8080;
  proxy_http_version 1.1;
  proxy_set_header Connection "";
  proxy_set_header Host app.example.com;
  proxy_set_header Forwarded "";
  proxy_set_header X-Forwarded-For $remote_addr;
  proxy_set_header X-Forwarded-Proto https;
  proxy_set_header X-Forwarded-Host app.example.com;
  proxy_set_header X-Forwarded-Port "";
  proxy_set_header X-Forwarded-Protocol "";
  proxy_set_header X-Url-Scheme "";
  proxy_set_header Front-End-Https "";
  proxy_set_header X-Forwarded-Ssl "";
}

The explicit body limit avoids nginx's default 1m limit unexpectedly rejecting larger uploads. Coordinate this body-only cap with Soklet's payload and aggregate request limits, which also account for metadata and framing. Clearing X-Forwarded-Port avoids synthesizing an explicit :443 on the public origin. See nginx body limits.

For Caddy, its default proxy header handling sets X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host. Remove the remaining forwarded families explicitly:

app.example.com {
  reverse_proxy 127.0.0.1:8080 {
    header_up Host app.example.com
    header_up X-Forwarded-Host app.example.com
    header_up X-Forwarded-Proto https
    header_up -Forwarded
    header_up -X-Forwarded-Port
    header_up -X-Forwarded-Protocol
    header_up -X-Url-Scheme
    header_up -Front-End-Https
    header_up -X-Forwarded-Ssl
  }
}

When an ALB, CDN, or another proxy terminates TLS before nginx or Caddy, these examples need adaptation. Keep a configured public authority and scheme when possible. Variables such as $scheme and $server_port describe nginx's incoming connection, which may be plain HTTP even for a public HTTPS request; do not substitute them blindly for the public URL. Derive public scheme, host, port, and client IP only from metadata sanitized by that outer trusted edge, configure the complete trusted proxy chain, and overwrite or remove every remaining family at the final hop. Do not trust an arbitrary incoming header to repair the public URL. Apply the same sanitation to dedicated SSE and MCP proxy routes, and configure their streaming behavior and timeout budgets separately.

Load Balancers And Streaming

A managed load balancer, such as AWS Application Load Balancer, can provide the edge layer. Configure its targets to speak HTTP/1.1 to Soklet, and route ordinary HTTP, dedicated SSE, and MCP traffic to their respective listener ports when your application uses all three.

For streaming workloads, check these settings along the complete client-to-server path:

  • Forward streamed bytes promptly. Disable response buffering in any proxy or CDN layer that would otherwise collect the response before delivering it.
  • Budget idle timeouts for the wait before the first response byte and for gaps between subsequent bytes. Heartbeats or progress only keep an idle connection alive when bytes actually reach the edge.
  • Preserve the intended public Host authority and include its hostname in the MCP listener's allowedHosts. Trust forwarded client addresses only through your configured proxy policy.
  • Allow target draining and process termination enough time for graceful shutdown.

For AWS Application Load Balancer, review its connection idle timeout and Host header preservation settings. HTTP/2 PING frames do not reset its idle timeout; application response bytes do. Test a long-lived stream through the deployed public URL, including quiet periods and deployment drain.

Timeouts And Backpressure

Production configs should set explicit limits instead of relying only on defaults:

  • HttpServer.Builder.requestHeaderTimeout and SseServer.Builder.requestHeaderTimeout set the transport-layer read bound for the request line and headers. Lower values strengthen slow-client and slow-loris protection.
  • requestBodyTimeout is a standard HTTP transport-layer read bound for the complete request body after headers have been received. It is a total body-phase timeout, not an idle-progress timeout. SSE handshakes do not accept request bodies.
  • responseWriteIdleTimeout is a standard HTTP write-side idle bound for non-streaming responses. It protects fixed-length and file responses from stalled readers after the request has completed. The default is 60 seconds; set it to Duration.ZERO to disable this timeout.
  • HttpServer.Builder.requestHandlerTimeout bounds HTTP resource handling, and SseServer.Builder.requestHandlerTimeout bounds an SSE handshake. MCP instead uses an absolute requestTimeout that covers the client-visible lifetime of its semantic request.
  • requestHandlerConcurrency and requestHandlerQueueCapacity bound active and queued handler work; the SSE and MCP builders expose the same-named controls.
  • maximumRequestSizeInBytes rejects oversized request lines, headers, framing, and bodies before resource-method invocation; SSE exposes the same aggregate-request bound; MCP's same-named setting bounds its request body, with header and request-target limits configured separately. It is also the per-connection buffering bound while a request is being read, so it directly controls worst-case pre-dispatch memory; lower it to the smallest value your API needs.
  • maximumRequestBodySizeInBytes independently caps the standard HTTP body payload after transfer framing is removed and before optional Content-Encoding decompression. It defaults to tracking the aggregate request limit and cannot exceed it. Use this control when the permitted payload is smaller than the buffer budget needed for request metadata and framing.
  • maximumHeaderCount, maximumHeadersSizeInBytes, and maximumRequestTargetLengthInBytes reject request-shape attacks that can otherwise stay under a total byte-size ceiling; SSE and MCP expose the same-named bounds.
  • ResponseMarshaler::forUnparsedRequest customizes standard HTTP parser and request-construction rejections that occur before a valid Request exists. Their default and fallback statuses are 400, 408, 413, 414, 415, 417, and 431; custom responses may select another final status from 200 through 599 and include application policy such as Cache-Control: no-store. Soklet runs this per-rejection work on the configured request-handler executor under requestHandlerTimeout; the framework-managed default executor has bounded concurrency and queue capacity. The timeout bounds transport waiting and cooperatively interrupts the worker. Soklet safely falls back when that work is saturated, times out, or fails. The associated raw-input capture is capped at 64 KiB but may contain credentials or other sensitive data; review the Advanced Response Marshaling privacy guidance before inspecting it.
  • SseServer.Builder.writeTimeout and McpServer.Builder.writeTimeout bound stream writes. The SSE setting also bounds handshake and rejection-response writes. SSE permits Duration.ZERO to disable every SSE write deadline, including handshake and failsafe writes; MCP requires a positive finite value and a shorter positive keepAliveInterval.
  • streamingResponseTimeout and streamingResponseIdleTimeout bound HTTP streaming producers.
  • LifecyclePolicy.Builder.gracefulShutdownTimeout sets the shared graceful-drain budget; forcedShutdownTimeout sets the subsequent forced-shutdown budget. The defaults are 15 seconds and 3 seconds respectively. Interruption cannot guarantee that noncooperative application code stops.

Treat queue capacity as a memory and latency budget, not just a throughput knob. A large queue can absorb bursts, but it can also hide overload and increase tail latency. In most production systems, a bounded queue plus fast 503 Service Unavailable is preferable to unbounded request accumulation.

The default HTTP handler queue also buffers dispatch bursts while idle workers are waking. A very small requestHandlerQueueCapacity can therefore return 503 before every handler is busy. Size it for bursts as well as expected steady-state queueing, and measure overload behavior.

Transport settings are configured on their server builders before the transport is added to SokletConfig. Startup and shutdown deadlines instead belong to one shared LifecyclePolicy, installed with SokletConfig.Builder.lifecyclePolicy(...). Its budgets apply across the owner's configured lifecycle components, not separately to each server or executor.

Builder references:

See Server Configuration for complete examples showing where these builder methods are set.

HTTP streaming bounds both retained payload and chunk metadata. The payload budget is streamingQueueCapacityInBytes; queued and in-flight payload chunks also share a count ceiling of max(16, streamingQueueCapacityInBytes / 256). Small writes can coalesce into pending chunks up to streamingChunkSizeInBytes; an in-flight chunk is never modified. Reaching either bound applies backpressure until socket progress frees capacity or the stream terminates. These settings bound the transport queue, not application-owned buffers or total process memory.

Dead Peers And Stream Capacity

A heartbeat schedules a write, not a remote acknowledgment. FIN, RST, and write failures can expose a disconnected client, but a silently unreachable peer can remain represented until TCP retries fail or an applicable lease expires. The timing depends on the operating system and network; it can be several minutes. Linux documents how TCP retry policy affects that timeout. Do not apply a host-wide retry setting as a universal recipe.

The default dedicated SSE capacity is 256 admitted lifetimes, so undetected dead peers and reconnecting clients can compete for those slots and cause HTTP 503 responses. A dead MCP subscription stream can also retain its endpoint/authorization-partition subscription quota, whose default is 32, until cleanup or lease expiry. A short keep-alive interval alone does not guarantee timely quota recovery.

Test silent loss as well as explicit disconnects through the deployed edge. Size lifecycle capacity, subscription duration, queues, file descriptors, and memory together for the expected client population and reconnect overlap. Raising capacity alone does not improve failure detection. Where a stricter liveness bound is required, design and test application acknowledgments or lease/reconnect policy with the deployment's transport timeouts.

Secure Defaults Audit

Soklet's built-in defaults are intentionally bounded for request shape, slow-client protection, and connection counts. Treat the table below as the audit checklist for safe out-of-the-box posture versus production overrides.

SurfaceDefault postureProduction decision
Standard HTTP request parsing60s absolute header/keep-alive-idle and body timeouts, 10 MB aggregate request limit, body-only limit tracks the aggregate limit, 100 headers, 64 KB header section, 8 KB request targetLower the body-only payload cap and aggregate buffering bound independently to the smallest values your API needs
Standard HTTP and SSE bind0.0.0.0 wildcard (all interfaces)Bind to a specific interface or loopback when an edge proxy is the only intended client
MCP transport parsing and connections60s header/body timeouts, 10 MiB request-body limit, 100 headers, 64 KiB header section, 8 KiB request target, 64 KiB read buffer, 8,192 concurrent connectionsTune MCP transport bounds to the workload; the body limit can be raised only as far as 16 MiB, and the connection cap and per-connection buffering together determine memory exposure
Standard HTTP response writes60s non-streaming response write-idle timeoutKeep enabled; lower it if stalled readers should be reaped faster
Standard HTTP connection countconcurrentConnectionLimit(8_192)Tune the cap below the process file-descriptor limit and below the edge/proxy connection budget
HTTP streaming responses256 retained lifetimes, four callback workers, 5s cleanup budget, 1 MB producer queue per stream, 16 KB chunks, streaming idle timeout defaults to requestBodyTimeout, total stream timeout disabledUse streamingResponseIdleTimeout for periods with neither producer output nor socket write progress; size lifecycle and queue limits for the payload/resource workload; add a total timeout only if streams should have a maximum lifetime
SSE handshakes and streams256 admitted connection lifetimes, 128 queued application writes per connection, 60s handshake timeouts, 64 KB maximum handshake request, 64 KB header section, bounded queues/caches, concurrentConnectionLimit(8_192), 30s stream writeTimeoutTune the connection cap to your FD budget and lower or disable writeTimeout deliberately
MCP transportLoopback bind; anonymous admission; present origins rejected by default; 60s absolute request timeout; 32 active handlers plus 128 queued; 128 pending messages per stream; 15s keep-alive and 30s write timeout; 32 live subscriptions per endpoint and admitted authorization/quota partition, per server instance with a 24h maximumConfigure bind/Host and admission deliberately, configure application quotas where needed, and tune handler/stream/subscription bounds for the workload

The standard HTTP and SSE 8192-connection defaults are protective ceilings, not universal production recommendations. SSE also has a separate default capacity of 256 admitted connections; raise both limits deliberately when more simultaneous clients are needed. Queue element counts do not bound payload bytes. Internet-facing production systems should still size them deliberately, because the right values depend on your ulimit -n, pod/container density, long-lived stream count, and edge rate-limit policy. Passing 0 to the standard HTTP or SSE concurrentConnectionLimit(...) setting disables that cap when an embedder intentionally delegates connection limiting to another layer.

Suggested tuning values for two common HTTP/SSE archetypes, not a table of built-in defaults. Tune from here based on observed queue depth, p99 latency, and saturation behavior. MCP exposes a different set of controls; start with its bounded defaults and review the workload guidance in MCP.

SettingJSON APIStreaming-heavy
requestHeaderTimeout (SSE)Above the upstream connection idle timeout with latency/jitter margin when HTTP or MCP connections are reusedSame HTTP/MCP reuse constraint; dedicated SSE's handshake timeout is separate from stream lifetime
requestBodyTimeout30snot applicable
responseWriteIdleTimeout30s30s for non-streaming responses
requestHandlerTimeout (SSE)10s5s (handshake)
requestHandlerConcurrency (SSE)2× CPU1× CPU
requestHandlerQueueCapacity (SSE)200100
maximumRequestSizeInBytes (SSE)1 MB1 MB
maximumRequestBodySizeInByteslargest accepted encoded payload, no greater than 1 MBlargest accepted encoded HTTP payload, if any; not applicable to SSE handshakes
maximumHeaderCount (SSE)100100
maximumHeadersSizeInBytes (SSE)64 KB64 KB
maximumRequestTargetLengthInBytes (SSE)8 KB8 KB
concurrentConnectionLimit (SSE)finite HTTP connection cap, often lower than the 8192 defaultfinite SSE stream cap, often lower than the 8192 default
gracefulShutdownTimeout (shared lifecycle policy)30s30s
forcedShutdownTimeout (shared lifecycle policy)3s3s
writeTimeoutnot applicable30s
streamingResponseTimeoutnot applicableunset (or large)
streamingResponseIdleTimeoutnot applicable60s

Notes:

  • Standard HTTP and MCP requestHeaderTimeout also close idle keep-alive connections. Their 60-second default is equal to nginx's upstream keep-alive idle default and the ALB idle default, and below Caddy's two-minute upstream keep-alive default. These defaults do not establish a safe reuse margin. Set the backend budget comfortably above the proxy's upstream idle timeout, allowing for round-trip latency and scheduling/network jitter, or reduce the proxy's idle reuse window. Otherwise the proxy can reuse a connection as Soklet closes it and return a 502, particularly for requests it cannot safely retry. The timer restarts after a response completes; the next request shares its remaining idle/header budget, and incoming header bytes do not reset it. Dedicated SSE uses its header timeout for the handshake, not established-stream lifetime; coordinate SSE heartbeat and write/edge idle settings separately.
  • Concurrency multipliers assume virtual-thread executors. For platform-thread pools, start lower (1× CPU) and rely on the queue.
  • The deployment platform's grace period must budget for graceful drain, forced shutdown, any application cleanup, and operational margin. Kubernetes also counts preStop time against that period; see the Kubernetes recipe.
  • Long-running MCP tool calls (LLM, RAG retrieval, external tool execution) may require a larger MCP requestTimeout, but that deadline remains absolute and does not forcibly stop non-cooperative code.
  • Large or slow uploads may need a larger requestBodyTimeout because it bounds total body-read time even when bytes continue arriving.
  • streamingResponseTimeout is intentionally left unset for streaming-heavy workloads; rely on streamingResponseIdleTimeout to stop streams with neither producer output nor socket write progress, without bounding total stream lifetime. Continued socket progress can renew the idle deadline while the producer is stalled. Size the per-stream queue and lifecycle capacity together: the defaults allow roughly 256 MiB of queued payload alone, before chunks, request state, application resources and other JVM memory. Use a smaller queue or fewer streams for smaller heaps.
  • Size connection limits from the bottom up: reserve file descriptors for outbound clients, files, logs, and the JVM, then allocate the remainder across listeners. The edge should usually reject or queue before Soklet reaches its own transport bounds.

Request Buffering And Heap

Size connection and request limits together before exposing a listener to uploads. As a conservative starting heuristic, keep the sum of concurrentConnectionLimit × maximumRequestSizeInBytes across all HTTP, SSE, and MCP listeners at no more than about half the Java heap. Use a finite, explicit connection cap for this calculation. The standard HTTP defaults alone allow 8,192 × 10 MiB, about 80 GiB of potential request buffering, so a typical container heap cannot support every permitted connection uploading near the default limit at once.

This calculation is a sizing heuristic, not an aggregate memory limit or a guarantee against exhaustion. MCP's request-size setting bounds body bytes while headers and framing have separate limits; allow for those too. Reserve additional heap for buffer growth and transient copies, decompression, parsed JSON and other application objects, queued handlers and response payloads, HTTP streaming queues, SSE/MCP queues, caches, and the application's normal working set. Leave container memory outside -Xmx for thread stacks, direct buffers, metaspace, and other native allocations. Load-test concurrent near-limit uploads and streaming with the deployment's actual heap and all enabled listeners; reduce limits further where necessary.

A JVM that survives OutOfMemoryError can lose transport or timeout threads and remain alive while unable to serve requests or finish orderly shutdown. Use -XX:+ExitOnOutOfMemoryError with an external supervisor that restarts the process; health checks alone do not make recovery or graceful shutdown reliable after heap exhaustion. This flag is not a general native-resource failure handler: native-thread or file-descriptor exhaustion can still leave the process unable to serve without triggering that exit policy. Budget and monitor those resources separately, and have the supervisor enforce a tested recovery policy.

Threading Model

Soklet uses transport threads for network mechanics and separate executors for application work:

  • HTTP resource methods and response marshaling run on the HTTP request-handler executor.
  • HTTP StreamingResponseBody producers run on the HTTP streaming executor, so long-lived streams do not occupy request-handler threads.
  • SSE handshakes run on the SSE request-handler executor.
  • Established SSE connections are processed on a separate connection executor; SseBroadcaster::broadcastEvent enqueues work and returns without performing socket writes inline.
  • MCP application-owned handlers run behind the McpServer's server-wide execution-slot and admitted-queue bounds. Framework-owned discovery and catalog operations do not consume an application-handler slot.
  • MCP POST progress, modern subscriptions, and explicitly configured 2025 GET notification streams use bounded SSE queues. Both 2025 profiles can deliver authorized resource/catalog invalidations over leased GET when sessions, HTTP transport admission, subscriptions, and effective change sources are configured. GET admission alone grants no URI permission; delivery is best effort without event history or lost-POST-result recovery. See legacy notification delivery.
  • Observer and metric callbacks follow the threading contract on each method. Lifecycle-transition callbacks (willStart*, didStart*, didFailToStart*, willStop*, didStop*) are serialized on a daemon observer worker.

Soklet requires JDK 21 or newer. Default HTTP and MCP application executors and SSE connection processing use virtual threads, subject to the server's admission and lifecycle bounds. You can supply custom executor services through the server builders when you need to integrate with an application-specific executor policy.

Internal lifecycle/process coordination, finalization, HTTP/SSE listener and timeout threads, SSE peer monitoring, and MCP cancellation, deadline, observation, subscription-cleanup and metric helpers do not copy application InheritableThreadLocal values. These helpers retain their creator's context class loader for resource discovery and callbacks, and explicitly propagate Soklet lifecycle ownership.

In the default standalone startup path, inheritable values set on the thread calling Soklet.run(...) do not reach request handlers through the lifecycle and listener thread chain. This includes inheritable logging, tenant or configuration context. Application handler and protocol-request factories and supplied custom executors retain their own inheritance settings, but cannot recover values discarded by an earlier helper. Custom executors can establish application context independently.

Prefer explicit configuration or service references for application-wide state. Obtain request-specific context from the available request/context objects, or bind it in RequestInterceptor.wrapRequest around requestProcessor.accept(request). Restore the previous value, or remove the binding when there was none, in finally. This scope covers synchronous request processing; streaming body producers must capture the immutable context they need and bind and restore it separately.

This policy controls Soklet's own helper construction. The tested Java 21/25 runtimes can still invoke childValue while creating JVM-managed virtual-thread carriers, even when the virtual helper itself disables inheritance. Those hooks must remain prompt and failure-contained when the runtime invokes them.

Custom HTTP request-handler executors must dispatch asynchronously and own their concurrency/queue bounds. Direct or caller-runs dispatch receives 503 and connection closure before application handling; choose a throwing rejection policy. SSE handshake executors must also dispatch asynchronously to keep connection admission responsive. HTTP handler deadlines include queue time and remain active for admitted requests during graceful drain. A timeout response and cooperative interrupt do not prove handler termination; shutdown continues tracking residual application work within its shared budgets.

Each run owns a non-daemon lifecycle coordinator through full finalization, including cleanup after the last listener retires. awaitShutdownAsync() observes its completion without creating another waiting thread. Completion callbacks are delivered separately from lifecycle shutdown; keep dependent application work bounded. When enabled, the JVM hook joins bounded core shutdown, eligible cleanup, and terminal reporting without joining the process owner afterward. Normal await methods and scoped return additionally include process-registration release. Soklet-created auxiliary workers are daemon threads, including streaming callbacks, diagnostics and supervision, MCP policy/cancelation workers and protocol timers. A blocked residual handler or callback on those auxiliary workers alone cannot keep the JVM alive after Soklet publishes its terminal outcome. Daemon status does not prove termination: an incomplete result stays incomplete, and configured application cleanup is skipped. Running built-in HTTP/SSE listeners are non-daemon and retain process liveness until shutdown releases them. Inline connection observers and metric callbacks run on those listeners; a callback that never returns can retain the listener even after an incomplete shutdown. Keep them prompt. Custom transports and supplied executors own their thread/liveness policies. The runner does not force JVM exit.

Returning from run(...) or either await method does not wait for lifecycle-transition observer delivery. Those callbacks may be lost when the JVM exits. Put required cleanup in bounded ShutdownCleanup; if cleanup depends on observer state, provide an application-owned delivery barrier.

Startup cancellation competes atomically with readiness. If interruption-driven cancellation wins, Soklet reports a startup failure after attempted teardown. If readiness wins, startup succeeds and the caller's interrupt flag is restored without requesting shutdown of the running lifecycle. Soklet does not install console-input listeners; application code owns any input operation that controls its lifetime.

Inline observer and metric callbacks are hot-path callbacks. Some are invoked from selector, accept-loop, and stream-processing threads, so blocking them can stall socket I/O or connection cleanup. Keep them thread-safe, non-blocking, and failure-contained. Do not perform network I/O, blocking exports, or heavyweight logging directly inside those callbacks. Do not call blocking awaitShutdown() or join the async stage from these callbacks; use nonblocking requestShutdown() and let a separate control thread await completion. Built-in transport observer and metric callbacks reject a blocking wait on their own unfinished shutdown with IllegalStateException. Custom callback/executor paths still require application discipline; this diagnostic does not make blocking callbacks safe.

Owner-specific self-wait checks also cover MCP catalog, access-policy, localization, request-state protection and Skills policy callbacks, plus MCP publisher release. SSE fallback response handlers/postprocessors, handshake materialization and owned-body cleanup carry the same checks. Request shutdown nonblockingly and return from the callback before another thread waits for completion. Joining the shutdown stage directly or waiting from arbitrary application-owned threads remains outside these callback guards.

The default lifecycle observer formats and writes stderr records on one daemon worker, shared with the fallback used when a log observer throws. The worker has a queue of 128 records; a stalled stderr pipe cannot make that logging path perform output on a selector or request thread. Default event messages are capped at 4,096 UTF-16 characters without splitting surrogate pairs. The queue bounds record count, not the size of attached Throwable graphs. Delivery is best effort: full queues and worker-start failures discard records, and application shutdown or JVM exit does not flush pending records. Keep process output draining and use application-owned logging when delivery must be reliable. Custom observers still run on the emitting thread and need their own bounded, nonblocking handoff if their sink can block.

The console worker retires after one idle second and restarts on demand. Retirement releases its class-loader reference when no logging work is active, allowing stopped applications to unload in a container or plugin host. The timeout does not interrupt active formatting or output; a stalled stderr write can retain its worker and class loader until it returns.

Process Configuration

JVM Flags

A starting point for Java 24+ (where ZGC is generational):

-Xmx2g
-XX:+UseZGC
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/tmp/heap-dump.hprof
-XX:+ExitOnOutOfMemoryError

Notes:

  • On Java 21–23, add -XX:+ZGenerational if you choose generational ZGC. Do not carry that obsolete option into Java 24+ configurations; newer JVMs ignore or reject it. Recheck flags when changing the deployment JDK.
  • Generational ZGC suits Soklet's typical workload mix of many short HTTP requests plus long-lived SSE connections and MCP request/subscription streams. Sub-millisecond pauses keep streaming connections from being starved during collection.
  • Set -Xmx explicitly. The JVM autodetects container memory limits, but explicit sizing keeps heap behavior deterministic across base-image and runtime updates.
  • -XX:+ExitOnOutOfMemoryError is preferable for orchestrated deployments. Heap exhaustion can leave a live JVM with dead transport or timer threads, unable to serve or complete shutdown. Let the orchestrator restart the exited process; do not assume the server can recover from an OutOfMemoryError.
  • For CPU-constrained environments, also set -XX:ActiveProcessorCount=N to match the container's CPU limit. The JVM otherwise sizes its internal pools to the host's CPU count, not the container's.

File Descriptor Limits

Long-lived SSE and MCP streams hold one file descriptor per connection. Default container limits (often 1024) saturate at modest concurrency. Verify and raise:

ulimit -n 65536

Container images that run the JVM as PID 1 often inherit unhelpful defaults. Verify the effective limit inside the container with cat /proc/$$/limits.

Kubernetes does not expose RLIMIT_NOFILE as a portable per-pod field — securityContext.sysctls configures kernel /proc/sys parameters, not per-process resource limits. Practical options:

  • Bake the limit into your container image entrypoint (e.g., a wrapper script that calls ulimit -n 65536 before exec java ...).
  • Configure your container runtime's default ulimits at the node level (containerd default_ulimits, Docker --default-ulimit).
  • Use a platform-specific extension if your distribution offers one.

SSE handshakes use independent header-read and handler budgets. Queue wait and application handling consume the same handler budget; header reading/parsing pause it. Partial-header read expiry routes through forUnparsedRequest, with a default 408. Observation and marshaling share the remaining handler budget; if they time out, the original bodyless rejection is sent. Idle read expiry and incomplete-header EOF close quietly, so zero-byte TCP health checks do not count as internal transport failures. Configure both budgets for your edge and client behavior; see Server Configuration.

The HTTP socketSelectTimeout must be positive and caps the selector's wait; pending request, idle, response and close deadlines can shorten it. Socket-write progress means the kernel accepted bytes, not that the peer consumed them: a slow reader can time out while consuming data already buffered by the kernel. Connections above a configured connection cap can be accepted at TCP level and then closed without an HTTP response.

After a completed closing response, fully consumed requests with no observed surplus input close promptly. One nonblocking read also checks for input queued on the socket while the handler ran, without adding a wait. When unread input may remain, the built-in HTTP server uses a bounded input discard before socket close, including any byte consumed by that probe in its discard limit. The physical connection still counts toward its connection limit and consumes the graceful shutdown budget during that period; forced shutdown bypasses the drain wait. The bound helps early responses reach uploading clients; it does not guarantee delivery for arbitrary uploads or bytes that race the final close.

Graceful Shutdown

Graceful HTTP drain stops admitting requests, including connections still uploading a request body. An incomplete upload can be closed without an HTTP response; clients must tolerate that transport failure and apply their own retry/idempotency policy.

For explicit lifecycle control, start standalone applications and embedded services with Soklet.run(config). It returns after readiness and by default owns a JVM shutdown hook that joins bounded finalization. requestShutdown() requests termination promptly; awaitShutdown() blocks for the full outcome, and awaitShutdownAsync() observes it through a read-only completion stage. Neither await method initiates shutdown. An embedded host must request and await Soklet shutdown before closing shared dependencies. The automatic hook does not establish ordering with other JVM hooks. For tests and finite embedded work, the scoped overload Soklet.run(config, action) owns teardown when its no-argument callback returns or throws. The callback runs on the calling thread after readiness and is not itself deadline-bounded or forcibly interrupted by external shutdown. Scoped return waits for full finalization and propagates callback/lifecycle failures; see scoped execution.

A host that needs a load-balancer deregistration delay before drain can set SokletConfig.Builder.jvmShutdownHookEnabled(Boolean.FALSE). The option defaults to Boolean.TRUE; null restores that default. The host must prevent new runs once termination begins, perform its bounded deregistration/delay, then call requestShutdown() and synchronously awaitShutdown() before its own hook returns. Release shared dependencies only after successful shutdown. The lifecycle owner does not keep a JVM alive after all shutdown hooks return. All run overloads honor the option; cleanup, programmatic shutdown, and scoped teardown remain active. See Host-Owned JVM Shutdown for the full contract.

JVM shutdown hooks run concurrently, with no guaranteed order. Coordinate independently registered logging and resource hooks so they do not close dependencies while Soklet is draining. Required application cleanup belongs in ShutdownCleanup, which runs only after complete core shutdown. On signal-driven JVM shutdown, post-run code and a caller's finally block may never finish. The runner does not select the signal's process exit status, so complete shutdown does not promise exit code zero.

Request shutdown from an owner outside the work being drained. Calling System.exit() inside a handler, streaming producer, or cleanup action can make the JVM hook wait for the same work that is waiting for JVM exit, exhausting the shutdown budget. Let the process owner or supervisor determine process termination.

The default shared LifecyclePolicy allows 15 seconds of graceful drain and a separate 3 seconds of forced shutdown. The ordinary request-handler timeout and MCP request timeout default to 60 seconds; these are independent policies. A shorter drain is a valid choice when deployment speed is more important than allowing every permitted request to finish. For full-completion deployments, budget for the maximum remaining request work plus response transmission, then allow forced shutdown and operational margin in the surrounding platform's termination grace period. Long-lived streams cannot be covered by a simple timeout inequality, and code that ignores cancelation/interruption cannot be guaranteed to stop.

Stopping a Soklet instance first stops accepting new connections. Standard HTTP closes idle keep-alives immediately, lets already-dispatched handlers finish, writes their responses with Connection: close, and then force-closes remaining HTTP connections when the shared gracefulShutdownTimeout expires. Active SSE connections terminate with StreamTerminationReason.SERVER_STOPPING. MCP preserves already-admitted finite unary responses and request-progress streams while they drain within the grace budget; indefinite subscriptions close promptly and a writable subscription receives its terminal complete result. When the budget expires, Soklet force-cancels remaining work and closes its response paths with McpStreamTerminationReason.SERVER_STOPPING, documented in MCP. Server executors are asked to shut down gracefully within the configured budgets.

Requests racing shutdown can receive 503 Service Unavailable even while other admitted requests drain. A proxy may pass that response through; nginx does not retry upstream 503 responses by default. Plan client retries around the operation's idempotency and verify target draining through the deployed edge.

Streaming and producer code should cooperate with shutdown and client disconnects:

Zero Lifecycle Budgets

All four LifecyclePolicy timeouts accept Duration.ZERO as an immediate deadline. Use positive budgets for normal deployments. Zero provides no waiting allowance for the selected phase; it does not disable the timeout or make the wait unlimited.

Each timeout must fit in signed 64-bit nanoseconds. The sum of startupCancelationTimeout, gracefulShutdownTimeout, and forcedShutdownTimeout must also fit within Duration.ofNanos(Long.MAX_VALUE) (about 292 years); build() rejects a larger total. startupTimeout has its own independent budget and is not included in that sum.

SettingEffect of zero
startupTimeoutNo waiting allowance for setup or transport startup; startup can immediately produce TIMED_OUT.
startupCancelationTimeoutNo waiting allowance for the active startup call to return before graceful/forced shutdown.
gracefulShutdownTimeoutUnresolved participants proceed immediately to forced shutdown.
forcedShutdownTimeoutNo waiting allowance for forced termination proof; any still-unproven or residual work produces INCOMPLETE.

With both shutdown budgets zero, even an idle running listener can produce INCOMPLETE because stop calls and termination proof are asynchronous. Proof already available at classification can still establish completion. Requesting interruption is not proof that application work exited.

Terminal Stderr Report

During finalization, Soklet attempts a multiline soklet-terminal-report directly on standard error, captured when the run's runtime is created. It is triggered by any of these conditions:

  • A runner primary failure: startup, process ownership, unexpected termination or incomplete shutdown.
  • Startup disposition FAILED or TIMED_OUT.
  • Shutdown disposition FORCED or INCOMPLETE.
  • An unexpectedly terminated component.
  • Configured application cleanup failing or timing out.

A complete FORCED shutdown still triggers the report. A startup canceled by interrupting the calling thread throws SokletStartupException but is an expected outcome and prints no report. Ordinary expected graceful shutdown is silent unless another trigger applies.

The report bypasses LifecycleObserver and LogEvent. It contains bounded lifecycle/component/cleanup state, retention and observer diagnostics, and failure class names, without exception messages, stack traces or cause/suppressed traversal. Output is capped at 16 KiB of valid UTF-8. The runner and JVM hook share one 250-millisecond reporting allowance; reporting is best effort, and failure or timeout does not replace the lifecycle result. A blocked output worker may outlive that allowance. There is no public reporter switch; configure process stderr capture and include the reporting allowance in your deployment budget. This report is separate from the default observer's stderr logging.

Observability

Use LifecycleObserver for detailed event hooks and request/stream tracing. Use MetricsCollector for counters, gauges, and histograms. The default collector can expose Prometheus/OpenMetrics-compatible text. If your platform standardizes on OpenTelemetry, use soklet-otel for both metrics and spans.

Soklet parses inbound W3C traceparent and tracestate headers into Request::getTraceContext. Core Soklet does not create spans, make sampling decisions, generate child span IDs, or install ambient tracing scope. MCP separately validates trace context carried in request _meta; its OpenTelemetry span does not fall back to physical HTTP trace headers. See MCP for that privacy boundary.

Keep trace IDs out of metric labels. Trace IDs belong in spans and logs; metric labels should stay low-cardinality. If you need metrics-to-trace drill-down, use OpenTelemetry exemplars instead of adding trace IDs to counters or histograms.

Exposing Metrics For Scraping

For self-hosted scraping with the default in-memory collector, expose a resource method:

@GET("/metrics")
public MarshaledResponse metrics(@NonNull MetricsCollector metricsCollector) {
  String body = metricsCollector.snapshotText(
    SnapshotTextOptions.fromMetricsFormat(MetricsFormat.PROMETHEUS)
  ).orElse(null);

  if (body == null)
    return MarshaledResponse.fromStatusCode(204);

  return MarshaledResponse.withStatusCode(200)
    .headers(Map.of("Content-Type", List.of("text/plain; charset=UTF-8")))
    .body(body.getBytes(StandardCharsets.UTF_8))
    .build();
}

Require an authorized monitoring identity or restrict this endpoint to an access-controlled monitoring network. The example shows export formatting only; do not expose it on a public listener without access control.

See Metrics Collection for filter/format options, OpenMetrics output, and OpenTelemetry-backed collectors. OpenTelemetryMetricsCollector exports through OTel's pipeline and does not require a /metrics endpoint.

At minimum, production dashboards should cover:

  • Accepted and rejected connections by server type
  • Low-level transport failures across HTTP, SSE, and MCP, especially write-idle timeouts, write timeouts, accept-loop failures, and event-loop task failures
  • Request read failures and request-handler rejections
  • HTTP response counts and durations by route
  • Streaming and SSE terminations, plus MCP request-stream and subscription terminations, by reason
  • Active SSE clients, MCP handlers/queue entries, MCP request streams, and MCP subscriptions
  • MCP admitted-request outcomes and durations by registered endpoint path and bounded method

Multi-Node Deployments

The built-in MCP subscription quota is per endpoint and admitted authorization/quota partition per server instance, not a distributed quota. With several endpoints and replicas, the same application partition key can hold up to the configured limit for each endpoint on each replica. Applications needing a fleet-wide limit must coordinate that policy themselves.

SSE broadcasters are node-local. A broadcast on one Soklet node only reaches clients connected to that node. For clustered SSE, publish domain events to a shared queue or pub/sub system and let each node rebroadcast locally. If you support Last-Event-ID catch-up, store replay data in a shared durable log.

Modern and session-disabled 2025 MCP requests are stateless and do not require session affinity. Multi-round-trip framework-protected state can continue on another instance when every node shares the production protection keys and admission resolves the same authorization partition. Resource-subscription event distribution is application-owned: use a distributed McpSubscriptionEventPublisher when updates must reach streams connected to different nodes.

MCP Tasks add an interoperable recovery boundary for long-running work. Every eligible node should use an McpTaskManager backed by the same durable task authority and should resolve equivalent admitted identities. When task notifications are enabled, its McpTaskEventPublisher must broadcast each task-ID hint to every node that might host a matching subscriber. Mcp-Name: <taskId> can help a load balancer with affinity, but correctness must not depend on affinity or the originating node remaining alive. See MCP Tasks for the full ownership contract.

Failures, Retries, And Durable Work

Explicitly enabled 2025 sessions are node-local. Route initialization and all later POST, GET, and DELETE requests to the same node using affinity learned from the first response or an equivalent routing policy; hashing a new session ID cannot route initialization. Restart/node loss yields neutral 404. Automatic host recovery and the suitability of session defaults for production remain unverified; document manual reconnection. No shared session backend, event history, replay, or lost-POST-result recovery is provided. See 2025 session configuration.

For modern and session-disabled 2025 requests, stateless MCP routing means that a new request may reach any healthy Soklet instance without session affinity. It does not transfer a live TCP connection, request stream, Java handler, or partially written response between instances. If an instance fails before delivering a terminal result, the client or edge observes a disconnect or timeout; the failed instance cannot send a JSON-RPC error or Retry-After. A retry of an ordinary operation is a new invocation, even when it reaches another instance.

A task changes what can be recovered, not what can be migrated:

State when the connection or node is lostWhat another node can do
The tool has not committed durable workNothing exists to recover; a retry is a new invocation.
Durable work committed, but the task ID response was lostThe task may exist, but the client needs an application idempotency key and lookup/deduplication policy to rediscover it.
The client received the task IDServe tasks/get, tasks/update, and tasks/cancel through the shared manager.
A live subscription was lostOpen a replacement, then reconcile each task with authoritative tasks/get.

No design can make a dead node send retry guidance after abrupt process loss. Design the application for the ambiguous middle case even when planned deployments normally drain cleanly.

Decide Whether A Retry Is Safe

Discovery, catalog, read-only operations, and tasks/get can normally be retried with bounded exponential backoff and jitter when the application preserves their read-only semantics. Honor Retry-After when Soklet returns a rate-limit denial as HTTP 429.

Do not blindly retry an operation that may have side effects. A connection failure, active-request deadline, or lost response does not prove that the handler failed to perform its work. Soklet's defined handler-capacity and request-state-protector 503 responses reject before handler invocation, but a proxy-generated 503 or interrupted response does not carry that guarantee.

A JSON-RPC request ID correlates one request or stream; it is not a durable idempotency key and may be reused by independent requests. Likewise, McpToolAnnotations contains advisory client hints, not enforced authorization, transaction, or deduplication policy.

For a retryable operation with side effects, use an application-level idempotency key in the operation's stable input and a shared durable result ledger. Bind the ledger entry to the authenticated tenant or principal, operation, and canonical request intent. Create or claim it atomically, return the recorded result for an equivalent retry, and reject reuse for different input. Coordinate the ledger with durable application effects through a transaction, outbox, or the strongest facility the affected system provides. This normally gives at-least-once invocation with idempotent effects; Soklet cannot promise exactly-once behavior across arbitrary external systems.

Task-management operations are designed for network retries against the same task ID. A manager must make tasks/update idempotent for duplicate or already-consumed input responses and must record tasks/cancel as cooperative intent rather than assuming the worker stopped. Those guarantees do not deduplicate the original task-producing tools/call; its application input still needs a stable idempotency key when duplicate durable work would be harmful.

Continue Only At An Explicit Request Boundary

An input_required result completes one request. The client performs the requested input and sends a fresh POST containing its responses and any requestState. That later request can reach another instance:

  • FRAMEWORK_PROTECTED state requires identical production protection material on every eligible instance and the same admitted authorization partition.
  • APPLICATION_PROTECTED state can carry a high-entropy opaque handle whose authoritative data lives in a shared durable application repository.

This transfers verified continuation state, not the previous handler's execution. If an instance fails before the client receives the input_required result, no continuation checkpoint was delivered. Framework-protected state is also not a server-side single-use store; applications that require replay prevention or atomic workflow consumption must enforce it separately. See Input and Request State.

A task's input_required state uses a different durable boundary. The manager returns outstanding input requests in the authoritative McpTask snapshot; the client sends a fresh tasks/update, and the manager atomically accepts the matching response subset. The worker later takes or reads those persisted responses through application infrastructure. Neither the original tool handler nor its request-scoped CancelationToken is retained.

Reconnect Progress Streams And Subscriptions

Request-scoped progress is not replayed after a disconnect, and the original invocation's terminal result cannot migrate to a new connection. Retrying the operation therefore follows the same idempotency rules described above. Modern disconnects, finite/uncommitted legacy disconnects, deadlines, and forced shutdown after graceful drain signal the request's CancelationToken, but cancelation is cooperative and does not roll back side effects. A committed legacy POST SSE disconnect instead detaches delivery, preserves physical worker reservations until exit, and leaves absolute deadlines in force.

A subscriptions/listen stream remains attached to the instance that accepted it. After that connection is lost, first establish a new subscription against a healthy instance and begin consuming its events. Then re-read or re-list authoritative resource state and call tasks/get for each subscribed task, reconciling those snapshots with buffered and subsequent events. Processing the same change twice is acceptable; leaving a gap between the snapshot and the new subscription is not.

A distributed McpSubscriptionEventPublisher can deliver resource events to live subscribers across the fleet, while McpTaskEventPublisher provides task-ID hints. Neither supplies reconnect replay. Modern subscriptions have no session or Last-Event-ID replay positions; optional 2025 sessions retain notification grants across GET gaps but also supply no event history. Applications that require gap-free resource delivery need a durable event log and an application-level reconciliation or cursor protocol. Task delivery already has an authoritative recovery path: use tasks/get, treating every task notification as advisory. See Progress and Subscriptions.

Use Tasks For Durable Long-Running Work

Work that must survive the accepting instance should use the MCP Tasks extension rather than relying on the lifetime of one MCP request:

  1. Require the client to declare io.modelcontextprotocol/tasks; a task-required tool is rejected before application work when that capability is absent.
  2. Atomically persist the job, authorization binding, framework-supplied McpTaskOrigin, and recoverable dispatch record before returning McpTaskCreatedResult.
  3. Store task state and checkpoints in shared durable storage, and make them independently authorizable through McpTaskManager.
  4. Let workers claim jobs with bounded leases and fencing so another worker can reclaim an expired lease.
  5. Persist terminal output before publishing a task-change hint; a reconnecting client retrieves the result through tasks/get on any eligible node.

A surviving worker can continue that logical job, and any surviving Soklet instance can serve its task state. The client still makes a new MCP request; Soklet does not migrate the original handler or socket. Soklet supplies no database, queue, worker, lease, or fencing implementation. Those production facilities remain behind the application-owned manager SPI.

Prefer Graceful Drain, But Design For Abrupt Loss

For a planned deployment, mark an instance not ready and remove it from load-balancer rotation before stopping it. Soklet preserves already-admitted finite unary responses and request-progress streams while they drain within the grace budget, closes indefinite subscriptions promptly, and force-cancels any remaining request work when the budget expires. Keep request code responsive to cooperative cancelation and interruption, and make the platform termination grace period longer than Soklet's combined graceful- and forced-shutdown budgets.

Soklet shutdown does not mark durable tasks failed or canceled and does not treat application-owned backlog as residual server activity. Application workers finish, checkpoint, or release their own leases according to application lifecycle policy. Abrupt process loss or SIGKILL cannot drain connections or return retry guidance, so task creation, worker claims, and side effects must remain correct under the ambiguous-outcome rules above. See Graceful Shutdown.

Health Checks

Expose an application-level readiness endpoint that verifies the dependencies your resource methods require. For simple transport-level health, Soklet also supports OPTIONS *, which lets a load balancer query server-wide capabilities without targeting an application route.

Keep readiness and liveness separate. A process can be alive while temporarily not ready to receive traffic because a dependency is unavailable, migrations are running, or a graceful shutdown has started.

Static Files

For bundled web assets, prefer StaticFiles over hand-rolled path joins. Set trustedImmutableRoot(true) only for an operator-controlled root whose ancestors, links, and files remain immutable while the helper or its responses are in use. Deploy a new immutable tree and construct a new helper after prior responses finish. Upload directories and attacker-writable roots are unsupported.

For high-volume public assets, many production systems should serve from object storage plus a CDN, such as S3 plus CloudFront or an equivalent setup, rather than sending every asset request through Soklet. Use Soklet for assets that are naturally app-owned, bundled with the deployment, or need application-local routing and policy.

When Soklet does serve files, use edge or CDN caching where appropriate. Configure Soklet cache policy deliberately: long-lived immutable caching for fingerprinted assets, and revalidation or no-cache for HTML and other frequently changing entrypoints.

The default weak metadata ETag is cheap and deterministic across nodes serving the same filesystem metadata. EntityTagResolver::fromContentHash provides strong ETags, but it reads the full file on the request-handling thread, including for HEAD. Use manifest-backed ETags for large files or HEAD-heavy traffic.

Do not follow symlinks unless the deployment requires it. Add X-Content-Type-Options: nosniff through headersResolver when serving browser-facing assets, and use accessResolver for path- or attribute-based hide/deny policy. Request-aware authorization should happen before calling StaticFiles.

See Static Files for routing examples, resolver configuration, MIME defaults, cache validators, and range behavior.

Packaging and Static Analysis

The optional @NonNull and @Nullable annotations used in advanced examples come from org.jspecify.annotations. If you use them in application source, declare org.jspecify:jspecify:1.0.1 as a compile-time dependency; Soklet's provided annotation dependency is not inherited by consumers.

Soklet's class files retain compile-time annotation references. Static analysis with jdeps may require the annotation JARs on its analysis classpath. If a missing-dependency report contains only those known annotation types, jdeps --ignore-missing-deps is another option; it is not a jlink option.

An automatic module name does not make the Soklet JAR directly linkable into a custom runtime image, and applications introspecting annotations may still need those annotation libraries.

Deployment Recipes

These are starting points. Tune sizes, timings, and flags to your workload and platform.

Dockerfile

A minimal production-shaped image. The exec form on ENTRYPOINT ensures the JVM receives SIGTERM directly so graceful shutdown engages.

FROM amazoncorretto:25

ENV JAVA_OPTS="-Xmx2g \
  -XX:+UseZGC \
  -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp \
  -XX:+ExitOnOutOfMemoryError"

# Application artifact
COPY build/libs/myapp.jar /app/myapp.jar

EXPOSE 8080
USER 1000

ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS -jar /app/myapp.jar"]

This recipe assumes myapp.jar is already built. If your container image builds Java source, make sure your build invokes Soklet's SokletProcessor, for example through Maven or Gradle annotation processing, or direct javac -processor com.soklet.SokletProcessor.

For a more complete buildable example, see the Toy Store App Docker recipe.

Docker stop sends the stop signal and then force-kills the container when its timeout expires. Unless configured otherwise, the Linux timeout is 10 seconds, shorter than Soklet's default 18-second running shutdown. Configure the container's stop budget explicitly. For example:

docker stop --timeout 40 myapp

Set the persistent budget with docker run --stop-timeout 40 ..., or Compose stop_grace_period: 40s. The 40-second example allows startup cancelation, default graceful/forced phases, five seconds of application cleanup, the terminal-report attempt, other hooks and reserve. Recalculate it when changing these budgets; the Kubernetes deployment includes external drain delays too.

Kubernetes Deployment

A starting-point manifest for the 30-second graceful and 3-second forced shutdown budgets suggested above. The 46-second termination grace includes the 5-second preStop delay, 2-second startup cancelation allowance, 250-millisecond terminal report, 2 seconds for other hooks and VM halt, and over 3 seconds of reserve; increase it if you also configure application cleanup or need more deployment headroom.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      # 5s preStop + 2s startup cancelation + 30s graceful + 3s forced
      # + 0.25s terminal report + 2s hooks/VM halt + over 3s reserve.
      # Add any application cleanup budget to this total.
      terminationGracePeriodSeconds: 46
      containers:
        - name: myapp
          image: myorg/myapp:latest
          ports:
            - containerPort: 8080
          resources:
            requests:
              cpu: "500m"
              memory: "1Gi"
            limits:
              memory: "2Gi"
          lifecycle:
            preStop:
              # Allow time for traffic-routing updates before JVM shutdown.
              # Validate the needed delay with your ingress or service mesh.
              exec:
                command: ["sh", "-c", "sleep 5"]
          readinessProbe:
            httpGet:
              path: /readiness
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 5
            failureThreshold: 2
          livenessProbe:
            httpGet:
              path: /liveness
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 30
            failureThreshold: 3

Key invariants:

  • Budget terminationGracePeriodSeconds for preStop + graceful drain + forced shutdown + any ShutdownCleanup timeout + operational margin. Kubernetes runs preStop before sending the container's termination signal, and the hook consumes the same grace period. When that period expires, remaining processes are forcibly killed; see Kubernetes Pod termination flow.
  • The preStop delay gives the service mesh or ingress controller time to observe endpoint changes before the JVM begins shutdown. It is not a guarantee that routing has converged: validate the delay with your infrastructure and account for traffic still arriving during the transition.
  • Readiness and liveness should target distinct paths and have different failure semantics. Readiness can fail temporarily without restarting the pod (dependency unavailable, migrations running, graceful shutdown started); liveness failures restart the container.
  • Modern and session-disabled 2025 MCP requests do not need sticky sessions. Explicitly enabled 2025 sessions require node affinity learned from initialization; keep protection material, authorization partitioning, and distributed subscription publishers consistent across replicas. See Multi-Node Deployments.

Service And Ingress

A standard Service exposing the deployment, plus your ingress of choice (nginx, ALB, Envoy, Cloudflare). The ingress is responsible for TLS termination, HTTP/2 or HTTP/3 negotiation with clients, WAF, rate limiting, and forwarded-header propagation. See Deployment Boundary.

Common Pitfalls

  • Underbudgeting terminationGracePeriodSeconds. Include the preStop delay, both lifecycle shutdown budgets, any application cleanup timeout, and operational margin. See the Kubernetes recipe; sizing only for graceful drain can cut off in-flight work or cleanup.
  • Default ulimit -n in containers. Many SSE/MCP connections saturate the per-process file-descriptor limit at modest concurrency. Raise to 65536 or higher.
  • Blocking I/O inside lifecycle observers or metrics collectors. Hot-path callbacks can run on selector, accept-loop, and stream-processing threads. Blocking exports, network I/O, or heavyweight logging here back-pressure request handling and connection cleanup. Buffer and flush asynchronously.
  • Trace IDs as metric labels. Cardinality explosion. Use OpenTelemetry exemplars for metrics-to-trace drill-down instead.
  • Reflecting Origin instead of allowlisting. Permissive CORS in production. See CORS for safe defaults.
  • Treating stateless MCP as stateless application data. Modern and session-disabled 2025 MCP have no session affinity; enabled 2025 sessions require learned node affinity. Cross-instance protected retries still require shared production keys and a stable authorization partition; distributed subscriptions require an application-owned fleet-wide publisher.
  • Assuming a default connection cap matches your FD budget. Standard HTTP and SSE have transport ceilings of 8192 concurrent connections; SSE additionally defaults to 256 retained streaming lifetimes. MCP streaming traffic also consumes descriptors. Reserve descriptors for logs, files, outbound clients, and JVM internals, then enforce the intended fleet connection policy at the edge and transport boundaries.
  • Using only maximumRequestSizeInBytes as an HTTP payload limit. Each standard HTTP connection may buffer up to the aggregate limit while a request is being read, so worst-case pre-dispatch memory is the connection cap multiplied by that limit. Keep maximumHeadersSizeInBytes tight, set maximumRequestBodySizeInBytes to the largest received body payload the API accepts, and size the aggregate limit with enough headroom for request metadata and transfer framing.
  • Assuming every proxy handles Expect: 100-continue the same way. Soklet sends 100 Continue for supported fixed-length and chunked bodies after validating their request line and headers, and returns 417 Expectation Failed for unsupported expectations. Verify whether your edge forwards or terminates this exchange, especially when clients use it for large uploads. A known header-byte count plus Content-Length exceeding the aggregate request limit receives 413 before 100 Continue.
  • Disabling SSE stream write timeouts for untrusted clients. SSE writeTimeout(Duration.ZERO) permits slow readers to stay connected indefinitely. MCP does not permit a zero write timeout; keep its positive timeout and shorter keep-alive interval sized for the network.
  • Request-time hashing of large static files. EntityTagResolver::fromContentHash reads the whole file on the request-handling thread, including for HEAD. Use metadata ETags or a manifest-backed resolver for large files.
  • Unbounded requestHandlerQueueCapacity. Hides overload as growing tail latency rather than surfacing it as fast 503 Service Unavailable. Prefer a small queue.
  • Missing -Xmx in containers. The JVM autodetects container memory but explicit sizing keeps heap behavior deterministic across base-image and runtime updates.
  • Shell-form ENTRYPOINT or CMD in Dockerfiles. Wraps the JVM in a shell that swallows SIGTERM; graceful shutdown never engages. Use exec form or exec sh -c "exec java ...".
Previous
Metrics Collection