sailfork / t3code-github / .repos/ alchemy-effect/ packages/ neon/ src/ OrganizationVPCEndpoint.ts

import * as Neon from "@distilled.cloud/neon";
import { OwnedBySomeoneElse, unownedUnlessPrevious } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import type { Providers } from "./Providers.ts";

export interface OrganizationVPCEndpointProps {
  /** Existing Neon organization ID. Changing it replaces the registration, cleaning up the old scope first. */
  orgId: string;
  /** Neon AWS region ID, such as aws-us-east-2. Azure is not supported. Changes replace the registration. */
  regionId: string;
  /** Existing AWS VPC endpoint ID, not a VPC ID. Changes replace the registration. */
  vpcEndpointId: string;
  /** Descriptive label on the Neon registration. */
  label: string;
}

export interface OrganizationVPCEndpointAttributes {
  /** Organization containing the registration. */
  orgId: string;
  /** Neon AWS region containing the registration. */
  regionId: string;
  /** Referenced AWS VPC endpoint; never created, modified, or deleted by this resource. */
  vpcEndpointId: string;
  /** Observed label, or null when the registration is absent. */
  label: string | null;
  /** Original adopted label; null denotes a registration created by Alchemy. */
  initialLabel: string | null;
  /** Last managed label, retained across refreshes for drift-safe cleanup. */
  managedLabel: string;
  /** Observed Neon registration state (for example new or accepted); null when absent. */
  state: string | null;
}

export interface OrganizationVPCEndpoint extends Resource<
  "Neon.OrganizationVPCEndpoint",
  OrganizationVPCEndpointProps,
  OrganizationVPCEndpointAttributes,
  never,
  Providers
> {}

/**
 * Register an EXISTING AWS PrivateLink endpoint with a Neon organization.
 * Requires an entitled organization admin and a supported AWS region matching
 * the endpoint and client. Azure is unsupported. Neon allows at most ten
 * private networking configurations per AWS region. This neither provisions
 * the AWS endpoint nor configures its DNS, and does not block public connections.
 *
 * Existing registrations require explicit resource-scoped adoption. Their label
 * is durably captured before mutation and restored on destroy, without revoking
 * the registration. New registrations are unregistered on destroy only if their
 * label is still managed and no projects restrict access through them.
 * IMPORTANT: Neon permanently prevents re-registering a removed endpoint in the
 * same organization. Replacement cleans up the old scope first; use a fresh AWS
 * endpoint when necessary. External drift blocks cleanup. Preserve the state
 * store and serialize writers: Neon exposes no conditional association writes.
 *
 * ### Register private networking
 * **Example:** Bind an existing AWS endpoint
 * ```typescript
 * const network = yield* Neon.OrganizationVPCEndpoint("PrivateNetwork", {
 *   orgId: "org-example-12345678",
 *   regionId: "aws-us-east-2",
 *   vpcEndpointId: "vpce-0123456789abcdef0",
 *   label: "Application network",
 * });
 * ```
 *
 * @resource
 * @product Organization
 */
export const OrganizationVPCEndpoint = Resource<OrganizationVPCEndpoint>(
  "Neon.OrganizationVPCEndpoint",
);

export class InvalidOrganizationVPCEndpoint extends Data.TaggedError(
  "InvalidOrganizationVPCEndpoint",
)<{
  /** Invalid scope or unsafe mutation condition. */
  message: string;
}> {}

/** @internal */
export const validateOrganizationVPCEndpoint = (props: OrganizationVPCEndpointProps) =>
  /^[a-z0-9-]{1,60}$/.test(props.orgId) &&
  /^aws-[a-z0-9-]+$/.test(props.regionId) &&
  /^vpce-[a-f0-9]+$/.test(props.vpcEndpointId) &&
  props.label.trim().length > 0
    ? Effect.void
    : Effect.fail(
        new InvalidOrganizationVPCEndpoint({
          message:
            "An organization ID, AWS Neon region, existing vpce- endpoint ID, and nonempty label are required",
        }),
      );

const request = (scope: { orgId: string; regionId: string; vpcEndpointId: string }) => ({
  org_id: scope.orgId,
  region_id: scope.regionId,
  vpc_endpoint_id: scope.vpcEndpointId,
});

const observe = (scope: { orgId: string; regionId: string; vpcEndpointId: string }) =>
  Neon.getOrganizationVPCEndpointDetails(request(scope)).pipe(
    Effect.catchTag("NotFound", () => Effect.undefined),
  );

export const OrganizationVPCEndpointProvider = () =>
  Provider.succeed(OrganizationVPCEndpoint, {
    stables: ["orgId", "regionId", "vpcEndpointId", "initialLabel"],
    diff: Effect.fn(function* ({ olds, news, output }) {
      const previous = output ?? olds;
      if (!("orgId" in news) || !("regionId" in news) || !("vpcEndpointId" in news)) {
        return { action: "replace", deleteFirst: true } as const;
      }
      for (const key of ["orgId", "regionId", "vpcEndpointId"] as const) {
        if (!isResolved(news[key]) || news[key] !== previous[key]) {
          return { action: "replace", deleteFirst: true } as const;
        }
      }
      if (!isResolved<OrganizationVPCEndpointProps>(news)) return;
      yield* validateOrganizationVPCEndpoint(news);
      if ((yield* observe(news))?.label !== news.label) {
        return { action: "update" } as const;
      }
    }),
    read: Effect.fn(function* ({ olds, output, previous }) {
      const scope = output ?? olds;
      if (!scope?.orgId || !scope.regionId || !scope.vpcEndpointId) return;
      const observed = yield* observe(scope);
      if (output)
        return {
          ...output,
          label: observed?.label ?? null,
          state: observed?.state ?? null,
        };
      if (!observed) return;
      return unownedUnlessPrevious(
        {
          orgId: scope.orgId,
          regionId: scope.regionId,
          vpcEndpointId: scope.vpcEndpointId,
          label: observed.label,
          initialLabel: observed.label,
          managedLabel: observed.label,
          state: observed.state,
        },
        previous,
        "vpcEndpointId",
      );
    }),
    reconcile: Effect.fn(function* ({ news, output, olds }) {
      yield* validateOrganizationVPCEndpoint(news);
      if (
        output &&
        (output.orgId !== news.orgId ||
          output.regionId !== news.regionId ||
          output.vpcEndpointId !== news.vpcEndpointId)
      ) {
        return yield* new InvalidOrganizationVPCEndpoint({
          message: "Registration identity changed without replacement",
        });
      }
      const observed = yield* observe(news);
      if (observed && !output) {
        return yield* new OwnedBySomeoneElse({
          message:
            "Existing VPC registration requires scoped adoption; an equal endpoint ID is not ownership",
          resourceType: "Neon.OrganizationVPCEndpoint",
        });
      }
      if (
        output &&
        !olds &&
        observed?.label !== output.managedLabel &&
        observed?.label !== news.label
      ) {
        return yield* new InvalidOrganizationVPCEndpoint({
          message: "VPC registration changed since its adoption baseline was captured",
        });
      }
      if (!observed && output) {
        return yield* new InvalidOrganizationVPCEndpoint({
          message:
            "The registration was removed externally; Neon forbids re-registering it in this organization",
        });
      }
      if (observed?.label !== news.label) {
        yield* Neon.assignOrganizationVPCEndpoint({
          ...request(news),
          label: news.label,
        }).pipe(
          Effect.catchTag(
            "Conflict",
            Effect.fn(function* (error) {
              const raced = yield* observe(news);
              if (!raced || raced.label !== news.label) return yield* error;
              if (!output)
                return yield* new OwnedBySomeoneElse({
                  message: "A registration appeared during creation; explicit adoption is required",
                  resourceType: "Neon.OrganizationVPCEndpoint",
                });
            }),
          ),
        );
      }
      const current = yield* observe(news);
      if (!current || current.label !== news.label) {
        return yield* new InvalidOrganizationVPCEndpoint({
          message: "VPC registration changed during reconciliation",
        });
      }
      return {
        orgId: news.orgId,
        regionId: news.regionId,
        vpcEndpointId: news.vpcEndpointId,
        label: current.label,
        initialLabel: output?.initialLabel ?? null,
        managedLabel: news.label,
        state: current.state,
      };
    }),
    delete: Effect.fn(function* ({ output, olds }) {
      const observed = yield* observe(output);
      if (!observed) return;
      if (output.initialLabel !== null && observed.label === output.initialLabel) return;
      if (observed.label !== output.managedLabel && observed.label !== olds.label) {
        return yield* new InvalidOrganizationVPCEndpoint({
          message: "Refusing cleanup of an externally relabeled VPC registration",
        });
      }
      if (output.initialLabel !== null) {
        yield* Neon.assignOrganizationVPCEndpoint({
          ...request(output),
          label: output.initialLabel,
        }).pipe(
          Effect.catchTag(
            "NotFound",
            Effect.fn(function* (error) {
              if (yield* observe(output)) return yield* error;
            }),
          ),
        );
      } else {
        if (observed.num_restricted_projects !== 0) {
          return yield* new InvalidOrganizationVPCEndpoint({
            message: "Remove project VPC restrictions before unregistering this endpoint",
          });
        }
        yield* Neon.deleteOrganizationVPCEndpoint(request(output)).pipe(
          Effect.catchTag("NotFound", () => Effect.void),
        );
      }
    }),
  });