# dns-sync plugin template

This directory is a documentation/example package. dns-sync does not load it
from this location.

Copy it to one of these locations and rename it for the application:

    dns_sync/plugins/adapters/<plugin_name>/

for a built-in plugin, or:

    $DNS_SYNC_PLUGIN_PATH/<plugin_name>/

for an external plugin.

The canonical package layout is:

    <plugin_name>/
    ├── __init__.py
    └── client.py

`__init__.py` is the dns-sync adapter boundary. It owns endpoint discovery,
generic capabilities, native-to-normalized translation, apply, verify, and
optional retirement behavior.

`client.py` is private to the plugin. It owns authentication, transport,
application-specific models, native request/response handling, and endpoint
operations.

## Before enabling a copied plugin

1. Rename `example`, `ExampleClient`, and `ExampleRecord`.
2. Implement `configured_endpoints(config)`.
3. Implement the native client methods.
4. Declare only capabilities the plugin really supports.
5. Implement discovery for those object types.
6. Translate normalized desired state into native state in `apply()`.
7. Re-discover mutations and return the real endpoint-local key.
8. Implement `verify()`.
9. Add `retire()` only when retirement/deletion is safely supported.
10. Add focused adapter/client tests.
11. Validate using read-only reconciliation before enabling mutations.

See the root `README.md` for the complete plugin contract and architecture.