@volter/twin-cloudflare 0.1.0

package/dist/src/cloudflare-connector.js

@@ -0,0 +1,418 @@
+// Cloudflare connector. All real I/O crosses the injected CloudflareExecute boundary.
+// Pull folds mutable account/zone/tunnel/configuration/DNS state through the kernel's observe. Perform
+// translates only explicitly modeled local actions and fails loudly on unknown writes.
+import { assertBudgetGuardIntact, observeResources, projectResources } from '@volter/world-core';
+import { CloudflareBudget, CloudflareBudgetError, cloudflareCallWeight } from "./cloudflare-budget.js";
+import { cloudflareConfigurationID } from "./cloudflare-twin.js";
+const SERVICE = 'cloudflare';
+/** The single live Cloudflare call site. It is budgeted before fetch and records 429/Retry-After. */
+export function liveCloudflareExecute(token, base = 'https://api.cloudflare.com/client/v4', opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, CloudflareBudget, 'liveCloudflareExecute')
+        : new CloudflareBudget({ token, ...(opts.budgetOptions ?? {}) });
+    return async (method, path, body) => {
+        const weight = cloudflareCallWeight(method, path);
+        const reservation = budget.checkBudget(weight);
+        const response = await doFetch(`${base}${path}`, {
+            method,
+            headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => { responseHeaders[key.toLowerCase()] = value; });
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused call
+        // that louder refusal wins; an answer Cloudflare ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, responseHeaders, { status: response.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof CloudflareBudgetError) || !response.ok)
+                throw error;
+        }
+        const text = await response.text();
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        return { status: response.status, body: parsed, headers: responseHeaders };
+    };
+}
+function resultOf(response, context) {
+    if (response.status < 200 || response.status >= 300
+        || !response.body || typeof response.body !== 'object' || Array.isArray(response.body)
+        || response.body.success !== true || !Object.hasOwn(response.body, 'result')) {
+        const detail = response.body?.errors?.[0]?.message ?? JSON.stringify(response.body);
+        throw new Error(`cloudflare pull ${context} refused: HTTP ${response.status} ${detail}`);
+    }
+    return response.body?.result;
+}
+function listResult(response, context) {
+    const result = resultOf(response, context);
+    if (!Array.isArray(result))
+        throw new Error(`cloudflare pull ${context} refused: result was not an array`);
+    return result;
+}
+function requiredString(value, key, context) {
+    const field = value[key];
+    if (typeof field !== 'string' || !field.trim()) {
+        throw new Error(`cloudflare pull ${context} refused: ${key} must be a nonempty string`);
+    }
+    return field;
+}
+// Account and zone ids anchor the `${account}:${name}` composite ids the provisioning slice
+// mints (worker_script, r2_bucket, …). Cloudflare account/zone ids are 32-char lowercase hex;
+// enforcing that on pull keeps those composite keyspaces unambiguous (a pulled id containing a
+// colon could otherwise collide two keyspaces).
+function requiredResourceID(value, key, context) {
+    const field = requiredString(value, key, context);
+    if (!/^[a-f0-9]{32}$/.test(field)) {
+        throw new Error(`cloudflare pull ${context} refused: ${key} must be a 32-character lowercase hex id`);
+    }
+    return field;
+}
+function optionalObject(value, key, context) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`cloudflare pull ${context} refused: ${key} must be an object`);
+    }
+    return value;
+}
+function pagePath(path, page) {
+    const url = new URL(path, 'https://api.cloudflare.invalid');
+    url.searchParams.set('page', String(page));
+    return `${url.pathname}${url.search}`;
+}
+async function listAll(execute, path, context, inventory) {
+    const values = [];
+    for (let page = 1; page <= 10_000; page++) {
+        const response = await execute('GET', page === 1 ? path : pagePath(path, page));
+        values.push(...listResult(response, `${context} page ${page}`));
+        const info = response.body.result_info;
+        if (info === undefined) {
+            inventory.complete = false;
+            return values;
+        }
+        if (!info || typeof info !== 'object' || Array.isArray(info)) {
+            throw new Error(`cloudflare pull ${context} page ${page} refused: result_info must be an object`);
+        }
+        const totalPages = Number(info.total_pages);
+        const currentPage = Number(info.page ?? page);
+        if (!Number.isInteger(totalPages) || totalPages < 1 || !Number.isInteger(currentPage) || currentPage !== page) {
+            throw new Error(`cloudflare pull ${context} page ${page} refused: invalid result_info pagination`);
+        }
+        if (page >= totalPages)
+            return values;
+    }
+    throw new Error(`cloudflare pull ${context} refused: pagination exceeded 10000 pages`);
+}
+export function mapCloudflareAccount(value) {
+    const id = requiredResourceID(value, 'id', 'account fixture');
+    const name = requiredString(value, 'name', 'account fixture');
+    return {
+        type: 'account',
+        id,
+        fields: {
+            name,
+            account_type: value.type ?? 'standard',
+            created_on: value.created_on ?? null,
+            settings: value.settings ?? {},
+            _vendor_observed: true,
+        },
+    };
+}
+export function mapCloudflareZone(value) {
+    const id = requiredResourceID(value, 'id', 'zone fixture');
+    const name = requiredString(value, 'name', 'zone fixture');
+    const account = optionalObject(value.account, 'account', 'zone fixture');
+    const accountID = account?.id ?? value.account_id;
+    if (typeof accountID !== 'string' || !accountID)
+        throw new Error('cloudflare pull zone fixture refused: account id must be a nonempty string');
+    return {
+        type: 'zone',
+        id,
+        fields: {
+            name,
+            account_id: accountID,
+            status: value.status ?? 'active',
+            paused: value.paused ?? false,
+            zone_type: value.type ?? 'full',
+            created_on: value.created_on ?? null,
+            modified_on: value.modified_on ?? null,
+            activated_on: value.activated_on ?? null,
+            name_servers: value.name_servers ?? [],
+            original_name_servers: value.original_name_servers ?? [],
+            _vendor_observed: true,
+        },
+    };
+}
+export function mapCloudflareTunnel(value) {
+    const id = requiredString(value, 'id', 'tunnel fixture');
+    const accountID = requiredString(value, 'account_tag', 'tunnel fixture');
+    const name = requiredString(value, 'name', 'tunnel fixture');
+    return {
+        type: 'cloudflare_tunnel',
+        id,
+        fields: {
+            account_id: accountID,
+            name,
+            config_src: value.config_src ?? 'cloudflare',
+            created_at: value.created_at ?? null,
+            deleted_at: value.deleted_at ?? null,
+            metadata: value.metadata ?? {},
+            status: value.status ?? 'inactive',
+            deleted: value.deleted_at != null, // the kernel's tombstone, cleared by the subject's next write
+            _vendor_observed: true,
+        },
+    };
+}
+export function mapCloudflareConfiguration(value) {
+    const accountID = requiredString(value, 'account_id', 'configuration fixture');
+    const tunnelID = requiredString(value, 'tunnel_id', 'configuration fixture');
+    const config = optionalObject(value.config, 'config', 'configuration fixture');
+    if (!config)
+        throw new Error('cloudflare pull configuration fixture refused: config must be an object');
+    return {
+        type: 'tunnel_configuration',
+        id: cloudflareConfigurationID(accountID, tunnelID),
+        fields: {
+            account_id: accountID,
+            tunnel_id: tunnelID,
+            source: value.source ?? 'cloudflare',
+            version: value.version ?? 1,
+            created_at: value.created_at ?? null,
+            config,
+            _vendor_observed: true,
+        },
+    };
+}
+export function mapCloudflareDnsRecord(value) {
+    const id = requiredString(value, 'id', 'DNS record fixture');
+    const zoneID = requiredString(value, 'zone_id', 'DNS record fixture');
+    const name = requiredString(value, 'name', 'DNS record fixture');
+    const recordType = requiredString(value, 'type', 'DNS record fixture').toUpperCase();
+    if (value.content !== undefined && typeof value.content !== 'string')
+        throw new Error('cloudflare pull DNS record fixture refused: content must be a string');
+    const data = optionalObject(value.data, 'data', 'DNS record fixture');
+    return {
+        type: 'dns_record',
+        id,
+        fields: {
+            zone_id: zoneID,
+            zone_name: value.zone_name,
+            name,
+            record_type: recordType,
+            ...(value.content !== undefined ? { content: value.content } : {}),
+            ...(data !== undefined ? { data } : {}),
+            ...(value.priority !== undefined ? { priority: value.priority } : {}),
+            ...(value.private_routing !== undefined ? { private_routing: value.private_routing } : {}),
+            ttl: value.ttl ?? 1,
+            proxied: value.proxied ?? false,
+            settings: value.settings ?? {},
+            meta: value.meta ?? {},
+            comment: value.comment ?? null,
+            tags: value.tags ?? [],
+            created_on: value.created_on ?? null,
+            modified_on: value.modified_on ?? null,
+            _vendor_observed: true,
+        },
+    };
+}
+async function pullCloudflareSnapshot(execute) {
+    const inventory = { complete: true };
+    const accounts = await listAll(execute, '/accounts?per_page=50', 'accounts', inventory);
+    const resources = accounts.map(mapCloudflareAccount);
+    const zones = await listAll(execute, '/zones?per_page=50', 'zones', inventory);
+    resources.push(...zones.map(mapCloudflareZone));
+    for (const account of accounts) {
+        const accountID = String(account.id);
+        const tunnels = await listAll(execute, `/accounts/${encodeURIComponent(accountID)}/cfd_tunnel?per_page=100&is_deleted=false`, `tunnels for ${accountID}`, inventory);
+        resources.push(...tunnels.map(mapCloudflareTunnel));
+        for (const tunnel of tunnels) {
+            if ((tunnel.config_src ?? 'cloudflare') !== 'cloudflare')
+                continue;
+            const tunnelID = String(tunnel.id);
+            const response = await execute('GET', `/accounts/${encodeURIComponent(accountID)}/cfd_tunnel/${encodeURIComponent(tunnelID)}/configurations`);
+            if (response.status === 404)
+                continue;
+            resources.push(mapCloudflareConfiguration(resultOf(response, `configuration ${tunnelID}`)));
+        }
+    }
+    for (const zone of zones) {
+        const zoneID = String(zone.id);
+        const records = await listAll(execute, `/zones/${encodeURIComponent(zoneID)}/dns_records?per_page=5000000`, `DNS records for ${zoneID}`, inventory);
+        resources.push(...records.map(mapCloudflareDnsRecord));
+    }
+    return { resources, complete: inventory.complete };
+}
+export async function pullCloudflareState(execute) {
+    return (await pullCloudflareSnapshot(execute)).resources;
+}
+/** D7 pull entry point. Defaults to a moving timestamp so A→B→A observations cannot dedupe. */
+export async function syncCloudflareFromReal(execute, opts = {}) {
+    const pulled = await pullCloudflareSnapshot(execute);
+    const occurredAt = opts.occurredAt ?? new Date().toISOString();
+    // protocol 2: the observation lands on the head through the kernel's fold — one batch, one instant. Identity is
+    // the kernel's too: a subject the head landed under the vendor's id is reached through the alias map, so the
+    // connector no longer keeps its own external-id table. A COMPLETE listing tombstones what it no longer holds
+    // (the kernel's `complete` sweep); an incomplete one never does, so a truncated page cannot erase an account.
+    const observed = pulled.resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields }));
+    if (pulled.complete) {
+        // a tunnel Cloudflare no longer lists is deleted, and Cloudflare says so with a timestamp — the kernel's own
+        // sweep would tombstone it bare, so the tunnels are named here, with the instant, and left out of the sweep
+        const present = new Set(observed.filter((r) => r.type === 'cloudflare_tunnel').map((r) => r.id));
+        for (const resource of projectResources(SERVICE, opts.root)) {
+            if (resource.type !== 'cloudflare_tunnel' || present.has(resource.id))
+                continue;
+            if (resource.deleted === true)
+                continue;
+            observed.push({ type: 'cloudflare_tunnel', id: resource.id, fields: { deleted: true, deleted_at: occurredAt } });
+        }
+    }
+    const report = observeResources(SERVICE, observed, {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        at: occurredAt,
+        batch: `obs:${SERVICE}:${occurredAt}`,
+        ...(pulled.complete ? { complete: ['account', 'zone', 'tunnel_configuration', 'dns_record'] } : {}),
+    });
+    return { observed: report.observed, deltasAppended: report.appended };
+}
+// ── PROTOCOL 2: the state system's two adapters, over the kernel's executor ──────────
+/** The pack's executor over the kernel's: the same API v4 call, carried by the head. */
+export function cloudflareExecuteOver(execute) {
+    return async (method, path, body) => {
+        const res = await execute({
+            method,
+            path: path.startsWith('/client/v4') ? path : `/client/v4${path}`,
+            headers: { accept: 'application/json', authorization: 'Bearer twin', ...(body ? { 'content-type': 'application/json' } : {}) },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        let parsed = {};
+        if (res.body) {
+            try {
+                parsed = JSON.parse(res.body);
+            }
+            catch {
+                parsed = { success: false, errors: [{ code: 0, message: res.body }] };
+            }
+        }
+        return { status: res.status, body: parsed };
+    };
+}
+/** The refresh adapter: pull the account's control plane through the executor and fold it into the root. */
+export async function syncCloudflareFromRemote(execute, opts = {}) {
+    return syncCloudflareFromReal(cloudflareExecuteOver(execute), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}),
+    });
+}
+function dnsBody(fields) {
+    return {
+        name: fields.name,
+        type: fields.record_type,
+        ttl: fields.ttl,
+        proxied: fields.proxied,
+        ...(typeof fields.content === 'string' ? { content: fields.content } : {}),
+        ...(fields.data !== null && typeof fields.data === 'object' && !Array.isArray(fields.data) ? { data: fields.data } : {}),
+        ...(typeof fields.priority === 'number' ? { priority: fields.priority } : {}),
+        ...(typeof fields.private_routing === 'boolean' ? { private_routing: fields.private_routing } : {}),
+        ...(fields.settings !== undefined ? { settings: fields.settings } : {}),
+        ...(fields.comment !== undefined ? { comment: fields.comment } : {}),
+        ...(fields.tags !== undefined ? { tags: fields.tags } : {}),
+    };
+}
+/** The one wire request an entry becomes, or null when the entry is the twin's own (an observation, a
+ *  locally-authored provisioning record) and crosses nothing. `resolve` is the kernel's: a local id that a
+ *  landing already adopted answers as the vendor's, so Cloudflare is asked about its own id, never ours. */
+export function cloudflareRequestForAction(action, resolve = (_t, id) => id) {
+    const fields = (action.fields ?? {});
+    const id = resolve(action.subject.type, action.subject.id);
+    // The Workers/R2/Hyperdrive/Queues provisioning slice is locally-authored control-plane
+    // state the connector does not push yet (a filed pull-audit gap). These operations are
+    // unpushable-BY-DESIGN, exactly like account/zone observations — return null so the reconcile
+    // batch skips them and continues, rather than throwing and permanently wedging every later
+    // DNS/tunnel action behind an unmapped provisioning action. The default arm below still fails
+    // loudly for a GENUINELY unknown operation.
+    const provisioningType = new Set(['worker_script', 'worker_route', 'worker_domain', 'workers_subdomain', 'durable_object_namespace', 'r2_bucket', 'hyperdrive_config', 'queue', 'queue_consumer', 'worker_asset_upload_session', 'worker_asset', 'worker_version']);
+    if (provisioningType.has(action.subject.type))
+        return null;
+    switch (action.operation) {
+        case 'account.observe':
+        case 'zone.observe':
+            return null;
+        case 'tunnel.create':
+            return {
+                method: 'POST',
+                path: `/accounts/${encodeURIComponent(String(fields.account_id))}/cfd_tunnel`,
+                body: { name: fields.name, config_src: fields.config_src, ...(fields.tunnel_secret ? { tunnel_secret: fields.tunnel_secret } : {}) },
+            };
+        case 'tunnel.update':
+            return {
+                method: 'PATCH',
+                path: `/accounts/${encodeURIComponent(String(fields.account_id))}/cfd_tunnel/${encodeURIComponent(id)}`,
+                body: { ...(fields.name !== undefined ? { name: fields.name } : {}), ...(fields.tunnel_secret !== undefined ? { tunnel_secret: fields.tunnel_secret } : {}) },
+            };
+        case 'tunnel.delete':
+            return { method: 'DELETE', path: `/accounts/${encodeURIComponent(String(fields.account_id))}/cfd_tunnel/${encodeURIComponent(id)}` };
+        case 'tunnel_configuration.update':
+            return { method: 'PUT', path: `/accounts/${encodeURIComponent(String(fields.account_id))}/cfd_tunnel/${encodeURIComponent(resolve('cloudflare_tunnel', String(fields.tunnel_id)))}/configurations`, body: { config: fields.config } };
+        case 'dns_record.create':
+            return { method: 'POST', path: `/zones/${encodeURIComponent(String(fields.zone_id))}/dns_records`, body: dnsBody(fields) };
+        case 'dns_record.update':
+            return { method: 'PATCH', path: `/zones/${encodeURIComponent(String(fields.zone_id))}/dns_records/${encodeURIComponent(id)}`, body: dnsBody(fields) };
+        case 'dns_record.replace':
+            return { method: 'PUT', path: `/zones/${encodeURIComponent(String(fields.zone_id))}/dns_records/${encodeURIComponent(id)}`, body: dnsBody(fields) };
+        case 'dns_record.delete':
+            return { method: 'DELETE', path: `/zones/${encodeURIComponent(String(fields.zone_id))}/dns_records/${encodeURIComponent(id)}` };
+        default:
+            throw new Error(`cloudflare push: unsupported operation '${action.operation}' — refusing to silently drop it`);
+    }
+}
+function pushResultIdentity(action, result, expectedID) {
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+        throw new Error(`cloudflare push ${action.operation} refused: result must be a nonempty object`);
+    }
+    const value = result;
+    if (action.operation === 'tunnel_configuration.update') {
+        if (typeof value.tunnel_id !== 'string' || !value.tunnel_id) {
+            throw new Error('cloudflare push tunnel_configuration.update refused: result.tunnel_id must be a nonempty string');
+        }
+        if (value.tunnel_id !== expectedID) {
+            throw new Error('cloudflare push tunnel_configuration.update refused: result.tunnel_id did not match the requested vendor tunnel id');
+        }
+        return value.tunnel_id;
+    }
+    if (typeof value.id !== 'string' || !value.id) {
+        throw new Error(`cloudflare push ${action.operation} refused: result.id must be a nonempty string`);
+    }
+    if (action.operation !== 'tunnel.create' && action.operation !== 'dns_record.create' && value.id !== expectedID) {
+        throw new Error(`cloudflare push ${action.operation} refused: result.id did not match the requested vendor id`);
+    }
+    return value.id;
+}
+/** The perform adapter: one entry crosses to Cloudflare through the executor, and the vendor's own id for what
+ *  it made comes back as the externalId (the kernel adopts it and every declared reference follows). An entry the
+ *  vendor has nothing to write for — an observation, a provisioning record — crosses nothing and keeps its id. */
+export async function performCloudflareAction(execute, action, ctx) {
+    const request = cloudflareRequestForAction(action, ctx.resolve);
+    if (!request)
+        return { externalId: action.subject.id, data: { performed: false, reason: `${action.operation ?? action.subject.type} is the twin's own record — nothing at Cloudflare to write` } };
+    const cloudflare = cloudflareExecuteOver(execute);
+    const response = await cloudflare(request.method, request.path, request.body);
+    const result = resultOf(response, `push ${action.operation}`);
+    const fields = (action.fields ?? {});
+    const expectedID = action.operation === 'tunnel_configuration.update'
+        ? ctx.resolve('cloudflare_tunnel', String(fields.tunnel_id))
+        : ctx.resolve(action.subject.type, action.subject.id);
+    const returnedID = pushResultIdentity(action, result, expectedID);
+    // a create is the one entry whose id the vendor chooses; every other names the id it was asked about
+    const isCreate = action.operation === 'tunnel.create' || action.operation === 'dns_record.create';
+    return { externalId: isCreate ? returnedID : expectedID };
+}

package/dist/src/cloudflare-openapi-operations.d.ts

@@ -0,0 +1,10 @@
+export type CloudflareOpenAPIOperation = {
+    id: string;
+    method: string;
+    path: string;
+    operationId: string;
+    summary: string;
+    area: string;
+    tier: 'core' | 'common' | 'niche';
+};
+export declare const CLOUDFLARE_OPENAPI_OPERATIONS: readonly CloudflareOpenAPIOperation[];