sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ HealthLake/ FHIRDatastore.ts

import * as healthlake from "@distilled.cloud/aws/healthlake";
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, diffTags, hasAlchemyTags } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import type { Providers } from "../Providers.ts";

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

export interface FHIRDatastoreIdentityProviderProps {
  /**
   * Authorization strategy for the data store — `"AWS_AUTH"` (SigV4, the
   * default), `"SMART_ON_FHIR"` or `"SMART_ON_FHIR_V1"`.
   */
  authorizationStrategy: healthlake.AuthorizationStrategy;
  /**
   * Whether fine-grained (SMART on FHIR scope based) authorization is
   * enabled.
   * @default false
   */
  fineGrainedAuthorizationEnabled?: boolean;
  /**
   * JSON metadata elements the identity provider uses in its authorization
   * flow (issuer, authorization/token endpoints, etc.).
   */
  metadata?: string;
  /**
   * ARN of the Lambda function the data store invokes to decode SMART on
   * FHIR access tokens.
   */
  idpLambdaArn?: string;
}

export interface FHIRDatastoreProps {
  /**
   * Name of the data store. Names do not have to be unique within an
   * account; the data store is identified by its auto-assigned id. Updated
   * in place.
   * @default a deterministic physical name derived from app, stage and logical id
   */
  datastoreName?: string;
  /**
   * FHIR release version supported by the data store. Only `"R4"` is
   * currently supported. Changing this replaces the data store.
   * @default "R4"
   */
  datastoreTypeVersion?: healthlake.FHIRVersion;
  /**
   * Customer-managed KMS key (id, ARN or alias) used to encrypt the data
   * store at rest. Changing this replaces the data store.
   * @default an AWS-owned KMS key
   */
  kmsKeyId?: string;
  /**
   * Preload the data store with synthetic sample data on creation —
   * `"SYNTHEA"` loads ~100k synthetic patient records. Changing this
   * replaces the data store.
   * @default no preloaded data
   */
  preloadDataType?: healthlake.PreloadDataType;
  /**
   * Identity provider configuration for SMART on FHIR authorization.
   * Updated in place.
   * @default AWS_AUTH (SigV4)
   */
  identityProviderConfiguration?: FHIRDatastoreIdentityProviderProps;
  /**
   * User-defined tags for the data store.
   */
  tags?: Record<string, string>;
}

export interface FHIRDatastore extends Resource<
  "AWS.HealthLake.FHIRDatastore",
  FHIRDatastoreProps,
  {
    /** The unique ID of the datastore. */
    datastoreId: string;
    /** The ARN of the datastore. */
    datastoreArn: string;
    /** The name of the datastore. */
    datastoreName: string;
    /** The current status of the datastore (`ACTIVE`, `CREATING`, ...). */
    datastoreStatus: string;
    /** The FHIR REST API endpoint of the datastore. */
    datastoreEndpoint: string;
    /** The FHIR version of the datastore (`R4`). */
    datastoreTypeVersion: string;
    /** The tags applied to the datastore. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An AWS HealthLake FHIR-enabled data store — a HIPAA-eligible, managed
 * store for FHIR R4 health data with a FHIR REST endpoint plus bulk
 * import/export.
 *
 * Data stores take roughly 15-30 minutes to provision (`CREATING` →
 * `ACTIVE`) and are billed while they exist; deletion is also asynchronous
 * (`DELETING` → gone). Destroy data stores you are not using.
 * ### Creating a Data Store
 * **Example:** Basic FHIR R4 Data Store
 * ```typescript
 * const datastore = yield* FHIRDatastore("Records", {});
 * ```
 *
 * **Example:** Data Store Preloaded with Synthetic Data
 * ```typescript
 * const datastore = yield* FHIRDatastore("Sandbox", {
 *   preloadDataType: "SYNTHEA",
 * });
 * ```
 *
 * ### Encryption
 * **Example:** Data Store Encrypted with a Customer-Managed KMS Key
 * ```typescript
 * const key = yield* KMS.Key("RecordsKey", {
 *   description: "healthlake data store key",
 * });
 * const datastore = yield* FHIRDatastore("Records", {
 *   kmsKeyId: key.keyArn,
 * });
 * ```
 *
 * @resource
 */
export const FHIRDatastore = Resource<FHIRDatastore>("AWS.HealthLake.FHIRDatastore");

const DEFAULT_FHIR_VERSION: healthlake.FHIRVersion = "R4";

const toIdpConfig = (
  props: FHIRDatastoreIdentityProviderProps | undefined,
): healthlake.IdentityProviderConfiguration | undefined =>
  props === undefined
    ? undefined
    : {
        AuthorizationStrategy: props.authorizationStrategy,
        FineGrainedAuthorizationEnabled: props.fineGrainedAuthorizationEnabled,
        Metadata: props.metadata,
        IdpLambdaArn: props.idpLambdaArn,
      };

const sameIdpConfig = (
  observed: healthlake.IdentityProviderConfiguration | undefined,
  desired: healthlake.IdentityProviderConfiguration,
): boolean =>
  observed !== undefined &&
  observed.AuthorizationStrategy === desired.AuthorizationStrategy &&
  (observed.FineGrainedAuthorizationEnabled ?? false) ===
    (desired.FineGrainedAuthorizationEnabled ?? false) &&
  observed.Metadata === desired.Metadata &&
  observed.IdpLambdaArn === desired.IdpLambdaArn;

export const FHIRDatastoreProvider = () =>
  Provider.effect(
    FHIRDatastore,
    Effect.gen(function* () {
      const toName = (id: string, props: Partial<FHIRDatastoreProps>) =>
        props.datastoreName
          ? Effect.succeed(props.datastoreName)
          : createPhysicalName({ id, maxLength: 256 });

      const readDatastoreTags = Effect.fn(function* (arn: string) {
        const response = yield* healthlake
          .listTagsForResource({ ResourceARN: arn })
          .pipe(Effect.orElseSucceed(() => ({ Tags: [] })));
        const tags: Record<string, string> = {};
        for (const tag of response.Tags ?? []) {
          tags[tag.Key] = tag.Value;
        }
        return tags;
      });

      // Describe by id; typed not-found → undefined. A data store in
      // DELETED status still describes for a while — callers decide how to
      // treat terminal/transitional statuses.
      const readDatastore = Effect.fn(function* (datastoreId: string) {
        const response = yield* healthlake
          .describeFHIRDatastore({ DatastoreId: datastoreId })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
        return response?.DatastoreProperties;
      });

      const isGoneOrGoing = (properties: healthlake.DatastoreProperties | undefined) =>
        properties === undefined ||
        properties.DatastoreStatus === "DELETED" ||
        properties.DatastoreStatus === "DELETING";

      // Data store ids are auto-assigned; recover an existing instance from
      // its deterministic name (bounded pagination, name-filtered).
      const findByName = Effect.fn(function* (name: string) {
        let nextToken: string | undefined;
        for (let page = 0; page < 20; page++) {
          const response = yield* healthlake.listFHIRDatastores({
            Filter: { DatastoreName: name },
            NextToken: nextToken,
          });
          const match = (response.DatastorePropertiesList ?? []).find(
            (properties) => !isGoneOrGoing(properties),
          );
          if (match !== undefined) return match;
          nextToken = response.NextToken;
          if (!nextToken) break;
        }
        return undefined;
      });

      // Bounded readiness wait. Provisioning typically completes in 15-30
      // minutes; budget ~35 min (70 * 30s). Terminal failure statuses stop
      // the wait immediately.
      const waitForActive = Effect.fn(function* (datastoreId: string) {
        const properties = yield* readDatastore(datastoreId).pipe(
          Effect.repeat({
            schedule: Schedule.max([Schedule.fixed("30 seconds"), Schedule.recurs(70)]),
            until: (p) =>
              p === undefined ||
              p.DatastoreStatus === "ACTIVE" ||
              p.DatastoreStatus === "CREATE_FAILED" ||
              p.DatastoreStatus === "UPDATE_FAILED" ||
              p.DatastoreStatus === "DELETED",
          }),
        );
        if (properties === undefined || properties.DatastoreStatus !== "ACTIVE") {
          const cause = properties?.ErrorCause?.ErrorMessage;
          return yield* new FHIRDatastoreNotReady({
            message: `HealthLake data store '${datastoreId}' did not become ACTIVE (status: ${
              properties?.DatastoreStatus ?? "gone"
            }${cause ? `: ${cause}` : ""})`,
          });
        }
        return properties;
      });

      // Wait for a data store to leave a transitional state (CREATING /
      // UPDATING) so delete does not hit ConflictException.
      const waitUntilSettled = Effect.fn(function* (datastoreId: string) {
        return yield* readDatastore(datastoreId).pipe(
          Effect.repeat({
            schedule: Schedule.max([Schedule.fixed("30 seconds"), Schedule.recurs(70)]),
            until: (p) =>
              p === undefined ||
              (p.DatastoreStatus !== "CREATING" && p.DatastoreStatus !== "UPDATING"),
          }),
        );
      });

      // Deletion is asynchronous (DELETING → gone); wait until the data
      // store is fully gone. Budget ~35 min (70 * 30s).
      const waitUntilGone = Effect.fn(function* (datastoreId: string) {
        const properties = yield* readDatastore(datastoreId).pipe(
          Effect.repeat({
            schedule: Schedule.max([Schedule.fixed("30 seconds"), Schedule.recurs(70)]),
            until: (p) => p === undefined || p.DatastoreStatus === "DELETED",
          }),
        );
        if (properties !== undefined && properties.DatastoreStatus !== "DELETED") {
          return yield* new FHIRDatastoreNotReady({
            message: `HealthLake data store '${datastoreId}' still exists after deletion (status: ${properties.DatastoreStatus})`,
          });
        }
      });

      const toAttrs = Effect.fn(function* (properties: healthlake.DatastoreProperties) {
        return {
          datastoreId: properties.DatastoreId,
          datastoreArn: properties.DatastoreArn,
          datastoreName: properties.DatastoreName ?? "",
          datastoreStatus: properties.DatastoreStatus,
          datastoreEndpoint: properties.DatastoreEndpoint,
          datastoreTypeVersion: properties.DatastoreTypeVersion,
          tags: yield* readDatastoreTags(properties.DatastoreArn),
        };
      });

      return {
        stables: ["datastoreId", "datastoreArn", "datastoreEndpoint", "datastoreTypeVersion"],

        diff: Effect.fn(function* ({ olds, news }) {
          if (!isResolved(news)) return undefined;
          const n = news ?? {};
          const o = olds ?? {};
          // Create-only properties force a replacement.
          if (
            (n.datastoreTypeVersion ?? DEFAULT_FHIR_VERSION) !==
            (o.datastoreTypeVersion ?? DEFAULT_FHIR_VERSION)
          ) {
            return { action: "replace" } as const;
          }
          if (n.kmsKeyId !== o.kmsKeyId) {
            return { action: "replace" } as const;
          }
          if (n.preloadDataType !== o.preloadDataType) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ id, olds, output }) {
          let properties = output?.datastoreId
            ? yield* readDatastore(output.datastoreId)
            : undefined;
          if (isGoneOrGoing(properties)) {
            const name = yield* toName(id, olds ?? {});
            properties = yield* findByName(name);
          }
          if (properties === undefined) return undefined;
          const attrs = yield* toAttrs(properties);
          return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const props = news!;
          const name = yield* toName(id, props);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...internalTags, ...props.tags };

          // 1. Observe — cloud state is authoritative; output is only an
          //    id cache. A deleted/deleting instance is treated as missing.
          let observed = output?.datastoreId ? yield* readDatastore(output.datastoreId) : undefined;
          if (isGoneOrGoing(observed)) {
            observed = yield* findByName(name);
          }

          // 2. Ensure — create if missing, then wait (bounded) for ACTIVE.
          //    ClientToken is an idempotency token filled in by distilled.
          if (observed === undefined) {
            const created = yield* healthlake.createFHIRDatastore({
              DatastoreName: name,
              DatastoreTypeVersion: props.datastoreTypeVersion ?? DEFAULT_FHIR_VERSION,
              SseConfiguration: props.kmsKeyId
                ? {
                    KmsEncryptionConfig: {
                      CmkType: "CUSTOMER_MANAGED_KMS_KEY",
                      KmsKeyId: props.kmsKeyId,
                    },
                  }
                : undefined,
              PreloadDataConfig: props.preloadDataType
                ? { PreloadDataType: props.preloadDataType }
                : undefined,
              IdentityProviderConfiguration: toIdpConfig(props.identityProviderConfiguration),
              Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
                Key,
                Value,
              })),
            });
            observed = yield* waitForActive(created.DatastoreId);
          } else if (observed.DatastoreStatus !== "ACTIVE") {
            // Mid-flight provisioning or a prior update still converging.
            observed = yield* waitForActive(observed.DatastoreId);
          }

          // 3. Sync mutable aspects — compute the update delta from
          //    OBSERVED state; skip the API entirely on no-op.
          const update: healthlake.UpdateFHIRDatastoreRequest = {
            DatastoreId: observed.DatastoreId,
          };
          let mutated = false;
          if (observed.DatastoreName !== name) {
            update.DatastoreName = name;
            mutated = true;
          }
          const desiredIdp = toIdpConfig(props.identityProviderConfiguration);
          if (
            desiredIdp !== undefined &&
            !sameIdpConfig(observed.IdentityProviderConfiguration, desiredIdp)
          ) {
            update.IdentityProviderConfiguration = desiredIdp;
            mutated = true;
          }
          if (mutated) {
            yield* healthlake.updateFHIRDatastore(update);
            observed = yield* waitForActive(observed.DatastoreId);
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags.
          const observedTags = yield* readDatastoreTags(observed.DatastoreArn);
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* healthlake.tagResource({
              ResourceARN: observed.DatastoreArn,
              Tags: upsert,
            });
          }
          if (removed.length > 0) {
            yield* healthlake.untagResource({
              ResourceARN: observed.DatastoreArn,
              TagKeys: removed,
            });
          }

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

        delete: Effect.fn(function* ({ output }) {
          const datastoreId = output.datastoreId;
          // A data store mid-create/update rejects deletion with
          // ConflictException — wait (bounded) for it to settle first.
          const settled = yield* waitUntilSettled(datastoreId).pipe(
            Effect.orElseSucceed(() => undefined),
          );
          if (settled === undefined || settled.DatastoreStatus === "DELETED") {
            return;
          }
          if (settled.DatastoreStatus !== "DELETING") {
            yield* healthlake.deleteFHIRDatastore({ DatastoreId: datastoreId }).pipe(
              Effect.retry({
                while: (e) => e._tag === "ConflictException",
                schedule: Schedule.max([Schedule.fixed("15 seconds"), Schedule.recurs(10)]),
              }),
              Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
            );
          }
          // Deletion is asynchronous — wait until the data store is gone so
          // dependent resources (e.g. the KMS key) can be deleted next.
          yield* waitUntilGone(datastoreId);
        }),

        list: () =>
          Effect.gen(function* () {
            // Bounded hand-rolled pagination.
            const datastores: healthlake.DatastoreProperties[] = [];
            let nextToken: string | undefined;
            for (let page = 0; page < 20; page++) {
              const response = yield* healthlake.listFHIRDatastores({
                NextToken: nextToken,
              });
              datastores.push(...(response.DatastorePropertiesList ?? []));
              nextToken = response.NextToken;
              if (!nextToken) break;
            }
            return yield* Effect.forEach(
              datastores.filter((properties) => !isGoneOrGoing(properties)),
              (properties) => toAttrs(properties),
              { concurrency: 4 },
            );
          }),
      };
    }),
  );