[release] Manage Appwrite Proxy Rules (custom domains) from the CLI

Adds first-class support for the Proxy service that the underlying
node-appwrite@23 SDK doesn't expose. Calls the REST endpoints directly with
the API key the user already supplies.

Declarative: AppwriteFunction and AppwriteSite gain an optional `domains:
string[]`. During --deployFunctions, after a function's deploy succeeds, its
declared domains are reconciled against the existing proxy rules — missing
ones are created, matching ones are kept untouched (idempotent). Pass
--pruneDomains to also delete rules whose domain is no longer listed.

Override / one-shot: --functionDomains "a.example.com,b.example.com" attaches
domains in a single-function deploy without touching config.

Standalone commands for ad-hoc rule management run before controller.init()
so they work in any cwd with bare credentials:
  --listRules <resourceId> --functionId <id> | --siteId <id>
  --createRule --domain X --functionId Y (or --siteId Y)
  --deleteRule <ruleId>

No new dependencies; uses fetch with X-Appwrite-Project / X-Appwrite-Key
headers. REST paths verified against @appwrite.io/console SDK source.

Author: ZachHandley

packages/appwrite-utils-cli/src/cli/commands/deployFunctionsFlow.ts

@@ -38,6 +38,8 @@ export interface DeployFunctionFieldOverrides {
   predeployCommands?: string;
   deployDir?: string;
   ignore?: string;
+  /** Comma-separated domains for --functionDomains. Reconciled after deploy. */
+  domains?: string;
 }
 
 export interface DeployFunctionsFlowOptions {
@@ -59,6 +61,9 @@ export interface DeployFunctionsFlowOptions {
   };
   /** Per-field overrides; only valid when exactly one function is targeted. */
   overrides?: DeployFunctionFieldOverrides;
+  /** When true, proxy rules attached to a function but absent from its
+   *  declared `domains` list are deleted after deploy. Default: false. */
+  pruneDomains?: boolean;
 }
 
 function expandTilde(p: string): string {
@@ -202,6 +207,7 @@ function applyOverrides(
   }
   if (overrides.deployDir !== undefined) next.deployDir = overrides.deployDir;
   if (overrides.ignore !== undefined) next.ignore = splitCsv(overrides.ignore);
+  if (overrides.domains !== undefined) next.domains = splitCsv(overrides.domains);
   return next;
 }
 
@@ -362,5 +368,42 @@ export async function runDeployFunctionsFlow(
   const results = await deployFunctionsBatch(client, items, {
     buildConcurrency: opts.buildConcurrency,
   });
+
+  // 8. Reconcile proxy rules ("domains") for every function that declared any
+  //    and whose deploy succeeded. Failures here don't fail the deploy — the
+  //    code is already on the server — but they're logged loudly.
+  const { reconcileResourceDomains } = await import("../../functions/proxyRules.js");
+  for (const item of items) {
+    const declared = (item.functionConfig as AppwriteFunction).domains ?? [];
+    if (declared.length === 0) continue;
+    const result = results.find((r) => r.functionId === (item.functionConfig as AppwriteFunction).$id);
+    if (!result || result.status !== "ready") continue;
+    try {
+      const summary = await reconcileResourceDomains(
+        client,
+        "function",
+        (item.functionConfig as AppwriteFunction).$id,
+        declared,
+        { prune: opts.pruneDomains }
+      );
+      const parts: string[] = [];
+      if (summary.created.length) parts.push(`created [${summary.created.join(", ")}]`);
+      if (summary.kept.length) parts.push(`kept [${summary.kept.join(", ")}]`);
+      if (summary.deleted.length) parts.push(`deleted [${summary.deleted.join(", ")}]`);
+      MessageFormatter.success(
+        `Domains for ${item.functionName}: ${parts.join("; ") || "no changes"}`,
+        { prefix: "Functions" }
+      );
+    } catch (err) {
+      MessageFormatter.error(
+        `Failed to reconcile domains for ${item.functionName}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+        undefined,
+        { prefix: "Functions" }
+      );
+    }
+  }
+
   return results.filter((r) => r.status === "failed").length + skipped.length;
 }

packages/appwrite-utils-cli/src/functions/proxyRules.ts

@@ -0,0 +1,183 @@
+/**
+ * Thin REST wrappers around Appwrite's Proxy service.
+ *
+ * The `node-appwrite@23` SDK that the rest of the CLI uses does not expose
+ * the Proxy service yet (`@appwrite.io/console@12` does, but that's a
+ * browser SDK with the wrong auth model). The endpoints are stable and
+ * documented; we just call them with the API key the user already gave us.
+ *
+ * Endpoint shapes were verified against
+ * `node_modules/.bun/@appwrite.io+console@12.0.0/dist/esm/sdk.js`:
+ *   GET    /v1/proxy/rules          (queries[]=, search=, total=)
+ *   POST   /v1/proxy/rules/function ({ domain, functionId, branch? })
+ *   POST   /v1/proxy/rules/site     ({ domain, siteId, branch? })
+ *   DELETE /v1/proxy/rules/{ruleId}
+ */
+import type { Client } from "node-appwrite";
+
+export interface ProxyRule {
+  $id: string;
+  $createdAt: string;
+  $updatedAt: string;
+  domain: string;
+  resourceType?: string;
+  resourceId?: string;
+  deploymentResourceType?: "function" | "site";
+  deploymentResourceId?: string;
+  deploymentVcsProviderBranch?: string;
+  status?: "created" | "verifying" | "verified" | "unverified";
+  type?: "api" | "deployment" | "redirect";
+  trigger?: "manual" | "deployment";
+  redirectUrl?: string;
+  redirectStatusCode?: number;
+  logs?: string;
+}
+
+export type ProxyResourceType = "function" | "site";
+
+function authHeaders(client: Client): Record<string, string> {
+  const { project, key } = client.config;
+  return {
+    "X-Appwrite-Project": project,
+    "X-Appwrite-Key": key,
+    "Content-Type": "application/json",
+  };
+}
+
+function baseUrl(client: Client): string {
+  // client.config.endpoint already includes /v1; the SDK just appends.
+  return client.config.endpoint.replace(/\/$/, "");
+}
+
+async function request<T>(
+  method: "GET" | "POST" | "DELETE",
+  url: string,
+  init: { headers: Record<string, string>; body?: unknown }
+): Promise<T> {
+  const res = await fetch(url, {
+    method,
+    headers: init.headers,
+    body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    // Surface Appwrite's structured error if present, otherwise the raw body.
+    let detail = text;
+    try {
+      const j = JSON.parse(text);
+      detail = j.message ? `${j.message} (${res.status})` : text;
+    } catch {}
+    throw new Error(`Proxy API ${method} ${url} failed: ${detail}`);
+  }
+  if (!text) return undefined as unknown as T;
+  return JSON.parse(text) as T;
+}
+
+/**
+ * List proxy rules attached to a function or site. Uses the same `queries[]`
+ * filtering wire format as the rest of the Appwrite REST API.
+ */
+export async function listRulesForResource(
+  client: Client,
+  resourceType: ProxyResourceType,
+  resourceId: string
+): Promise<ProxyRule[]> {
+  const queries = [
+    JSON.stringify({ method: "equal", attribute: "deploymentResourceType", values: [resourceType] }),
+    JSON.stringify({ method: "equal", attribute: "deploymentResourceId", values: [resourceId] }),
+  ];
+  const params = new URLSearchParams();
+  for (const q of queries) params.append("queries[]", q);
+  const url = `${baseUrl(client)}/proxy/rules?${params.toString()}`;
+  const body = await request<{ total: number; rules: ProxyRule[] }>(
+    "GET",
+    url,
+    { headers: authHeaders(client) }
+  );
+  return body.rules ?? [];
+}
+
+export async function createFunctionRule(
+  client: Client,
+  params: { domain: string; functionId: string; branch?: string }
+): Promise<ProxyRule> {
+  return request<ProxyRule>(
+    "POST",
+    `${baseUrl(client)}/proxy/rules/function`,
+    { headers: authHeaders(client), body: params }
+  );
+}
+
+export async function createSiteRule(
+  client: Client,
+  params: { domain: string; siteId: string; branch?: string }
+): Promise<ProxyRule> {
+  return request<ProxyRule>(
+    "POST",
+    `${baseUrl(client)}/proxy/rules/site`,
+    { headers: authHeaders(client), body: params }
+  );
+}
+
+export async function deleteRule(client: Client, ruleId: string): Promise<void> {
+  await request<void>(
+    "DELETE",
+    `${baseUrl(client)}/proxy/rules/${encodeURIComponent(ruleId)}`,
+    { headers: authHeaders(client) }
+  );
+}
+
+/**
+ * Reconcile a resource's desired vs existing proxy rules. Always creates
+ * missing domains; only deletes extras when `prune` is true. Idempotent —
+ * existing rules with matching domains are left alone.
+ *
+ * Returns a summary so the caller can log what changed.
+ */
+export async function reconcileResourceDomains(
+  client: Client,
+  resourceType: ProxyResourceType,
+  resourceId: string,
+  desiredDomains: string[],
+  options: { prune?: boolean; branch?: string } = {}
+): Promise<{ created: string[]; deleted: string[]; kept: string[] }> {
+  const desired = new Set(desiredDomains.map((d) => d.trim()).filter(Boolean));
+  const existing = await listRulesForResource(client, resourceType, resourceId);
+  const existingByDomain = new Map(existing.map((r) => [r.domain, r]));
+
+  const created: string[] = [];
+  const deleted: string[] = [];
+  const kept: string[] = [];
+
+  for (const domain of desired) {
+    if (existingByDomain.has(domain)) {
+      kept.push(domain);
+      continue;
+    }
+    if (resourceType === "function") {
+      await createFunctionRule(client, {
+        domain,
+        functionId: resourceId,
+        branch: options.branch,
+      });
+    } else {
+      await createSiteRule(client, {
+        domain,
+        siteId: resourceId,
+        branch: options.branch,
+      });
+    }
+    created.push(domain);
+  }
+
+  if (options.prune) {
+    for (const rule of existing) {
+      if (!desired.has(rule.domain)) {
+        await deleteRule(client, rule.$id);
+        deleted.push(rule.domain);
+      }
+    }
+  }
+
+  return { created, deleted, kept };
+}