sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ RePostSpace/ Space.ts

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

/** Unwrap a distilled sensitive value into its plain string. */
const unwrapSensitive = (
  value: string | Redacted.Redacted<string> | undefined,
): string | undefined =>
  value === undefined ? undefined : Redacted.isRedacted(value) ? Redacted.value(value) : value;

export interface SpaceSupportedEmailDomains {
  /**
   * Whether the supported-email-domains feature is enabled for the
   * private re:Post.
   */
  enabled?: "ENABLED" | "DISABLED";
  /**
   * Email domains allowed to join the private re:Post.
   */
  allowedDomains?: string[];
}

export interface SpaceProps {
  /**
   * Display name of the private re:Post. Must be unique within the account.
   * Changing the name replaces the space.
   * @default a deterministic physical name derived from app, stage, and id
   */
  name?: string;
  /**
   * Subdomain the private re:Post is served from
   * (`https://{subdomain}-{random}.private.repost.aws`). Must be globally
   * unique across AWS re:Post Private. Changing the subdomain replaces the
   * space.
   * @default a deterministic lowercase physical name derived from app, stage, and id
   */
  subdomain?: string;
  /**
   * Pricing tier of the private re:Post — `"BASIC"` or `"STANDARD"`.
   * Updated in place.
   * @default "BASIC"
   */
  tier?: repostspace.TierLevel;
  /**
   * Human-readable description of the private re:Post.
   */
  description?: string;
  /**
   * ARN of a customer-managed KMS key used to encrypt the space's data.
   * Changing the key replaces the space.
   * @default an AWS-owned key
   */
  userKMSKey?: string;
  /**
   * ARN of the IAM role that grants AWS re:Post Private access to
   * resources in your account (e.g. for IAM Identity Center integration).
   */
  roleArn?: string;
  /**
   * Email domains allowed to join the private re:Post without an explicit
   * invite.
   */
  supportedEmailDomains?: SpaceSupportedEmailDomains;
  /**
   * User-defined tags for the space. Merged with internal Alchemy tags.
   */
  tags?: Record<string, string>;
}

export interface Space extends Resource<
  "AWS.RePostSpace.Space",
  SpaceProps,
  {
    /**
     * Unique ID of the private re:Post space.
     */
    spaceId: string;
    /**
     * ARN of the space.
     */
    spaceArn: string;
    /**
     * Display name of the space.
     */
    name: string;
    /**
     * Current space status (e.g. `"CREATE_COMPLETED"`).
     */
    status: string;
    /**
     * IAM Identity Center configuration status of the space
     * (e.g. `"CONFIGURED"` / `"UNCONFIGURED"`).
     */
    configurationStatus: string;
    /**
     * Client ID of the space's IAM Identity Center application.
     */
    clientId: string;
    /**
     * ID of the IAM Identity Center identity store backing the space.
     */
    identityStoreId: string | undefined;
    /**
     * ARN of the space's IAM Identity Center application.
     */
    applicationArn: string | undefined;
    /**
     * Description of the space.
     */
    description: string | undefined;
    /**
     * Subdomain the space is served from.
     */
    vanityDomain: string;
    /**
     * Approval status of the vanity domain (e.g. `"PENDING"`, `"APPROVED"`).
     */
    vanityDomainStatus: string;
    /**
     * AWS-generated domain the space is reachable on.
     */
    randomDomain: string;
    /**
     * ARN of the customer-provided IAM role the space uses for account
     * integrations (mirrors the `roleArn` prop).
     */
    customerRoleArn: string | undefined;
    /**
     * Pricing tier of the space (`"BASIC"` or `"STANDARD"`).
     */
    tier: string;
    /**
     * Storage limit of the space, in bytes.
     */
    storageLimit: number;
    /**
     * Customer-managed KMS key encrypting the space's data, if any.
     */
    userKMSKey: string | undefined;
    /**
     * Tags on the space (including internal Alchemy tags).
     */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An AWS re:Post Private space — a private, organization-scoped version of
 * AWS re:Post with curated Q&A, articles, and selected public content.
 *
 * re:Post Private is a paid feature (Basic or Standard tier) that requires
 * AWS IAM Identity Center to be enabled in the account. Space provisioning
 * is asynchronous and can take tens of minutes; the provider waits for the
 * space to reach `CREATE_COMPLETED` before returning.
 * ### Creating a Space
 * **Example:** Basic Space
 * ```typescript
 * import * as RePostSpace from "@alchemy.run/aws/RePostSpace";
 *
 * const space = yield* RePostSpace.Space("Support", {
 *   subdomain: "my-org-support",
 *   tier: "BASIC",
 * });
 * ```
 *
 * **Example:** Space with Description and Tags
 * ```typescript
 * const space = yield* RePostSpace.Space("Engineering", {
 *   name: "Engineering Knowledge Base",
 *   subdomain: "my-org-engineering",
 *   tier: "STANDARD",
 *   description: "Internal Q&A for the engineering org",
 *   tags: { team: "platform" },
 * });
 * ```
 *
 * ### Encryption
 * **Example:** Space with a Customer-Managed KMS Key
 * ```typescript
 * const space = yield* RePostSpace.Space("Secure", {
 *   subdomain: "my-org-secure",
 *   userKMSKey: key.keyArn,
 * });
 * ```
 *
 * @resource
 */
export const Space = Resource<Space>("AWS.RePostSpace.Space");

const DEFAULT_TIER = "BASIC";

/**
 * Raised when a re:Post Private space enters a terminal failure state
 * (`CREATE_FAILED`) or starts deleting while the provider is waiting for
 * provisioning to complete.
 */
export class RePostSpaceProvisioningFailed extends Data.TaggedError(
  "RePostSpaceProvisioningFailed",
)<{ spaceId: string; status: string }> {}

/** Internal marker error driving the bounded readiness retry loop. */
class RePostSpaceNotReady extends Data.TaggedError("RePostSpaceNotReady")<{
  spaceId: string;
  status: string;
}> {}

const sameStringSet = (
  a: readonly string[] | undefined,
  b: readonly string[] | undefined,
): boolean => {
  const left = [...new Set(a ?? [])].sort();
  const right = [...new Set(b ?? [])].sort();
  return left.length === right.length && left.every((v, i) => v === right[i]);
};

export const SpaceProvider = () =>
  Provider.effect(
    Space,
    Effect.gen(function* () {
      const toName = (id: string, props: Partial<SpaceProps>) =>
        props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 30 });

      const toSubdomain = (id: string, props: Partial<SpaceProps>) =>
        props.subdomain
          ? Effect.succeed(props.subdomain)
          : createPhysicalName({ id, maxLength: 63, lowercase: true });

      const getSpaceOrUndefined = Effect.fn(function* (spaceId: string) {
        return yield* repostspace
          .getSpace({ spaceId })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      // Locate a live (not deleting/deleted) space by display name. Space
      // IDs are auto-assigned, so this is the fallback when the state
      // output cache is absent (e.g. after a past persistence failure).
      const findByName = Effect.fn(function* (name: string) {
        const chunk = yield* repostspace.listSpaces.items({}).pipe(Stream.runCollect);
        return Array.from(chunk).find(
          (space) => unwrapSensitive(space.name) === name && !space.status.startsWith("DELETE"),
        );
      });

      const readSpaceTags = Effect.fn(function* (arn: string) {
        const response = yield* repostspace
          .listTagsForResource({ resourceArn: arn })
          .pipe(Effect.orElseSucceed(() => undefined));
        const tags: Record<string, string> = {};
        for (const [key, value] of Object.entries(response?.tags ?? {})) {
          if (value !== undefined) tags[key] = value;
        }
        return tags;
      });

      // Explicitly-typed pipeable retry helper. Inlining `Effect.retry` in a
      // provider lifecycle op leaks `Retry.Return`'s conditional into
      // declaration emit and widens the provider layer to `unknown` R for
      // every consumer of `AWS.providers()`.
      const retryWhileSpaceNotReady = <A, E extends { readonly _tag: string }, R>(
        self: Effect.Effect<A, E, R>,
      ): Effect.Effect<A, E, R> =>
        Effect.retry(self, {
          while: (e) => e._tag === "RePostSpaceNotReady",
          schedule: Schedule.max([Schedule.fixed("30 seconds"), Schedule.recurs(80)]),
        });

      // Bounded readiness wait. Space provisioning is asynchronous and can
      // take ~30 minutes; budget 40 min (80 * 30s). CREATE_FAILED and any
      // DELETE* status are terminal failures and stop the retry loop.
      const waitForCreated = Effect.fn(function* (spaceId: string) {
        return yield* retryWhileSpaceNotReady(
          Effect.gen(function* () {
            const space = yield* repostspace.getSpace({ spaceId });
            if (space.status === "CREATE_FAILED" || space.status.startsWith("DELETE")) {
              return yield* new RePostSpaceProvisioningFailed({
                spaceId,
                status: space.status,
              });
            }
            if (space.status !== "CREATE_COMPLETED") {
              return yield* new RePostSpaceNotReady({ spaceId, status: space.status });
            }
            return space;
          }),
        );
      });

      const toAttrs = Effect.fn(function* (space: repostspace.GetSpaceOutput) {
        return {
          spaceId: space.spaceId,
          spaceArn: space.arn,
          name: unwrapSensitive(space.name) ?? "",
          status: space.status,
          configurationStatus: space.configurationStatus,
          clientId: space.clientId,
          identityStoreId: space.identityStoreId,
          applicationArn: space.applicationArn,
          description: unwrapSensitive(space.description),
          vanityDomain: space.vanityDomain,
          vanityDomainStatus: space.vanityDomainStatus,
          randomDomain: space.randomDomain,
          customerRoleArn: space.customerRoleArn,
          tier: space.tier,
          storageLimit: space.storageLimit,
          userKMSKey: space.userKMSKey,
          tags: yield* readSpaceTags(space.arn),
        };
      });

      return Space.Provider.of({
        stables: ["spaceId", "spaceArn", "clientId"],

        list: () =>
          Effect.gen(function* () {
            const chunk = yield* repostspace.listSpaces.items({}).pipe(Stream.runCollect);
            const items = yield* Effect.forEach(
              Array.from(chunk),
              (space) =>
                repostspace.getSpace({ spaceId: space.spaceId }).pipe(
                  Effect.flatMap((full) => toAttrs(full)),
                  // A space can vanish between enumeration and hydration.
                  Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
                ),
              { concurrency: 4 },
            );
            return items.filter(Predicate.isNotUndefined);
          }),

        read: Effect.fn(function* ({ id, olds, output }) {
          let spaceId = output?.spaceId;
          if (spaceId === undefined) {
            const name = yield* toName(id, olds ?? {});
            const found = yield* findByName(name);
            spaceId = found?.spaceId;
          }
          if (spaceId === undefined) return undefined;
          const space = yield* getSpaceOrUndefined(spaceId);
          if (space === undefined || space.status.startsWith("DELETE")) {
            return undefined;
          }
          const attrs = yield* toAttrs(space);
          return (yield* hasAlchemyTags(id, attrs.tags)) ? attrs : Unowned(attrs);
        }),

        diff: Effect.fn(function* ({ id, olds, news }) {
          if (!isResolved(news)) return undefined;
          const n = news ?? {};
          const o = olds ?? {};
          // Create-only properties force a replacement.
          if ((yield* toName(id, o)) !== (yield* toName(id, n))) {
            return { action: "replace" } as const;
          }
          if ((yield* toSubdomain(id, o)) !== (yield* toSubdomain(id, n))) {
            return { action: "replace" } as const;
          }
          if (n.userKMSKey !== o.userKMSKey) {
            return { action: "replace" } as const;
          }
          // tier, description, roleArn, supportedEmailDomains update in place.
        }),

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

          // 1. Observe — cloud state is authoritative; output is only an
          //    id cache. Fall through to a by-name lookup when the cached
          //    space no longer exists.
          let spaceId = output?.spaceId;
          if (spaceId !== undefined) {
            const cached = yield* getSpaceOrUndefined(spaceId);
            if (cached === undefined || cached.status.startsWith("DELETE")) {
              spaceId = undefined;
            }
          }
          if (spaceId === undefined) {
            const found = yield* findByName(name);
            spaceId = found?.spaceId;
          }

          // 2. Ensure — create if missing; a ConflictException means a peer
          //    created it concurrently (or the name/subdomain is taken), so
          //    fall back to the by-name lookup.
          if (spaceId === undefined) {
            const subdomain = yield* toSubdomain(id, props);
            spaceId = yield* repostspace
              .createSpace({
                name,
                subdomain,
                tier: desiredTier,
                description: props.description,
                userKMSKey: props.userKMSKey,
                roleArn: props.roleArn,
                supportedEmailDomains: props.supportedEmailDomains,
                tags: desiredTags,
              })
              .pipe(
                Effect.map((r) => r.spaceId),
                Effect.catchTag("ConflictException", (error) =>
                  findByName(name).pipe(
                    Effect.flatMap((existing) =>
                      existing !== undefined
                        ? Effect.succeed(existing.spaceId)
                        : Effect.fail(error),
                    ),
                  ),
                ),
              );
            yield* session.note(`created space ${spaceId}, provisioning...`);
          }

          // Provisioning is asynchronous — wait (bounded) for the space to
          // become usable before syncing mutable aspects.
          let observed = yield* waitForCreated(spaceId);

          // 3. Sync — compute the update delta from OBSERVED state and call
          //    updateSpace only when something actually changed.
          const update: {
            description?: string;
            tier?: repostspace.TierLevel;
            roleArn?: string;
            supportedEmailDomains?: repostspace.SupportedEmailDomainsParameters;
          } = {};
          let mutated = false;
          if (
            props.description !== undefined &&
            props.description !== unwrapSensitive(observed.description)
          ) {
            update.description = props.description;
            mutated = true;
          }
          if (props.tier !== undefined && props.tier !== observed.tier) {
            update.tier = props.tier;
            mutated = true;
          }
          if (props.roleArn !== undefined && props.roleArn !== observed.customerRoleArn) {
            update.roleArn = props.roleArn;
            mutated = true;
          }
          if (props.supportedEmailDomains !== undefined) {
            const observedDomains = (observed.supportedEmailDomains?.allowedDomains ?? []).map(
              (domain: string | Redacted.Redacted<string>) => unwrapSensitive(domain) ?? "",
            );
            if (
              props.supportedEmailDomains.enabled !== observed.supportedEmailDomains?.enabled ||
              !sameStringSet(props.supportedEmailDomains.allowedDomains, observedDomains)
            ) {
              update.supportedEmailDomains = props.supportedEmailDomains;
              mutated = true;
            }
          }
          if (mutated) {
            yield* repostspace.updateSpace({ spaceId, ...update });
            const refreshed = yield* getSpaceOrUndefined(spaceId);
            if (refreshed !== undefined) observed = refreshed;
          }

          // 3b. Sync tags — diff against OBSERVED cloud tags so adoption
          //     converges.
          const observedTags = yield* readSpaceTags(observed.arn);
          const { removed, upsert } = diffTags(observedTags, desiredTags);
          if (upsert.length > 0) {
            yield* repostspace.tagResource({
              resourceArn: observed.arn,
              tags: Object.fromEntries(upsert.map((t) => [t.Key, t.Value])),
            });
          }
          if (removed.length > 0) {
            yield* repostspace.untagResource({
              resourceArn: observed.arn,
              tagKeys: removed,
            });
          }

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

        delete: Effect.fn(function* ({ output }) {
          yield* repostspace
            .deleteSpace({ spaceId: output.spaceId })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      });
    }),
  );