dns-sync/examples/plugin_template/README.md

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.