/** * `cloudhal push` / `cloudhal pull`: move the site between the local project and its Cloudflare * deployment through the admin Worker (`/api/admin/sites/:id/bundle`, deployment token). */ import { readFile } from "node:fs/promises"; import path from "node:path"; import { exportSite, importSite, mediaBlobKey, type SiteBundle, withPrimaryDomain, } from "@cloudhal/core-ts"; import { openLocalStore } from "@cloudhal/core-ts/local"; import { readProjectConfig } from "../config.ts"; export interface SyncOptions { readonly projectDir: string; /** Overwrite diverged content on the receiving side. */ readonly replace?: boolean; /** * `cloudhal push --cancel-schedules` (RFC-0008 §16): cancel the deployment's open releases * before replacing the graph their pins point into. Without it a push refuses while any exist. */ readonly cancelSchedules?: boolean; /** Admin Worker URL; default from `/deploy/state.json`. */ readonly adminUrl?: string; readonly log?: (line: string) => void; /** Injected in tests. */ readonly fetch?: typeof fetch; } /** Error bodies may be HTML pages (e.g. a not-yet-live workers.dev host); keep messages short. */ export function brief(body: string): string { const text = body .replace(/||<[^>]+>/g, " ") .replace(/\s+/g, " ") .trim(); return text.length > 300 ? `${text.slice(0, 300)}…` : text; } /** The deployment's admin Worker and its operator token (from `cloudhal deploy`'s state). */ export async function deployment(options: SyncOptions) { const cfg = await readProjectConfig(options.projectDir); const dir = path.join(options.projectDir, cfg.dataDir, "deploy"); let adminUrl = options.adminUrl; if (!adminUrl) { try { adminUrl = ( JSON.parse(await readFile(path.join(dir, "state.json"), "utf8")) as { adminUrl?: string } ).adminUrl; } catch { // not deployed } } if (!adminUrl) throw new Error("no deployment found: run `cloudhal deploy` first (or pass --admin-url)"); const secrets = JSON.parse(await readFile(path.join(dir, "secrets.json"), "utf8")) as { CLOUDHAL_DEPLOY_TOKEN?: string; }; if (!secrets.CLOUDHAL_DEPLOY_TOKEN) throw new Error("deployment token missing in .cloudhal/deploy/secrets.json"); return { cfg, adminUrl, token: secrets.CLOUDHAL_DEPLOY_TOKEN, fetch: options.fetch ?? fetch }; } async function target(options: SyncOptions) { const { cfg, adminUrl, token, fetch: f } = await deployment(options); const url = new URL(`/api/admin/sites/${cfg.siteId}/bundle`, adminUrl); return { cfg, url, token, fetch: f }; } /** * `ifAbsent`: whether the deployment already has the site. Only a 200 (it has it) and a 404 (it * does not) are answers. A 401 throws an error `whileTokenPropagates` retries: right after a * Workers Builds deploy the edge can still check the new token against the previous admin * Worker, and pushing then would hit the site the deployment does have. Anything else throws * too, and nothing is pushed. */ async function deploymentHasSite(f: typeof fetch, url: URL, auth: Record) { const probe = await f(url, { headers: auth }); if (probe.status === 200) return true; if (probe.status === 404) return false; throw new Error( `checking whether the deployment has the site failed (${probe.status}): ${brief(await probe.text())}; nothing was pushed`, ); } /** A bootstrap PUT refused because the deployment already has this site (SyncConflictError). */ const alreadyHasSite = (status: number, body: string) => status === 409 && body.includes('"error":"conflict"') && body.includes("already has site"); export async function pushSite( options: SyncOptions & { ifAbsent?: boolean }, ): Promise<{ pushed: boolean; message: string }> { const log = options.log ?? (() => {}); const { cfg, url, token, fetch: f } = await target(options); const auth = { authorization: `Bearer ${token}` }; const keepDeployed = () => { log( "the deployment already has this site; leaving it as the source of truth (use `cloudhal pull`)", ); return { pushed: false, message: "already deployed" }; }; if (options.ifAbsent && (await deploymentHasSite(f, url, auth))) return keepDeployed(); const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir)); let bundle: SiteBundle; try { bundle = await exportSite(local, cfg.siteId); // Media bytes first (RFC-0004 §4.7): the deployment refuses a bundle whose media it lacks. let uploaded = 0; for (const m of bundle.media ?? []) { const mediaUrl = new URL(`/api/admin/sites/${cfg.siteId}/media/${m.sha256}`, url); const head = await f(mediaUrl, { method: "HEAD", headers: auth }); if (head.status === 200) continue; const bytes = await local.blobs.get(mediaBlobKey(cfg.siteId, m.sha256)); if (!bytes) throw new Error(`local media ${m.sha256} is missing; run \`cloudhal media verify\``); const put = await f(mediaUrl, { method: "PUT", headers: { ...auth, "content-type": "application/octet-stream" }, body: bytes, }); if (!put.ok) throw new Error(`uploading media failed (${put.status}): ${brief(await put.text())}`); uploaded++; } if (uploaded) log(`media: ${uploaded} file(s) uploaded`); } finally { await local.close(); } url.searchParams.set("mode", options.replace ? "replace" : "bootstrap"); if (options.cancelSchedules) url.searchParams.set("cancelSchedules", "1"); const res = await f(url, { method: "PUT", headers: { ...auth, "content-type": "application/json" }, body: JSON.stringify(bundle), }); const body = await res.text(); // The probe said absent, yet the site is there (it arrived between the two): same outcome. if (options.ifAbsent && !options.replace && alreadyHasSite(res.status, body)) return keepDeployed(); if (res.status === 409 && /"error":"schedules_(pending|running)"/.test(body)) { const parsed = JSON.parse(body) as { error: string; message: string; details?: { releases?: { id: string; state: string; executeAt?: string; title?: string }[] }; }; const list = (parsed.details?.releases ?? []) .map( (r) => ` ${r.id} ${r.state}${r.executeAt ? ` at ${r.executeAt}` : ""}${r.title ? ` — ${r.title}` : ""}`, ) .join("\n"); throw new Error( parsed.error === "schedules_running" ? `${parsed.message}` : `the deployment has open releases; a push replaces the graph their pinned versions point into:\n${list}\nCancel them in Studio, or push with --cancel-schedules.`, ); } if (res.status === 409) throw new Error( `the deployment has diverged from your local copy: ${brief(body)}\nRun \`cloudhal pull\` first, or \`cloudhal push --replace\` to overwrite.`, ); if (!res.ok) throw new Error(`push failed (${res.status}): ${brief(body)}`); log(`pushed: ${body}`); return { pushed: true, message: body }; } /** * Makes `hostname` the deployed site's primary domain (preview links, canonical URLs) and mirrors * it in the local store. Used by `cloudhal deploy` once a custom domain is routed. */ export async function setPrimaryDomain( options: SyncOptions & { hostname: string }, ): Promise<{ changed: boolean }> { const { cfg, url, token, fetch: f } = await target(options); const res = await f(new URL(`/api/admin/sites/${cfg.siteId}/domains`, url), { method: "PUT", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify({ primary: options.hostname }), }); const body = await res.text(); if (!res.ok) throw new Error(`setting the site's domain failed (${res.status}): ${brief(body)}`); const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir)); try { const site = await local.store.getSite(cfg.siteId); if (site && site.domains.find((d) => d.primary)?.hostname !== options.hostname) await local.store.updateSite({ ...site, domains: withPrimaryDomain(site.domains, options.hostname), }); } finally { await local.close(); } return { changed: (JSON.parse(body) as { changed?: boolean }).changed === true }; } export async function pullSite(options: SyncOptions): Promise<{ message: string }> { const log = options.log ?? (() => {}); const { cfg, url, token, fetch: f } = await target(options); const res = await f(url, { headers: { authorization: `Bearer ${token}` } }); if (!res.ok) throw new Error(`pull failed (${res.status}): ${brief(await res.text())}`); const bundle = (await res.json()) as SiteBundle; const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir)); try { // Media bytes first (RFC-0004 §4.7), verified by SHA-256 as they land. let downloaded = 0; for (const m of bundle.media ?? []) { const key = mediaBlobKey(cfg.siteId, m.sha256); if (await local.blobs.head(key)) continue; const got = await f(new URL(`/api/admin/sites/${cfg.siteId}/media/${m.sha256}`, url), { headers: { authorization: `Bearer ${token}` }, }); if (!got.ok) throw new Error(`downloading media failed (${got.status})`); await local.blobs.put(key, new Uint8Array(await got.arrayBuffer()), { sha256: m.sha256, contentType: m.mediaType, }); downloaded++; } if (downloaded) log(`media: ${downloaded} file(s) downloaded`); const result = await importSite(local, bundle, { mode: options.replace ? "replace" : "bootstrap", log, // RFC-0045 §1: the local renderer reads reference and repeater fields (`openLocalStore`). fieldTypes: local.store.fieldTypes, }); const message = JSON.stringify(result); log(`pulled: ${message}`); return { message }; } finally { await local.close(); } }