sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ OSIS/ PipelineEndpoint.ts

import * as osis from "@distilled.cloud/aws/osis";
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 * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { jsonEquals } from "./internal.ts";

export class PipelineEndpointUnexpectedResponse extends Data.TaggedError(
  "PipelineEndpointUnexpectedResponse",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export interface PipelineEndpointVpcOptions {
  /**
   * Subnet IDs the endpoint's network interfaces are placed into. Changing
   * subnets replaces the endpoint.
   */
  subnetIds: string[];
  /**
   * Security group IDs applied to the endpoint's network interfaces.
   * Changing security groups replaces the endpoint.
   */
  securityGroupIds?: string[];
}

export interface PipelineEndpointProps {
  /**
   * ARN of the OSIS pipeline the endpoint ingests into. Changing the
   * pipeline replaces the endpoint.
   */
  pipelineArn: string;
  /**
   * VPC placement for the endpoint. All fields are create-only — any change
   * replaces the endpoint.
   */
  vpcOptions: PipelineEndpointVpcOptions;
}

export interface PipelineEndpoint extends Resource<
  "AWS.OSIS.PipelineEndpoint",
  PipelineEndpointProps,
  {
    /**
     * Opaque id of the pipeline endpoint, assigned by OSIS on create.
     */
    endpointId: string;
    /**
     * ARN of the pipeline the endpoint ingests into.
     */
    pipelineArn: string;
    /**
     * Endpoint status (e.g. `ACTIVE`, `CREATING`, `REVOKED`).
     */
    status: string;
    /**
     * Id of the VPC the endpoint lives in.
     */
    vpcId: string | undefined;
    /**
     * The VPC-private ingest URL for the endpoint.
     */
    ingestEndpointUrl: string | undefined;
  },
  never,
  Providers
> {}

/**
 * A VPC endpoint for an Amazon OpenSearch Ingestion (OSIS) pipeline — lets
 * clients inside a VPC ingest data into a pipeline privately, without
 * traversing the public ingest endpoint.
 *
 * The target pipeline must itself be a VPC pipeline (`vpcOptions` set), and
 * the endpoint must live in a different VPC than the pipeline — within the
 * pipeline's own VPC, use its ingest URL instead. Every VPC involved needs
 * `enableDnsSupport` and `enableDnsHostnames`. Cross-account endpoints also
 * need an {@link ResourcePolicy} granting `osis:CreatePipelineEndpoint`.
 *
 * All properties are create-only; any change replaces the endpoint. The
 * endpoint id is assigned by OSIS on create.
 * ### Creating a Pipeline Endpoint
 * **Example:** Private Ingest From a VPC
 * ```typescript
 * const endpoint = yield* OSIS.PipelineEndpoint("Private", {
 *   pipelineArn: pipeline.pipelineArn,
 *   vpcOptions: {
 *     subnetIds: [subnet.subnetId],
 *     securityGroupIds: [securityGroup.securityGroupId],
 *   },
 * });
 * // endpoint.ingestEndpointUrl — the VPC-private ingest URL
 * ```
 *
 * @resource
 */
export const PipelineEndpoint = Resource<PipelineEndpoint>("AWS.OSIS.PipelineEndpoint");

/**
 * A pipeline endpoint whose asynchronous create converged to a failed
 * status.
 */
export class PipelineEndpointCreateFailed extends Data.TaggedError(
  "OsisPipelineEndpointCreateFailed",
)<{
  readonly endpointId: string;
  readonly status: string;
}> {}

export const PipelineEndpointProvider = () =>
  Provider.effect(
    PipelineEndpoint,
    Effect.gen(function* () {
      /**
       * There is no `getPipelineEndpoint` — observe by enumerating the
       * account's endpoints and matching the id.
       */
      const findEndpoint = Effect.fn(function* (endpointId: string) {
        return yield* osis.listPipelineEndpoints.pages({}).pipe(
          Stream.runCollect,
          Effect.map((chunk) =>
            Array.from(chunk)
              .flatMap((page) => page.PipelineEndpoints ?? [])
              .find((endpoint) => endpoint.EndpointId === endpointId),
          ),
        );
      });

      const toAttrs = Effect.fn(function* (endpoint: osis.PipelineEndpoint) {
        if (!endpoint.EndpointId || !endpoint.PipelineArn) {
          return yield* new PipelineEndpointUnexpectedResponse({
            message: `OSIS pipeline endpoint '${endpoint.EndpointId}' is missing its id or pipeline ARN`,
          });
        }
        return {
          endpointId: endpoint.EndpointId,
          pipelineArn: endpoint.PipelineArn,
          status: endpoint.Status ?? "ACTIVE",
          vpcId: endpoint.VpcId,
          ingestEndpointUrl: endpoint.IngestEndpointUrl,
        };
      });

      /**
       * Endpoint creation provisions VPC network interfaces and typically
       * takes a few minutes. Bounded: 15s x 40 (~10 minutes). The explicit
       * return annotation is load-bearing — see `waitForPipelineSettled` in
       * `internal.ts`.
       */
      const waitForSettled = <E, R>(
        read: Effect.Effect<osis.PipelineEndpoint | undefined, E, R>,
      ): Effect.Effect<osis.PipelineEndpoint | undefined, E, R> =>
        Effect.repeat(read, {
          schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(40)]),
          until: (endpoint): boolean => endpoint === undefined || endpoint.Status !== "CREATING",
        });

      return {
        stables: ["endpointId", "pipelineArn"],

        diff: Effect.fn(function* ({ olds, news }) {
          if (!isResolved(news)) return undefined;
          // Every property is create-only.
          if (
            olds?.pipelineArn !== news.pipelineArn ||
            !jsonEquals(olds?.vpcOptions, news.vpcOptions)
          ) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ output }) {
          // The endpoint id is assigned by OSIS on create; without a
          // persisted id there is nothing deterministic to look up.
          if (output?.endpointId === undefined) return undefined;
          const endpoint = yield* findEndpoint(output.endpointId);
          if (endpoint === undefined) return undefined;
          // Endpoints are not taggable — ownership is implied by the
          // persisted create-assigned id.
          return yield* toAttrs(endpoint);
        }),

        reconcile: Effect.fn(function* ({ news, output, session }) {
          const props = news!;

          // 1. Observe — the persisted id is a cache, not a guarantee.
          let observed =
            output?.endpointId !== undefined ? yield* findEndpoint(output.endpointId) : undefined;

          // 2. Ensure — create if missing (ids are server-assigned, so
          // there is no AlreadyExists race to tolerate).
          if (observed === undefined) {
            const created = yield* osis.createPipelineEndpoint({
              PipelineArn: props.pipelineArn,
              VpcOptions: {
                SubnetIds: props.vpcOptions.subnetIds,
                SecurityGroupIds: props.vpcOptions.securityGroupIds,
              },
            });
            if (created.EndpointId === undefined) {
              return yield* new PipelineEndpointUnexpectedResponse({
                message: "OSIS createPipelineEndpoint returned no EndpointId",
              });
            }
            observed = yield* findEndpoint(created.EndpointId);
          }

          // Wait (bounded) for the asynchronous create to settle; there is
          // no mutable aspect to sync — every property is create-only.
          if (observed?.Status === "CREATING" && observed.EndpointId) {
            observed = yield* waitForSettled(findEndpoint(observed.EndpointId));
          }
          if (observed === undefined) {
            return yield* new PipelineEndpointUnexpectedResponse({
              message: "OSIS pipeline endpoint disappeared while waiting for create",
            });
          }
          if (observed.Status === "CREATE_FAILED") {
            return yield* new PipelineEndpointCreateFailed({
              endpointId: observed.EndpointId ?? "",
              status: observed.Status,
            });
          }

          yield* session.note(observed.EndpointId ?? "");
          return yield* toAttrs(observed);
        }),

        delete: Effect.fn(function* ({ output }) {
          // Observe first for idempotency — the delete error union carries
          // no typed not-found tag.
          const observed = yield* findEndpoint(output.endpointId);
          if (observed === undefined || observed.Status === "DELETING") {
            return;
          }
          yield* osis.deletePipelineEndpoint({
            EndpointId: output.endpointId,
          });
        }),

        list: () =>
          osis.listPipelineEndpoints.pages({}).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) => page.PipelineEndpoints ?? []),
            ),
            Effect.flatMap(
              Effect.forEach((endpoint) => toAttrs(endpoint), {
                concurrency: 4,
              }),
            ),
          ),
      };
    }),
  );