cloudflare-ddns-sync 4.0.0-beta.2 → 4.0.0-rc.1

package/dist/index.js

@@ -1,58 +1,304 @@
+import { isIP } from 'node:net';
 import CloudflareClient from './lib/cloudflare-client.js';
-import Cron from './lib/cron.js';
-import ipUtils from './lib/ip-utils.js';
-export default class CloudflareDDNSSync {
+import IPUtils from './lib/ip-utils.js';
+import { SyncError } from './lib/sync-error.js';
+import { ScheduledSyncJob, WatchSyncJob } from './lib/sync-job.js';
+const defaultWatchIntervalMs = 10_000;
+const maxTimerDelayMs = 2_147_483_647;
+const recordTypes = new Set(['A', 'AAAA', 'CNAME', 'HTTPS', 'TXT', 'LOC', 'NS', 'SPF', 'CERT', 'DNSKEY', 'DS', 'NAPTR', 'SMIMEA', 'SSHFP', 'SVCB', 'TLSA']);
+export class DdnsError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'DdnsError';
+    }
+}
+export { SyncError };
+export class Ddns {
     cloudflareClient;
-    constructor(auth) {
-        this.cloudflareClient = new CloudflareClient(auth);
+    configuredRecords;
+    zone;
+    resolveIp;
+    jobs = new Set();
+    closed = false;
+    constructor(options = {}) {
+        const { records, zone, resolveIp, ...auth } = options;
+        this.cloudflareClient = new CloudflareClient(resolveAuth(auth));
+        this.zone = normalizeZone(zone);
+        this.resolveIp = resolveIp;
+        this.configuredRecords = records === undefined ? undefined : normalizeRecords(records, this.zone);
     }
-    getIp() {
-        return ipUtils.getIpv4();
+    async sync(first, second = {}) {
+        this.ensureOpen();
+        const { records, options } = getSyncArguments(first, second);
+        validateSyncOptions(options);
+        const selectedRecords = normalizeSyncRecords(this.resolveRecords(records));
+        if (selectedRecords.length === 0) {
+            return [];
+        }
+        return this.cloudflareClient.syncRecords(await this.withContent(selectedRecords, options));
     }
-    getIpv6() {
-        return ipUtils.getIpv6();
+    async plan(first, second = {}) {
+        this.ensureOpen();
+        const { records, options } = getSyncArguments(first, second);
+        validateSyncOptions(options);
+        const selectedRecords = normalizeSyncRecords(this.resolveRecords(records));
+        if (selectedRecords.length === 0) {
+            return [];
+        }
+        return this.cloudflareClient.planRecords(await this.withContent(selectedRecords, options));
     }
-    getRecordDataForDomain(domain) {
-        return this.cloudflareClient.getRecordsByDomain(domain);
+    schedule(expression, options = {}) {
+        this.ensureOpen();
+        const job = new ScheduledSyncJob(this, expression, copyJobOptions(options));
+        this.jobs.add(job);
+        return job;
     }
-    getRecordDataForDomains(domains) {
-        return this.cloudflareClient.getRecordsByDomains(domains);
+    async watch(options = {}) {
+        this.ensureOpen();
+        const copiedOptions = copyWatchOptions(options);
+        const job = new WatchSyncJob(this, copiedOptions, this.dynamicFamilies(this.resolveRecords(copiedOptions.records), copiedOptions));
+        await job.start();
+        this.jobs.add(job);
+        return job;
     }
-    getRecordDataForRecord(record) {
-        return this.cloudflareClient.getRecordDataForRecord(record);
+    async list(filter = {}) {
+        this.ensureOpen();
+        validateListFilter(filter);
+        if ('domains' in filter && filter.domains !== undefined) {
+            const domains = toArray(filter.domains);
+            validateDomains(domains);
+            const grouped = await this.cloudflareClient.getRecordDataForDomains(domains);
+            return filter.groupBy === 'domain' ? grouped : Object.values(grouped).flat();
+        }
+        return this.cloudflareClient.getRecordDataForRecords(this.resolveRecords(filter.records));
     }
-    getRecordDataForRecords(records) {
-        return this.cloudflareClient.getRecordDataForRecords(records);
+    async remove(records) {
+        this.ensureOpen();
+        const selectedRecords = normalizeRecords(records, this.zone);
+        await Promise.all(selectedRecords.map((record) => this.cloudflareClient.removeRecordByNameAndType(record.name, record.type)));
     }
-    removeRecord(recordName, recordType) {
-        return this.cloudflareClient.removeRecordByNameAndType(recordName, recordType);
+    async ip(family = 4) {
+        this.ensureOpen();
+        if (family !== 4 && family !== 6) {
+            throw invalidConfig('IP family must be 4 or 6.');
+        }
+        try {
+            return this.resolveIp ? await this.resolveIp(family) : family === 4 ? await IPUtils.getIpv4() : await IPUtils.getIpv6();
+        }
+        catch (error) {
+            throw new DdnsError('IP_UNAVAILABLE', `Could not determine the public IPv${family} address.`, error);
+        }
     }
-    stopSyncOnIpChange(changeListenerId) {
-        ipUtils.removeIpChangeListener(changeListenerId);
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        await Promise.all([...this.jobs].map(async (job) => job.stop()));
+        this.jobs.clear();
     }
-    syncByCronTime(cronExpression, records, callback, ip) {
-        return Cron.createCronJob(cronExpression, async () => {
-            const result = await this.syncRecords(records, ip);
-            callback(result);
-        });
+    resolveRecords(records) {
+        const selectedRecords = records === undefined ? this.configuredRecords : normalizeRecords(records, this.zone);
+        if (selectedRecords === undefined) {
+            throw invalidConfig('Provide records when creating Ddns or when calling this method.');
+        }
+        return selectedRecords.map((record) => ({ ...record }));
     }
-    async syncOnIpChange(records, callback) {
-        const changeListenerId = await ipUtils.addIpChangeListener(async (ip) => {
-            const result = await this.syncRecords(records, ip);
-            callback(result);
-        });
-        // Sync records to make sure the current ip is already set.
-        const currentIp = await ipUtils.getIpv4();
-        this.syncRecords(records, currentIp).then((syncedRecords) => {
-            callback(syncedRecords);
+    ensureOpen() {
+        if (this.closed) {
+            throw new DdnsError('INVALID_CONFIG', 'This Ddns instance is closed.');
+        }
+    }
+    dynamicFamilies(records, options) {
+        const families = new Set();
+        for (const record of records) {
+            if (record.content) {
+                continue;
+            }
+            if ((record.type === undefined || record.type === 'A') && options.ipv4 === undefined) {
+                families.add(4);
+            }
+            if (record.type === 'AAAA' && options.ipv6 === undefined) {
+                families.add(6);
+            }
+        }
+        return [...families];
+    }
+    async withContent(records, options) {
+        for (const record of records) {
+            if (!record.content && record.type !== 'A' && record.type !== 'AAAA') {
+                throw invalidConfig(`Record "${record.name}" of type ${record.type} requires content.`);
+            }
+        }
+        const families = this.dynamicFamilies(records, options);
+        const addresses = new Map();
+        await Promise.all(families.map(async (family) => {
+            addresses.set(family, await this.ip(family));
+        }));
+        const preparedRecords = records.map((record) => {
+            if (record.content) {
+                return record;
+            }
+            if (record.type === 'A') {
+                return { ...record, content: options.ipv4 ?? addresses.get(4) };
+            }
+            return { ...record, content: options.ipv6 ?? addresses.get(6) };
         });
-        return changeListenerId;
+        for (const record of preparedRecords) {
+            validatePreparedRecord(record);
+        }
+        return preparedRecords;
+    }
+}
+export function createDdns(options = {}) {
+    return new Ddns(options);
+}
+function normalizeRecords(records, zone) {
+    return toArray(records).map((input, index) => {
+        const record = typeof input === 'string' ? { name: input } : { ...input };
+        record.name = normalizeRecordName(record.name, zone);
+        validateRecord(record, `records[${index}]`);
+        return record;
+    });
+}
+function normalizeZone(zone) {
+    if (zone === undefined) {
+        return undefined;
+    }
+    if (typeof zone !== 'string' || zone.trim().length === 0) {
+        throw invalidConfig('zone must be a non-empty domain.');
+    }
+    return zone.toLowerCase();
+}
+function normalizeRecordName(name, zone) {
+    if (!zone) {
+        return name;
+    }
+    if (name === '@') {
+        return zone;
+    }
+    if (!name.includes('.')) {
+        return `${name}.${zone}`;
+    }
+    if (name === zone || name.endsWith(`.${zone}`)) {
+        return name;
+    }
+    throw invalidConfig(`Record "${name}" is outside configured zone "${zone}".`);
+}
+function normalizeSyncRecords(records) {
+    return records.map((record) => ({ ...record, type: record.type ?? 'A' }));
+}
+function getSyncArguments(first, second) {
+    if (first === undefined) {
+        return { options: second };
+    }
+    if (isSyncOptions(first)) {
+        return { options: first };
+    }
+    return { records: first, options: second };
+}
+function isSyncOptions(value) {
+    return !Array.isArray(value) && typeof value === 'object' && !('name' in value) && Object.keys(value).every((key) => key === 'ipv4' || key === 'ipv6');
+}
+function resolveAuth(auth) {
+    if (auth.token !== undefined || auth.key !== undefined || auth.email !== undefined) {
+        if (auth.token && !auth.key) {
+            return { token: auth.token };
+        }
+        if (auth.key?.startsWith('v1.0-') && !auth.token && !auth.email) {
+            return { key: auth.key };
+        }
+        if (auth.key && auth.email && !auth.token) {
+            return { email: auth.email, key: auth.key };
+        }
+        throw invalidConfig('Provide either a Cloudflare API token, an email and API key, or a User Service key.');
     }
-    syncRecord(record, ip) {
-        return this.cloudflareClient.syncRecord(record, ip);
+    const token = process.env.CLOUDFLARE_API_TOKEN;
+    if (!token) {
+        throw invalidConfig('Provide a Cloudflare API token or set CLOUDFLARE_API_TOKEN.');
     }
-    syncRecords(records, ip) {
-        return this.cloudflareClient.syncRecords(records, ip);
+    return { token };
+}
+function validateRecord(record, path) {
+    if (typeof record.name !== 'string' || record.name.trim().length === 0) {
+        throw invalidConfig(`${path}.name must be a non-empty hostname.`);
+    }
+    if (record.type !== undefined && !recordTypes.has(record.type)) {
+        throw invalidConfig(`${path}.type is not supported.`);
+    }
+    if (record.content !== undefined && (typeof record.content !== 'string' || record.content.trim().length === 0)) {
+        throw invalidConfig(`${path}.content must be a non-empty string when provided.`);
+    }
+    if (record.ttl !== undefined && (!Number.isInteger(record.ttl) || record.ttl < 1)) {
+        throw invalidConfig(`${path}.ttl must be a positive integer.`);
+    }
+    if (record.priority !== undefined && (!Number.isInteger(record.priority) || record.priority < 0)) {
+        throw invalidConfig(`${path}.priority must be a non-negative integer.`);
+    }
+}
+function validateSyncOptions(options) {
+    if (options.ipv4 !== undefined && isIP(options.ipv4) !== 4) {
+        throw invalidConfig('ipv4 must be a valid IPv4 address.');
+    }
+    if (options.ipv6 !== undefined && isIP(options.ipv6) !== 6) {
+        throw invalidConfig('ipv6 must be a valid IPv6 address.');
+    }
+}
+function validatePreparedRecord(record) {
+    if (!record.content) {
+        throw invalidConfig(`Record "${record.name}" is missing content.`);
+    }
+    if ((!record.type || record.type === 'A') && isIP(record.content) !== 4) {
+        throw invalidConfig(`Record "${record.name}" requires an IPv4 address.`);
+    }
+    if (record.type === 'AAAA' && isIP(record.content) !== 6) {
+        throw invalidConfig(`Record "${record.name}" requires an IPv6 address.`);
     }
 }
+function validateDomains(domains) {
+    for (const [index, domain] of domains.entries()) {
+        if (typeof domain !== 'string' || domain.trim().length === 0) {
+            throw invalidConfig(`domains[${index}] must be a non-empty domain.`);
+        }
+    }
+}
+function validateListFilter(filter) {
+    const hasRecords = 'records' in filter && filter.records !== undefined;
+    const hasDomains = 'domains' in filter && filter.domains !== undefined;
+    if (hasRecords && hasDomains) {
+        throw invalidConfig('Use either records or domains when listing records.');
+    }
+    if (filter.groupBy !== undefined && !hasDomains) {
+        throw invalidConfig('groupBy requires a domains filter.');
+    }
+    if (filter.groupBy !== undefined && filter.groupBy !== 'domain') {
+        throw invalidConfig('groupBy must be "domain".');
+    }
+}
+function copyJobOptions(options) {
+    validateSyncOptions(options);
+    return {
+        ...options,
+        records: options.records === undefined ? undefined : normalizeRecords(options.records),
+    };
+}
+function copyWatchOptions(options) {
+    const copied = copyJobOptions(options);
+    const intervalMs = options.intervalMs ?? defaultWatchIntervalMs;
+    if (!Number.isInteger(intervalMs) || intervalMs < 1 || intervalMs > maxTimerDelayMs) {
+        throw invalidConfig(`intervalMs must be an integer between 1 and ${maxTimerDelayMs}.`);
+    }
+    return { ...copied, intervalMs };
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+function invalidConfig(message) {
+    return new DdnsError('INVALID_CONFIG', message);
+}
 export * from './types/index.js';
+export default createDdns;

package/dist/lib/cloudflare-client.d.ts

@@ -1,25 +1,31 @@
-import Cloudflare, { ClientOptions as CloudflareOptions } from 'cloudflare';
-import { Record } from '../types/index.js';
+import { Auth, DomainRecordList, Record, RecordData } from '../types/index.js';
 export default class CloudflareClient {
     private cloudflare;
     private zoneMap;
-    constructor(cloudflareOptions: CloudflareOptions);
-    syncRecord(record: Record, ip?: string): Promise<Cloudflare.DNS.Records.DNSRecord>;
-    syncRecords(records: Array<Record>, ip?: string): Promise<Cloudflare.DNS.Records.DNSRecord[]>;
+    constructor(auth: Auth);
+    syncRecords(records: Array<Record>): Promise<Array<RecordData>>;
+    planRecords(records: Array<Record>): Promise<Array<{
+        record: Record;
+        action: 'create' | 'update' | 'unchanged';
+        before?: RecordData;
+        after: Record;
+    }>>;
     removeRecordByNameAndType(recordName: string, recordType?: string): Promise<void>;
-    getRecordDataForRecord(record: Record): Promise<Cloudflare.DNS.Records.DNSRecord>;
-    getRecordDataForRecords(records: Array<Record>): Promise<any[]>;
-    getRecordsByDomains(domains: Array<string>): Promise<{}>;
-    getRecordsByDomain(domain: string): Promise<Cloudflare.DNS.Records.DNSRecord[]>;
+    getRecordDataForRecords(records: Array<Record>): Promise<Array<RecordData>>;
+    getRecordDataForDomains(domains: Array<string>): Promise<DomainRecordList>;
+    getRecordDataForDomain(domain: string): Promise<Array<RecordData>>;
     private createRecord;
     private updateRecord;
+    private prepareRecord;
     private updateZoneMap;
     private getRecordIdByNameAndType;
     private getZoneIdByRecordName;
     private getRecordByNameAndType;
-    private getRecordIdsForRecords;
+    private isUnchanged;
     private getRecordIdMapKey;
+    private getRecordsByDomain;
     private getZoneIdByDomain;
     private getDomainsFromRecords;
     private getDomainByRecordName;
+    private isValidDomain;
 }