ol.clave.automation
Public API for the ACME certificate automation layer.
The automation layer manages TLS certificate lifecycle automatically: - Obtains certificates for managed domains - Renews certificates before expiration - Handles OCSP stapling - Provides events for monitoring
Quick Start
(require ' [ol.clave.automation :as auto]
' [ol.clave.storage.file :as fs])
;; Create the automation system
(def system (auto/create {:storage (fs/file-storage {:root "/var/lib/acme" })
:issuers [{:directory-url "https://acme-v02.api.letsencrypt.org/directory"
:email "admin@example.com" }]
:solvers {:http-01 my-http-solver}}))
;; Optionally subscribe to bounded lifecycle events before starting
(def events (auto/subscribe-events system))
;; Start the maintenance loop
(auto/start system)
;; Add domains to manage
(auto/manage-domains system ["example.com" ])
;; Look up certificate for TLS handshake
(auto/lookup-cert system "example.com" )
;; Release the subscription and stop the system
(auto/unsubscribe-events system events)
(auto/stop system)
Configuration
The config map supports:
| key | description |
|---|---|
|
Storage implementation (required) |
|
Vector of issuer configs with |
|
|
|
|
|
Reuse private key on renewal (default false) |
|
Map of solver types to implementations |
|
OCSP config with |
|
ARI config with |
|
Max certificates in cache (nil = unlimited) |
|
Function: domain → config overrides |
|
HTTP client options for ACME requests |
create
(create config)
Creates the automation system without starting the maintenance loop.
Returns a system handle that is not yet started.
Throws if configuration is invalid or storage cannot be initialized.
After calling this function you might be interested in subscribe-events and start.
stop
(stop system)
Stops the automation system.
Signals the maintenance loop to stop, waits for in-flight operations, and releases resources.
| key | description |
|---|---|
|
System handle from |
started?
(started? system)
Returns true if the system is in started state.
| key | description |
|---|---|
|
System handle from |
manage-domains
(manage-domains system domains)
Adds domains to management, triggering immediate certificate obtain.
Returns nil on success.
Throws with :errors in ex-data if any domain is invalid.
| key | description |
|---|---|
|
System handle from |
|
Vector of domain names to manage |
unmanage-domains
(unmanage-domains system domains)
Removes domains from management.
Stops renewal and maintenance for these domains. Certificates remain in storage but are no longer actively managed.
| key | description |
|---|---|
|
System handle from |
|
Vector of domain names to unmanage |
lookup-cert
(lookup-cert system hostname)
Finds a certificate for a hostname.
Tries exact match first, then wildcard match. Returns the certificate bundle or nil if not found.
| key | description |
|---|---|
|
System handle from |
|
Hostname to look up |
list-domains
(list-domains system)
Lists all managed domains with status.
Returns a vector of maps with :domain, :status, and :not-after.
| key | description |
|---|---|
|
System handle from |
get-domain-status
(get-domain-status system domain)
Gets detailed status for a specific domain.
Returns a map with :domain, :status, :not-after, :issuer,
:needs-renewal, or nil if domain is not managed.
| key | description |
|---|---|
|
System handle from |
|
Domain name to check |
has-valid-cert?
(has-valid-cert? system domain)
Returns true if the system has a valid certificate for the domain.
| key | description |
|---|---|
|
System handle from |
|
Domain name to check |
subscribe-events
(subscribe-events system)
(subscribe-events system opts)
Creates an independent bounded event subscription.
Every active subscription receives every live event published after it is
created.
Events are not replayed.
The returned java.util.concurrent.LinkedBlockingQueue supports .take,
.poll, and .poll(timeout, unit) directly.
Options:
| key | description | default |
|---|---|---|
|
Any positive queue capacity up to JVM limits |
|
A subscriber that fills its queue receives :subscription-overflow and is
disconnected without affecting automation or other subscribers.
Call unsubscribe-events when the consumer stops before system shutdown.
System shutdown places a :system-stopped event in every active queue.
| key | description |
|---|---|
|
System handle from |
|
Optional subscription options |
unsubscribe-events
(unsubscribe-events system queue)
Removes one event subscription.
The removed queue receives a :subscription-closed event so a blocked
consumer can exit.
This function is idempotent and returns true only when it removes an active
subscription.
| key | description |
|---|---|
|
System handle from |
|
Queue returned by |
renew-managed
(renew-managed system)
Forces renewal of all managed certificates.
Submits renewal commands for every managed certificate in the cache. Commands are submitted asynchronously - this function returns immediately.
Normally certificates are renewed automatically. Use this for testing or when you need to force renewal.
Returns the number of certificates queued for renewal.
| key | description |
|---|---|
|
System handle from |
revoke
(revoke system certificate opts)
Revokes a certificate.
The certificate parameter can be:
- A domain string - looks up the certificate from the cache
- A bundle map - uses the bundle directly
| key | description |
|---|---|
|
System handle from |
|
Domain string or bundle map |
|
Options map (see below) |
Options:
| key | description |
|---|---|
|
When true, deletes certificate files from storage |
|
RFC 5280 revocation reason code (0-6, 8-10) |
Returns {:status :success} on successful revocation,
or {:status :error :message …} on failure.