sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ CodeConnections/ Host.ts

import * as codeconnections from "@distilled.cloud/aws/codeconnections";
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 * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { fetchObservedTags, syncResourceTags, toTagList } from "./internal.ts";

/**
 * VPC configuration provisioned for a {@link Host} whose self-managed
 * provider is only reachable from inside a VPC.
 */
export interface HostVpcConfiguration {
  /**
   * ID of the VPC connected to the provider's infrastructure.
   */
  vpcId: string;
  /**
   * IDs of the subnets associated with the VPC.
   */
  subnetIds: string[];
  /**
   * IDs of the security groups associated with the VPC.
   */
  securityGroupIds: string[];
  /**
   * PEM value of the TLS certificate used by the provider's infrastructure,
   * for endpoints served with a self-signed or private CA certificate.
   * This is public certificate material (not a private key).
   */
  tlsCertificate?: string;
}

export interface HostProps {
  /**
   * Name of the host (1-64 chars). If omitted a deterministic physical name
   * is generated. Changing the name replaces the host.
   */
  name?: string;
  /**
   * The self-managed source provider the host is installed on. Changing the
   * provider replaces the host.
   */
  providerType: "GitHubEnterpriseServer" | "GitLabSelfManaged";
  /**
   * Endpoint of the infrastructure the provider is installed on, e.g.
   * `https://ghe.example.com`.
   */
  providerEndpoint: string;
  /**
   * VPC configuration to provision for the host when the provider endpoint
   * is only reachable from inside a VPC.
   */
  vpcConfiguration?: HostVpcConfiguration;
  /**
   * User-defined tags.
   */
  tags?: Record<string, string>;
}

export interface Host extends Resource<
  "AWS.CodeConnections.Host",
  HostProps,
  {
    /** Physical name of the host. */
    hostName: string;
    /** ARN of the host (passed as `hostArn` to a `Connection`). */
    hostArn: string;
    /**
     * Host state. A freshly created host is `PENDING` until its setup is
     * completed **manually** in the AWS console; it then becomes
     * `AVAILABLE`.
     */
    hostStatus: string;
    /** The self-managed source provider. */
    providerType: string;
    /** Endpoint of the provider's infrastructure. */
    providerEndpoint: string;
  },
  never,
  Providers
> {}

/**
 * An AWS CodeConnections host — the infrastructure representation of a
 * self-managed source provider (GitHub Enterprise Server or GitLab
 * self-managed). One host serves all connections to that provider.
 *
 * A host is created in the `PENDING` state. Completing it requires a
 * one-time setup performed **manually** in the AWS console — there is no
 * API to finish the setup. Once completed the host becomes `AVAILABLE` and
 * `Connection`s can reference it via `hostArn`.
 * ### Creating a Host
 * **Example:** GitHub Enterprise Server Host (created PENDING)
 * ```typescript
 * const host = yield* CodeConnections.Host("GHE", {
 *   providerType: "GitHubEnterpriseServer",
 *   providerEndpoint: "https://ghe.example.com",
 * });
 * // host.hostStatus === "PENDING"
 * // Complete the setup in the console before creating connections on it.
 * ```
 *
 * **Example:** Connection on a Host
 * ```typescript
 * const connection = yield* CodeConnections.Connection("GHEConn", {
 *   providerType: "GitHubEnterpriseServer",
 *   hostArn: host.hostArn,
 * });
 * ```
 *
 * ### Reaching a Private Endpoint
 * **Example:** Host with VPC Configuration
 * ```typescript
 * const host = yield* CodeConnections.Host("PrivateGHE", {
 *   providerType: "GitHubEnterpriseServer",
 *   providerEndpoint: "https://ghe.internal.example.com",
 *   vpcConfiguration: {
 *     vpcId: vpc.vpcId,
 *     subnetIds: [subnetA.subnetId, subnetB.subnetId],
 *     securityGroupIds: [securityGroup.securityGroupId],
 *   },
 * });
 * ```
 *
 * @resource
 */
export const Host = Resource<Host>("AWS.CodeConnections.Host");

const toWireVpcConfiguration = (
  vpc: HostVpcConfiguration | undefined,
): codeconnections.VpcConfiguration | undefined =>
  vpc === undefined
    ? undefined
    : {
        VpcId: vpc.vpcId,
        SubnetIds: vpc.subnetIds,
        SecurityGroupIds: vpc.securityGroupIds,
        TlsCertificate: vpc.tlsCertificate,
      };

const sameVpcConfiguration = (
  observed: codeconnections.VpcConfiguration | undefined,
  desired: codeconnections.VpcConfiguration | undefined,
): boolean =>
  observed?.VpcId === desired?.VpcId &&
  JSON.stringify([...(observed?.SubnetIds ?? [])].sort()) ===
    JSON.stringify([...(desired?.SubnetIds ?? [])].sort()) &&
  JSON.stringify([...(observed?.SecurityGroupIds ?? [])].sort()) ===
    JSON.stringify([...(desired?.SecurityGroupIds ?? [])].sort()) &&
  (observed?.TlsCertificate ?? undefined) === (desired?.TlsCertificate ?? undefined);

export const HostProvider = () =>
  Provider.effect(
    Host,
    Effect.gen(function* () {
      const toName = (id: string, props: Partial<HostProps>) =>
        props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 64 });

      /**
       * Read a host by ARN; a missing host reads as absent. `GetHost` does
       * not echo the ARN back, so it is re-attached from the input.
       */
      const getByArn = Effect.fn(function* (arn: string) {
        const response = yield* codeconnections
          .getHost({ HostArn: arn })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
        return response === undefined
          ? undefined
          : ({ ...response, HostArn: arn } satisfies codeconnections.Host);
      });

      /** Find a host by name (getHost only accepts an ARN). */
      const findByName = Effect.fn(function* (name: string) {
        const hosts = yield* codeconnections.listHosts.pages({}).pipe(
          Stream.runCollect,
          Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Hosts ?? [])),
        );
        return hosts.find((h) => h.Name === name);
      });

      const toAttrs = (host: codeconnections.Host, name: string) => ({
        hostName: host.Name ?? name,
        hostArn: host.HostArn!,
        hostStatus: host.Status ?? "PENDING",
        providerType: host.ProviderType ?? "",
        providerEndpoint: host.ProviderEndpoint ?? "",
      });

      return {
        stables: ["hostName", "hostArn", "providerType"],

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          if ((yield* toName(id, olds ?? {})) !== (yield* toName(id, news ?? {}))) {
            return { action: "replace" } as const;
          }
          // Provider type is immutable — replace on change. Endpoint and VPC
          // configuration are mutable via UpdateHost.
          if ((news?.providerType ?? undefined) !== (olds?.providerType ?? undefined)) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          const name = output?.hostName ?? (yield* toName(id, olds ?? {}));
          const host = output?.hostArn ? yield* getByArn(output.hostArn) : yield* findByName(name);
          if (host?.HostArn === undefined) return undefined;
          const attrs = toAttrs(host, name);
          const tags = yield* fetchObservedTags(attrs.hostArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = output?.hostName ?? (yield* toName(id, news));
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...news.tags };
          const desiredVpc = toWireVpcConfiguration(news.vpcConfiguration);

          // 1. Observe — cloud state is authoritative.
          let observed = output?.hostArn
            ? yield* getByArn(output.hostArn)
            : yield* findByName(name);

          // 2. Ensure — create if missing. The host is created PENDING and
          // its setup is completed manually in the console.
          if (observed?.HostArn === undefined) {
            const created = yield* codeconnections.createHost({
              Name: name,
              ProviderType: news.providerType,
              ProviderEndpoint: news.providerEndpoint,
              VpcConfiguration: desiredVpc,
              Tags: toTagList(desiredTags),
            });
            observed = created.HostArn ? yield* getByArn(created.HostArn) : yield* findByName(name);
            if (observed?.HostArn === undefined) {
              observed = {
                Name: name,
                HostArn: created.HostArn,
                ProviderType: news.providerType,
                ProviderEndpoint: news.providerEndpoint,
                VpcConfiguration: desiredVpc,
                Status: "PENDING",
              };
            }
          }

          // 3. Sync — endpoint + VPC configuration, diffed against OBSERVED
          // cloud state; skip the API entirely on no-op.
          if (
            observed.ProviderEndpoint !== news.providerEndpoint ||
            !sameVpcConfiguration(observed.VpcConfiguration, desiredVpc)
          ) {
            yield* codeconnections.updateHost({
              HostArn: observed.HostArn!,
              ProviderEndpoint: news.providerEndpoint,
              VpcConfiguration: desiredVpc,
            });
            observed = (yield* getByArn(observed.HostArn!)) ?? observed;
          }

          // 4. Sync tags — diff against OBSERVED cloud tags.
          yield* syncResourceTags(observed.HostArn!, desiredTags);

          yield* session.note(name);
          return toAttrs(observed, name);
        }),

        delete: Effect.fn(function* ({ output }) {
          // A host cannot be deleted while its VPC configuration is
          // initializing/deleting — retry the transient state, bounded.
          yield* codeconnections.deleteHost({ HostArn: output.hostArn }).pipe(
            Effect.retry({
              while: (e): boolean => e._tag === "ResourceUnavailableException",
              schedule: Schedule.exponential("2 seconds"),
              times: 8,
            }),
            Effect.catchTag("ResourceNotFoundException", () => Effect.void),
          );
        }),

        list: () =>
          codeconnections.listHosts.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk)
                .flatMap((page) => page.Hosts ?? [])
                .flatMap((h) =>
                  h.HostArn !== undefined
                    ? [
                        {
                          hostName: h.Name ?? "",
                          hostArn: h.HostArn,
                          hostStatus: h.Status ?? "PENDING",
                          providerType: h.ProviderType ?? "",
                          providerEndpoint: h.ProviderEndpoint ?? "",
                        },
                      ]
                    : [],
                ),
            ),
          ),
      };
    }),
  );