Server configuration#

server {
	host                 = ""         # Address to listen on. Empty means all of them
	port                 = 9000
	max_request_size     = 10MiB      # Limit on the request body
	max_header_size      = 16KiB      # Limit on the headers as a whole
	idle_timeout = 60s
	trust_proxy          = false      # Whether to believe X-Forwarded-For / X-Forwarded-Proto
	compression          = true       # Whether to gzip text responses (1KB and up)
	access_log           = true       # Whether to write the access log ([Logging](./log))
	bot_access_log       = true       # Whether to split out the bot access log
	access_log_mask      = []         # Extra query names whose values the access log hides ([Logging](./log))
	strict_routes        = false      # Throw on routes nothing can reach (turn this on in CI)

	shutdown_grace   = 0s      # From "start stopping" to refusing new requests (seconds)
	shutdown_timeout = 15s     # How long to wait for in-flight work (seconds)

	backlog            = 1024  # Connections the OS holds while accept catches up
	write_queue_length = 0     # Length of the response write queue; 0/1 means "no queue"
	smart_async_writes = false # With a queue, write inline while it is not busy
	tcp_no_delay       = true  # TCP_NODELAY (turn Nagle off; send small writes at once)
}

Accepting connections and writing responses#

backlog is the number of connections the OS holds for you while accept catches up. Past that, the OS turns callers away — it never reaches the application, so not a single line appears in your log. Raise it for bursty traffic (just after a restart, a campaign, a wave of reconnects); it does not make anything faster. It only lets the backlog wait instead of being refused.

write_queue_length is the length of the queue responses are written through. At 0 or 1 there is no queue and the response is written inline (the default). At 2 or more, another thread does the writing, so your handler can move on while a slow client is still being written to. What is queued sits in memory, though — a bigger queue is not a faster server.

smart_async_writes chooses, when there is a queue, between "always queue" and "write inline while the queue is idle, switch to queueing when it gets busy".

tcp_no_delay sets TCP_NODELAY on accepted connections (turns Nagle's algorithm off). The default is true (Helidon's default is false).

Without it, a response written to outputStream() in several pieces (Transfer-Encoding: chunked: HTML, SSE and so on) is delayed by about 40 ms per request from the second request on the same connection: the later small write waits for the ACK of the earlier one (Nagle), and that meets the client's delayed ACK. nginx reuses upstream connections (keepalive), so this happens behind a proxy too. Responses written in one go with Content-Length (json() and the like) are not delayed.

In aqSell, turning it on was enough for this (one CPU, one user, reused connections, the checkout flow):

Many small responses can mean more packets on the wire, but the delayed-ACK waits disappear. Set it to false only in the special case where you rely on Nagle.

The startup log says which one was chosen.

サーバー設定（接続）: 接続待ち=1024 / 書き出し列=作らない（その場で書く） / TCP_NODELAY=true
サーバー設定（接続）: 接続待ち=1024 / 書き出し列=32（空いていればその場で書く） / TCP_NODELAY=false

Write nothing and you get the defaults above. What is actually in effect is printed in the startup log.

jimble を起動しました: http://localhost:9000
サーバー設定: 待受=全部 / 本文上限=10485760byte / ヘッダ上限=16384byte / アイドル=60秒 / 圧縮=true / プロキシ信頼=false

Port#

The port, and only the port, can also be given as a system property. That is so a container can change the port without touching the configuration file.

java -Djimble.server.port=8080 -jar app.jar

The order of precedence is -Djimble.server.port > server.port > 9000.

The listen address#

Empty means it listens on every address. Narrow it down for anything that must not be visible from outside.

server { host = "127.0.0.1" }

Limits#

Uploads have a separate limit of their own (File upload).

There are no read or write timeouts.

Behind a proxy#

By default X-Forwarded-* is not believed. You start believing it once you know for certain that every request comes through the proxy in front.

server {
	trust_proxy      = true
	trusted_proxies  = ["10.0.0.0/8"]   # IPs / CIDRs of the proxies; when set, headers are read only from them
	client_ip_header = ""                # "CF-Connecting-IP", "X-Real-IP", ...; trusted only when set
}

With true, proxyAddress() returns the source in this order.

1. if trusted_proxies is set and the connection source is not in it, the connection source (the headers are just claims)
2. if client_ip_header is set, that header's value
3. X-Forwarded-For read from the right, the first entry not in trusted_proxies (the last entry when it is not set)
4. the connection source, if none of those are there

With true, scheme() / isSecure() also read X-Forwarded-Proto (since 2.5.3). Even with TLS terminated in front, the app can tell the client came over https (this is also what makes the HSTS header go out).

• With trusted_proxies set, it is only read when the connection comes from one of them
• With several values, the rightmost one is used (added by the nearest hop); the left ones can be made up by the client
• Values other than http / https are ignored and the connection's scheme is used

Compression#

server.compression (default true) turns it on / off. When the client says it accepts it in Accept-Encoding, only text responses (text/*, JSON, JavaScript, XML, SVG) of 1KB or more are compressed (since 2.5.2).

• Images, video, zip files and downloads are not compressed (they do not shrink, it costs CPU, and Content-Length is lost)
• Small responses are not compressed (setting up the compressor costs more than it saves)
• SSE (text/event-stream) is not compressed (it would be held back and arrive late)

Blocking bots#

If you only need to tell them apart, splitting the access log is enough (Logging). To block them, declare it.

before(BotBlocker.forbidden());                          // return 403
before(BotBlocker.of(context -> context.response().redirect("/")));   // return whatever you like

What is not here#

Stopping#

It does not stop dead. stop() goes in this order.

1. Mark itself as stopping — Shutdown.isStopping() becomes true. Ordinary requests are still served
2. Wait server.shutdown_grace (default 0)
3. Refuse new requests (503)
4. Wait for the in-flight ones to finish, up to server.shutdown_timeout (default 15 seconds)
5. Stop the server

On SIGTERM this runs by itself (that is what a container sends, and then it waits).

Take the health check down first#

jimble does not provide a health check route. Write it like this.

get("/health_check", context ->
	context.response().send(Shutdown.isStopping() ? 503 : 200));

The running marker (RUNNING_PID_{port})#

Once it is listening, jimble puts a file named like RUNNING_PID_8080 in the directory that holds the application jar. Its content is the process ID. It is removed when stop() completes (SIGTERM included).

kill $(cat /opt/app/RUNNING_PID_8080)   # stop it
test -f /opt/app/RUNNING_PID_8080       # is it running?

• The port number is part of the name, so several servers started from the same directory do not erase each other's marker
• When not running from a jar (jimbleRun, tests) nothing is written. The place is "the jar's directory", and there is no jar to sit next to
• If a marker from the previous run is still there (kill -9, power loss), it warns and overwrites. Startup is not blocked
• If it cannot be written (read-only directory, for instance) it warns and keeps listening

Making jimble the proxy#

The other way round: jimble can forward on to another server.

install(() -> ReverseProxy.mount("/api", "http://backend:8080"));

X-Forwarded-For is appended to the existing value (not overwritten). The timeouts are proxy.connect_timeout (5 seconds) and proxy.request_timeout (30 seconds), and a forward that fails returns 502.

The body has no total limit by default so large downloads and SSE are not cut off midway. The path is re-encoded segment by segment, and a path containing . or .. gets 400 (so a request cannot climb out of the base URL's path).

The equivalents of nginx's proxy_set_header and friends#

Pass a configured proxy to mount. Finish the configuration before mount (changing it after it has handled a request throws).

install(() -> ReverseProxy.mount("/shop", new ReverseProxy("http://shop:9000")
	.preserveHost()                                     // proxy_set_header Host $http_host
	.setHeader("X-App", "front")                        // proxy_set_header X-App front
	.setHeader("X-User", context -> userId(context))    // value built from the request (null: not sent)
	.removeHeader("Cookie")                             // proxy_set_header Cookie ""
	.hideResponseHeader("X-Powered-By")                 // proxy_hide_header X-Powered-By
	.redirect("http://shop.internal/", "/shop/")        // proxy_redirect http://shop.internal/ /shop/
	.cookieDomain("shop.internal", "example.com")       // proxy_cookie_domain shop.internal example.com
	.cookiePath("/", "/shop/")));                       // proxy_cookie_path / /shop/