# ol.protocol53

> One Clojure API for managing DNS records across providers.

![doc](https://img.shields.io/badge/doc-outskirtslabs-orange.svg)
![status: experimental](https://img.shields.io/badge/status-experimental-red.svg)
![alt=nixbot](https://ci.outskirtslabs.com/repos/github/outskirtslabs/protocol53/badge.svg)

`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](https://docs.outskirtslabs.com/open-source-vital-signs#experimental)**.

## Available Providers

* [Cloudflare](https://docs.outskirtslabs.com/ol.protocol53/next/providers/cloudflare)
* [deSEC](https://docs.outskirtslabs.com/ol.protocol53/next/providers/desec)
* [GoDaddy](https://docs.outskirtslabs.com/ol.protocol53/next/providers/godaddy)
* [Porkbun](https://docs.outskirtslabs.com/ol.protocol53/next/providers/porkbun)

## Installation

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

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

For the API alone:

```clojure
{: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:

```clojure
(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

* [Docs](https://docs.outskirtslabs.com/ol.protocol53/next/)
* [API Reference](https://docs.outskirtslabs.com/ol.protocol53/next/api)
* [Support via GitHub Issues](https://github.com/outskirtslabs/protocol53/issues)

## 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`](https://docs.outskirtslabs.com/ol.clave/next/) 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.

* [Clave documentation](https://docs.outskirtslabs.com/ol.clave/next/)
* [Clave source code](https://github.com/outskirtslabs/clave)

## Development

Run commands inside the Nix devshell:

```shell
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

Copyright (C) 2026 Casey Link mailto:casey@outskirtslabs.com[casey@outskirtslabs.com]

Distributed under the [MIT](https://spdx.org/licenses/MIT.html) license.