import * as datazone from "@distilled.cloud/aws/datazone";
import * as iam from "@distilled.cloud/aws/iam";
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, hasAlchemyTags } from "alchemy/Tags";
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 { AWSEnvironment } from "../Environment.ts";
import { syncDataZoneTags, toTagRecord, unredact } from "./internal.ts";
/**
* Single sign-on configuration for a DataZone domain via IAM Identity Center.
*/
export interface DomainSingleSignOn {
/** The SSO type — `IAM_IDC` to enable IAM Identity Center, `DISABLED` otherwise. */
type?: string;
/** How users are assigned — `AUTOMATIC` or `MANUAL`. */
userAssignment?: string;
/** The ARN of the IAM Identity Center instance. */
idcInstanceArn?: string;
}
export interface DomainProps {
/**
* Display name of the domain. If omitted, a deterministic physical name is
* generated from the app, stage, and logical ID. The name is mutable — it
* converges via `UpdateDomain` without replacement.
*/
name?: string;
/**
* A description of the domain.
*/
description?: string;
/**
* The ARN of an existing IAM role for DataZone to act on behalf of domain
* users (metadata catalog, search, etc.). When omitted, an execution role
* is created automatically with `datazone.amazonaws.com` trust and the
* `AmazonDataZoneDomainExecutionRolePolicy` managed policy attached.
*/
domainExecutionRole?: string;
/**
* The ARN of the service role used by V2 (SageMaker Unified Studio)
* domains. Only relevant when `domainVersion` is `"V2"`.
*/
serviceRole?: string;
/**
* The identifier of a KMS key to encrypt the domain with. Changing it
* triggers a replacement.
*/
kmsKeyIdentifier?: string;
/**
* The version of the domain — `"V1"` (classic DataZone) or `"V2"`
* (SageMaker Unified Studio). Changing it triggers a replacement.
* @default "V1"
*/
domainVersion?: string;
/**
* Single sign-on configuration via IAM Identity Center.
*/
singleSignOn?: DomainSingleSignOn;
/**
* Tags to apply to the domain. Merged with internal Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface Domain extends Resource<
"AWS.DataZone.Domain",
DomainProps,
{
/** The unique identifier of the domain (`dzd_...`). */
domainId: string;
/** The ARN of the domain. */
domainArn: string;
/** The display name of the domain. */
name: string;
/** The status of the domain (`AVAILABLE` once settled). */
status: string;
/** The URL of the DataZone data portal for this domain. */
portalUrl: string | undefined;
/** The identifier of the root domain unit. */
rootDomainUnitId: string | undefined;
/** The ARN of the domain execution role. */
domainExecutionRole: string;
/**
* Name of the auto-created execution role. `undefined` when an explicit
* {@link DomainProps.domainExecutionRole} is used.
*/
roleName: string | undefined;
}
> {}
/**
* An Amazon DataZone domain — the top-level container for data-governance
* projects, environments, glossaries, and assets.
*
* `Domain` owns the domain lifecycle. Domain creation is asynchronous
* (typically 1–2 minutes) and is polled to `AVAILABLE` with a bounded wait.
* An execution role is created automatically (trusted by
* `datazone.amazonaws.com`, with the `AmazonDataZoneDomainExecutionRolePolicy`
* managed policy) unless an explicit `domainExecutionRole` is supplied.
*
* ### Creating Domains
* **Example:** Minimal Domain
* ```typescript
* import * as DataZone from "@alchemy.run/aws/DataZone";
*
* const domain = yield* DataZone.Domain("governance", {
* description: "Company-wide data governance domain",
* });
* ```
*
* **Example:** Domain with an Explicit Execution Role
* ```typescript
* const domain = yield* DataZone.Domain("governance", {
* name: "acme-governance",
* domainExecutionRole: role.roleArn,
* tags: { Team: "data-platform" },
* });
* ```
*
* ### Using the Domain
* **Example:** Create a Project in the Domain
* ```typescript
* const project = yield* DataZone.Project("analytics", {
* domainId: domain.domainId,
* description: "Analytics team project",
* });
* ```
*
* @resource
*/
export const Domain = Resource<Domain>("AWS.DataZone.Domain");
/** The domain never leaves a failed create — surface it as a typed error. */
export class DomainCreationFailed extends Data.TaggedError("AWS.DataZone.DomainCreationFailed")<{
readonly domainId: string;
readonly status: string;
}> {}
/** Domain status values indicating an in-flight transition to wait out. */
const DOMAIN_TRANSIENT = new Set(["CREATING", "DELETING"]);
/**
* A freshly created (or re-observed) IAM role is eventually consistent;
* `createDomain` / `updateDomain` can transiently reject a role DataZone
* cannot yet assume. Wrapped in an explicitly-typed helper so the
* `Effect.retry` conditional return type does not leak into declaration emit
* and widen the provider layer's requirement to `unknown` (see PATTERNS §7).
*/
const retryWhileRoleAssumeFails = <A, E extends { _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) =>
(e._tag === "ValidationException" || e._tag === "AccessDeniedException") &&
"message" in e &&
typeof e.message === "string" &&
(e.message.toLowerCase().includes("role") || e.message.toLowerCase().includes("assume")),
schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
});
const DOMAIN_EXECUTION_MANAGED_POLICY =
"arn:aws:iam::aws:policy/service-role/AmazonDataZoneDomainExecutionRolePolicy";
export const DomainProvider = () =>
Provider.effect(
Domain,
Effect.gen(function* () {
const createName = Effect.fn(function* (id: string, props: DomainProps) {
return props.name ?? (yield* createPhysicalName({ id, maxLength: 64 }));
});
const createRoleName = (id: string) => createPhysicalName({ id, maxLength: 64 });
// A deleted (or never-existing) domain is reported by GetDomain as
// AccessDeniedException ("User is not permitted to perform operation:
// GetDomain"), NOT ResourceNotFoundException — DataZone evaluates
// domain-scoped authorization before existence. Both mean "absent".
const getDomainOrUndefined = Effect.fn(function* (identifier: string) {
return yield* datazone.getDomain({ identifier }).pipe(
Effect.catchTags({
ResourceNotFoundException: () => Effect.undefined,
AccessDeniedException: () => Effect.undefined,
}),
);
});
const findByName = Effect.fn(function* (name: string) {
const pages = yield* datazone.listDomains.pages({}).pipe(Stream.runCollect);
const summary = Array.from(pages)
.flatMap((page) => page.items ?? [])
.find(
(s) => unredact(s.name) === name && s.status !== "DELETING" && s.status !== "DELETED",
);
return summary?.id;
});
// Poll the domain to a settled (non-transient) status. V1 domains are
// usually AVAILABLE synchronously; V2 creation takes 1-2 minutes —
// bounded at ~3 minutes. An "absent" observation keeps polling: right
// after createDomain the creator's user profile can lag, surfacing the
// same AccessDenied that a deleted domain does.
const waitForSettled = Effect.fn(function* (identifier: string) {
return yield* getDomainOrUndefined(identifier).pipe(
Effect.repeat({
schedule: Schedule.fixed("5 seconds"),
until: (domain) => domain !== undefined && !DOMAIN_TRANSIENT.has(domain.status),
times: 36,
}),
);
});
// Poll the domain until it no longer exists. Domain deletion typically
// completes in 1-2 minutes — bounded at ~3 minutes.
const waitForGone = Effect.fn(function* (identifier: string) {
yield* getDomainOrUndefined(identifier).pipe(
Effect.repeat({
schedule: Schedule.fixed("5 seconds"),
until: (domain) => domain === undefined || domain.status === "DELETED",
times: 36,
}),
);
});
const domainArnOf = (region: string, accountId: string, domainId: string) =>
`arn:aws:datazone:${region}:${accountId}:domain/${domainId}`;
const ensureExecutionRole = Effect.fn(function* ({
id,
roleName,
accountId,
}: {
id: string;
roleName: string;
accountId: string;
}) {
const tags = yield* createInternalTags(id);
const role = yield* iam
.createRole({
RoleName: roleName,
AssumeRolePolicyDocument: JSON.stringify({
Version: "2012-10-17",
Statement: [
{
Effect: "Allow",
Principal: { Service: "datazone.amazonaws.com" },
Action: ["sts:AssumeRole", "sts:TagSession"],
Condition: {
StringEquals: { "aws:SourceAccount": accountId },
"ForAllValues:StringLike": { "aws:TagKeys": "datazone*" },
},
},
],
}),
Tags: Object.entries(tags).map(([Key, Value]) => ({ Key, Value })),
})
.pipe(
Effect.catchTag("EntityAlreadyExistsException", () =>
iam.getRole({ RoleName: roleName }),
),
);
yield* iam
.attachRolePolicy({
RoleName: roleName,
PolicyArn: DOMAIN_EXECUTION_MANAGED_POLICY,
})
.pipe(
// attaching an already-attached managed policy is a no-op, but
// tolerate racy duplicates anyway.
Effect.catchTag("InvalidInputException", () => Effect.void),
);
return role.Role.Arn;
});
return Domain.Provider.of({
stables: ["domainId", "domainArn", "rootDomainUnitId"],
list: () =>
Effect.gen(function* () {
const { region, accountId } = yield* AWSEnvironment.current;
const pages = yield* datazone.listDomains.pages({}).pipe(Stream.runCollect);
const summaries = Array.from(pages)
.flatMap((page) => page.items ?? [])
.filter((s) => s.status !== "DELETING" && s.status !== "DELETED");
return summaries.map((s) => ({
domainId: s.id,
domainArn: s.arn ?? domainArnOf(region, accountId, s.id),
name: unredact(s.name),
status: s.status,
portalUrl: s.portalUrl,
rootDomainUnitId: undefined as string | undefined,
domainExecutionRole: "",
roleName: undefined as string | undefined,
}));
}),
read: Effect.fn(function* ({ id, olds, output }) {
const { region, accountId } = yield* AWSEnvironment.current;
const domainId =
output?.domainId ??
(yield* findByName(output?.name ?? (yield* createName(id, olds ?? {}))));
if (domainId === undefined) return undefined;
const domain = yield* getDomainOrUndefined(domainId);
if (domain === undefined || domain.status === "DELETING" || domain.status === "DELETED") {
return undefined;
}
const attrs = {
domainId: domain.id,
domainArn: domain.arn ?? domainArnOf(region, accountId, domain.id),
name: domain.name ?? "",
status: domain.status,
portalUrl: domain.portalUrl,
rootDomainUnitId: domain.rootDomainUnitId,
domainExecutionRole: domain.domainExecutionRole,
roleName: output?.roleName,
};
const tags = toTagRecord(domain.tags);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return undefined;
if (olds?.kmsKeyIdentifier !== news?.kmsKeyIdentifier) {
return { action: "replace" } as const;
}
if (olds?.domainVersion !== news?.domainVersion) {
return { action: "replace" } as const;
}
// name, description, execution role, service role, SSO, and tags
// all converge via updateDomain / tagResource.
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const { accountId, region } = yield* AWSEnvironment.current;
const name = yield* createName(id, news);
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
// Ensure the execution role first — the domain cannot exist without
// one. Managed unless an explicit domainExecutionRole is provided.
let executionRoleArn = news.domainExecutionRole;
let roleName = output?.roleName;
if (executionRoleArn === undefined) {
roleName = roleName ?? (yield* createRoleName(id));
executionRoleArn = yield* ensureExecutionRole({
id,
roleName,
accountId,
});
}
// 1. OBSERVE — cloud state is authoritative; output is only an id
// cache. Fall back to a name lookup after state loss.
let domain = output?.domainId ? yield* getDomainOrUndefined(output.domainId) : undefined;
if (domain === undefined) {
const foundId = yield* findByName(name);
if (foundId !== undefined) {
domain = yield* getDomainOrUndefined(foundId);
}
}
if (domain === undefined) {
// 2. ENSURE — create and wait out the async provisioning.
const created = yield* retryWhileRoleAssumeFails(
datazone.createDomain({
name,
description: news.description,
domainExecutionRole: executionRoleArn,
serviceRole: news.serviceRole,
kmsKeyIdentifier: news.kmsKeyIdentifier,
domainVersion: news.domainVersion,
singleSignOn: news.singleSignOn,
tags: desiredTags,
}),
);
domain = (yield* waitForSettled(created.id)) ?? undefined;
if (domain === undefined || domain.status !== "AVAILABLE") {
return yield* new DomainCreationFailed({
domainId: created.id,
status: domain?.status ?? "CREATING",
});
}
} else {
// 3. SYNC — wait out any in-flight transition, then converge the
// mutable aspects by diffing OBSERVED state against desired.
domain = (yield* waitForSettled(domain.id)) ?? domain;
const drifted =
domain.name !== name ||
(domain.description ?? undefined) !== (news.description ?? undefined) ||
domain.domainExecutionRole !== executionRoleArn ||
(news.serviceRole !== undefined && domain.serviceRole !== news.serviceRole);
if (drifted) {
yield* retryWhileRoleAssumeFails(
datazone.updateDomain({
identifier: domain.id,
name,
description: news.description,
domainExecutionRole: executionRoleArn,
serviceRole: news.serviceRole,
singleSignOn: news.singleSignOn,
}),
);
domain = (yield* getDomainOrUndefined(domain.id)) ?? domain;
}
}
const domainId = domain.id;
const domainArn = domain.arn ?? domainArnOf(region, accountId, domainId);
// 3b. SYNC TAGS — diff against OBSERVED cloud tags (create-time tags
// only apply on first create; adoption may carry foreign tags).
yield* syncDataZoneTags(domainArn, toTagRecord(domain.tags), desiredTags);
yield* session.note(domainId);
return {
domainId,
domainArn,
name: domain.name ?? name,
status: domain.status,
portalUrl: domain.portalUrl,
rootDomainUnitId: domain.rootDomainUnitId,
domainExecutionRole: executionRoleArn,
roleName,
};
}),
delete: Effect.fn(function* ({ output }) {
yield* datazone
.deleteDomain({
identifier: output.domainId,
skipDeletionCheck: true,
})
.pipe(
Effect.catchTags({
ResourceNotFoundException: () => Effect.void,
// an already-deleted domain surfaces as AccessDenied ("User is
// not permitted to perform operation: DeleteDomain") — DataZone
// checks domain-scoped auth before existence.
AccessDeniedException: () => Effect.void,
// a concurrent DELETING domain rejects a second delete — the
// wait below observes it through to gone either way.
ConflictException: () => Effect.void,
}),
);
yield* waitForGone(output.domainId);
// Tear down the managed execution role (absent when an explicit
// domainExecutionRole was supplied). Every step tolerates a
// partially or fully removed role.
if (output.roleName !== undefined) {
const roleName = output.roleName;
yield* iam
.detachRolePolicy({
RoleName: roleName,
PolicyArn: DOMAIN_EXECUTION_MANAGED_POLICY,
})
.pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
yield* iam
.deleteRole({ RoleName: roleName })
.pipe(Effect.catchTag("NoSuchEntityException", () => Effect.void));
}
}),
});
}),
);