sailfork / t3code-github / .repos/ alchemy-effect/ packages/ neon/ src/ ProjectVPCEndpoint.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 { validateOrganizationVPCEndpoint } from "./OrganizationVPCEndpoint.ts";
import type { Providers } from "./Providers.ts";

export interface ProjectVPCEndpointProps {
  /** Project to restrict. Changing the project replaces the association, cleaning up the old scope first. */
  project: {
    /** Neon project identity. */
    projectId: string;
  };
  /** Already configured organization VPC endpoint in the project's organization and AWS region. */
  endpoint: {
    /** Existing Neon organization identity. */
    orgId: string;
    /** Neon AWS region identity. */
    regionId: string;
    /** Existing registered AWS VPC endpoint identity. */
    vpcEndpointId: string;
  };
  /** Descriptive label for this project restriction. */
  label: string;
}

export interface ProjectVPCEndpointAttributes {
  /** Restricted project identity. */
  projectId: string;
  /** Organization containing the project and registered endpoint. */
  orgId: string;
  /** AWS Neon region shared by the project and registered endpoint. */
  regionId: string;
  /** Registered AWS VPC endpoint identity. */
  vpcEndpointId: string;
  /** Observed restriction label, or null when absent. */
  label: string | null;
  /** Original adopted restriction label; null means Alchemy created the restriction. */
  initialLabel: string | null;
  /** Last managed label, retained across refreshes for drift-safe cleanup. */
  managedLabel: string;
}

export interface ProjectVPCEndpoint extends Resource<
  "Neon.ProjectVPCEndpoint",
  ProjectVPCEndpointProps,
  ProjectVPCEndpointAttributes,
  never,
  Providers
> {}

/**
 * Manage one project's restriction to an already registered organization VPC
 * endpoint. Requires an organization admin entitled to AWS Private Networking.
 * The project, endpoint, and client must share an AWS region and the endpoint
 * must belong to the project's organization. Azure is unsupported.
 * This does not change the AWS endpoint, its organization registration, or
 * the project's separate block_public_connections setting. Other restrictions
 * are left untouched. Removing the last restriction can broaden connectivity.
 *
 * Existing associations require explicit resource-scoped adoption. Their
 * original label is durably captured before mutation and restored on destroy;
 * an adopted restriction is never silently removed. New restrictions are
 * removed on destroy only when their label still matches the managed value.
 * Scope changes replace with old-scope cleanup first, avoiding stale managed
 * grants. Preserve state and serialize writers; Neon has no conditional writes.
 *
 * ### Restrict a project
 * **Example:** Reference an organization registration
 * ```typescript
 * const restriction = yield* Neon.ProjectVPCEndpoint("PrivateAccess", {
 *   project,
 *   endpoint: network,
 *   label: "Application access",
 * });
 * ```
 *
 * @resource
 * @product Project
 */
export const ProjectVPCEndpoint = Resource<ProjectVPCEndpoint>("Neon.ProjectVPCEndpoint");

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

/** @internal */
export const validateProjectVPCEndpoint = Effect.fn(function* (props: ProjectVPCEndpointProps) {
  if (!props.project.projectId.trim()) {
    return yield* new InvalidProjectVPCEndpoint({
      message: "A project ID is required",
    });
  }
  yield* validateOrganizationVPCEndpoint({
    ...props.endpoint,
    label: props.label,
  });
});

const scopeOf = (props: ProjectVPCEndpointProps) => ({
  projectId: props.project.projectId,
  orgId: props.endpoint.orgId,
  regionId: props.endpoint.regionId,
  vpcEndpointId: props.endpoint.vpcEndpointId,
});

const request = (scope: { projectId: string; vpcEndpointId: string }) => ({
  project_id: scope.projectId,
  vpc_endpoint_id: scope.vpcEndpointId,
});

const observe = (scope: { projectId: string; vpcEndpointId: string }) =>
  Neon.listProjectVPCEndpoints({ project_id: scope.projectId }).pipe(
    Effect.map((result) =>
      result.endpoints.find((endpoint) => endpoint.vpc_endpoint_id === scope.vpcEndpointId),
    ),
    Effect.catchTag("NotFound", () => Effect.undefined),
  );

const validateCloudScope = Effect.fn(function* (scope: {
  projectId: string;
  orgId: string;
  regionId: string;
  vpcEndpointId: string;
}) {
  const { project } = yield* Neon.getProject({ project_id: scope.projectId });
  if (project.org_id !== scope.orgId || project.region_id !== scope.regionId) {
    return yield* new InvalidProjectVPCEndpoint({
      message: "Project and registered endpoint must share an organization and AWS region",
    });
  }
  yield* Neon.getOrganizationVPCEndpointDetails({
    org_id: scope.orgId,
    region_id: scope.regionId,
    vpc_endpoint_id: scope.vpcEndpointId,
  });
});

export const ProjectVPCEndpointProvider = () =>
  Provider.succeed(ProjectVPCEndpoint, {
    stables: ["projectId", "orgId", "regionId", "vpcEndpointId", "initialLabel"],
    diff: Effect.fn(function* ({ olds, news, output }) {
      const previous = output ?? scopeOf(olds);
      if (
        !("project" in news) ||
        !("endpoint" in news) ||
        !isResolved(news.project) ||
        !isResolved(news.endpoint) ||
        news.project.projectId !== previous.projectId ||
        news.endpoint.orgId !== previous.orgId ||
        news.endpoint.regionId !== previous.regionId ||
        news.endpoint.vpcEndpointId !== previous.vpcEndpointId
      )
        return { action: "replace", deleteFirst: true } as const;
      if (!isResolved<ProjectVPCEndpointProps>(news)) return;
      yield* validateProjectVPCEndpoint(news);
      const scope = scopeOf(news);
      yield* validateCloudScope(scope);
      if ((yield* observe(scope))?.label !== news.label) {
        return { action: "update" } as const;
      }
    }),
    read: Effect.fn(function* ({ olds, output, previous }) {
      if (
        !output &&
        (!olds?.project?.projectId ||
          !olds.endpoint?.orgId ||
          !olds.endpoint.regionId ||
          !olds.endpoint.vpcEndpointId)
      )
        return;
      const scope = output ?? scopeOf(olds);
      const observed = yield* observe(scope);
      if (output) return { ...output, label: observed?.label ?? null };
      if (!observed) return;
      yield* validateCloudScope(scope);
      return unownedUnlessPrevious(
        {
          ...scope,
          label: observed.label,
          initialLabel: observed.label,
          managedLabel: observed.label,
        },
        previous,
        "vpcEndpointId",
      );
    }),
    reconcile: Effect.fn(function* ({ news, output, olds }) {
      yield* validateProjectVPCEndpoint(news);
      const scope = scopeOf(news);
      if (
        output &&
        (output.projectId !== scope.projectId ||
          output.orgId !== scope.orgId ||
          output.regionId !== scope.regionId ||
          output.vpcEndpointId !== scope.vpcEndpointId)
      )
        return yield* new InvalidProjectVPCEndpoint({
          message: "Restriction identity changed without replacement",
        });
      yield* validateCloudScope(scope);
      const observed = yield* observe(scope);
      if (observed && !output)
        return yield* new OwnedBySomeoneElse({
          message:
            "Existing project VPC restriction requires scoped adoption; an equal endpoint ID is not ownership",
          resourceType: "Neon.ProjectVPCEndpoint",
        });
      if (
        output &&
        !olds &&
        observed?.label !== output.managedLabel &&
        observed?.label !== news.label
      ) {
        return yield* new InvalidProjectVPCEndpoint({
          message: "Project restriction changed since its adoption baseline was captured",
        });
      }
      if (observed?.label !== news.label) {
        yield* Neon.assignProjectVPCEndpoint({
          ...request(scope),
          label: news.label,
        }).pipe(
          Effect.catchTag(
            "Conflict",
            Effect.fn(function* (error) {
              const raced = yield* observe(scope);
              if (!raced || raced.label !== news.label) return yield* error;
              if (!output)
                return yield* new OwnedBySomeoneElse({
                  message:
                    "A project restriction appeared during creation; explicit adoption is required",
                  resourceType: "Neon.ProjectVPCEndpoint",
                });
            }),
          ),
        );
      }
      const current = yield* observe(scope);
      if (!current || current.label !== news.label)
        return yield* new InvalidProjectVPCEndpoint({
          message: "Project restriction changed during reconciliation",
        });
      return {
        ...scope,
        label: current.label,
        initialLabel: output?.initialLabel ?? null,
        managedLabel: news.label,
      };
    }),
    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 InvalidProjectVPCEndpoint({
          message: "Refusing cleanup of an externally relabeled project restriction",
        });
      }
      // A transferred project must not be mutated under its previous organization.
      const exists = yield* validateCloudScope(output).pipe(
        Effect.as(true),
        Effect.catchTag(
          "NotFound",
          Effect.fn(function* (error) {
            if (yield* observe(output)) return yield* error;
            return false;
          }),
        ),
      );
      if (!exists) return;
      if (output.initialLabel !== null) {
        yield* Neon.assignProjectVPCEndpoint({
          ...request(output),
          label: output.initialLabel,
        }).pipe(
          Effect.catchTag(
            "NotFound",
            Effect.fn(function* (error) {
              if (yield* observe(output)) return yield* error;
            }),
          ),
        );
      } else {
        yield* Neon.deleteProjectVPCEndpoint(request(output)).pipe(
          Effect.catchTag("NotFound", () => Effect.void),
        );
      }
    }),
  });