sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ OpenSearch/ DataPlaneHttp.ts

import * as Credentials from "@distilled.cloud/aws/Credentials";
import * as Region from "@distilled.cloud/aws/Region";
import * as SigV4 from "@distilled.cloud/aws/SigV4";
/**
 * Shared scaffolding for the OpenSearch domain data-plane bindings.
 *
 * An OpenSearch domain serves its search/index REST API under the domain's
 * `endpoint`, authorized by the IAM method actions (`es:ESHttpGet`,
 * `es:ESHttpPut`, …). There is no distilled operation for these — every
 * request is a SigV4-signed HTTP call (service `"es"`) made with the host
 * Function's own credentials.
 *
 * NOT exported from `index.ts` — only the per-capability contracts
 * (`DomainRead` / `DomainWrite` / `DomainReadWrite`) and their `*Http`
 * layers are public.
 */
import * as Output from "alchemy/Output";
import type { SourceError } from "effect/ConfigProvider";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";
import * as AWSBindings from "../AWSBindings.ts";
import type {
  BulkResponse,
  CountResponse,
  GetDocumentResponse,
  RefreshOption,
  SearchRequest,
  SearchResponse,
  WriteDocumentResponse,
} from "./DataPlaneTypes.ts";
import { OpenSearchApiError } from "./DataPlaneTypes.ts";
import type { Domain } from "./Domain.ts";
import type { ReadDomainClient } from "./DomainRead.ts";
import type { WriteDomainClient } from "./DomainWrite.ts";

/** One signed request against the domain's REST data plane. */
export interface OpenSearchHttpRequest {
  method: "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "PATCH";
  /** Path relative to the domain endpoint, e.g. `"songs/_search"`. */
  path: string;
  /** Query-string parameters (undefined values are skipped). */
  query?: Record<string, string | undefined>;
  /** JSON body (sent as `application/json`). */
  json?: unknown;
  /** Raw NDJSON body (used by `_bulk`; sent as `application/x-ndjson`). */
  ndjson?: string;
  /** Statuses (besides 2xx) whose body is returned instead of failing. */
  allowStatuses?: readonly number[];
}

/**
 * Signs and sends one {@link OpenSearchHttpRequest} and returns the parsed
 * JSON body (`undefined` for empty bodies, e.g. `HEAD` responses — check
 * `status` instead).
 */
export type OpenSearchSend = (
  request: OpenSearchHttpRequest,
) => Effect.Effect<
  { status: number; body: unknown },
  OpenSearchApiError | Credentials.CredentialsError | SourceError | SigV4.SigningError
>;

const refreshParam = (refresh: RefreshOption | undefined): Record<string, string | undefined> =>
  refresh === undefined ? {} : { refresh: String(refresh) };

/**
 * Build the shared body of an OpenSearch data-plane `*Http` binding layer:
 * resolve the ambient distilled `Credentials`/`Region` context once at layer
 * construction, register the least-privilege IAM statement on the host
 * Function at deploy time (`iamActions` on the domain and `domain/*`), and
 * hand a signed-request `send` function to the capability-specific
 * `makeClient`.
 */
export const makeOpenSearchDataPlaneBinding = <Client>(options: {
  /** Capability name used in the binding SID and trace spans, e.g. `"DomainRead"`. */
  name: string;
  /** IAM actions the capability requires, e.g. `["es:ESHttpGet"]`. */
  iamActions: string[];
  /** Build the typed runtime client from the signed-request sender. */
  makeClient: (send: OpenSearchSend) => Client;
}) =>
  Effect.gen(function* () {
    const bind = yield* AWSBindings.Bind;
    const services = yield* AWSBindings.withCredentials(
      Effect.context<Credentials.Credentials | Region.Region>(),
    );

    return Effect.fn(function* (domain: Domain) {
      const Endpoint = yield* domain.endpoint;
      if (!globalThis.__ALCHEMY_RUNTIME__) {
        yield* bind`AWS.OpenSearch.${options.name}(${domain})`({
          policyStatements: [
            {
              Effect: "Allow",
              Action: options.iamActions,
              Resource: [domain.domainArn, Output.interpolate`${domain.domainArn}/*`],
            },
          ],
        });
      }

      const send: OpenSearchSend = Effect.fn(`AWS.OpenSearch.${options.name}(${domain.LogicalId})`)(
        function* (request: OpenSearchHttpRequest) {
          const endpoint = yield* Endpoint;
          if (endpoint === undefined) {
            return yield* new OpenSearchApiError({
              method: request.method,
              path: request.path,
              status: 0,
              body: "domain has no endpoint (still provisioning, or VPC-only)",
            });
          }

          const url = new URL(
            request.path.replace(/^\//, ""),
            `https://${endpoint.replace(/^https?:\/\//, "")}/`,
          );
          for (const [key, value] of Object.entries(request.query ?? {})) {
            if (value !== undefined) url.searchParams.set(key, value);
          }

          const headers: Record<string, string> = {};
          let body: string | undefined;
          if (request.json !== undefined) {
            body = JSON.stringify(request.json);
            headers["content-type"] = "application/json";
          } else if (request.ndjson !== undefined) {
            body = request.ndjson;
            headers["content-type"] = "application/x-ndjson";
          }

          // Resolve credentials fresh per request (SSO/STS sessions rotate) and
          // sign for the domain's own region, parsed from its endpoint.
          const { credentials, region } = yield* Effect.gen(function* () {
            const credentials = yield* yield* Credentials.Credentials;
            const region =
              /\.([a-z0-9-]+)\.(?:es|aos)\.amazonaws\.com$/.exec(url.hostname)?.[1] ??
              (yield* yield* Region.Region);
            return { credentials, region };
          }).pipe(Effect.provideContext(services));

          const signed = yield* SigV4.sign({
            method: request.method,
            url: url.toString(),
            headers,
            body,
            accessKeyId: Redacted.value(credentials.accessKeyId),
            secretAccessKey: credentials.secretAccessKey,
            sessionToken: credentials.sessionToken,
            service: "es",
            region,
            allHeaders: true,
          });

          const toError = (status: number) => (cause: unknown) =>
            new OpenSearchApiError({
              method: request.method,
              path: request.path,
              status,
              body: cause instanceof Error ? cause.message : String(cause),
            });

          const response = yield* Effect.tryPromise({
            try: () =>
              fetch(signed.url, {
                method: signed.method,
                headers: signed.headers,
                body,
              }),
            catch: toError(0),
          });
          const text = yield* Effect.tryPromise({
            try: () => response.text(),
            catch: toError(response.status),
          });

          const ok =
            (response.status >= 200 && response.status < 300) ||
            (request.allowStatuses?.includes(response.status) ?? false);
          if (!ok) {
            return yield* new OpenSearchApiError({
              method: request.method,
              path: request.path,
              status: response.status,
              body: text,
            });
          }
          if (text.trim() === "") {
            return { status: response.status, body: undefined };
          }

          const parsed = yield* Effect.try({
            try: () => JSON.parse(text) as unknown,
            catch: toError(response.status),
          });
          return { status: response.status, body: parsed };
        },
      );

      return options.makeClient(send);
    });
  });

const encodePath = (...segments: string[]): string =>
  segments.map((segment) => encodeURIComponent(segment)).join("/");

/** Build the read half of the domain data-plane client. */
export const makeReadDomainClient = (send: OpenSearchSend): ReadDomainClient => ({
  search: <TDoc>(request?: SearchRequest) =>
    send({
      method: "GET",
      path:
        request?.index !== undefined ? `${encodeURIComponent(request.index)}/_search` : "_search",
      query: {
        ...request?.query,
        // The Query-DSL body travels in the `source` parameter so searches
        // stay on es:ESHttpGet (POST would require the write IAM action).
        ...(request?.body !== undefined
          ? {
              source: JSON.stringify(request.body),
              source_content_type: "application/json",
            }
          : {}),
      },
    }).pipe(Effect.map(({ body }) => body as SearchResponse<TDoc>)),
  count: (request) =>
    send({
      method: "GET",
      path: request?.index !== undefined ? `${encodeURIComponent(request.index)}/_count` : "_count",
      query:
        request?.body !== undefined
          ? {
              source: JSON.stringify(request.body),
              source_content_type: "application/json",
            }
          : undefined,
    }).pipe(Effect.map(({ body }) => body as CountResponse)),
  getDocument: <TDoc>(index: string, id: string) =>
    send({
      method: "GET",
      path: encodePath(index, "_doc", id),
      allowStatuses: [404],
    }).pipe(Effect.map(({ body }) => body as GetDocumentResponse<TDoc>)),
  existsDocument: (index, id) =>
    send({
      method: "HEAD",
      path: encodePath(index, "_doc", id),
      allowStatuses: [404],
    }).pipe(Effect.map(({ status }) => status === 200)),
  get: (path, query) => send({ method: "GET", path, query }).pipe(Effect.map(({ body }) => body)),
});

/** Build the write half of the domain data-plane client. */
export const makeWriteDomainClient = (send: OpenSearchSend): WriteDomainClient => ({
  indexDocument: (index, document, options) =>
    send(
      options?.id !== undefined
        ? {
            method: "PUT",
            path: encodePath(index, "_doc", options.id),
            json: document,
            query: refreshParam(options.refresh),
          }
        : {
            method: "POST",
            path: encodePath(index, "_doc"),
            json: document,
            query: refreshParam(options?.refresh),
          },
    ).pipe(Effect.map(({ body }) => body as WriteDocumentResponse)),
  updateDocument: (index, id, body, options) =>
    send({
      method: "POST",
      path: encodePath(index, "_update", id),
      json: body,
      query: refreshParam(options?.refresh),
    }).pipe(Effect.map(({ body }) => body as WriteDocumentResponse)),
  deleteDocument: (index, id, options) =>
    send({
      method: "DELETE",
      path: encodePath(index, "_doc", id),
      query: refreshParam(options?.refresh),
      allowStatuses: [404],
    }).pipe(Effect.map(({ body }) => body as WriteDocumentResponse)),
  bulk: (operations, options) =>
    send({
      method: "POST",
      path: "_bulk",
      ndjson: `${operations.map((line) => JSON.stringify(line)).join("\n")}\n`,
      query: refreshParam(options?.refresh),
    }).pipe(Effect.map(({ body }) => body as BulkResponse)),
});