ol.clave.ext.aleph

Automatic HTTPS certificates for Aleph listeners.

Add aleph/aleph to your application dependencies; Clave does not pull it in.

Use start-server to run separate HTTP and HTTPS listeners with automatic ACME certificate management. It serves HTTP-01 on the cleartext listener and TLS-ALPN-01 on the HTTPS listener, and renews certificates without restarting either listener.

Call stop to shut the listeners and certificate automation down together.

start-server

(start-server handler {::keys [config] :as opts})

Serves handler with automatically managed HTTPS certificates.

opts are ordinary aleph.http/start-server HTTPS options. The HTTPS listener defaults to port 443. Provide the optional cleartext listener through :ol.clave.ext.aleph/http-options; it defaults to {:port 80} and serves HTTP-01 before applying the optional HTTPS redirect.

Clave configuration belongs under :ol.clave.ext.aleph/config. Calling this function signifies acceptance of the CA’s Subscriber Agreement and Terms of Service.

Clave options:

key description default

key	description	default
`:domains`	Domain names to manage	required
`:redirect-http?`	Redirect non-challenge HTTP requests to HTTPS	`true`
`:challenge-types`	Adapter-managed challenge solvers	`#{:http-01 :tls-alpn-01}`
`:startup-timeout-ms`	Initial certificate timeout, or `nil` to disable	`120000`
`:startup-poll-interval-ms`	Initial certificate polling interval	`100`

:domains

Domain names to manage

required

:redirect-http?

Redirect non-challenge HTTP requests to HTTPS

true

:challenge-types

Adapter-managed challenge solvers

#{:http-01 :tls-alpn-01}

:startup-timeout-ms

Initial certificate timeout, or nil to disable

120000

:startup-poll-interval-ms

Initial certificate polling interval

100

Other configuration keys pass to ol.clave.automation/create. User solvers such as DNS-01 are preserved. A user solver whose type is also in :challenge-types is rejected instead of being silently replaced.

Optional JDK TLS policy belongs under :ol.clave.ext.aleph/tls-options; see ol.clave.ext.netty/ssl-context for supported keys. Required client authentication cannot be combined with adapter-managed TLS-ALPN-01; use HTTP-01 or DNS-01 until separate challenge TLS policy is supported.

Both listeners start before ol.clave.automation/manage-domains. This function blocks until every initial certificate is available or the startup timeout expires.

Returns a map-like Aleph server for stop with :server, :https-server, :http-server, and :system. The result implements java.io.Closeable and aleph.netty/AlephServer, so it works with with-open, aleph.netty/port, and aleph.netty/wait-for-close.

Example:

(require '[ol.clave.ext.aleph :as clave-aleph])

(def server
  (clave-aleph/start-server
   handler
   {:port                      443
    :http-versions             [:http2 :http1]
    ::clave-aleph/http-options {:port 80}
    ::clave-aleph/config
    {:domains ["example.com" "www.example.com"]
     :issuers [{:directory-url "https://acme-v02.api.letsencrypt.org/directory"
                :email         "admin@example.com"}]}}))

;; Renewed certificates are selected by SNI without a restart.

(clave-aleph/stop server)

source

stop

(stop context)

Stops a context returned by start-server.

Stop is idempotent. It first stops certificate automation while challenge listeners remain available, then closes the HTTP and HTTPS listeners.

source