sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ ResourceSharing/ ShareResource.ts

import * as resourceSharing from "@distilled.cloud/cloudflare/resource-sharing";
import { isResolved } from "alchemy/Diff";
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";
import type { ShareableResourceType, ShareStatus } from "./Share.ts";

const TypeId = "Cloudflare.ResourceSharing.ShareResource" as const;
type TypeId = typeof TypeId;

export type ShareResourceProps = {
  /**
   * The share this resource belongs to. Changing the share triggers a
   * replacement.
   */
  shareId: string;
  /**
   * Type of the shared resource (e.g. `gateway-policy`). Changing the type
   * triggers a replacement.
   */
  resourceType: ShareableResourceType;
  /**
   * Identifier of the resource being shared (e.g. the gateway policy id).
   * Changing it triggers a replacement.
   */
  resourceId: string;
  /**
   * Account that owns the resource being shared. Changing it triggers a
   * replacement.
   * @default the current account
   */
  resourceAccountId?: string;
  /**
   * Resource metadata forwarded to the share API. The only mutable field.
   * @default {}
   */
  meta?: unknown;
};

export type ShareResourceAttributes = {
  /**
   * Server-assigned share-resource identifier — distinct from the shared
   * `resourceId`. Stable across updates.
   */
  shareResourceId: string;
  /**
   * The Cloudflare account that owns the share.
   */
  accountId: string;
  /**
   * The share this resource belongs to.
   */
  shareId: string;
  /**
   * Type of the shared resource.
   */
  resourceType: ShareableResourceType;
  /**
   * Identifier of the resource being shared.
   */
  resourceId: string;
  /**
   * Account that owns the resource being shared.
   */
  resourceAccountId: string;
  /**
   * Resource metadata.
   */
  meta: unknown;
  /**
   * Version of the shared resource.
   */
  resourceVersion: number;
  /**
   * Lifecycle status of the share resource.
   */
  status: ShareStatus;
  /**
   * When the share resource was created.
   */
  created: string;
  /**
   * When the share resource was last modified.
   */
  modified: string;
};

export type ShareResource = Resource<
  TypeId,
  ShareResourceProps,
  ShareResourceAttributes,
  never,
  Providers
>;

/**
 * A resource entry on an existing Cloudflare share — adds a shareable
 * resource (gateway policy, custom ruleset, …) to a `Share` incrementally.
 *
 * Only `meta` is mutable in place; changing the share, type, id, or owning
 * account triggers a replacement. A share must always retain at least one
 * resource — the last entry cannot be deleted (delete the `Share` instead).
 * Do not manage the same entry both inline on `Share.resources` and through
 * this resource.
 * ### Adding a Resource to a Share
 * **Example:** Share an additional gateway policy
 * ```typescript
 * const entry = yield* Cloudflare.ResourceSharing.ShareResource("ExtraPolicy", {
 *   shareId: share.shareId,
 *   resourceType: "gateway-policy",
 *   resourceId: policy.ruleId,
 * });
 * ```
 *
 * ### Updating Metadata
 * **Example:** Update `meta` in place
 * ```typescript
 * const entry = yield* Cloudflare.ResourceSharing.ShareResource("ExtraPolicy", {
 *   shareId: share.shareId,
 *   resourceType: "gateway-policy",
 *   resourceId: policy.ruleId,
 *   meta: { note: "rotated" },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/fundamentals/manage-account-resources/
 *
 * @resource
 * @product Resource Sharing
 * @category Account & Identity
 */
export const ShareResource = Resource<ShareResource>(TypeId);

/**
 * Returns true if the given value is a ShareResource resource.
 */
export const isShareResource = (value: unknown): value is ShareResource =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

export const ShareResourceProvider = () =>
  Provider.succeed(ShareResource, {
    stables: [
      "shareResourceId",
      "accountId",
      "shareId",
      "resourceType",
      "resourceId",
      "resourceAccountId",
      "created",
    ],
    diff: Effect.fn(function* ({ olds, news, output }) {
      if (!isResolved(news)) return undefined;
      const { accountId } = yield* yield* CloudflareEnvironment;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // The share is a path parameter — an entry cannot move between
      // shares in place. By diff time both sides are resolved strings.
      const oldShareId = output?.shareId ?? olds?.shareId;
      if (
        typeof oldShareId === "string" &&
        typeof news.shareId === "string" &&
        oldShareId !== news.shareId
      ) {
        return { action: "replace" } as const;
      }
      const oldType = output?.resourceType ?? olds?.resourceType;
      if (oldType !== undefined && oldType !== news.resourceType) {
        return { action: "replace" } as const;
      }
      const oldResourceId = output?.resourceId ?? olds?.resourceId;
      if (
        typeof oldResourceId === "string" &&
        typeof news.resourceId === "string" &&
        oldResourceId !== news.resourceId
      ) {
        return { action: "replace" } as const;
      }
      const oldOwner = output?.resourceAccountId ?? olds?.resourceAccountId;
      const newOwner = news.resourceAccountId ?? accountId;
      if (typeof oldOwner === "string" && typeof newOwner === "string" && oldOwner !== newOwner) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ olds, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const shareId = output?.shareId ?? (olds?.shareId as string | undefined);
      if (shareId === undefined) return undefined;

      if (output?.shareResourceId) {
        const observed = yield* getEntry(acct, shareId, output.shareResourceId);
        return observed ? toAttributes(observed, acct, shareId) : undefined;
      }
      // Cold read — recover from lost state by matching the natural key
      // (resourceType, resourceId) among the share's live entries.
      const resourceType = olds?.resourceType as ShareableResourceType | undefined;
      const resourceId = olds?.resourceId as string | undefined;
      if (resourceType === undefined || resourceId === undefined) {
        return undefined;
      }
      const match = yield* findEntry(acct, shareId, resourceType, resourceId);
      return match ? toAttributes(match, acct, shareId) : undefined;
    }),
    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      const shareId = news.shareId as string;
      const resourceId = news.resourceId as string;
      const desiredMeta = news.meta ?? {};

      // Observe — the id cached on `output` is a hint; fall through to a
      // natural-key lookup so an AlreadyExists race converges instead of
      // failing, then to create.
      const observed =
        (output?.shareResourceId
          ? yield* getEntry(acct, shareId, output.shareResourceId)
          : undefined) ?? (yield* findEntry(acct, shareId, news.resourceType, resourceId));

      if (!observed) {
        // Ensure — greenfield (or out-of-band delete).
        const created = yield* resourceSharing.createResource({
          accountId: acct,
          shareId,
          resourceType: news.resourceType,
          resourceId,
          resourceAccountId: (news.resourceAccountId as string) ?? acct,
          meta: desiredMeta,
        });
        return toAttributes(created, acct, shareId);
      }

      // Sync — `meta` is the only mutable field; skip the PUT on a no-op.
      if (JSON.stringify(observed.meta ?? {}) !== JSON.stringify(desiredMeta)) {
        const updated = yield* resourceSharing.updateResource({
          accountId: acct,
          shareId,
          shareResourceId: observed.id,
          meta: desiredMeta,
        });
        return toAttributes(updated, acct, shareId);
      }
      return toAttributes(observed, acct, shareId);
    }),
    delete: Effect.fn(function* ({ output }) {
      // Deletion is asynchronous (`status: deleting`); the DELETE call is
      // idempotent against a missing entry. Deleting the last resource of
      // a share is a genuine dependency violation and propagates.
      yield* resourceSharing
        .deleteResource({
          accountId: output.accountId,
          shareId: output.shareId,
          shareResourceId: output.shareResourceId,
        })
        .pipe(Effect.catchTag("ShareResourceNotFound", () => Effect.void));
    }),
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Parent fan-out: a ShareResource is a sub-resource of a Share with
      // no account-wide enumeration of its own. Enumerate every share we
      // send (account-scoped), then list each share's resource entries
      // with bounded concurrency, paginating both levels exhaustively.
      const shares = yield* resourceSharing.listResourceSharings
        .pages({ accountId, kind: "sent" })
        .pipe(
          Stream.runCollect,
          Effect.map((chunk) =>
            Array.from(chunk).flatMap((page) =>
              (page.result ?? []).filter((s) => s.status !== "deleted"),
            ),
          ),
        );
      const rows = yield* Effect.forEach(
        shares,
        (share) =>
          resourceSharing.listResources.pages({ accountId, shareId: share.id }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.from(chunk).flatMap((page) =>
                (page.result ?? [])
                  .filter((r) => r.status !== "deleted" && r.status !== "deleting")
                  .map((entry) => toAttributes(entry, accountId, share.id)),
              ),
            ),
            // A share removed out-of-band between enumeration and the
            // per-share list surfaces as ShareNotFound — skip it.
            Effect.catchTag("ShareNotFound", () => Effect.succeed([] as ShareResourceAttributes[])),
          ),
        { concurrency: 10 },
      );
      return rows.flat();
    }),
  });

type ObservedEntry = resourceSharing.GetResourceResponse;

/**
 * Read a share-resource entry by id, mapping "gone"
 * (`ShareResourceNotFound`, HTTP 404) and the terminal `deleted` status to
 * `undefined`.
 */
const getEntry = (accountId: string, shareId: string, shareResourceId: string) =>
  resourceSharing.getResource({ accountId, shareId, shareResourceId }).pipe(
    Effect.map((entry): ObservedEntry | undefined =>
      entry.status === "deleted" ? undefined : entry,
    ),
    Effect.catchTag("ShareResourceNotFound", () => Effect.undefined),
  );

/**
 * Find a live entry by its natural key (resourceType, resourceId). A missing
 * share surfaces as `ShareNotFound` — treat it as "no entry".
 */
const findEntry = (
  accountId: string,
  shareId: string,
  resourceType: ShareableResourceType,
  resourceId: string,
) =>
  resourceSharing.listResources({ accountId, shareId, resourceType, perPage: 50 }).pipe(
    Effect.map((list) =>
      list.result.find(
        (r) => r.resourceId === resourceId && r.status !== "deleted" && r.status !== "deleting",
      ),
    ),
    Effect.catchTag("ShareNotFound", () => Effect.undefined),
  );

const toAttributes = (
  entry:
    | ObservedEntry
    | resourceSharing.CreateResourceResponse
    | resourceSharing.UpdateResourceResponse
    | resourceSharing.ListResourcesResponse["result"][number],
  accountId: string,
  shareId: string,
): ShareResourceAttributes => ({
  shareResourceId: entry.id,
  accountId,
  shareId,
  // Distilled widens generated string enums to open unions (`string & {}`).
  resourceType: entry.resourceType as ShareableResourceType,
  resourceId: entry.resourceId,
  resourceAccountId: entry.resourceAccountId,
  meta: entry.meta,
  resourceVersion: entry.resourceVersion,
  status: entry.status as ShareStatus,
  created: entry.created,
  modified: entry.modified,
});