Liking cljdoc? Tell your friends :D

Configuration

Busker is configured with an ordinary Clojure map.

The same config shape is used when starting a server with ol.busker/start! and when changing a running server with ol.busker/reload!. You can write that map directly or generate it from environment variables, files, a database, or other application state. It’s just data.

When Busker starts or reloads, it turns your config map into a normalized config snapshot. A snapshot is the effective config after defaults are applied.

A running server is backed by a runtime generation. A generation is the set of runtime resources built from one snapshot. For example, it includes open sockets, worker threads, native protocol state, handlers, and TLS automation state.

On reload, Busker builds a new generation while the current one keeps serving traffic. If the new generation starts successfully, new connections and requests move to it. The old generation stops accepting new work and drains the connections and requests it is already handling. If the new generation fails to start, the old generation keeps serving traffic.

A minimal HTTP config with HTTP/1.1, HTTP/2, and automatic gzip/zstd/brotli compression is:

{:entrypoints {:http {:bind "127.0.0.1:8080"
                      :tls false}}
 :dispatch    [{:handler (fn [_req]
                           {:status 200
                            :headers {"content-type" "text/plain"}
                            :body "ok"})}]}

That’s how you would use Busker when coming from traditional Clojure ring-adapters like Jetty or http-kit.

A minimal HTTP+HTTPS config with HTTP/1.1, HTTP/2, HTTP/3, automatic gzip/zstd/brotli compression, and certificates obtained and renewed automatically is:

{:tls         {:certificates {:manage ["example.com"]}}
 :entrypoints {:http {:bind ":80"
                      :tls  false}
               :https {:bind ":443"}}
 :dispatch    [{:handler (fn [_req]
                           {:status 200
                            :headers {"content-type" "text/plain"}
                            :body "ok"})}]}

Note the addition of the example.com domain, that is required so Busker can manage the certificate lifecyle for you.

An entrypoint names one or more network listeners and the protocols they accept.

A dispatcher is one ordered step in the request pipeline that can match, transform, or handle requests for one or more entrypoints. In conventional Clojure programs there is usually only a single dispatcher: the Ring handler.

Busker accepts the following top-level config keys.

:entrypoints and :dispatch are required. Other keys are optional and either use their documented default or remain unset.

keyvalue

:entrypoints

Map of entrypoint ids to entrypoint maps (see below).

:dispatch

Ordered vector of dispatcher maps (see below).

:tls

Global TLS, certificate, ACME, and session ticket config (see below).

:n-workers

Positive integer event loop worker count. The default is half the processors available to the JVM, rounded down, at least 2 and at most 8.

:worker-hot-poll-micros

Non-negative integer, default 0. Longest time in microseconds that a worker with live requests polls for new work before it sleeps. 0 disables the poll. A positive value such as 50 lowers latency when handlers finish inside it, and costs up to that much worker CPU per idle gap.

:request-threads

:per-request (default) or :reuse-within-connection. :per-request runs every request on a new virtual thread. :reuse-within-connection lets quick requests of one connection run one after another on one virtual thread, which can help many quick HTTP/2 and HTTP/3 requests per connection on machines with many CPUs. Anything bound to the thread then stays for the next request of that connection. See Sharing virtual threads within a connection.

:max-connections

Positive integer connection cap, default 1024.

:output-buffer-size

Positive response byte budget and native streaming block size, default 32768. Zero is invalid.

:fixed-response-max-body-size

Largest body in bytes that a fixed-response slot takes, 1 to Integer/MAX_VALUE, default 32768. The limit is the smaller of this and :output-buffer-size. See Output storage and backpressure.

:fixed-response-slots

Fixed-response slots per worker, 1 to 65535, default 256. See Output storage and backpressure.

:large-response-head-warnings?

Boolean, default true. Logs at most one :ol.busker.response/large-head warning a minute for response heads that do not fit a fixed-response slot.

:server-name

Server header value, default "ol.busker/dev".

:proxy-status-identity

Optional Proxy-Status identity.

:max-request-entity-size

Optional positive integer request body byte limit.

:max-delegations

Optional positive integer internal delegation limit.

:max-reprocesses

Optional positive integer internal reprocess limit.

:handshake-timeout

Optional TLS handshake timeout in milliseconds.

:max-spare-pipes

Optional non-negative idle pipe cache limit.

:http1-req-timeout

Optional HTTP/1.1 request timeout in milliseconds.

:http1-req-io-timeout

Optional HTTP/1.1 request I/O timeout in milliseconds. See HTTP/1 streaming timeouts.

:http1-upgrade?

Allow h2c upgrade, default true.

:http1-req-io-timeout-while-generating?

Also run :http1-req-io-timeout while a response waits for the application’s next output, default false. See HTTP/1 streaming timeouts.

:http2-idle-timeout

Optional HTTP/2 idle timeout in milliseconds.

:http2-graceful-shutdown-timeout

Optional HTTP/2 graceful shutdown timeout in milliseconds.

:http2-max-streams

Optional positive integer concurrent HTTP/2 stream limit.

:http2-max-requests

Optional positive integer concurrent HTTP/2 request limit.

:http2-max-streaming-requests

Optional positive integer streaming request limit.

:http2-max-priority-streams

Optional positive integer priority stream tracking limit.

:http2-stream-window-size

Optional positive integer per-stream window bytes.

:http2-dos-delay

Optional suspicious behavior delay in milliseconds.

:http3-idle-timeout

Optional HTTP/3 idle timeout in milliseconds.

:http3-graceful-shutdown-timeout

Optional HTTP/3 graceful shutdown timeout in milliseconds.

:http3-stream-window-size

Optional positive integer per-stream window bytes.

:http3-ack-frequency

Optional non-negative ACK frequency; 0 uses the QUIC default.

:compress?

Enable response compression, default true.

:compress-min-size

Minimum response bytes for compression, default 100.

:compress-gzip-level

Gzip level 0 through 9, default 1.

:compress-brotli-level

Brotli level 0 through 11, default 1.

:compress-zstd-level

Zstandard compression level, default 3.

Output storage and backpressure

Each worker reserves 256 blocks of :output-buffer-size bytes of native streaming storage at startup: 8 MiB per worker at the default 32768 bytes. The size is at most Integer/MAX_VALUE. Busker manages the pools and rejects a :buffer-pool key. Each response may have at most :output-buffer-size pending payload bytes, at most 64 pending body receipts, and one native send of at most that size. A small nonempty write uses a whole block at first. Protocol and compression buffers and request metadata cost memory in addition.

Each worker also has :fixed-response-slots fixed-response slots for complete responses whose body fits both :output-buffer-size and :fixed-response-max-body-size, and whose head fits 64 header pairs and 16384 staging bytes. Other responses use streaming storage. A slot takes about 16384 + L + 2150 bytes, where L is the smaller of the two sizes, so the default 256 slots take about 12.5 MiB per worker. When every slot of a worker is in use, a fixed response waits for a free one. A reload with other sizes builds new slots, and the previous generation keeps its slots while it drains.

Blocking emitter calls park under pressure and nonblocking calls return full. flush! and close! need no block, receipt or mailbox space.

HTTP/1 streaming timeouts

:http1-req-io-timeout (default 5000) limits how long HTTP/1 request I/O may make no progress: receipt of the request and its body, and each response write that the client does not read. By default it does not run while the application has nothing to send, so a silent HTTP/1 stream, such as an SSE stream between events, stays open. With :http1-req-io-timeout-while-generating? set to true, the timeout also runs while a streaming response waits for the application, so the server closes an HTTP/1 stream that stays silent longer than the timeout. Every HTTP/1 stream that should stay open then needs a heartbeat at least that often.

:http2-idle-timeout applies only while an HTTP/2 connection has no response waiting for the application, so a silent HTTP/2 stream stays open. An HTTP/3 connection closes when it receives no packet for :http3-idle-timeout (default 30000) or the client’s idle limit, whichever is shorter. A silent HTTP/3 stream stays open only while the client sends packets or acknowledges server heartbeats.

Heartbeats also let on-close! run promptly after an idle HTTP/1 client goes away (see When an idle HTTP/1.1 client disconnects), and keep proxies and clients with idle limits from closing the stream. An SSE heartbeat sends comment bytes such as ":\n\n" with {:wait? false :flush? true}. An empty write or a flush alone is not a heartbeat. Choose the interval from the shortest idle limit between the server and the client. Keep at most one heartbeat receipt pending, and skip a heartbeat while one is pending or admission returns full.

Entrypoints (:entrypoints)

Entrypoints describe how traffic enters Busker.

Each entrypoint gives a stable id to one or more bind addresses and the protocol and TLS settings used by those listeners. The id exists so other config sections can refer to the entrypoint without repeating host and port details.

:entrypoints in the top-level config is a map from keyword entrypoint ids to maps:

{:entrypoints {:plain {:bind ["127.0.0.1:8080" "[::1]:8080"]
                       :tls false}
               :secure {:bind ":8443"}}}

The ids (:plain and :secure above) are arbitrary user-defined keywords.

  • :bind is a string or non-empty vector of strings. TCP and UDP bind forms are ":8080", "host:8080", and "[::1]:8080". Unix domain sockets use pathname form "unix:/path.sock" or abstract namespace form "unix:@abstract-name".

  • :tls is false for cleartext or a map to enable TLS. A TLS entrypoint requires top-level :tls :certificates :load or :tls :certificates :manage. Entrypoint-local TLS settings use the same keys as top-level :tls, but certificate material remains top-level.

  • :http1? and :http2? default to true.

  • :http3? defaults to true when TLS is enabled and false otherwise. HTTP/3 requires TLS and is not supported on Unix domain sockets.

Dispatchers (:dispatch)

Dispatchers describe what Busker does with each request after it arrives.

Busker evaluates them in order, optionally restricting them by entrypoint, match predicate, group, middleware, and terminal behavior.

:dispatch in the top-level config is an ordered vector of dispatcher maps.

For conventional Clojure programs, the most common shape is a single dispatcher that points at one Ring handler. Start with this unless one server needs multiple entrypoint-specific or staged request pipelines.

{:dispatch [{:handler your-ring-handler}]}

Advanced use-cases can add entrypoint filters, match predicates, mutually exclusive groups, middleware, and terminal behavior. This is useful when using Busker as an application router or reverse-proxy-style edge, where one server routes different traffic classes before handing each request to the appropriate Ring handler or upstream:

{:dispatch [{:entrypoints #{:secure}
             :group :site
             :match my.app/api-request?
             :middleware [[my.app/wrap-audit {:mode :strict}]
                          my.app/wrap-auth]
             :handler my.app/handler
             :terminal? true}]}
  • :entrypoints - Optional set of entrypoint ids where the dispatcher may run (default: all entrypoints).

  • :group - Optional key that allows only the first matching dispatcher in the group (default: none).

  • :match - Optional predicate of the current request (default: match every request).

  • :middleware - Vector of middleware functions, symbols, or [middleware opts] entries (default: []).

  • :handler - Handler function for the dispatcher (default: {:status 200}).

  • :terminal? - Return the handler result immediately when true (default: false).

Function references in :match, :handler, and :middleware may be direct functions or qualified symbols.

Middleware entries are Ring-style wrapper functions. [wrap opts] calls (wrap handler opts), and a bare wrap calls (wrap handler).

Non-terminal dispatcher results become the current value for later dispatchers, so dispatchers can act as request transforms before a terminal handler returns a Ring response.

TLS (:tls, top-level)

The top-level TLS config describes how Busker terminates encrypted traffic, finds certificate material, and runs certificate automation for TLS entrypoints.

:tls in the top-level config is a map of options:

  • :certificates - Map of certificate sources and managed names; see below (default: none).

  • :storage - Storage instance or storage factory map; see Storage factory map below (default: Clave file storage for managed certificates).

  • :issuers - Vector of issuer maps; see Issuer maps below (default: Let’s Encrypt production).

  • :issuer-selection - ACME issuer choice strategy, :in-order or :shuffle (default: :in-order).

  • :key-type - Certificate key algorithm (default: :p256).

  • :key-reuse - Reuse private keys when renewing certificates (default: false).

  • :cache-capacity - Positive integer certificate cache capacity (default: 1000).

  • :solvers - ACME challenge solver map; see Solvers below (default: Busker-managed :http-01 for managed certificates).

  • :ocsp - OCSP option map; see OCSP map below (default: none).

  • :config-fn - Function or qualified symbol returning per-subject/per-domain overrides (default: none).

  • :http-client - HTTP client option map for ACME requests (default: none).

  • :tls-compatibility-mode - TLS cipher/protocol preset, :modern or :intermediate (default: :modern).

  • :session-tickets - Session ticket map; see Session ticket map below (default: enabled in memory).

Certificates map (:tls :certificates)

The :certificates map contains:

  • :load - Vector of static certificate source maps (default: []).

    • :type - Source type, either :pem or :folder (required).

    • :cert-file - PEM certificate chain path for :pem sources.

    • :key-file - PEM private key path for :pem sources.

    • :path - Directory path for :folder sources.

  • :manage - Vector of subject names (domain names) Busker should obtain and renew automatically (default: []).

    • Entries are strings such as "example.com" or "*.example.com".

Static sources in :load are read during startup and reload. Busker extracts subject names from each certificate and uses SNI to choose a matching static certificate during the TLS handshake. If there is no SNI match, Busker falls back to the first loaded static certificate.

Subject names in :manage are handed to Clave certificate automation. Busker starts the automation machinery during startup and reload, stores issued certificates in TLS storage, and uses SNI to look them up during TLS handshakes. Certificate lifecycle work such as obtain, renewal, and OCSP maintenance operates in the background.

Obtain certificates automatically
{:tls {:certificates {:manage ["example.com" "www.example.com"]}}}
Load certificates from files
{:tls {:certificates {:load [{:type :pem
                              :cert-file "example.com/fullchain.pem"
                              :key-file "example.com/privkey.pem"}]}}}

Storage factory map (:tls :storage)

The :storage key may be a ol.clave.storage/Storage instance or a factory map.

When omitted, managed certificate automation uses ol.clave.storage.file/file-storage with its no-arg default root.

The Clave default is to use <dir>/ol.clave, where <dir> is $STATE_DIRECTORY (for systemd usage) or $XDG_DATA_HOME. While often not necessary, you can configure this explicitly.

When used as a map :storage contains:

  • :factory - Function or qualified symbol returning an ol.clave.storage/Storage implementation (required).

  • factory-specific keys - Options passed to the factory (default: none). For the built-in filesystem storage factory, see ol.clave.storage.file/file-storage. Its options include :root, a root directory string or java.nio.file.Path.

Issuer maps (:tls :issuers)

The :issuers vector contains maps:

  • :directory-url - ACME directory URL (required).

  • :email - Contact email for certificate notifications (default: none).

  • :eab - External account binding credentials for restricted CAs (default: none).

OCSP map (:tls :ocsp)

The :ocsp map contains:

  • :enabled? - Enable OCSP stapling (default: true).

  • :must-staple? - Require OCSP must-staple in certificates (default: false).

Session ticket map (:tls :session-tickets)

The :session-tickets map contains:

  • :disabled? - Disable session ticket resumption when true (default: false).

  • :persistence - Session ticket persistence mode, :memory or :storage (default: :memory).

    • :storage persistence requires top-level :tls :storage.

  • :max-keys - Maximum number of ticket keys retained in rotation (default: 4).

  • :lifetime-seconds - TLS session ticket lifetime in seconds (default: 86400).

Solvers (:tls :solvers)

Solvers describe how ACME challenge records are presented and cleaned up while Busker obtains managed certificates.

Busker provides an integrated :http-01 solver by default. It serves /.well-known/acme-challenge/…​ through the Ring handler pipeline. Busker does not provide :dns-01 or :tls-alpn-01 by default; add those to :solvers when needed.

The :solvers map contains additional Clave solver entries keyed by challenge type:

  • :http-01 - HTTP challenge solver for public HTTP validation. Busker always replaces the value of this key with its integrated solver.

  • :dns-01 - DNS challenge solver for DNS-provider validation. This is required for wildcard names such as "*.example.com".

  • :tls-alpn-01 - TLS ALPN challenge solver for port 443 validation.

To write a custom solver, see ol.clave.certificate and ol.clave.certificate/validate-solvers.

This example adds :dns-01, while Busker still adds its integrated :http-01 solver:

{:tls {:certificates {:manage ["example.com" "*.example.com"]}
       :solvers {:dns-01 my-dns-solver}}}

Can you improve this documentation?Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
←Move to previous article
→Move to next article
Ctrl+/Jump to the search field
× close