sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ CloudMap/ Service.ts

import * as sd from "@distilled.cloud/aws/servicediscovery";
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 { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
import { toWireSeconds } from "alchemy/Util/Duration";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import {
  awaitOperation,
  deregisterAllInstances,
  fetchObservedTags,
  retryWhileResourceInUse,
  syncTags,
} from "./internal.ts";

export interface ServiceDnsRecord {
  /**
   * The DNS record type Cloud Map creates in the namespace's hosted zone
   * when an instance is registered. Changing the set of record types
   * replaces the service.
   */
  type: "A" | "AAAA" | "SRV" | "CNAME";
  /**
   * The TTL of the DNS record (e.g. `"10 seconds"` or
   * `Duration.seconds(10)`; a bare number is milliseconds). Mutable.
   */
  ttl: Duration.Input;
}

export interface ServiceProps {
  /**
   * Name of the service — for DNS namespaces this becomes the DNS label
   * (`{name}.{namespace}`). Changing the name replaces the service.
   * @default a generated DNS-compatible physical name
   */
  name?: string;
  /**
   * The ID of the namespace to register the service in. Changing the
   * namespace replaces the service.
   */
  namespaceId: string;
  /**
   * A description for the service.
   */
  description?: string;
  /**
   * DNS records Cloud Map creates when instances are registered. Omit for
   * API-only (HTTP namespace) services. TTLs are mutable; changing the set
   * of record types replaces the service.
   */
  dnsRecords?: ServiceDnsRecord[];
  /**
   * How Route 53 responds to DNS queries: `MULTIVALUE` returns up to eight
   * healthy records, `WEIGHTED` returns one. Create-only — changing it
   * replaces the service.
   * @default "MULTIVALUE"
   */
  routingPolicy?: "MULTIVALUE" | "WEIGHTED";
  /**
   * A Route 53 health check for instances (public DNS namespaces only).
   * Mutually exclusive with `healthCheckCustomConfig`.
   */
  healthCheckConfig?: {
    /** The endpoint protocol Route 53 health-checks: HTTP, HTTPS, or TCP. */
    type: "HTTP" | "HTTPS" | "TCP";
    /** The path Route 53 requests, e.g. `/health` (HTTP/HTTPS only). */
    resourcePath?: string;
    /** Consecutive failures before the instance is considered unhealthy. */
    failureThreshold?: number;
  };
  /**
   * Custom health checking — instance health is pushed via
   * `UpdateInstanceCustomHealthStatus` instead of probed by Route 53.
   * Create-only: it cannot be added, changed, or removed after creation, so
   * any change replaces the service.
   */
  healthCheckCustomConfig?: {
    /** Deprecated by AWS (always behaves as 1); retained for parity. */
    failureThreshold?: number;
  };
  /**
   * Set to `"HTTP"` to force API-only discovery even inside a DNS namespace.
   * Create-only — changing it replaces the service.
   */
  type?: "HTTP";
  /**
   * Custom service-level attributes (up to 30 key/value pairs) stored on the
   * service and readable at runtime via `GetServiceAttributes`. Mutable —
   * reconcile diffs the observed attributes against this map, upserting
   * changed keys and deleting keys no longer declared.
   */
  attributes?: Record<string, string>;
  /**
   * Tags to apply to the service. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface Service extends Resource<
  "AWS.CloudMap.Service",
  ServiceProps,
  {
    /**
     * The unique identifier of the service.
     */
    serviceId: string;
    /**
     * The ARN of the service.
     */
    serviceArn: string;
    /**
     * Name of the service.
     */
    serviceName: string;
    /**
     * The namespace the service belongs to.
     */
    namespaceId: string;
    /**
     * Name of the namespace the service belongs to.
     */
    namespaceName: string;
  },
  {},
  Providers
> {}

/**
 * An AWS Cloud Map service — a named entry in a namespace that instances
 * register against. For DNS namespaces, Cloud Map creates the configured DNS
 * records per registered instance; every service is also queryable via the
 * `DiscoverInstances` API. This is what ECS `serviceRegistries[].registryArn`
 * consumes.
 * ### Creating Services
 * **Example:** DNS Service with A Records
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const namespace = yield* AWS.CloudMap.PrivateDnsNamespace("AppNamespace", {
 *   name: "internal.example.com",
 *   vpc: vpc.vpcId,
 * });
 *
 * const service = yield* AWS.CloudMap.Service("Backend", {
 *   namespaceId: namespace.namespaceId,
 *   dnsRecords: [{ type: "A", ttl: "10 seconds" }],
 *   routingPolicy: "MULTIVALUE",
 * });
 * ```
 *
 * **Example:** API-only Service in an HTTP Namespace
 * ```typescript
 * const namespace = yield* AWS.CloudMap.HttpNamespace("AppNamespace");
 * const service = yield* AWS.CloudMap.Service("Backend", {
 *   namespaceId: namespace.namespaceId,
 * });
 * ```
 *
 * **Example:** Service with Custom Health Checks
 * ```typescript
 * const service = yield* AWS.CloudMap.Service("Backend", {
 *   namespaceId: namespace.namespaceId,
 *   dnsRecords: [{ type: "SRV", ttl: "10 seconds" }],
 *   healthCheckCustomConfig: {},
 * });
 * ```
 *
 * **Example:** Service with Custom Attributes
 * ```typescript
 * const service = yield* AWS.CloudMap.Service("Backend", {
 *   namespaceId: namespace.namespaceId,
 *   attributes: { tier: "backend", version: "2" },
 * });
 * ```
 *
 * ### Discovering Instances
 * **Example:** Discover Healthy Instances from a Lambda
 * ```typescript
 * // init
 * const discover = yield* AWS.CloudMap.DiscoverInstances(service);
 *
 * // runtime
 * const { Instances } = yield* discover({ HealthStatus: "HEALTHY" });
 * ```
 *
 * @resource
 */
export const Service = Resource<Service>("AWS.CloudMap.Service");

export const ServiceProvider = () =>
  Provider.effect(
    Service,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: { name?: string | undefined }) {
        // 63 = the Route 53 per-label limit; the service name becomes the
        // DNS label `{name}.{namespace}` for DNS namespaces
        return props.name ?? (yield* createPhysicalName({ id, maxLength: 63, lowercase: true }));
      });

      /** Observe by cached id, falling back to name lookup in the namespace. */
      const observeService = Effect.fn(function* (
        namespaceId: string,
        name: string,
        serviceId: string | undefined,
      ) {
        if (serviceId !== undefined) {
          const byId = yield* sd.getService({ Id: serviceId }).pipe(
            Effect.map((r) => r.Service),
            Effect.catchTag("ServiceNotFound", () => Effect.undefined),
          );
          if (byId !== undefined) {
            return byId;
          }
        }
        const summary = yield* sd.listServices
          .pages({
            Filters: [{ Name: "NAMESPACE_ID", Values: [namespaceId], Condition: "EQ" }],
          })
          .pipe(
            Stream.map((page) => page.Services ?? []),
            Stream.flattenIterable,
            Stream.filter((s) => s.Name === name),
            Stream.runHead,
            Effect.map(Option.getOrUndefined),
          );
        if (summary?.Id === undefined) {
          return undefined;
        }
        return yield* sd.getService({ Id: summary.Id }).pipe(
          Effect.map((r) => r.Service),
          Effect.catchTag("ServiceNotFound", () => Effect.undefined),
        );
      });

      const resolveNamespaceName = Effect.fn(function* (namespaceId: string) {
        const namespace = yield* sd.getNamespace({ Id: namespaceId });
        return namespace.Namespace?.Name ?? "";
      });

      const toDesiredDnsConfig = (props: ServiceProps) =>
        props.dnsRecords !== undefined
          ? {
              DnsRecords: props.dnsRecords.map((record) => ({
                Type: record.type,
                TTL: toWireSeconds(record.ttl)!,
              })),
              RoutingPolicy: props.routingPolicy,
            }
          : undefined;

      const toDesiredHealthCheckConfig = (props: ServiceProps) =>
        props.healthCheckConfig !== undefined
          ? {
              Type: props.healthCheckConfig.type,
              ResourcePath: props.healthCheckConfig.resourcePath,
              FailureThreshold: props.healthCheckConfig.failureThreshold,
            }
          : undefined;

      const recordKey = (records: { Type: string; TTL: number }[]) =>
        records
          .map((r) => `${r.Type}:${r.TTL}`)
          .sort()
          .join(",");

      const recordTypeKey = (records: { type: string }[] | undefined) =>
        (records ?? [])
          .map((r) => r.type)
          .sort()
          .join(",");

      return Service.Provider.of({
        stables: ["serviceId", "serviceArn", "serviceName", "namespaceId", "namespaceName"],

        list: () =>
          Effect.gen(function* () {
            const pages = yield* sd.listServices.pages({}).pipe(Stream.runCollect);
            const summaries = Array.from(pages).flatMap((page) => page.Services ?? []);
            const items = yield* Effect.forEach(
              summaries,
              (summary) =>
                Effect.gen(function* () {
                  if (summary.Id === undefined) return undefined;
                  const service = yield* sd.getService({ Id: summary.Id }).pipe(
                    Effect.map((r) => r.Service),
                    Effect.catchTag("ServiceNotFound", () => Effect.undefined),
                  );
                  if (
                    service?.Id === undefined ||
                    service.Arn === undefined ||
                    service.Name === undefined ||
                    service.NamespaceId === undefined
                  ) {
                    return undefined;
                  }
                  const namespaceName = yield* resolveNamespaceName(service.NamespaceId).pipe(
                    Effect.catchTag("NamespaceNotFound", () => Effect.succeed("")),
                  );
                  return {
                    serviceId: service.Id,
                    serviceArn: service.Arn,
                    serviceName: service.Name,
                    namespaceId: service.NamespaceId,
                    namespaceName,
                  };
                }),
              { concurrency: 10 },
            );
            return items.filter((item): item is Service["Attributes"] => item !== undefined);
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const namespaceId = output?.namespaceId ?? olds?.namespaceId;
          if (namespaceId === undefined) return undefined;
          const name = output?.serviceName ?? (yield* createName(id, olds ?? {}));
          const service = yield* observeService(namespaceId, name, output?.serviceId);
          if (
            service?.Id === undefined ||
            service.Arn === undefined ||
            service.NamespaceId === undefined
          ) {
            return undefined;
          }
          const namespaceName = yield* resolveNamespaceName(service.NamespaceId).pipe(
            Effect.catchTag("NamespaceNotFound", () => Effect.succeed("")),
          );
          const attrs = {
            serviceId: service.Id,
            serviceArn: service.Arn,
            serviceName: service.Name ?? name,
            namespaceId: service.NamespaceId,
            namespaceName,
          };
          const tags = yield* fetchObservedTags(attrs.serviceArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ id, news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldName = yield* createName(id, olds);
          const newName = yield* createName(id, news);
          if (oldName !== newName) {
            return { action: "replace" } as const;
          }
          if (olds.namespaceId !== news.namespaceId) {
            return { action: "replace" } as const;
          }
          if (olds.routingPolicy !== news.routingPolicy) {
            return { action: "replace" } as const;
          }
          if (recordTypeKey(olds.dnsRecords) !== recordTypeKey(news.dnsRecords)) {
            return { action: "replace" } as const;
          }
          // healthCheckCustomConfig cannot be added, changed, or removed
          if (
            (olds.healthCheckCustomConfig === undefined) !==
            (news.healthCheckCustomConfig === undefined)
          ) {
            return { action: "replace" } as const;
          }
          if (olds.type !== news.type) {
            return { action: "replace" } as const;
          }
          // description / record TTLs / healthCheckConfig / tags → update
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.serviceName ?? (yield* createName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — cloud state is authoritative
          let service = yield* observeService(news.namespaceId, name, output?.serviceId);

          // 2. ENSURE — createService is synchronous
          if (service === undefined) {
            service = yield* sd
              .createService({
                Name: name,
                NamespaceId: news.namespaceId,
                Description: news.description,
                DnsConfig: toDesiredDnsConfig(news),
                HealthCheckConfig: toDesiredHealthCheckConfig(news),
                HealthCheckCustomConfig: news.healthCheckCustomConfig
                  ? {
                      FailureThreshold: news.healthCheckCustomConfig.failureThreshold,
                    }
                  : undefined,
                Type: news.type,
                Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                  Key,
                  Value,
                })),
              })
              .pipe(
                Effect.map((r) => r.Service),
                // a concurrent reconciler created it — observe instead
                Effect.catchTag("ServiceAlreadyExists", (e) =>
                  e.ServiceId !== undefined
                    ? sd.getService({ Id: e.ServiceId }).pipe(Effect.map((r) => r.Service))
                    : observeService(news.namespaceId, name, undefined),
                ),
              );
          }
          if (service?.Id === undefined || service.Arn === undefined) {
            return yield* sd.ServiceNotFound.make({
              message: `service ${name} not visible after create`,
            });
          }

          // 3. SYNC — description / DNS record TTLs / health check config.
          // UpdateService deletes DnsRecords/HealthCheckConfig omitted from
          // the change, so we always send the FULL desired configuration and
          // only skip the call when observed already matches desired.
          const desiredDns = toDesiredDnsConfig(news);
          const desiredHealth = toDesiredHealthCheckConfig(news);
          const observedRecords = service.DnsConfig?.DnsRecords ?? [];
          const desiredRecords = desiredDns?.DnsRecords ?? [];
          const dnsDelta = recordKey([...observedRecords]) !== recordKey(desiredRecords);
          const descriptionDelta =
            (news.description ?? undefined) !== (service.Description ?? undefined);
          const observedHealth = service.HealthCheckConfig;
          const healthDelta =
            (desiredHealth === undefined) !== (observedHealth === undefined) ||
            (desiredHealth !== undefined &&
              (desiredHealth.Type !== observedHealth?.Type ||
                (desiredHealth.ResourcePath ?? undefined) !==
                  (observedHealth?.ResourcePath ?? undefined) ||
                (desiredHealth.FailureThreshold ?? undefined) !==
                  (observedHealth?.FailureThreshold ?? undefined)));
          if (dnsDelta || descriptionDelta || healthDelta) {
            const update = yield* sd.updateService({
              Id: service.Id,
              Service: {
                Description: news.description,
                DnsConfig:
                  desiredDns !== undefined ? { DnsRecords: desiredDns.DnsRecords } : undefined,
                HealthCheckConfig: desiredHealth,
              },
            });
            if (update.OperationId !== undefined) {
              yield* awaitOperation(update.OperationId);
            }
          }

          // 3b. SYNC SERVICE ATTRIBUTES — diff OBSERVED custom attributes
          // against the desired map; upsert changed keys, delete undeclared
          const observedAttributes: { [key: string]: string | undefined } = yield* sd
            .getServiceAttributes({ ServiceId: service.Id })
            .pipe(
              Effect.map((r) => r.ServiceAttributes?.Attributes ?? {}),
              Effect.catchTag("ServiceNotFound", () => Effect.succeed({})),
            );
          const desiredAttributes = news.attributes ?? {};
          const attributeUpserts = Object.entries(desiredAttributes).filter(
            ([key, value]) => observedAttributes[key] !== value,
          );
          const attributeRemovals = Object.keys(observedAttributes).filter(
            (key) => !(key in desiredAttributes),
          );
          if (attributeUpserts.length > 0) {
            yield* sd.updateServiceAttributes({
              ServiceId: service.Id,
              Attributes: Object.fromEntries(attributeUpserts),
            });
          }
          if (attributeRemovals.length > 0) {
            yield* sd.deleteServiceAttributes({
              ServiceId: service.Id,
              Attributes: attributeRemovals,
            });
          }

          // 3c. SYNC TAGS — diff against OBSERVED cloud tags
          const observedTags = yield* fetchObservedTags(service.Arn);
          yield* syncTags(service.Arn, observedTags, desiredTags);

          const namespaceId = service.NamespaceId ?? news.namespaceId;
          const namespaceName = yield* resolveNamespaceName(namespaceId);

          yield* session.note(service.Id);
          return {
            serviceId: service.Id,
            serviceArn: service.Arn,
            serviceName: service.Name ?? name,
            namespaceId,
            namespaceName,
          };
        }),

        delete: Effect.fn(function* ({ output }) {
          // OBSERVE — instances registered at runtime (RegisterInstance
          // binding) block DeleteService; deregister any that remain and
          // await the async operations before deleting.
          yield* deregisterAllInstances(output.serviceId).pipe(
            Effect.catchTag("ServiceNotFound", () => Effect.void),
          );
          // deregistrations still propagating surface as ResourceInUse —
          // retry through the visibility window (bounded)
          yield* retryWhileResourceInUse(sd.deleteService({ Id: output.serviceId })).pipe(
            Effect.catchTag("ServiceNotFound", () => Effect.void),
          );
        }),
      });
    }),
  );