@x47base/pocketbase-addon 0.1.0 → 0.2.0

package/hosting/scripts/dns.mjs

@@ -0,0 +1,116 @@
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+const [file, mode = "plan"] = process.argv.slice(2);
+if (!file || !["plan", "apply"].includes(mode))
+  throw Error("Usage: node scripts/dns.mjs dns.json [plan|apply]");
+const plan = JSON.parse(readFileSync(file));
+if (
+  !["cloudflare", "route53"].includes(plan.provider) ||
+  !/^[A-Za-z0-9]{1,64}$/.test(plan.zoneID) ||
+  !Array.isArray(plan.records) ||
+  plan.records.length < 1 ||
+  plan.records.length > 100
+)
+  throw Error("Invalid DNS plan");
+const domain = /^(?=.{1,253}$)[a-z0-9_-]+(?:\.[a-z0-9_-]+)+$/;
+for (const r of plan.records) {
+  if (
+    !domain.test(r.name) ||
+    !["TXT", "CNAME", "A", "AAAA"].includes(r.type) ||
+    typeof r.content !== "string" ||
+    r.content.length > 2048 ||
+    /[\r\n]/.test(r.content) ||
+    !Number.isInteger(r.ttl) ||
+    r.ttl < 60 ||
+    r.ttl > 86400
+  )
+    throw Error("Invalid DNS record");
+}
+if (mode === "plan") {
+  console.log(
+    JSON.stringify(
+      {
+        provider: plan.provider,
+        zoneID: plan.zoneID,
+        operation:
+          "create only; existing different records are not overwritten",
+        records: plan.records,
+      },
+      null,
+      2,
+    ),
+  );
+  process.exit(0);
+}
+if (plan.provider === "route53") {
+  const batch = {
+    Changes: plan.records.map((r) => ({
+      Action: "CREATE",
+      ResourceRecordSet: {
+        Name: r.name,
+        Type: r.type,
+        TTL: r.ttl,
+        ResourceRecords: [
+          { Value: r.type === "TXT" ? JSON.stringify(r.content) : r.content },
+        ],
+      },
+    })),
+  };
+  const result = spawnSync(
+    "aws",
+    [
+      "route53",
+      "change-resource-record-sets",
+      "--hosted-zone-id",
+      plan.zoneID,
+      "--change-batch",
+      JSON.stringify(batch),
+    ],
+    { stdio: "inherit", shell: false },
+  );
+  if (result.status !== 0)
+    throw Error("Route 53 create failed; inspect DNS state before repeating");
+} else {
+  if (
+    !/^[A-Z][A-Z0-9_]{0,127}$/.test(plan.tokenEnv) ||
+    !process.env[plan.tokenEnv]
+  )
+    throw Error("Cloudflare API token environment reference required");
+  const base = `https://api.cloudflare.com/client/v4/zones/${plan.zoneID}/dns_records`;
+  const headers = {
+    Authorization: "Bearer " + process.env[plan.tokenEnv],
+    "Content-Type": "application/json",
+  };
+  for (const r of plan.records) {
+    const lookup = await fetch(
+      base + "?" + new URLSearchParams({ name: r.name, type: r.type }),
+      { headers, redirect: "error", signal: AbortSignal.timeout(15000) },
+    );
+    const existing = await lookup.json();
+    if (!lookup.ok || !existing.success) throw Error("DNS lookup failed");
+    if (existing.result.length) {
+      if (existing.result.some((v) => v.content !== r.content))
+        throw Error("Existing record differs; no overwrite performed");
+      continue;
+    }
+    const response = await fetch(base, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        name: r.name,
+        type: r.type,
+        content: r.content,
+        ttl: r.ttl,
+        proxied: false,
+      }),
+      redirect: "error",
+      signal: AbortSignal.timeout(15000),
+    });
+    const data = await response.json();
+    if (!response.ok || !data.success)
+      throw Error("DNS create failed; inspect records before repeating");
+  }
+  console.log(
+    "DNS create plan applied. Verify ownership in PocketBase, then export routes and provision TLS.",
+  );
+}

package/hosting/scripts/routes.mjs

@@ -0,0 +1,39 @@
+import { readFileSync, writeFileSync, renameSync } from "node:fs";
+const [url, blueprintFile, output] = process.argv.slice(2);
+if (!url || !blueprintFile || !output)
+  throw Error(
+    "Usage: HOSTING_PB_TOKEN=... node scripts/routes.mjs https://admin.example blueprint.json output.json",
+  );
+const endpoint = new URL(url);
+if (
+  endpoint.username ||
+  endpoint.password ||
+  endpoint.search ||
+  endpoint.hash ||
+  endpoint.pathname !== "/" ||
+  !(
+    endpoint.protocol === "https:" ||
+    (endpoint.protocol === "http:" &&
+      ["127.0.0.1", "localhost"].includes(endpoint.hostname))
+  )
+)
+  throw Error("Fixed HTTPS management origin required");
+if (!process.env.HOSTING_PB_TOKEN) throw Error("HOSTING_PB_TOKEN required");
+const res = await fetch(new URL("/api/vendure/domain-routes", endpoint), {
+  headers: { Authorization: process.env.HOSTING_PB_TOKEN },
+  redirect: "error",
+  signal: AbortSignal.timeout(15000),
+});
+if (!res.ok) throw Error("Route export failed");
+const { items } = await res.json();
+if (!Array.isArray(items) || !items.length)
+  throw Error("No verified, open-store domain routes available");
+const blueprint = JSON.parse(readFileSync(blueprintFile));
+blueprint.domains = items.map(({ host, store }) => ({ host, store }));
+writeFileSync(output + ".tmp", JSON.stringify(blueprint, null, 2) + "\n", {
+  mode: 0o600,
+});
+renameSync(output + ".tmp", output);
+console.log(
+  "Verified domain routes exported. Render and review before gateway reload.",
+);

package/hosting/ui/main.js

@@ -0,0 +1,36 @@
+const base = app.pb.buildURL("/_/extensions/x47-hosting/");
+const css = document.createElement("link");
+css.rel = "stylesheet";
+css.href = base + "page.css";
+document.head.append(css);
+app.routes.superuserOnly("#/hosting", () => {
+  let cancelled = false,
+    dispose = () => {};
+  return t.div(
+    { className: "page x47-hosting" },
+    t.div({
+      className: "page-content",
+      onmount: async (root) => {
+        root.textContent = "Loading backup policies…";
+        try {
+          const { mount } = await import(base + "page.js");
+          if (!cancelled && root.isConnected) dispose = mount(root, app);
+        } catch {
+          if (!cancelled)
+            root.textContent =
+              "Hosting could not load. Reload the dashboard to try again.";
+        }
+      },
+      onunmount: () => {
+        cancelled = true;
+        dispose();
+      },
+    }),
+  );
+});
+if (!app.store.headerLinks.some((x) => x.href === "#/hosting"))
+  app.store.headerLinks.push({
+    href: "#/hosting",
+    label: "Hosting",
+    icon: "ri-server-line",
+  });

package/hosting/ui/page.css

@@ -0,0 +1,86 @@
+.x47-hosting .page-content {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 32px;
+}
+.x47-hosting h1 {
+  font-size: 28px;
+  margin-bottom: 16px;
+}
+.x47-hosting h2 {
+  font-size: 20px;
+  margin: 24px 0 16px;
+}
+.x47-hosting p {
+  line-height: 1.6;
+  margin: 10px 0;
+}
+.hosting-card {
+  border: 1px solid var(--base-alt-2, #ddd);
+  border-radius: 12px;
+  padding: 20px;
+  margin: 16px 0;
+}
+.hosting-card h2 {
+  margin-top: 0;
+}
+.hosting-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 18px;
+}
+.hosting-grid label {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.hosting-grid input,
+.hosting-grid select {
+  width: 100%;
+}
+.hosting-grid .hosting-check {
+  flex-direction: row;
+  align-items: center;
+}
+.hosting-check input {
+  width: auto;
+}
+.hosting-table {
+  overflow: auto;
+}
+.hosting-table th,
+.hosting-table td {
+  text-align: left;
+  padding: 12px;
+  vertical-align: top;
+}
+.hosting-table code {
+  overflow-wrap: anywhere;
+}
+#hostingNotice {
+  color: var(--primary-color, #18655d);
+}
+@media (max-width: 650px) {
+  .hosting-grid {
+    grid-template-columns: 1fr;
+  }
+  .x47-hosting .page-content {
+    padding: 16px;
+  }
+}
+
+.hosting-grid input:not([type="checkbox"]),
+.hosting-grid select {
+  min-height: 42px;
+  padding: 8px 12px;
+  border: 1px solid var(--base-alt-2, #c8cdd2);
+  border-radius: 6px;
+  background: var(--base-color, #fff);
+  color: inherit;
+  font: inherit;
+}
+.hosting-grid input:focus,
+.hosting-grid select:focus {
+  outline: 2px solid var(--primary-color, #18655d);
+  outline-offset: 2px;
+}

package/hosting/ui/page.js

@@ -0,0 +1,112 @@
+export function mount(root, app) {
+  let disposed = false,
+    busy = false,
+    editing = null;
+  const escape = (x) =>
+    String(x ?? "").replace(
+      /[&<>"']/g,
+      (c) =>
+        ({
+          "&": "&amp;",
+          "<": "&lt;",
+          ">": "&gt;",
+          '"': "&quot;",
+          "'": "&#39;",
+        })[c],
+    );
+  const api = (path, method = "GET", body) =>
+    app.pb.send("/api/hosting/" + path, { method, body, requestKey: null });
+  async function load() {
+    const data = await api("backups");
+    if (disposed) return;
+    editing = null;
+    root.innerHTML = `<h1>Hosting & backups</h1><p>Snapshots protect this entire PocketBase database and all its stores. Vendure/PostgreSQL requires a separate backup policy.</p><p>Targets are configured on the server. Named S3 targets require encrypted backups. Restore snapshots through the platform administrator's backup recovery workflow.</p><p role="status" id="hostingNotice"></p>
+    <section class="hosting-card"><h2 id="policyHeading">Create a backup policy</h2><form id="backupPolicy" class="hosting-grid"><label>Name<input name="name" maxlength="128" required></label><label>Target<select name="target">${data.targets.map((t) => `<option value="${escape(t.key)}">${escape(t.key)} (${escape(t.kind)})</option>`).join("")}</select></label><label>Interval (minutes)<input name="intervalMinutes" type="number" min="5" max="43200" value="60" required></label><label>Keep snapshots<input name="keep" type="number" min="1" max="1000" value="24" required></label><label class="hosting-check"><input name="enabled" type="checkbox"> Enable schedule</label><div><button class="btn btn-primary" type="submit">Save policy</button> <button class="btn" id="cancelEdit" type="button" hidden>Cancel edit</button></div></form></section>
+    <h2>Backup policies</h2>${data.policies.length ? data.policies.map((p) => `<section class="hosting-card"><h3>${escape(p.name)}</h3><p>${escape(p.target)} · every ${p.intervalMinutes} minutes · keep ${p.keep} · <strong>${p.enabled ? "Enabled" : "Paused"}</strong> · ${escape(p.lastStatus || "No runs yet")}</p><p>Next scheduled run: ${p.enabled ? escape(p.nextRun) : "Paused"}</p><button class="btn" data-edit="${p.id}">Edit policy</button> <button class="btn" data-run="${p.id}">Run backup now</button> <button class="btn" data-toggle="${p.id}">${p.enabled ? "Pause" : "Enable"}</button></section>`).join("") : "<p>No policies yet. Create one above, then run your first snapshot.</p>"}
+    <h2>Recent runs</h2>${data.runs.length ? '<div class="hosting-table"><table><thead><tr><th>Status</th><th>Started</th><th>Snapshot</th><th>Details</th></tr></thead><tbody>' + data.runs.map((r) => `<tr><td>${escape(r.status)}</td><td>${escape(r.created)}</td><td><code>${escape(r.key)}</code></td><td>${escape(r.message || "—")}</td></tr>`).join("") + "</tbody></table></div>" : "<p>No backups have run yet.</p>"}`;
+    const form = root.querySelector("#backupPolicy");
+    form.onsubmit = (e) => {
+      e.preventDefault();
+      run(async () => {
+        const values = Object.fromEntries(new FormData(form));
+        values.intervalMinutes = Number(values.intervalMinutes);
+        values.keep = Number(values.keep);
+        values.enabled = form.elements.enabled.checked;
+        await api(
+          "backups/policies" + (editing ? "/" + editing : ""),
+          editing ? "PUT" : "POST",
+          values,
+        );
+        await load();
+      });
+    };
+    root.querySelector("#cancelEdit").onclick = () => run(load);
+    root.querySelectorAll("[data-edit]").forEach(
+      (b) =>
+        (b.onclick = () => {
+          if (busy) return;
+          const p = data.policies.find((p) => p.id === b.dataset.edit);
+          editing = p.id;
+          for (const key of ["name", "target", "intervalMinutes", "keep"])
+            form.elements[key].value = p[key];
+          form.elements.enabled.checked = p.enabled;
+          root.querySelector("#policyHeading").textContent =
+            "Edit backup policy";
+          root.querySelector("#cancelEdit").hidden = false;
+          form.elements.name.focus();
+        }),
+    );
+    root.querySelectorAll("[data-run]").forEach(
+      (b) =>
+        (b.onclick = () =>
+          run(async () => {
+            root.querySelector("#hostingNotice").textContent =
+              "Creating snapshot… This may take several minutes. Keep this page open.";
+            await api("backups/policies/" + b.dataset.run + "/run", "POST", {});
+            await load();
+          })),
+    );
+    root.querySelectorAll("[data-toggle]").forEach(
+      (b) =>
+        (b.onclick = () =>
+          run(async () => {
+            const p = data.policies.find((p) => p.id === b.dataset.toggle);
+            await api("backups/policies/" + p.id, "PUT", {
+              name: p.name,
+              target: p.target,
+              intervalMinutes: p.intervalMinutes,
+              keep: p.keep,
+              enabled: !p.enabled,
+            });
+            await load();
+          })),
+    );
+  }
+  async function run(fn) {
+    if (busy) return;
+    busy = true;
+    root.setAttribute("aria-busy", "true");
+    root.querySelectorAll("button").forEach((b) => (b.disabled = true));
+    try {
+      await fn();
+    } catch (e) {
+      if (!disposed) {
+        const notice = root.querySelector("#hostingNotice");
+        if (notice) notice.textContent = e.message;
+        else
+          root.textContent =
+            "Backups could not load. Reload the dashboard to try again.";
+      }
+    } finally {
+      busy = false;
+      if (!disposed) {
+        root.removeAttribute("aria-busy");
+        root.querySelectorAll("button").forEach((b) => (b.disabled = false));
+      }
+    }
+  }
+  run(load);
+  return () => {
+    disposed = true;
+  };
+}

package/multinode/README.md

@@ -0,0 +1,87 @@
+# Multinode — @x47base/pocketbase-addon
+
+Included in the combined npm package; see the [installation guide](../README.md).
+
+A small Go gateway for single-owner tenant routing and bounded public-read caching. Co-developed with AI. Included in the combined package; publication is a separate release step.
+
+This is **not a PocketBase replication engine**. Multiple gateway processes may serve the same tenants, but every tenant routes to one authoritative PocketBase origin. Different tenant partitions may use different origins. Writes and private reads always use that origin. Gateway caches are independent and expire after at most 60 seconds (default two seconds); no broadcast is sent for each request.
+
+## Run locally
+
+```sh
+npx pocketbase-addon gateway -config gateway.example.json -listen 127.0.0.1:8095
+```
+
+The example sends requests for `127.0.0.1:8095` to the local commerce example on port 8093. Open the shop through port 8095. Health: `/healthz`; aggregate counters: `/metrics`. These endpoints describe the gateway, not database health. Stop with Ctrl+C.
+
+```sh
+curl -i http://127.0.0.1:8095/api/commerce/stores/main
+curl -i http://127.0.0.1:8095/api/commerce/stores/main
+```
+
+The second response should include `X-Public-Cache: hit`. Stock, prices, customer accounts, orders, applications, admin routes and GraphQL are never cached. Only exact configured public store projection paths qualify, and the origin must explicitly respond `Cache-Control: public, max-age=...`. Credentials, cookies, range/conditional requests, CORS origins, query strings, Set-Cookie and non-Origin Vary responses bypass caching. PocketBase’s `Vary: Origin` is supported only for requests without an Origin header.
+
+Install the combined package as described in [the root README](../README.md). `npx pocketbase-addon init` creates a loopback-only development config. For the example below, copy `node_modules/@x47base/pocketbase-addon/multinode/gateway.example.json` to your application directory and adjust its hosts and origins.
+
+## Docker
+
+Build from the installed package source:
+
+```sh
+docker build --target gateway -t your-registry/gateway:your-version node_modules/@x47base/pocketbase-addon
+```
+
+Supply `/config/gateway.json` as a readable mount and put the gateway on a network that reaches the private origins. The image listens on port 8095. Do not expose the origin publicly. `allowHTTP` explicitly permits development or private-network HTTP; otherwise origins require HTTPS. Put TLS and upstream DDoS protection in front of public deployments. See [hosting deployment](../hosting/docs/DEPLOYMENT.md) for the commerce image contracts.
+
+## Bounds and consistency
+
+- Unknown hosts fail with 421. The request Host never becomes an arbitrary upstream URL. Forwarded IP headers are rebuilt from the connection, not trusted from the caller. Private operator headers are stripped. The CLI caps simultaneous connections at 512; custom Go hosts must bound their listeners too.
+- Default 128 admitted requests per process; overflow gets 503 with Retry-After. Default request body limit 2 MiB, checked before proxying when Content-Length is known and while streaming otherwise.
+- Request headers have five seconds; total admitted request lifetime is two minutes, including streaming subscriptions (clients must reconnect). No buffered request bodies; cache objects are capped at 64 KiB, 128 entries by default. Cache misses for the same public key coalesce.
+- Writes have no application-level retry or automatic origin failover. An unavailable owner causes 502, not a write to an inconsistent replica. Inspect uncertain mutation outcomes before retrying.
+- Cache staleness is bounded by the shorter of configured TTL and origin max-age. Authenticated requests bypass it for read-after-write. Cache hits do not grant downstream caches a fresh TTL.
+- A running origin remains a failure domain. Durable failover needs fenced ownership, a tested backup/restore process, and explicit RPO/RTO. This package does not provide consensus, replication, migrations or distributed locks.
+
+## Scaling architecture
+
+```mermaid
+flowchart LR
+  Clients --> Edge[CDN / DDoS protection]
+  Edge --> G1[Gateway replicas]
+  G1 --> P1[PocketBase owner: partition A]
+  G1 --> P2[PocketBase owner: partition B]
+  P1 --> V[Vendure API replicas]
+  P2 --> V
+  V --> DB[(PostgreSQL)]
+  V --> Q[Redis / workers]
+```
+
+Use a dealer as the commercial channel boundary and ordinary PocketBase records for teams and stores. Do not create a complete catalog or Vendure channel for every team shop. Use immutable/versioned published snapshots with a CDN for truly high-volume public browsing. Keep private workflow writes on their designated owner, and use partitioned client/server storage when a partition exceeds a single writer's capacity.
+
+SQLite WAL requires shared memory on the same host and cannot serve as a network filesystem replication protocol ([SQLite WAL](https://www.sqlite.org/wal.html)). SQLite permits one writer per database at a time; many simultaneous writers warrant a client/server database ([SQLite usage guidance](https://www.sqlite.org/whentouse.html)). Vendure's [horizontal scaling guide](https://docs.vendure.io/current/core/deployment/horizontal-scaling/) describes API/worker scaling.
+
+Millions of concurrent interactions are an unverified target, not a capability claim. Measure cache hit rate, origin request rate, p95/p99 latency, memory, SQLite lock wait, tenant skew, checkout correctness, queue lag, and recovery under owner loss. Gateways reduce repeat public reads; they do not remove database write limits or protect an already saturated network link.
+
+## Verification
+
+```sh
+go test ./multinode
+go test -race ./multinode
+go vet ./multinode
+```
+
+Tests cover tenant isolation, concurrent cache misses, expiration, credential/private response bypass, unknown hosts, body limits (including chunked reads), spoofed forwarding headers and no automatic mutation retries. They do not establish production capacity.
+
+## Store-bound domains and reload
+
+Set a tenant's optional `store` to a commerce store slug. The gateway then permits only that store's public storefront/account/application route contract, rejects administration and cross-store paths, and preserves the configured host when proxying to the owner. The owner must also validate the live PocketBase domain lease via `commerce.GuardStoreHost` and resolve its public endpoints to that store. Keep the origin private; do not rely on a public Host header as authentication.
+
+```json
+{"host":"team.example.com","store":"team-autumn","origin":"http://pocketbase:8090","publicPaths":["/api/commerce/stores/team-autumn","/api/commerce/stores/team-autumn/offers"]}
+```
+
+Only the explicitly listed public paths can be cached; cookies/authenticated requests and writes bypass public caching. The metrics and health routes are operational endpoints and must be restricted at ingress if not intended publicly. A cached projection may outlive revocation for its configured cache TTL.
+
+The CLI accepts `SIGHUP`: it validates a replacement configuration before swapping handlers; invalid configurations leave the previous routing active. Replacement handlers start with empty caches and release old idle connections. In-flight requests may finish on the previous handler. Keep concurrency allowances in mind during a reload; no global distributed rate-limit or ownership failover is added.
+
+The combined package’s `hosting` command renders Docker/Kubernetes resources and exports verified domain routes. With a single-file Docker bind mount, recreate the service after atomically replacing the host file; otherwise the container may retain its old inode. Kubernetes configmap changes require a gateway rollout/reload after the mount updates.

package/multinode/gateway.docker.json

@@ -0,0 +1 @@
+{"allowHTTP":true,"cacheSeconds":2,"cacheEntries":128,"maxConcurrent":128,"tenants":[{"host":"127.0.0.1:8095","origin":"http://host.docker.internal:8093","publicPaths":["/api/commerce/stores/main"]}]}

package/multinode/gateway.example.json

@@ -0,0 +1 @@
+{"allowHTTP":true,"cacheSeconds":2,"cacheEntries":128,"maxConcurrent":128,"maxBodyBytes":2097152,"tenants":[{"host":"127.0.0.1:8095","origin":"http://127.0.0.1:8093","publicPaths":["/api/commerce/stores/main","/api/commerce/stores/store","/api/commerce/stores/alpine-club"]}]}