import * as iam from "@distilled.cloud/cloudflare/iam";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";
const TypeId = "Cloudflare.Iam.ResourceGroup" as const;
type TypeId = typeof TypeId;
/**
* The scope of a resource group — a scope key (e.g.
* `com.cloudflare.api.account.{accountId}`) plus the objects it contains
* (e.g. `com.cloudflare.api.account.zone.{zoneId}` or `*` for everything
* in the scope).
*/
export interface ResourceGroupScopeInput {
/**
* The scope key, e.g. `com.cloudflare.api.account.{accountId}`.
*/
key: string;
/**
* The objects within the scope this resource group spans, e.g.
* `com.cloudflare.api.account.zone.{zoneId}` or `*`.
*/
objects: { key: string }[];
}
/**
* A fully-resolved resource group scope as observed on Cloudflare.
*/
export interface ResourceGroupScope {
/** The scope key, e.g. `com.cloudflare.api.account.{accountId}`. */
key: string;
/** The objects within the scope this resource group spans. */
objects: { key: string }[];
}
export interface ResourceGroupProps {
/**
* Name of the resource group. If omitted, a unique name is generated
* from the app, stage, and logical ID.
* @default ${app}-${stage}-${id}
*/
name?: string;
/**
* The scope of the resource group: a scope key (typically
* `com.cloudflare.api.account.{accountId}`) and the objects it
* contains (zones, or `*` for the whole account). Mutable in place.
*/
scope: ResourceGroupScopeInput;
}
export interface ResourceGroupAttributes {
/** Cloudflare-assigned identifier of the resource group. */
resourceGroupId: string;
/** The Cloudflare account the resource group belongs to. */
accountId: string;
/** Name of the resource group. */
name: string;
/** The scope of the resource group as observed on Cloudflare. */
scope: ResourceGroupScope;
}
export type ResourceGroup = Resource<
TypeId,
ResourceGroupProps,
ResourceGroupAttributes,
never,
Providers
>;
/**
* A Cloudflare IAM resource group — a named set of account resources
* (zones, or the whole account) that fine-grained policies attach to.
*
* Resource groups pair with permission groups inside a user group policy:
* the permission group says *what* actions are allowed, the resource group
* says *which* resources they apply to. Both `name` and `scope` are mutable
* in place.
*
* Account-scoped IAM (resource groups, user groups) is an Enterprise
* feature.
* ### Creating a Resource Group
* **Example:** Scope a group to the whole account
* ```typescript
* const { accountId } = yield* yield* Cloudflare.CloudflareEnvironment;
* const group = yield* Cloudflare.Iam.ResourceGroup("AllResources", {
* scope: {
* key: `com.cloudflare.api.account.${accountId}`,
* objects: [{ key: "*" }],
* },
* });
* ```
*
* **Example:** Scope a group to a single zone
* ```typescript
* const group = yield* Cloudflare.Iam.ResourceGroup("ZoneOnly", {
* name: "my-zone-resources",
* scope: {
* key: `com.cloudflare.api.account.${accountId}`,
* objects: [
* { key: `com.cloudflare.api.account.zone.${zone.zoneId}` },
* ],
* },
* });
* ```
*
* ### Using with User Groups
* **Example:** Attach to a user group policy
* ```typescript
* yield* Cloudflare.Iam.UserGroup("Readers", {
* policies: [
* {
* access: "allow",
* permissionGroups: [readOnlyPermissionGroupId],
* resourceGroups: [group.resourceGroupId],
* },
* ],
* });
* ```
*
* @see https://developers.cloudflare.com/fundamentals/manage-members/scoped-roles/
*
* @resource
* @product IAM
* @category Account & Identity
*/
export const ResourceGroup = Resource<ResourceGroup>(TypeId);
/**
* Returns true if the given value is an ResourceGroup resource.
*/
export const isResourceGroup = (value: unknown): value is ResourceGroup =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const ResourceGroupProvider = () =>
Provider.succeed(ResourceGroup, {
stables: ["resourceGroupId", "accountId"],
read: Effect.fn(function* ({ id, output, olds }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const acct = output?.accountId ?? accountId;
if (output?.resourceGroupId) {
const observed = yield* getResourceGroup(acct, output.resourceGroupId);
if (observed) return toAttributes(observed, acct);
return undefined;
}
// Cold read — recover from lost state by matching the deterministic
// physical name. Names are not unique on Cloudflare's side; an exact
// match on our generated/explicit name is the best identity we have.
const name = yield* createGroupName(id, olds?.name);
const match = yield* findByName(acct, name);
return match ? toAttributes(match, acct) : undefined;
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const name = yield* createGroupName(id, news.name);
// Inputs have been resolved to concrete strings by Plan.
const desiredScope = resolveScope(news.scope);
// 1. Observe — the id cached on `output` is a hint, not a guarantee:
// a missing group falls through to the name scan and then create.
let observed = output?.resourceGroupId
? yield* getResourceGroup(accountId, output.resourceGroupId)
: undefined;
if (!observed) {
observed = yield* findByName(accountId, name);
}
// 2. Ensure — create when missing. Names are not unique on
// Cloudflare's side, so there is no AlreadyExists race to tolerate.
if (!observed) {
const created = yield* iam.createResourceGroup({
accountId,
name,
scope: desiredScope,
});
return toAttributes(created, accountId);
}
// 3. Sync — diff observed name/scope against desired; the update is
// a PUT, so send the full body, but skip the call on a no-op.
const observedScope = parseScope(observed.scope);
const dirty = (observed.name ?? "") !== name || !sameScope(observedScope, desiredScope);
if (!dirty) {
return toAttributes(observed, accountId);
}
const updated = yield* iam.updateResourceGroup({
accountId,
resourceGroupId: observed.id,
name,
scope: desiredScope,
});
return toAttributes(updated, accountId);
}),
delete: Effect.fn(function* ({ output }) {
yield* iam
.deleteResourceGroup({
accountId: output.accountId,
resourceGroupId: output.resourceGroupId,
})
.pipe(Effect.catchTag("ResourceGroupNotFound", () => Effect.void));
}),
// Account collection — the list op returns the full group record (id,
// name, scope) per page, so each item maps straight to the `read`
// Attributes shape without a per-item GET. Predefined/system resource
// groups are returned alongside ours, so a read-only list is often
// non-empty. Cloudflare paginates a single page set; exhaust it.
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
return yield* iam.listResourceGroups.pages({ accountId }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? [])
// Cloudflare seeds every account with predefined, non-editable
// system resource groups named `com.cloudflare.api.account.*`.
// They can't be deleted (`UnprocessableEntity: non-editable`),
// so exclude them from enumeration.
.filter((group) => !isSystemGroupName(group.name))
.map((group) => toAttributes(group, accountId)),
),
),
);
}),
});
type ObservedResourceGroup = {
id: string;
name?: string | null;
scope: iam.ResourceGroupsListResultItemScope;
};
/**
* Cloudflare's predefined, non-editable account resource groups use the
* reserved `com.cloudflare.api.account.*` name. They are seeded on every
* account and cannot be deleted, so they must be excluded from enumeration.
*/
const isSystemGroupName = (name: string | null | undefined): boolean =>
(name ?? "").startsWith("com.cloudflare.api.");
/**
* Read a resource group by id, mapping "gone" (`ResourceGroupNotFound`,
* HTTP 404 / Cloudflare error code 404) to `undefined`.
*/
const getResourceGroup = (accountId: string, resourceGroupId: string) =>
iam.getResourceGroup({ accountId, resourceGroupId }).pipe(
Effect.map((g): ObservedResourceGroup | undefined => g),
Effect.catchTag("ResourceGroupNotFound", () => Effect.undefined),
);
/**
* Find a resource group by exact name. Names are not unique on
* Cloudflare's side; pick the lexicographically-first id for determinism.
*/
const findByName = (accountId: string, name: string) =>
iam.listResourceGroups.items({ accountId, name }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk)
.filter((g): g is ObservedResourceGroup & { name: string } => g.name === name)
.sort((a, b) => a.id.localeCompare(b.id))
.at(0),
),
);
const createGroupName = (id: string, name: string | undefined) =>
Effect.gen(function* () {
return name ?? (yield* createPhysicalName({ id, lowercase: true }));
});
/** Resolve `Input<string>` scope fields to concrete strings (post-Plan). */
const resolveScope = (scope: ResourceGroupScopeInput): ResourceGroupScope => ({
key: scope.key as string,
objects: scope.objects.map((o) => ({ key: o.key as string })),
});
/**
* Decode the `unknown`-typed observed scope into our structured shape.
* Cloudflare always returns `{ key, objects: [{ key }] }` for a persisted
* resource group.
*/
const parseScope = (scope: unknown): ResourceGroupScope => {
const key = Predicate.hasProperty(scope, "key") && typeof scope.key === "string" ? scope.key : "";
const objects =
Predicate.hasProperty(scope, "objects") && Array.isArray(scope.objects)
? scope.objects.flatMap((o: unknown) =>
Predicate.hasProperty(o, "key") && typeof o.key === "string" ? [{ key: o.key }] : [],
)
: [];
return { key, objects };
};
const sameScope = (a: ResourceGroupScope, b: ResourceGroupScope) =>
a.key === b.key &&
a.objects.length === b.objects.length &&
a.objects
.map((o) => o.key)
.sort()
.join(",") ===
b.objects
.map((o) => o.key)
.sort()
.join(",");
const toAttributes = (
group: ObservedResourceGroup,
accountId: string,
): ResourceGroupAttributes => ({
resourceGroupId: group.id,
accountId,
name: group.name ?? "",
scope: parseScope(group.scope),
});