This version is still in development and is not considered stable yet. For the latest stable version, please use ol.protocol53 0.0.1!

ol.protocol53

One Clojure API for managing DNS records across providers.

ol.protocol53 gives Clojure applications one provider-independent API for querying and changing DNS records. Applications can switch DNS services without changing their record-management code.

The shared API lives in api/. Provider integrations live in providers/ and translate the common operations into each service’s API. Protocol53 supports:

retrieving records from a zone
adding records
creating or replacing whole RRsets
removing matching records
listing available zones

Provider capabilities and limitations vary, but applications use the same core abstractions across every supported integration.

Project status: Experimental.

Available Providers

Installation

Add the provider you need; it includes the shared API transitively:

{:deps {com.outskirtslabs/protocol53-cloudflare {:mvn/version "0.0.1"}}}

For the API alone:

{:deps {com.outskirtslabs/protocol53 {:mvn/version "0.0.1"}}}

Quick Start

Create a provider, then pass it to the common operations with a time budget:

(require '[ol.protocol53 :as protocol53]
         '[ol.protocol53.cloudflare :as cloudflare])
(import '[java.time Duration])

(def dns
  (cloudflare/provider {:api-token (System/getenv "CLOUDFLARE_API_TOKEN")}))

(protocol53/append-records!
 dns
 "example.com"
 [{:name "_acme-challenge"
   :type "TXT"
   :ttl  60
   :data "challenge-token"}]
 {:timeout (Duration/ofSeconds 10)})

Operations return either :ol.protocol53/result or :ol.protocol53/error; expected provider failures do not throw.

Documentation

Scope

ol.protocol53 targets common DNS record operations rather than every provider-specific feature. DNS record types and provider APIs vary too much for a universal abstraction, so Protocol53 focuses on the operations applications use across providers.

Related Projects

ol.clave is Outskirts Labs' ACME client for automated HTTPS certificate management. ACME DNS-01 validation needs temporary TXT records, which Protocol53 can manage across its supported DNS providers. A direct Clave adapter remains future work.

Development

Run commands inside the Nix devshell:

bb qa
bb artifacts
bb jar:all
bb gen-docs

Jars are written to target/. bb jar builds the API; bb jar:providers cloudflare desec builds selected providers. Module deps.edn files supply artifact metadata and versions. Local builds can package providers before the API exists on Clojars; deployment requires released Maven dependency coordinates and annotated artifact tags.

Maintainers: follow the release workflow in AGENTS.md.

License

Distributed under the MIT license.