Merge pull request #9 from worryboy/feature/containerize-schlundtech

Feature/containerize schlundtech

Author: worryboy

.dockerignore

@@ -1,5 +1,6 @@
 .git
 .env
+.env.dns
 state/*
 !state/.gitkeep
 logs/

CHANGELOG.md

@@ -1,7 +1,12 @@
 # Changelog
 
-## 0.4.0 - Traefik/CrowdSec Example
+## 0.4.0 - Provider Interface And Traefik/CrowdSec Example
 
+- Separated generic worker flow from DNS provider/interface code.
+- Made the current provider/interface explicit: InterNetX / AutoDNS / SchlundTech-related DNS via the InterNetX XML interface.
+- Added InterNetX XML as the first concrete provider implementation behind the provider contract.
+- Added provider documentation for InterNetX XML `auth_session` configuration and limits.
+- Added a lightweight verification design note for provider checks, optional public resolver checks, and optional local resolver checks.
 - Added a dedicated Traefik/CrowdSec DynDNS example for one-host / many-hostname deployments.
 - Added `.env.dns.example` and wired the example compose file to `.env.dns` to keep DNS settings separate from the Traefik/CrowdSec stack `.env`.
 - Documented how the example extends, but does not replace, the goNeuland Traefik/CrowdSec guide and migration note.

Dockerfile

@@ -7,18 +7,19 @@ LABEL org.opencontainers.image.title="InterNetX DynDNS" \
       org.opencontainers.image.version="${APP_VERSION}" \
       org.opencontainers.image.vendor="worryboy"
 
-RUN apk add --no-cache \
-        ca-certificates \
-        libcurl \
-        libxml2 \
-    && apk add --no-cache --virtual .build-deps \
+WORKDIR /app
+
+RUN set -eux; \
+    apk add --no-cache --virtual .phpize-deps \
         $PHPIZE_DEPS \
         curl-dev \
-        libxml2-dev \
-    && docker-php-ext-install curl dom \
-    && apk del .build-deps
-
-WORKDIR /app
+        libxml2-dev; \
+    docker-php-ext-install -j"$(nproc)" curl dom; \
+    apk add --no-cache \
+        ca-certificates \
+        libcurl \
+        libxml2; \
+    apk del --no-network .phpize-deps
 
 COPY . /app
 

README.Docker.md

@@ -2,10 +2,15 @@
 
 Containerized InterNetX DynDNS worker for IPv4/IPv6-aware DNS updates.
 
-This image runs as a long-lived outbound-only worker. It detects the current public IPv4 and/or IPv6 address once per cycle, validates one configured `TARGET_HOST` or multiple `TARGET_HOSTS`, and updates existing `A` and `AAAA` records through the InterNetX/AutoDNS XML API when the address changes.
+This image runs as a long-lived outbound-only worker. It detects the current public IPv4 and/or IPv6 address once per cycle, validates one configured `TARGET_HOST` or multiple `TARGET_HOSTS`, and updates existing `A` and `AAAA` records through the current DNS provider interface when the address changes.
 
 Current release: `0.4.0`
 
+Current provider: InterNetX / AutoDNS / SchlundTech-related DNS.
+Current interface: InterNetX XML with `auth_session`.
+
+The worker core is separated from provider/interface code. Provider-specific configuration and limits for the current InterNetX XML support live in [docs/providers/internetx-xml.md](docs/providers/internetx-xml.md).
+
 Source code is available on GitHub: [worryboy/internetx-dyndns](https://github.com/worryboy/internetx-dyndns)
 Container image is available on Docker Hub: [worryboy/internetx-dyndns](https://hub.docker.com/r/worryboy/internetx-dyndns)
 
@@ -29,6 +34,8 @@ This project is container-only. The image only needs outbound HTTPS access to:
 
 No inbound ports are required. The worker does not listen on any port, and no `ports:` mapping is needed.
 
+Future providers or future interfaces of the same provider can be added behind the provider layer without changing the container runtime model.
+
 ## Image Tags
 
 - `worryboy/internetx-dyndns:0.4.0` - versioned release
@@ -305,6 +312,8 @@ Example and documentation release:
 - dedicated Traefik/CrowdSec DynDNS example
 - DNS-specific `.env.dns` separation for the example
 - reference alignment with the goNeuland Traefik/CrowdSec guide
+- provider/interface separation with InterNetX XML as the current implementation
+- provider documentation for current InterNetX XML configuration and limits
 - `PUSHOVER_LOCATION_PREFIX` examples for IP change notifications
 
 ### 0.3.0

README.md

@@ -2,7 +2,12 @@
 
 `InterNetX DynDNS` is a containerized PHP worker that keeps one explicitly configured DNS host in sync with the current public IP address of the machine or network running the container.
 
-The worker uses the InterNetX/AutoDNS XML gateway. The default live XML API endpoint remains `https://gateway.autodns.com`, which is current provider API terminology. Runtime API calls use the documented XML `auth_session` flow: create a session, reuse its hash for this run, then close it.
+Current provider: InterNetX / AutoDNS / SchlundTech-related DNS.
+Current interface: InterNetX XML.
+
+The default live XML API endpoint remains `https://gateway.autodns.com`. Runtime API calls use the XML `auth_session` flow: create a session, reuse its hash for this run, then close it.
+
+The generic worker flow is separated from the DNS provider/interface implementation. Provider-specific details for the current InterNetX XML support are documented in [docs/providers/internetx-xml.md](docs/providers/internetx-xml.md). Future providers, or a future InterNetX interface such as JSON, can be added behind the provider layer without rewriting the worker core.
 
 Source code is available on GitHub: [worryboy/internetx-dyndns](https://github.com/worryboy/internetx-dyndns)
 Container image is available on Docker Hub: [worryboy/internetx-dyndns](https://hub.docker.com/r/worryboy/internetx-dyndns)
@@ -188,9 +193,10 @@ Before running live updates, check the zone for every configured target:
 | `HTTP_REQUEST_TIMEOUT` | optional runtime/debug | No | Total HTTP request timeout for IP and XML requests. | `20` |
 | `LOG_TARGET` | optional runtime/debug | No | PHP stream or file path for logs. | `php://stdout` |
 
-`INTERNETX_SYSTEM_NS` is not part of XML authentication and is not required for the normal update path. InterNetX documents `system_ns` on the Zone object as the first system-managed nameserver, and ZoneInfo examples may include it. If set, this worker sends it as `<system_ns>` in the read-only ZoneInfo request. Normal DynDNS users usually leave it unset.
+`INTERNETX_*` settings are provider-specific for the current InterNetX XML interface. `INTERNETX_SYSTEM_NS` is not part of XML authentication and is not required for the normal update path. InterNetX documents `system_ns` on the Zone object as the first system-managed nameserver, and ZoneInfo examples may include it. If set, this worker sends it as `<system_ns>` in the read-only ZoneInfo request. Normal DynDNS users usually leave it unset.
 
 There are no optional advanced authentication settings in the current worker. Credentials are used for `AuthSessionCreate` and `AuthSessionDelete`; zone inquiry and update requests use `<auth_session><hash>...</hash></auth_session>`.
+See [docs/providers/internetx-xml.md](docs/providers/internetx-xml.md) for the provider-specific InterNetX XML configuration notes.
 
 ## Safe Local Validation
 
@@ -290,7 +296,7 @@ Example dry-run startup:
 [2026-04-23T08:00:02+00:00] INFO IPv6 detection disabled by configuration attempted=false
 [2026-04-23T08:00:02+00:00] SUCCESS Public IP detection completed with at least one usable address ipv4_detected=true ipv6_detected=false
 [2026-04-23T08:00:03+00:00] DEBUG Runtime stage entered stage=authentication/session preflight dry_run=true mutation_allowed=false live_mutation_attempted=false
-[2026-04-23T08:00:03+00:00] INFO Starting InterNetX authentication/session preflight auth_flow=auth_session session_create_task_code=1321001 mutation_allowed=false
+[2026-04-23T08:00:03+00:00] INFO Starting DNS provider authentication/session preflight provider=InterNetX provider_interface=XML auth_flow=auth_session mutation_allowed=false
 [2026-04-23T08:00:03+00:00] DEBUG InterNetX XML request prepared operation=AuthSessionCreate task_code=1321001 api_call_type=auth_session_create stage=authentication/session preflight mutation=false dry_run=true auth_mode=session_create session_established=false payload=<request>...</request>
 [2026-04-23T08:00:03+00:00] DEBUG InterNetX XML response received operation=AuthSessionCreate task_code=1321001 api_call_type=auth_session_create stage=authentication/session preflight mutation=false dry_run=true auth_mode=session_create session_established=false http_status=200 transport_success=true response_result_status_code=S1321001 response_result_status_type=success stid=20260423-app1 api_business_success=true payload=<response>...</response>
 [2026-04-23T08:00:03+00:00] SUCCESS InterNetX session created auth_mode=auth_session session_hash=9b4b...73dd session_persisted=false
@@ -325,6 +331,10 @@ The session hash is treated as a secret. It is kept only in memory, never persis
 
 The updater does not create missing DNS records. If IPv4 is enabled and detected, the target `A` record must already exist. If IPv6 is enabled and detected, the target `AAAA` record must already exist too.
 
+## Verification Direction
+
+The current primary check is provider-side ZoneInfo before update decisions. A future verification pass should stay staged and optional: provider check first, configurable public resolver checks second, and local resolver checks only as a convenience. See [docs/design/verification.md](docs/design/verification.md).
+
 ## Docker-Compatible Runtime
 
 Build and run continuously:
@@ -385,10 +395,14 @@ docker compose version
 - [`VERSION`](VERSION)
 - [`CHANGELOG.md`](CHANGELOG.md)
 - [`README.Docker.md`](README.Docker.md)
-- [`src/Config.php`](src/Config.php)
-- [`src/XmlGatewayClient.php`](src/XmlGatewayClient.php)
-- [`src/PublicIpResolver.php`](src/PublicIpResolver.php)
-- [`src/DynDnsService.php`](src/DynDnsService.php)
+- [`src/Core/DynDnsService.php`](src/Core/DynDnsService.php)
+- [`src/Core/PublicIpResolver.php`](src/Core/PublicIpResolver.php)
+- [`src/Config/Config.php`](src/Config/Config.php)
+- [`src/Provider/DnsProvider.php`](src/Provider/DnsProvider.php)
+- [`src/Provider/InterNetX/InterNetXXmlProvider.php`](src/Provider/InterNetX/InterNetXXmlProvider.php)
+- [`src/Provider/InterNetX/InterNetXXmlGatewayClient.php`](src/Provider/InterNetX/InterNetXXmlGatewayClient.php)
+- [`docs/providers/internetx-xml.md`](docs/providers/internetx-xml.md)
+- [`docs/design/verification.md`](docs/design/verification.md)
 - [`.env.example`](.env.example)
 - [`docker-compose.yml`](docker-compose.yml)
 - [`Dockerfile`](Dockerfile)

bin/dyndns.php

@@ -37,7 +37,7 @@
     $config->connectTimeout(),
     $config->requestTimeout()
 );
-$gateway = new XmlGatewayClient($config, $logger);
+$provider = new InterNetXXmlProvider(new InterNetXXmlGatewayClient($config, $logger));
 $pushover = new PushoverNotifier(
     $logger,
     $config->pushoverAppKey(),
@@ -46,7 +46,7 @@
     $config->connectTimeout(),
     $config->requestTimeout()
 );
-$service = new DynDnsService($config, $logger, $stateStore, $resolver, $gateway, $pushover);
+$service = new DynDnsService($config, $logger, $stateStore, $resolver, $provider, $pushover);
 
 $exitCode = $service->runOnce();
 exit($exitCode);

docs/design/verification.md

@@ -0,0 +1,11 @@
+# Verification Notes
+
+Provider-side validation is the primary check for this worker. The current InterNetX XML implementation reads the provider zone with ZoneInfo before deciding whether a live update is needed.
+
+A later verification feature should stay lightweight and staged:
+
+1. Provider check: read the authoritative provider state after update when the provider interface supports it.
+2. Optional public resolver check: query configured public resolvers to see whether the new value is visible outside the provider.
+3. Optional local resolver check: query the local resolver only as an operator convenience.
+
+Local DNS lookup alone is not enough to prove propagation or provider-side correctness. Public resolver checks should be configurable because TTLs, resolver caches, and split DNS can make immediate results noisy.

docs/providers/internetx-xml.md

@@ -0,0 +1,51 @@
+# InterNetX XML Provider
+
+Current provider: InterNetX / AutoDNS / SchlundTech-related DNS service.
+Current interface: XML.
+
+The worker uses the XML `auth_session` flow:
+
+- create a session with username, password, and context
+- use the session hash for read-only ZoneInfo and live ZoneUpdate requests
+- close the session at the end of the cycle
+
+## Required Env
+
+```env
+INTERNETX_HOST=https://gateway.autodns.com
+INTERNETX_USER=your-api-user
+INTERNETX_PASSWORD=your-api-password
+INTERNETX_CONTEXT=9
+```
+
+Target selection still belongs to the generic worker config:
+
+```env
+TARGET_HOST=dyndns.example.com
+```
+
+or:
+
+```env
+TARGET_HOSTS=app1.example.com,app2.example.com
+```
+
+## Optional Provider Env
+
+```env
+INTERNETX_SYSTEM_NS=ns.example.com
+```
+
+`INTERNETX_SYSTEM_NS` maps to the XML Zone object field `<system_ns>` during read-only zone inquiry. Most DynDNS runs leave it unset.
+
+## Context Handling
+
+`INTERNETX_CONTEXT` is required for the current XML session login. This project defaults the example value to `9`, matching the existing working setup. If your InterNetX/AutoDNS account uses a different context, set it explicitly.
+
+## Assumptions And Limits
+
+- The worker updates existing `A` and `AAAA` records; it does not create missing records.
+- The XML templates `request-get.xml` and `request-put.xml` are still used for ZoneInfo and ZoneUpdate.
+- `DRY_RUN=true` permits read-only provider validation but blocks live mutation.
+- The session hash is kept only in memory and is redacted in debug logs.
+- Future InterNetX interfaces, for example JSON, should be added as a separate provider interface implementation rather than changing the XML client in place.

src/Config.php src/Config/Config.phpsrc/Config.php renamed to src/Config/Config.php

@@ -328,7 +328,7 @@ public function checkInterval(): int
         return $this->checkInterval;
     }
 
-    public function validateForGateway(): void
+    public function validateProviderConfig(): void
     {
         $required = array(
             'INTERNETX_HOST' => $this->host,