sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Connectivity/ DirectoryService.ts

import * as connectivity from "@distilled.cloud/cloudflare/connectivity";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.Connectivity.DirectoryService" as const;
type TypeId = typeof TypeId;

/**
 * Protocol of a Connectivity Directory service.
 */
export type DirectoryServiceType = "tcp" | "http";

/**
 * Application protocol hint for `tcp` services.
 */
export type DirectoryServiceAppProtocol = "postgresql" | "mysql" | (string & {});

export declare namespace DirectoryService {
  /**
   * Network a private IP host is reachable through — identified by the
   * Cloudflare Tunnel that carries the traffic.
   */
  export interface Network {
    /**
     * UUID of the `cfd_tunnel` that provides connectivity to the host.
     * Accepts a reference to a `Cloudflare.Tunnel.Tunnel` output.
     */
    tunnelId: string;
  }

  /**
   * Network a private hostname is resolved and reached through.
   */
  export interface ResolverNetwork {
    /**
     * UUID of the `cfd_tunnel` that provides connectivity to the host.
     * Accepts a reference to a `Cloudflare.Tunnel.Tunnel` output.
     */
    tunnelId: string;
    /**
     * IP addresses of the DNS resolvers used to resolve the hostname
     * inside the private network.
     */
    resolverIps?: string[];
  }

  /**
   * Private IPv4 host reached through a tunnel.
   */
  export interface Ipv4Host {
    /** Private IPv4 address of the service. */
    ipv4: string;
    /** Tunnel-backed network the address lives in. */
    network: Network;
  }

  /**
   * Private IPv6 host reached through a tunnel.
   */
  export interface Ipv6Host {
    /** Private IPv6 address of the service. */
    ipv6: string;
    /** Tunnel-backed network the address lives in. */
    network: Network;
  }

  /**
   * Dual-stack (IPv4 + IPv6) host reached through a tunnel.
   */
  export interface DualStackHost {
    /** Private IPv4 address of the service. */
    ipv4: string;
    /** Private IPv6 address of the service. */
    ipv6: string;
    /** Tunnel-backed network the addresses live in. */
    network: Network;
  }

  /**
   * Private hostname resolved and reached through a tunnel.
   */
  export interface HostnameHost {
    /** Private hostname of the service (e.g. `db.internal`). */
    hostname: string;
    /** Tunnel-backed resolver network used to resolve and reach the host. */
    resolverNetwork: ResolverNetwork;
  }

  /**
   * Host a directory service is reachable at — a private IPv4/IPv6
   * address or a hostname, always reached through a Cloudflare Tunnel.
   */
  export type Host = Ipv4Host | Ipv6Host | DualStackHost | HostnameHost;

  /**
   * Fully-resolved host shape returned in Output Attributes (all tunnel
   * references resolved to concrete UUID strings).
   */
  export type HostAttributes =
    | { ipv4: string; network: { tunnelId: string } }
    | { ipv6: string; network: { tunnelId: string } }
    | { ipv4: string; ipv6: string; network: { tunnelId: string } }
    | {
        hostname: string;
        resolverNetwork: { tunnelId: string; resolverIps?: string[] };
      };
}

export type DirectoryServiceProps = {
  /**
   * Display name of the directory service. Must be unique within the
   * account. If omitted, a unique name is generated from the app, stage,
   * and logical ID.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Service protocol: `tcp` (arbitrary TCP, e.g. a database) or `http`
   * (plain HTTP/HTTPS origins).
   */
  type: DirectoryServiceType;
  /**
   * Host the service is reachable at — IPv4, IPv6, dual-stack, or
   * hostname, reached through a Cloudflare Tunnel.
   */
  host: DirectoryService.Host;
  /**
   * Port the service listens on. Only valid for `type: "tcp"` services.
   */
  tcpPort?: number;
  /**
   * Port for plain HTTP traffic. Only valid for `type: "http"` services.
   * @default 80
   */
  httpPort?: number;
  /**
   * Port for HTTPS traffic. Only valid for `type: "http"` services.
   * @default 443
   */
  httpsPort?: number;
  /**
   * Application protocol hint for `tcp` services (e.g. `postgresql`).
   */
  appProtocol?: DirectoryServiceAppProtocol;
  /**
   * TLS settings used when connecting to the service.
   * @default { certVerificationMode: "verify_full" }
   */
  tlsSettings?: {
    /** Certificate verification mode (e.g. `verify_full`). */
    certVerificationMode: string;
  };
};

export type DirectoryServiceAttributes = {
  /**
   * Unique identifier of the directory service.
   */
  serviceId: string;
  /**
   * The Cloudflare account the service belongs to.
   */
  accountId: string;
  /**
   * Display name of the service.
   */
  name: string;
  /**
   * Service protocol (`tcp` or `http`).
   */
  type: DirectoryServiceType;
  /**
   * Host the service is reachable at, with tunnel references resolved.
   */
  host: DirectoryService.HostAttributes;
  /**
   * TCP port (only set for `tcp` services).
   */
  tcpPort: number | undefined;
  /**
   * HTTP port (only set for `http` services).
   */
  httpPort: number | undefined;
  /**
   * HTTPS port (only set for `http` services).
   */
  httpsPort: number | undefined;
  /**
   * Application protocol hint (only set for `tcp` services).
   */
  appProtocol: DirectoryServiceAppProtocol | undefined;
  /**
   * Certificate verification mode in effect.
   */
  certVerificationMode: string | undefined;
  /**
   * When the service was created.
   */
  createdAt: string | undefined;
  /**
   * When the service was last updated.
   */
  updatedAt: string | undefined;
};

export type DirectoryService = Resource<
  TypeId,
  DirectoryServiceProps,
  DirectoryServiceAttributes,
  never,
  Providers
>;

/**
 * A Cloudflare Connectivity Directory service — a named entry in the
 * account's private-network service directory that maps a service name to
 * a private host (IP or hostname) reachable through a Cloudflare Tunnel.
 *
 * Directory services are the registry behind Workers VPC and Zero Trust
 * private-network connectivity: a `tcp` service describes a database-style
 * origin (with an optional `appProtocol` hint), an `http` service describes
 * an HTTP/HTTPS origin with explicit ports.
 *
 * Names are unique within the account. All properties — including the host
 * and even the protocol type — are mutable in place via a full PUT; nothing
 * forces a replacement except moving accounts.
 * ### Creating a Directory Service
 * **Example:** TCP database service through a tunnel
 * ```typescript
 * const tunnel = yield* Cloudflare.Tunnel.Tunnel("DbTunnel", {
 *   ingress: [{ service: "tcp://localhost:5432" }],
 * });
 * const db = yield* Cloudflare.Connectivity.DirectoryService("Postgres", {
 *   type: "tcp",
 *   tcpPort: 5432,
 *   appProtocol: "postgresql",
 *   host: { ipv4: "10.0.0.21", network: { tunnelId: tunnel.tunnelId } },
 * });
 * ```
 *
 * **Example:** HTTP service on a private hostname
 * ```typescript
 * const api = yield* Cloudflare.Connectivity.DirectoryService("InternalApi", {
 *   type: "http",
 *   httpPort: 8080,
 *   httpsPort: 8443,
 *   host: {
 *     hostname: "api.internal",
 *     resolverNetwork: { tunnelId: tunnel.tunnelId, resolverIps: ["10.0.0.53"] },
 *   },
 * });
 * ```
 *
 * ### Updating
 * **Example:** Changing the host in place
 * ```typescript
 * // Host, ports, name, and TLS settings are all mutable — the service
 * // keeps its serviceId across updates.
 * const db = yield* Cloudflare.Connectivity.DirectoryService("Postgres", {
 *   type: "tcp",
 *   tcpPort: 5432,
 *   host: {
 *     hostname: "db.internal",
 *     resolverNetwork: { tunnelId: tunnel.tunnelId },
 *   },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/
 *
 * @resource
 * @product Connectivity
 * @category Cloudflare One (Zero Trust)
 */
export const DirectoryService = Resource<DirectoryService>(TypeId);

/**
 * Returns true if the given value is a DirectoryService resource.
 */
export const isDirectoryService = (value: unknown): value is DirectoryService =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

export const DirectoryServiceProvider = () =>
  Provider.succeed(DirectoryService, {
    stables: ["serviceId", "accountId", "createdAt"],
    diff: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      // Directory services are account-scoped; moving accounts replaces.
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // Everything else (name, type, host, ports, appProtocol, TLS) is
      // mutable via the full-body PUT — let the engine default to update.
      return undefined;
    }),
    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      // Owned path: refresh by the persisted service id.
      if (output?.serviceId) {
        const observed = yield* getService(acct, output.serviceId);
        return observed ? toAttributes(observed, acct) : undefined;
      }

      // Cold read — recover from lost state by matching the deterministic
      // physical name. Names are unique within the account (the API
      // rejects duplicates), but the service carries no ownership markers,
      // so brand the match `Unowned` and let the engine gate takeover
      // behind the adopt policy.
      const name = yield* createServiceName(id, olds?.name);
      const match = yield* findByName(acct, name);
      if (match) return Unowned(toAttributes(match, acct));
      return undefined;
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const name = yield* createServiceName(id, news.name);

      // Observe — the serviceId cached on `output` is a hint, not a
      // guarantee: a missing service falls through to a name scan
      // (adoption / lost-state recovery) and then to create.
      let observed = output?.serviceId ? yield* getService(acct, output.serviceId) : undefined;
      if (!observed) {
        observed = yield* findByName(acct, name);
      }

      // Ensure — create when missing. A concurrent create surfaces as
      // the typed `VpcServiceNameAlreadyExists` (Cloudflare code 5101):
      // converge by re-scanning for the service that won the race.
      if (!observed) {
        const created = yield* connectivity
          .createDirectoryService({
            accountId: acct,
            name,
            ...toRequestBody(news),
          })
          .pipe(
            Effect.catchTag("VpcServiceNameAlreadyExists", (error) =>
              findByName(acct, name).pipe(
                Effect.flatMap((existing) =>
                  existing ? Effect.succeed(existing) : Effect.fail(error),
                ),
              ),
            ),
          );
        observed = created;
      }

      // Sync — diff observed cloud state against desired. The update API
      // is a full-body PUT, so send everything, but skip the call
      // entirely on a no-op.
      const current = toAttributes(observed, acct);
      if (!isDirty(current, name, news)) {
        return current;
      }
      const updated = yield* connectivity.updateDirectoryService({
        accountId: acct,
        serviceId: current.serviceId,
        name,
        ...toRequestBody(news),
      });
      return toAttributes(updated, acct);
    }),
    delete: Effect.fn(function* ({ output }) {
      // Idempotent — an already-gone service surfaces as the typed
      // `VpcServiceNotFound` (Cloudflare code 5104).
      yield* connectivity
        .deleteDirectoryService({
          accountId: output.accountId,
          serviceId: output.serviceId,
        })
        .pipe(Effect.catchTag("VpcServiceNotFound", () => Effect.void));
    }),
    // Account-scoped collection: enumerate every directory service in the
    // account, exhaustively paginating the list API, and hydrate each into
    // the same Attributes shape `read` returns.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* connectivity.listDirectoryServices.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((service) => toAttributes(service, accountId)),
          ),
        ),
      );
    }),
  });

type ObservedService = connectivity.GetDirectoryServiceResponse;

const createServiceName = (id: string, name: string | undefined) =>
  Effect.gen(function* () {
    if (name) return name;
    return yield* createPhysicalName({ id, lowercase: true, maxLength: 63 });
  });

/**
 * Read a directory service by id, mapping "gone" (`VpcServiceNotFound`,
 * Cloudflare error code 5104) to `undefined`.
 */
const getService = (accountId: string, serviceId: string) =>
  connectivity
    .getDirectoryService({ accountId, serviceId })
    .pipe(Effect.catchTag("VpcServiceNotFound", () => Effect.undefined));

/**
 * Find a directory service by its (account-unique) name.
 */
const findByName = (accountId: string, name: string) =>
  connectivity.listDirectoryServices.items({ accountId }).pipe(
    Stream.filter((s) => s.name === name),
    Stream.runHead,
    Effect.map(Option.getOrUndefined),
  );

/**
 * Build the shared create/update request body from desired props. Inputs
 * (tunnel references) have been resolved to concrete strings by the Plan
 * layer before reconcile runs.
 */
const toRequestBody = (news: DirectoryServiceProps) => {
  const host = news.host;
  const requestHost =
    "hostname" in host
      ? {
          hostname: host.hostname,
          resolverNetwork: {
            tunnelId: host.resolverNetwork.tunnelId,
            resolverIps: host.resolverNetwork.resolverIps,
          },
        }
      : "ipv4" in host && "ipv6" in host
        ? {
            ipv4: host.ipv4,
            ipv6: host.ipv6,
            network: { tunnelId: host.network.tunnelId },
          }
        : "ipv4" in host
          ? { ipv4: host.ipv4, network: { tunnelId: host.network.tunnelId } }
          : { ipv6: host.ipv6, network: { tunnelId: host.network.tunnelId } };
  return {
    type: news.type,
    host: requestHost,
    tcpPort: news.tcpPort,
    httpPort: news.httpPort,
    httpsPort: news.httpsPort,
    appProtocol: news.appProtocol,
    tlsSettings: news.tlsSettings,
  };
};

/**
 * Compare observed attributes against the desired props (with the resolved
 * physical name) to decide whether the full-body PUT can be skipped.
 */
const isDirty = (
  current: DirectoryServiceAttributes,
  name: string,
  news: DirectoryServiceProps,
): boolean => {
  if (current.name !== name) return true;
  if (current.type !== news.type) return true;
  if (news.tcpPort !== undefined && current.tcpPort !== news.tcpPort) {
    return true;
  }
  if (news.httpPort !== undefined && current.httpPort !== news.httpPort) {
    return true;
  }
  if (news.httpsPort !== undefined && current.httpsPort !== news.httpsPort) {
    return true;
  }
  if (news.appProtocol !== undefined && current.appProtocol !== news.appProtocol) {
    return true;
  }
  if (
    news.tlsSettings !== undefined &&
    current.certVerificationMode !== news.tlsSettings.certVerificationMode
  ) {
    return true;
  }
  return !sameHost(current.host, news.host);
};

/**
 * Structural host equality between the observed (resolved) host and the
 * desired host props.
 */
const sameHost = (
  observed: DirectoryService.HostAttributes,
  desired: DirectoryService.Host,
): boolean => {
  const canon = (h: {
    hostname?: string;
    ipv4?: string;
    ipv6?: string;
    tunnelId?: unknown;
    resolverIps?: string[] | undefined;
  }) => JSON.stringify([h.hostname, h.ipv4, h.ipv6, h.tunnelId, [...(h.resolverIps ?? [])].sort()]);
  const flat = (h: DirectoryService.HostAttributes | DirectoryService.Host) =>
    Predicate.hasProperty(h, "hostname")
      ? {
          hostname: h.hostname,
          tunnelId: h.resolverNetwork.tunnelId,
          resolverIps: h.resolverNetwork.resolverIps ?? undefined,
        }
      : {
          ...(Predicate.hasProperty(h, "ipv4") ? { ipv4: h.ipv4 } : {}),
          ...(Predicate.hasProperty(h, "ipv6") ? { ipv6: h.ipv6 } : {}),
          tunnelId: h.network.tunnelId,
        };
  return canon(flat(observed)) === canon(flat(desired));
};

const toHostAttributes = (host: ObservedService["host"]): DirectoryService.HostAttributes => {
  if ("hostname" in host) {
    return {
      hostname: host.hostname,
      resolverNetwork: {
        tunnelId: host.resolverNetwork.tunnelId,
        ...(host.resolverNetwork.resolverIps
          ? { resolverIps: [...host.resolverNetwork.resolverIps] }
          : {}),
      },
    };
  }
  if ("ipv4" in host && "ipv6" in host) {
    return {
      ipv4: host.ipv4,
      ipv6: host.ipv6,
      network: { tunnelId: host.network.tunnelId },
    };
  }
  if ("ipv4" in host) {
    return { ipv4: host.ipv4, network: { tunnelId: host.network.tunnelId } };
  }
  return { ipv6: host.ipv6, network: { tunnelId: host.network.tunnelId } };
};

const toAttributes = (
  service: {
    serviceId?: string | null;
    name: string;
    // Distilled widens generated string enums to open unions (`string & {}`);
    // the API only ever returns the known variants here.
    type: string;
    host: ObservedService["host"];
    tcpPort?: number | null;
    httpPort?: number | null;
    httpsPort?: number | null;
    appProtocol?: DirectoryServiceAppProtocol | null;
    tlsSettings?: { certVerificationMode: string } | null;
    createdAt?: string | null;
    updatedAt?: string | null;
  },
  accountId: string,
): DirectoryServiceAttributes => ({
  serviceId: service.serviceId!,
  accountId,
  name: service.name,
  type: service.type as DirectoryServiceType,
  host: toHostAttributes(service.host),
  tcpPort: service.tcpPort ?? undefined,
  httpPort: service.httpPort ?? undefined,
  httpsPort: service.httpsPort ?? undefined,
  appProtocol: service.appProtocol ?? undefined,
  certVerificationMode: service.tlsSettings?.certVerificationMode ?? undefined,
  createdAt: service.createdAt ?? undefined,
  updatedAt: service.updatedAt ?? undefined,
});