sailfork / t3code-github / .repos/ alchemy-effect/ packages/ gcp/ src/ ServiceDirectory/ Endpoint.ts

import * as servicedirectory from "@distilled.cloud/gcp/servicedirectory_v1";
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 { tagRecord } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { GcpEnvironment } from "../Environment.ts";
import {
  ALCHEMY_LABEL_PREFIX,
  createInternalLabels,
  diffLabels,
  hasAlchemyLabels,
  stripInternalLabels,
} from "../Labels.ts";
import type { Providers } from "../Providers.ts";

const MAX_ENDPOINT_ID_LENGTH = 63;
const DEFAULT_PORT = 0;

export type EndpointProps = {
  /**
   * Parent Service Directory service. Full name
   * `projects/{project}/locations/{location}/namespaces/{namespace}/services/{service}`
   * or the service id (combined with `namespace`). Immutable — changing
   * it replaces the endpoint.
   */
  service: string;
  /**
   * Parent namespace. Full name
   * `projects/{project}/locations/{location}/namespaces/{namespace}` or
   * the namespace id (combined with `location`). Used when `service` is
   * a bare id. Immutable — changing it replaces the endpoint.
   */
  namespace?: string;
  /**
   * Location of the endpoint (e.g. `us-central1`). Used when `service`
   * is a bare id. Immutable — changing it replaces the endpoint.
   * `US-CENTRAL1` is accepted and normalized to `us-central1`.
   * @default the stack's GCP region (`GCP.Region`, else the profile
   *   region, else `us-central1`)
   */
  location?: string;
  /**
   * Endpoint id (the `{endpoint}` segment of
   * `.../services/{service}/endpoints/{endpoint}`). If omitted, a unique
   * name is generated from the stack, stage, and logical id. Must be
   * 1-63 characters and match `[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?`.
   * Immutable — changing it replaces the endpoint.
   */
  endpointId?: string;
  /**
   * IPv4 or IPv6 address. Host:port, IPv6 brackets, and truncated
   * addresses are rejected. Limited to 45 characters.
   */
  address?: string;
  /**
   * Port in `[0, 65535]`.
   * @default 0
   */
  port?: number;
  /**
   * User annotations consumed by service clients. Alchemy ownership
   * (`alchemy-stack` / `alchemy-stage` / `alchemy-id`) is merged in
   * automatically. The entire annotations map may contain at most 512
   * characters across all key-value pairs.
   */
  annotations?: Record<string, string>;
  /**
   * Google Compute Engine network of the endpoint, as
   * `projects/{projectNumber}/locations/global/networks/{network}`. The
   * project must be a project *number*. Immutable — changing it
   * replaces the endpoint.
   */
  network?: string;
};

export type Endpoint = Resource<
  "GCP.ServiceDirectory.Endpoint",
  EndpointProps,
  {
    /** Full resource name `projects/{project}/locations/{location}/namespaces/{namespace}/services/{service}/endpoints/{endpoint}`. */
    name: string;
    /** Endpoint id (last path segment). */
    endpointId: string;
    /** Parent service resource name. */
    service: string;
    /** Parent namespace resource name. */
    namespace: string;
    /** Project id. */
    project: string;
    /** Location id (e.g. `us-central1`). */
    location: string;
    /** IPv4 or IPv6 address, if set. */
    address: string | undefined;
    /** Port currently on the endpoint. */
    port: number;
    /** User annotations (Alchemy ownership annotations stripped). */
    annotations: Record<string, string>;
    /** VPC network resource name, if set. */
    network: string | undefined;
    /** Server-assigned UUID4. */
    uid: string | undefined;
  },
  never,
  Providers
>;

/**
 * A Service Directory endpoint — an address/port registration on a
 * service. The parent service must already exist.
 *
 * Changing `endpointId`, `service`, `namespace`, `location`, or
 * `network` replaces the endpoint. `address`, `port`, and `annotations`
 * update in place.
 *
 * Endpoints have no labels field. Alchemy stamps ownership into
 * `annotations` so `list` / `pnpm nuke:gcp` can find owned endpoints
 * under alchemy-labeled namespaces.
 *
 * ### Creating an Endpoint
 * **Example:** Address and port on a service
 * ```typescript
 * const ns = yield* GCP.ServiceDirectory.Namespace("Services", {});
 * const api = yield* GCP.ServiceDirectory.Service("Api", {
 *   namespace: ns.name,
 * });
 * const endpoint = yield* GCP.ServiceDirectory.Endpoint("Https", {
 *   service: api.name,
 *   address: "10.0.0.1",
 *   port: 443,
 * });
 * ```
 *
 * **Example:** Explicit id and annotations
 * ```typescript
 * const endpoint = yield* GCP.ServiceDirectory.Endpoint("Https", {
 *   service: api.name,
 *   endpointId: "api-https",
 *   address: "10.0.0.1",
 *   port: 443,
 *   annotations: { protocol: "https" },
 * });
 * ```
 *
 * @resource
 * @category ServiceDirectory
 */
export const Endpoint = Resource<Endpoint>("GCP.ServiceDirectory.Endpoint");

export class EndpointNotResolved extends Data.TaggedError(
  "GCP.ServiceDirectory.EndpointNotResolved",
)<{
  resourceName: string;
}> {}

export class EndpointParentMissing extends Data.TaggedError(
  "GCP.ServiceDirectory.EndpointParentMissing",
)<{
  service: string;
}> {}

const lastSegment = (value: string) => {
  const trimmed = value.replace(/\/+$/, "");
  const parts = trimmed.split("/");
  return parts[parts.length - 1] || trimmed;
};

const normalizeLocation = (location: string | undefined, defaultLocation: string) =>
  lastSegment(location ?? defaultLocation).toLowerCase();

const normalizeOptional = (value: string | undefined) =>
  value === undefined || value === "" ? undefined : value;

const locationParent = (project: string, location: string) =>
  `projects/${project}/locations/${location}`;

const parseName = (name: string, defaultLocation: string) => {
  const parts = name.split("/").filter((part) => part.length > 0);
  const endpointsAt = parts.lastIndexOf("endpoints");
  const servicesAt = parts.lastIndexOf("services");
  const namespacesAt = parts.lastIndexOf("namespaces");
  const locationsAt = parts.lastIndexOf("locations");
  const projectsAt = parts.lastIndexOf("projects");
  const namespace = namespacesAt >= 0 ? parts.slice(0, namespacesAt + 2).join("/") : "";
  const service = servicesAt >= 0 ? parts.slice(0, servicesAt + 2).join("/") : "";
  return {
    project: projectsAt >= 0 && parts[projectsAt + 1] ? parts[projectsAt + 1]! : "",
    location:
      locationsAt >= 0 && parts[locationsAt + 1] ? parts[locationsAt + 1]! : defaultLocation,
    namespace,
    namespaceId: namespacesAt >= 0 && parts[namespacesAt + 1] ? parts[namespacesAt + 1]! : "",
    service,
    serviceId: servicesAt >= 0 && parts[servicesAt + 1] ? parts[servicesAt + 1]! : "",
    endpointId:
      endpointsAt >= 0 && parts[endpointsAt + 1] ? parts[endpointsAt + 1]! : lastSegment(name),
  };
};

const resolveParent = (
  project: string,
  service: string,
  namespace: string | undefined,
  location: string | undefined,
  region: string,
) => {
  if (service.includes("/")) {
    const parsed = parseName(
      service.includes("/endpoints/") ? service : `${service.replace(/\/+$/, "")}/endpoints/_`,
      region,
    );
    return {
      parent: parsed.service,
      location: parsed.location,
      project: parsed.project || project,
      namespace: parsed.namespace,
    };
  }
  const loc = normalizeLocation(location, region);
  if (namespace === undefined || namespace === "") {
    return undefined;
  }
  const namespaceName = namespace.includes("/namespaces/")
    ? namespace.replace(/\/+$/, "")
    : `projects/${project}/locations/${loc}/namespaces/${namespace}`;
  const parsed = parseName(`${namespaceName}/services/_/endpoints/_`, region);
  return {
    parent: `${parsed.namespace}/services/${service}`,
    location: parsed.location,
    project: parsed.project || project,
    namespace: parsed.namespace,
  };
};

const parentKey = (
  service: string | undefined,
  namespace: string | undefined,
  location: string | undefined,
  region: string,
) => {
  if (service === undefined || service === "") return undefined;
  const resolved = resolveParent("_", service, namespace, location, region);
  if (resolved === undefined) return undefined;
  return `${resolved.location}/${lastSegment(resolved.namespace)}/${lastSegment(resolved.parent)}`;
};

const resourceName = (parent: string, endpointId: string) => `${parent}/endpoints/${endpointId}`;

const userAnnotations = (
  annotations: Record<string, string | undefined> | null | undefined,
): Record<string, string> => stripInternalLabels(tagRecord(annotations));

const hasAlchemyAnnotation = (annotations: Record<string, string | undefined> | null | undefined) =>
  Object.keys(annotations ?? {}).some((key) => key.startsWith(ALCHEMY_LABEL_PREFIX));

const hasAlchemyNamespaceLabels = (labels: Record<string, string | undefined> | null | undefined) =>
  Object.keys(labels ?? {}).some((key) => key.startsWith(ALCHEMY_LABEL_PREFIX));

const toId = (id: string, endpointId: string | undefined, existing?: string) =>
  Effect.gen(function* () {
    if (endpointId !== undefined) return endpointId;
    if (existing !== undefined) return existing;
    const generated = yield* createPhysicalName({
      id,
      maxLength: MAX_ENDPOINT_ID_LENGTH,
      lowercase: true,
      forbiddenPrefixes: ["gcp"],
    });
    const named = /^[a-z]/.test(generated) ? generated : `e${generated}`;
    return named.replace(/-+$/g, "").slice(0, MAX_ENDPOINT_ID_LENGTH).replace(/-+$/g, "");
  });

const toAttrs = (endpoint: servicedirectory.Endpoint, project: string, region: string) => {
  const name = endpoint.name ?? "";
  const parsed = parseName(name, region);
  return {
    name,
    endpointId: parsed.endpointId,
    service: parsed.service,
    namespace: parsed.namespace,
    project: parsed.project || project,
    location: parsed.location,
    address: normalizeOptional(endpoint.address),
    port: endpoint.port ?? DEFAULT_PORT,
    annotations: userAnnotations(endpoint.annotations),
    network: normalizeOptional(endpoint.network),
    uid: endpoint.uid,
  };
};

const getByName = (name: string) =>
  servicedirectory
    .getProjectsLocationsNamespacesServicesEndpoints({ name })
    .pipe(Effect.catchTag("NotFound", () => Effect.undefined));

const deleteByName = (name: string) =>
  servicedirectory.deleteProjectsLocationsNamespacesServicesEndpoints({ name }).pipe(
    Effect.retry({
      while: (error) => error._tag === "Conflict",
      times: 8,
      schedule: Schedule.spaced("1 second"),
    }),
    Effect.catchTag("NotFound", () => Effect.void),
  );

const paginate = <A, E, R>(
  fetch: (
    pageToken: string | undefined,
  ) => Effect.Effect<{ items: A[]; nextPageToken?: string }, E, R>,
) =>
  Effect.gen(function* () {
    const found: A[] = [];
    let pageToken: string | undefined;
    do {
      const response = yield* fetch(pageToken);
      found.push(...response.items);
      pageToken = response.nextPageToken;
    } while (pageToken !== undefined && pageToken !== "");
    return found;
  });

const listNamespacesAt = (parent: string) =>
  paginate((pageToken) =>
    servicedirectory
      .listProjectsLocationsNamespaces({
        parent,
        pageSize: 1000,
        pageToken,
      })
      .pipe(
        Effect.map((response) => ({
          items: (response.namespaces ?? []).filter((namespace) =>
            hasAlchemyNamespaceLabels(namespace.labels),
          ),
          nextPageToken: response.nextPageToken,
        })),
        Effect.catchTag("NotFound", () =>
          Effect.succeed({
            items: [] as servicedirectory.Namespace[],
            nextPageToken: undefined,
          }),
        ),
      ),
  );

const listServicesAt = (parent: string) =>
  paginate((pageToken) =>
    servicedirectory
      .listProjectsLocationsNamespacesServices({
        parent,
        pageSize: 1000,
        pageToken,
      })
      .pipe(
        Effect.map((response) => ({
          items: response.services ?? [],
          nextPageToken: response.nextPageToken,
        })),
        Effect.catchTag("NotFound", () =>
          Effect.succeed({
            items: [] as servicedirectory.Service[],
            nextPageToken: undefined,
          }),
        ),
      ),
  );

const listEndpointsAt = (parent: string) =>
  paginate((pageToken) =>
    servicedirectory
      .listProjectsLocationsNamespacesServicesEndpoints({
        parent,
        pageSize: 1000,
        pageToken,
      })
      .pipe(
        Effect.map((response) => ({
          items: response.endpoints ?? [],
          nextPageToken: response.nextPageToken,
        })),
        Effect.catchTag("NotFound", () =>
          Effect.succeed({
            items: [] as servicedirectory.Endpoint[],
            nextPageToken: undefined,
          }),
        ),
      ),
  );

const listLocations = (project: string) =>
  paginate((pageToken) =>
    servicedirectory
      .listProjectsLocations({
        name: `projects/${project}`,
        pageSize: 100,
        pageToken,
      })
      .pipe(
        Effect.map((response) => ({
          items: (response.locations ?? [])
            .map((location) => location.name)
            .filter((name): name is string => !!name),
          nextPageToken: response.nextPageToken,
        })),
        Effect.catchTag("NotFound", () =>
          Effect.succeed({
            items: [] as string[],
            nextPageToken: undefined,
          }),
        ),
      ),
  );

export const EndpointProvider = () =>
  Provider.succeed(Endpoint, {
    stables: ["name", "endpointId", "service", "namespace", "project", "location", "uid"],

    diff: Effect.fn(function* ({ news, olds, output }) {
      if (!isResolved(news)) return undefined;
      const env = yield* GcpEnvironment.current;
      const previousId = olds?.endpointId ?? output?.endpointId;
      const nextId = news.endpointId ?? previousId;
      const idChanged = previousId !== undefined && nextId !== undefined && nextId !== previousId;

      const previousParent = parentKey(
        olds?.service ?? output?.service,
        olds?.namespace ?? output?.namespace,
        olds?.location ?? output?.location,
        env.region,
      );
      const nextParent = parentKey(
        news.service,
        news.namespace ?? olds?.namespace ?? output?.namespace,
        news.location ?? olds?.location ?? output?.location,
        env.region,
      );
      const parentChanged =
        previousParent !== undefined && nextParent !== undefined && previousParent !== nextParent;

      const previousNetwork = normalizeOptional(olds?.network ?? output?.network);
      const nextNetwork = normalizeOptional(news.network ?? previousNetwork);
      const networkChanged = previousNetwork !== nextNetwork;

      if (!idChanged && !parentChanged && !networkChanged) return undefined;
      return {
        action: "replace" as const,
        deleteFirst:
          networkChanged &&
          !idChanged &&
          !parentChanged &&
          previousId !== undefined &&
          nextId === previousId,
      };
    }),

    read: Effect.fn(function* ({ id, olds, output }) {
      const env = yield* GcpEnvironment.current;
      const endpointId = yield* toId(id, olds?.endpointId, output?.endpointId);
      const parent = resolveParent(
        env.project,
        olds?.service ?? output?.service ?? "",
        olds?.namespace ?? output?.namespace,
        olds?.location ?? output?.location,
        env.region,
      );
      const name =
        output?.name ??
        (parent !== undefined ? resourceName(parent.parent, endpointId) : undefined);
      if (name === undefined) return undefined;
      const existing = yield* getByName(name);
      if (existing === undefined) return undefined;
      const attrs = toAttrs(existing, env.project, env.region);
      return (yield* hasAlchemyLabels(id, tagRecord(existing.annotations)))
        ? attrs
        : Unowned(attrs);
    }),

    list: () =>
      Effect.gen(function* () {
        const env = yield* GcpEnvironment.current;
        const fallback = [locationParent(env.project, env.region)];
        const locations = yield* listLocations(env.project);
        const parents = locations.length > 0 ? locations : fallback;
        const namespacePages = yield* Effect.forEach(
          parents,
          (parent) => listNamespacesAt(parent),
          { concurrency: 4 },
        );
        const namespaces = namespacePages.flat();
        const servicePages = yield* Effect.forEach(
          namespaces,
          (namespace) =>
            namespace.name
              ? listServicesAt(namespace.name)
              : Effect.succeed([] as servicedirectory.Service[]),
          { concurrency: 4 },
        );
        const services = servicePages.flat();
        const endpointPages = yield* Effect.forEach(
          services,
          (service) =>
            service.name
              ? listEndpointsAt(service.name)
              : Effect.succeed([] as servicedirectory.Endpoint[]),
          { concurrency: 4 },
        );
        return endpointPages
          .flat()
          .filter((endpoint) => hasAlchemyAnnotation(endpoint.annotations))
          .map((endpoint) => toAttrs(endpoint, env.project, env.region));
      }),

    reconcile: Effect.fn(function* ({ id, news, output }) {
      const env = yield* GcpEnvironment.current;
      const endpointId = yield* toId(id, news.endpointId, output?.endpointId);
      const parent = resolveParent(
        env.project,
        news.service,
        news.namespace ?? output?.namespace,
        news.location ?? output?.location,
        env.region,
      );
      if (parent === undefined) {
        return yield* new EndpointParentMissing({ service: news.service });
      }
      const name = resourceName(parent.parent, endpointId);
      const desiredAnnotations = {
        ...tagRecord(news.annotations),
        ...(yield* createInternalLabels(id)),
      };
      const desiredAddress = news.address;
      const desiredPort = news.port ?? DEFAULT_PORT;
      const desiredNetwork = normalizeOptional(news.network);

      let current = yield* getByName(output?.name ?? name);

      if (current !== undefined && normalizeOptional(current.network) !== desiredNetwork) {
        yield* deleteByName(current.name ?? name);
        current = undefined;
      }

      if (current === undefined) {
        const created = yield* servicedirectory
          .createProjectsLocationsNamespacesServicesEndpoints({
            parent: parent.parent,
            endpointId,
            body: {
              address: desiredAddress,
              port: desiredPort,
              annotations: desiredAnnotations,
              network: desiredNetwork,
            },
          })
          .pipe(Effect.catchTag("Conflict", () => getByName(name)));
        current = created ?? undefined;
      }

      if (current === undefined) {
        return yield* new EndpointNotResolved({ resourceName: name });
      }

      const observedAnnotations = tagRecord(current.annotations);
      const { upsert, removed } = diffLabels(observedAnnotations, desiredAnnotations);
      const annotationsChanged = upsert.length > 0 || removed.length > 0;
      const addressChanged = (current.address ?? "") !== (desiredAddress ?? "");
      const portChanged = (current.port ?? DEFAULT_PORT) !== desiredPort;

      if (annotationsChanged || addressChanged || portChanged) {
        const updateMask = [
          annotationsChanged ? "annotations" : undefined,
          addressChanged ? "address" : undefined,
          portChanged ? "port" : undefined,
        ]
          .filter((field): field is string => field !== undefined)
          .join(",");
        current = yield* servicedirectory.patchProjectsLocationsNamespacesServicesEndpoints({
          name,
          updateMask,
          body: {
            name,
            annotations: desiredAnnotations,
            address: desiredAddress,
            port: desiredPort,
          },
        });
      }

      return toAttrs(current, env.project, env.region);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* deleteByName(output.name);
    }),
  });