import * as queues from "@distilled.cloud/cloudflare/queues";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import type { PropsInput } from "alchemy/Input";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { isResourceOfType, Resource, type ResourceClass } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Effectable from "effect/Effectable";
import * as Option from "effect/Option";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import type { Model } from "../AI/Model.ts";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Variant } from "../Images/Variant.ts";
import type { Namespace } from "../KV/Namespace.ts";
import type { Providers } from "../Providers.ts";
import type { Bucket } from "../R2/Bucket.ts";
import type { SuperSlurperJob } from "../R2/SuperSlurperJob.ts";
import type { Index } from "../Vectorize/VectorizeIndex.ts";
import type { Worker } from "../Workers/Worker.ts";
import type { WorkflowBinding, WorkflowResource } from "../Workflows/Workflow.ts";
const TypeId = "Cloudflare.Queues.Subscription" as const;
type TypeId = typeof TypeId;
/**
* The Cloudflare product whose events the subscription delivers into the
* Queue. Cloudflare allows a single subscription per source per account,
* and the source is fixed at creation — changing it triggers a
* replacement.
*/
export type SubscriptionSource =
| {
/** Cloudflare Images events. */
type: "images";
}
| {
/** Workers KV namespace events. */
type: "kv";
}
| {
/** R2 bucket events. */
type: "r2";
}
| {
/** Super Slurper migration events. */
type: "superSlurper";
}
| {
/** Vectorize index events. */
type: "vectorize";
}
| {
/** Workers AI model events for a specific model. */
type: "workersAi.model";
/** Name of the Workers AI model to subscribe to. */
modelName: string;
}
| {
/** Workers Builds events for a specific Worker. */
type: "workersBuilds.worker";
/** Name of the Worker whose build events to subscribe to. */
workerName: string;
}
| {
/** Workflows events for a specific workflow. */
type: "workflows.workflow";
/** Name of the workflow to subscribe to. */
workflowName: string;
}
| {
/** Email Sending lifecycle events for one sending domain. */
type: "email.sending";
/** Zone the sending domain belongs to. */
zoneId: string;
/** The zone apex or a verified sending subdomain, e.g. `mail.example.com`. */
domain: string;
};
export type SubscriptionProps = {
/**
* Human readable name of the subscription. If omitted, a unique name is
* generated from the app, stage, and logical ID.
* @default ${app}-${stage}-${id}
*/
name?: string;
/**
* The event source to subscribe to (e.g. `{ type: "r2" }` for R2 bucket
* events). The constructor also accepts Workflow bindings and supported
* Cloudflare resources or yielded `.ref(...)` references. Images variants,
* KV namespaces, R2 buckets, Super Slurper jobs, and Vectorize indexes select
* all events of that product in the account, not just the supplied resource.
* Models, Workers, and Workflows select their deferred physical names.
* References read persisted state without owning their sources.
* Fixed at creation — changing it triggers a replacement. Cloudflare
* allows at most one subscription per source per account.
*/
source: SubscriptionSource;
/**
* Account of a resource source, captured by the constructor. Resource sources
* must belong to the subscription's ambient Cloudflare account.
*/
sourceAccountId?: string;
/**
* Event types to deliver, scoped to the source (e.g. `bucket.created`
* and `bucket.deleted` for the `r2` source, `namespace.created` for
* `kv`). Must contain at least one event type valid for the source.
*/
events: string[];
/**
* The ID of the Queue that receives the events
* (the destination, e.g. `queue.queueId`).
*/
queueId: string;
/**
* Whether the subscription is active.
* @default true
*/
enabled?: boolean;
};
export type SubscriptionAttributes = {
/**
* Unique identifier for the subscription.
*/
subscriptionId: string;
/**
* The Cloudflare account the subscription belongs to.
*/
accountId: string;
/**
* Human readable name of the subscription.
*/
name: string;
/**
* The event source the subscription listens to.
*/
source: SubscriptionSource;
/**
* Event types delivered by this subscription.
*/
events: string[];
/**
* The ID of the destination Queue.
*/
queueId: string;
/**
* Whether the subscription is active.
*/
enabled: boolean;
/**
* When the subscription was created.
*/
createdAt: string;
/**
* When the subscription was last modified.
*/
modifiedAt: string;
};
export type Subscription = Resource<
TypeId,
SubscriptionProps,
SubscriptionAttributes,
never,
Providers
>;
/** Resources whose product events can be delivered to a Queue. */
export type SubscriptionResourceSource =
| WorkflowResource
| Variant
| Namespace
| Bucket
| SuperSlurperJob
| Index
| Model
| Worker;
/** Constructor inputs; resource sources are normalized before registration. */
export type SubscriptionInput = Omit<
PropsInput<SubscriptionProps>,
"source" | "sourceAccountId"
> & {
/** An explicit source, Workflow binding, resource, or yielded resource reference. */
source: PropsInput<SubscriptionProps>["source"] | WorkflowBinding | SubscriptionResourceSource;
};
type SubscriptionConstructor<Req = never> = {
Type: TypeId;
Props: SubscriptionProps;
<const Methods extends Record<string, any>>(methods: Methods): SubscriptionClass & Methods;
(id: string, props: SubscriptionInput): Effect.Effect<Subscription, never, Req>;
<PropsReq = never>(
id: string,
props: Effect.Effect<SubscriptionInput, never, PropsReq>,
): Effect.Effect<Subscription, never, PropsReq | Req>;
};
type SubscriptionClass = SubscriptionConstructor<Providers> &
Effect.Effect<SubscriptionConstructor> &
Pick<ResourceClass<Subscription>, "Self" | "Provider" | "Aliases" | "ref">;
const SubscriptionResource = Resource<Subscription>(TypeId, {
aliases: ["Cloudflare.Queue.Subscription"],
});
const isSourceResource = <Type extends SubscriptionResourceSource["Type"]>(
source: SubscriptionInput["source"],
type: Type,
): source is Extract<SubscriptionResourceSource, { Type: Type }> => isResourceOfType(source, type);
const isWorkflowBinding = (source: SubscriptionInput["source"]): source is WorkflowBinding =>
typeof source === "object" &&
source !== null &&
(source as WorkflowBinding).kind === "Cloudflare.Workflow";
const normalizeSubscriptionProps = (props: SubscriptionInput): PropsInput<SubscriptionProps> => {
const source = props.source;
// Resource references are Output proxies; inspect their type before binding fields.
if (isSourceResource(source, "Cloudflare.Workflow")) {
return {
...props,
sourceAccountId: source.accountId,
source: { type: "workflows.workflow", workflowName: source.workflowName },
};
}
if (isSourceResource(source, "Cloudflare.Worker")) {
return {
...props,
sourceAccountId: source.accountId,
source: { type: "workersBuilds.worker", workerName: source.workerName },
};
}
if (isSourceResource(source, "Cloudflare.AI.Model")) {
return {
...props,
sourceAccountId: source.accountId,
source: { type: "workersAi.model", modelName: source.modelName },
};
}
if (isSourceResource(source, "Cloudflare.Images.Variant")) {
return {
...props,
sourceAccountId: source.accountId,
source: { type: "images" },
};
}
if (isSourceResource(source, "Cloudflare.KV.Namespace")) {
return {
...props,
sourceAccountId: source.accountId,
source: { type: "kv" },
};
}
if (isSourceResource(source, "Cloudflare.R2.Bucket")) {
return {
...props,
sourceAccountId: source.accountId,
source: { type: "r2" },
};
}
if (isSourceResource(source, "Cloudflare.R2.SuperSlurperJob")) {
return {
...props,
sourceAccountId: source.accountId,
source: { type: "superSlurper" },
};
}
if (isSourceResource(source, "Cloudflare.VectorizeIndex")) {
return {
...props,
sourceAccountId: source.accountId,
source: { type: "vectorize" },
};
}
if (isWorkflowBinding(source)) {
return {
...props,
source: { type: "workflows.workflow", workflowName: source.workflowName },
};
}
return { ...props, source };
};
/** A resource source cannot select events in a different Cloudflare account. */
export class SubscriptionSourceAccountMismatch extends Data.TaggedError(
"SubscriptionSourceAccountMismatch",
)<{ readonly accountId: string; readonly sourceAccountId: string }> {}
const validateSourceAccount = (accountId: string, sourceAccountId?: string) =>
sourceAccountId !== undefined && sourceAccountId !== accountId
? Effect.fail(new SubscriptionSourceAccountMismatch({ accountId, sourceAccountId }))
: Effect.void;
/**
* A Cloudflare Queues event subscription — delivers platform events
* (R2 bucket events, KV namespace events, Workers Builds, Workflows,
* etc.) into a Queue as messages.
*
* The `source` selects which product emits the events and is fixed at
* creation (changing it replaces the subscription). `name`, `events`,
* `enabled`, and the destination `queueId` are all mutable in place.
* Cloudflare allows at most one subscription per source per account.
* ### Creating a Subscription
* **Example:** R2 bucket events into a Queue
* ```typescript
* const queue = yield* Cloudflare.Queues.Queue("EventsQueue");
*
* const subscription = yield* Cloudflare.Queues.Subscription("R2Events", {
* source: { type: "r2" },
* events: ["bucket.created", "bucket.deleted"],
* queueId: queue.queueId,
* });
* ```
*
* **Example:** KV namespace events with an explicit name
* ```typescript
* const subscription = yield* Cloudflare.Queues.Subscription("KvEvents", {
* name: "kv-events",
* source: { type: "kv" },
* events: ["namespace.created"],
* queueId: queue.queueId,
* });
* ```
*
* **Example:** Workers Builds events for one Worker
* ```typescript
* const subscription = yield* Cloudflare.Queues.Subscription("BuildEvents", {
* source: { type: "workersBuilds.worker", workerName: "my-worker" },
* events: ["build.started", "build.succeeded"],
* queueId: queue.queueId,
* });
* ```
*
* **Example:** Workflow lifecycle events, from a Workflow bound in this stack
* Pass the Workflow binding from the host Worker's `env` directly. Its
* physical name remains an `Output`, so the subscription works on the
* Workflow's first deployment and follows later renames. Only the source
* type and physical workflow name are persisted, not the binding metadata.
* ```typescript
* const worker = yield* Cloudflare.Worker("Worker", {
* main: "./src/worker.ts",
* env: { INGESTION: Cloudflare.Workflow("Ingestion", { className: "IngestionWorkflow" }) },
* });
*
* const subscription = yield* Cloudflare.Queues.Subscription("WorkflowEvents", {
* source: worker.env.INGESTION,
* events: ["instance.completed", "instance.errored"],
* queueId: queue.queueId,
* });
* ```
*
* **Example:** Workflow lifecycle events from a persisted resource reference
* Use the logical resource ID, including any namespace. References read
* persisted state, so deploy the host first. Omitting the options uses the
* current stack and stage; the reference does not take ownership of the host.
* ```typescript
* const subscription = yield* Cloudflare.Queues.Subscription("WorkflowEvents", {
* source: yield* Cloudflare.Workflow.ref("Ingestion", {
* stack: "workflow-host",
* stage: "production",
* }),
* events: ["instance.completed", "instance.errored"],
* queueId: queue.queueId,
* });
* ```
*
* **Example:** Workflow lifecycle events by an existing physical name
* ```typescript
* const subscription = yield* Cloudflare.Queues.Subscription("WorkflowEvents", {
* source: { type: "workflows.workflow", workflowName: "existing-ingestion" },
* events: ["instance.completed", "instance.errored"],
* queueId: queue.queueId,
* });
* ```
*
* **Example:** Bounces and complaints from an Email Sending domain
* ```typescript
* const subscription = yield* Cloudflare.Queues.Subscription("MailEvents", {
* source: { type: "email.sending", zoneId: zone.zoneId, domain: "mail.example.com" },
* events: ["message.bounced", "message.complained"],
* queueId: queue.queueId,
* });
* ```
*
* ### Resource and Reference Sources
* **Example:** Account-wide KV events from a namespace
* ```typescript
* const namespace = yield* Cloudflare.KV.Namespace("Cache");
* yield* Cloudflare.Queues.Subscription("NamespaceEvents", {
* source: namespace,
* events: ["namespace.created", "namespace.deleted"],
* queueId: queue.queueId,
* });
* ```
* KV, R2, Images, Vectorize, and Super Slurper sources are account-wide.
* Passing a resource retains its account and deployment dependency, but does
* not filter events to that resource. The subscription can miss the source's
* initial creation or final deletion because it depends on that source.
* Use an explicit product descriptor when the subscription must exist first.
*
* **Example:** R2 bucket reference from another stack
* ```typescript
* yield* Cloudflare.Queues.Subscription("BucketEvents", {
* source: yield* Cloudflare.R2.Bucket.ref("Uploads", {
* stack: "storage",
* stage: "production",
* }),
* events: ["bucket.created", "bucket.deleted"],
* queueId: queue.queueId,
* });
* ```
* All resource forms accept yielded `.ref` references with optional stack
* and stage selectors. The referenced resource must already be deployed in
* the same Cloudflare account. Removing a subscription does not remove its
* referenced resource.
*
* **Example:** Images upload events from a variant reference
* ```typescript
* yield* Cloudflare.Queues.Subscription("ImageEvents", {
* source: yield* Cloudflare.Images.Variant.ref("Thumbnail"),
* events: ["image.uploaded"],
* queueId: queue.queueId,
* });
* ```
* The variant selects its Images account; uploads are not filtered by variant.
*
* **Example:** Vectorize index events
* ```typescript
* yield* Cloudflare.Queues.Subscription("IndexEvents", {
* source: yield* Cloudflare.Vectorize.Index.ref("Search"),
* events: ["index.created", "index.deleted"],
* queueId: queue.queueId,
* });
* ```
*
* **Example:** Super Slurper migration events
* ```typescript
* yield* Cloudflare.Queues.Subscription("MigrationEvents", {
* source: yield* Cloudflare.R2.SuperSlurperJob.ref("Migration"),
* events: ["job.completed", "job.aborted"],
* queueId: queue.queueId,
* });
* ```
* This selects all migration jobs in the account, not one job's objects.
*
* **Example:** Workers AI batch events
* ```typescript
* const model = yield* Cloudflare.AI.Model("Embeddings", {
* modelName: "@cf/baai/bge-m3",
* });
* yield* Cloudflare.Queues.Subscription("BatchEvents", {
* source: model,
* events: ["batch.queued", "batch.succeeded", "batch.failed"],
* queueId: queue.queueId,
* });
* ```
* The model is a non-owning catalog handle. These events require asynchronous
* batch inference; ordinary synchronous inference does not emit them.
*
* **Example:** Workers Builds events from a Worker reference
* ```typescript
* yield* Cloudflare.Queues.Subscription("BuildEvents", {
* source: yield* Cloudflare.Worker.ref("Website"),
* events: ["build.started", "build.succeeded", "build.failed"],
* queueId: queue.queueId,
* });
* ```
* The Worker must have a Workers Builds integration to emit build events.
* An ordinary Alchemy Worker upload is not a Workers Builds run.
*
* Event delivery can lag subscription creation or replacement even after the
* destination Queue accepts messages. Deployment confirms configuration, not
* delivery readiness; verify delivery before emitting events that must be observed.
* During Vectorize subscription replacement or a destination Queue update,
* Cloudflare can still route new events to the previous Queue. Replacement events
* can carry the deleted subscription's ID; updates retain the same subscription ID.
* A single early event does not prove that routing has fully propagated. Keep the
* previous destination available during the transition and verify the receiving
* Queue, `metadata.eventSubscriptionId`, and the event's resource identity.
*
* ### Pausing delivery
* **Example:** Disable a subscription without deleting it
* ```typescript
* const subscription = yield* Cloudflare.Queues.Subscription("R2Events", {
* source: { type: "r2" },
* events: ["bucket.created"],
* queueId: queue.queueId,
* enabled: false,
* });
* ```
*
* @see https://developers.cloudflare.com/queues/event-subscriptions/
*
* @resource
* @product Queues
* @category Storage & Databases
*/
export const Subscription: SubscriptionClass = Object.assign(
(
...args:
| [id: string, props: SubscriptionInput | Effect.Effect<SubscriptionInput, never, any>]
| [methods: Record<string, any>]
) => {
if (typeof args[0] === "object") {
return Object.assign(Subscription, args[0]);
}
const [id, props] = args as [
string,
SubscriptionInput | Effect.Effect<SubscriptionInput, never, any>,
];
// Resource supplies Self while evaluating Effect-valued props.
return Effect.isEffect(props)
? SubscriptionResource(id, Effect.map(props, normalizeSubscriptionProps))
: SubscriptionResource(id, normalizeSubscriptionProps(props));
},
SubscriptionResource,
Effectable.Prototype({
label: `Resource<${TypeId}>`,
evaluate: (): Effect.Effect<SubscriptionConstructor> => Effect.succeed(Subscription),
}),
) as SubscriptionClass;
/**
* Returns true if the given value is a Subscription resource.
*/
export const isSubscription = (value: unknown): value is Subscription =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const SubscriptionProvider = () =>
Provider.succeed(SubscriptionResource, {
stables: ["subscriptionId", "accountId", "source", "createdAt"],
diff: Effect.fn(function* ({ olds, news, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
if (isResolved(news)) {
yield* validateSourceAccount(accountId, news.sourceAccountId);
}
if ((output?.accountId ?? accountId) !== accountId) {
return { action: "replace" } as const;
}
// An unresolved immutable source may change with its upstream resource.
// Delete first in case it resolves to the same account-unique source.
if (!("source" in news) || !isResolved(news.source)) {
return { action: "replace", deleteFirst: true } as const;
}
// The source is fixed at creation.
const oldSource = output?.source ?? olds?.source;
if (oldSource && !sameSource(oldSource, news.source)) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ id, output, olds, previous }) {
const { accountId } = yield* yield* CloudflareEnvironment;
if (!output) {
yield* validateSourceAccount(accountId, olds?.sourceAccountId);
}
const acct = output?.accountId ?? accountId;
if (output?.subscriptionId) {
const observed = yield* getSubscriptionOrUndefined(acct, output.subscriptionId);
return observed ? toAttributes(observed, acct) : undefined;
}
// Cold read — recover from lost state by matching the deterministic
// physical name. Names are not enforced unique server-side; an exact
// match on our generated/explicit name is the best identity we have.
const name = yield* createSubscriptionName(id, olds?.name);
const match = yield* findByName(acct, name);
if (!match) return undefined;
const attributes = toAttributes(match, acct);
// The generation a replacement is replacing is ours.
return olds?.name !== undefined && attributes.subscriptionId !== previous?.subscriptionId
? Unowned(attributes)
: attributes;
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
yield* validateSourceAccount(accountId, news.sourceAccountId);
const acct = output?.accountId ?? accountId;
const name = yield* createSubscriptionName(id, news.name);
// Observe — the subscriptionId cached on `output` is a hint, not a
// guarantee: a missing subscription falls through to create.
let observed = output?.subscriptionId
? yield* getSubscriptionOrUndefined(acct, output.subscriptionId)
: undefined;
// A source collision does not establish ownership of the existing subscription.
if (!observed) {
observed = yield* queues.createSubscription({
accountId: acct,
name,
enabled: news.enabled ?? true,
events: news.events,
source: news.source,
destination: { type: "queues.queue", queueId: news.queueId },
});
}
// Sync — diff observed cloud state against desired and patch only
// the delta; skip the API call entirely on a no-op.
const desired = {
name,
enabled: news.enabled ?? true,
events: news.events,
queueId: news.queueId,
};
const dirty =
observed.name !== desired.name ||
observed.enabled !== desired.enabled ||
observed.destination.queueId !== desired.queueId ||
!sameEvents(observed.events, desired.events);
const final = dirty
? yield* queues.patchSubscription({
accountId: acct,
subscriptionId: observed.id,
name: desired.name,
enabled: desired.enabled,
events: desired.events,
destination: { type: "queues.queue", queueId: desired.queueId },
})
: observed;
return toAttributes(final, acct);
}),
delete: Effect.fn(function* ({ output }) {
yield* queues
.deleteSubscription({
accountId: output.accountId,
subscriptionId: output.subscriptionId,
})
.pipe(Effect.catchTag("SubscriptionNotFound", () => Effect.void));
}),
// Account collection — subscriptions are account-scoped. Exhaustively
// paginate `listSubscriptions` (response array is `result`) and hydrate
// each row into the same Attributes shape `read` returns.
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
return yield* queues.listSubscriptions.pages({ accountId }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? []).map((sub) => toAttributes(sub, accountId)),
),
),
);
}),
});
type ObservedSubscription =
| queues.GetSubscriptionResponse
| queues.CreateSubscriptionResponse
| queues.PatchSubscriptionResponse;
/**
* Read a subscription by ID, mapping "gone" (`SubscriptionNotFound`,
* HTTP 404 "No subscription with this ID") to `undefined`.
*/
const getSubscriptionOrUndefined = (accountId: string, subscriptionId: string) =>
queues
.getSubscription({ accountId, subscriptionId })
.pipe(Effect.catchTag("SubscriptionNotFound", () => Effect.undefined));
/**
* Find a subscription by exact name. Cloudflare's list endpoint has no
* name filter, so scan the paginated stream.
*/
const findByName = (accountId: string, name: string) =>
queues.listSubscriptions.items({ accountId }).pipe(
Stream.filter((s) => s.name === name),
Stream.runHead,
Effect.map(Option.getOrUndefined),
);
const createSubscriptionName = (id: string, name: string | undefined) =>
Effect.gen(function* () {
return name ?? (yield* createPhysicalName({ id, lowercase: true }));
});
/**
* The wire shape of a subscription source — a flattened view of the
* response union (only the member matching `type` carries its name field).
*/
type WireSource = {
type?: string | null;
modelName?: string | null;
workerName?: string | null;
workflowName?: string | null;
zoneId?: string | null;
domain?: string | null;
};
const toSource = (wire: unknown): SubscriptionSource => {
const source = wire as WireSource;
switch (source.type) {
case "workersAi.model":
return { type: "workersAi.model", modelName: source.modelName ?? "" };
case "workersBuilds.worker":
return {
type: "workersBuilds.worker",
workerName: source.workerName ?? "",
};
case "workflows.workflow":
return {
type: "workflows.workflow",
workflowName: source.workflowName ?? "",
};
case "email.sending":
return {
type: "email.sending",
zoneId: source.zoneId ?? "",
domain: source.domain ?? "",
};
case "images":
case "kv":
case "r2":
case "superSlurper":
case "vectorize":
return { type: source.type };
default:
// Unknown/new source types added server-side: surface the raw type
// so diff treats it as a foreign source rather than crashing.
return { type: source.type as never };
}
};
const sameSource = (a: SubscriptionSource, b: SubscriptionSource): boolean => {
if (a.type !== b.type) return false;
switch (a.type) {
case "workersAi.model":
return a.modelName === (b as { modelName?: string }).modelName;
case "workersBuilds.worker":
return a.workerName === (b as { workerName?: string }).workerName;
case "workflows.workflow":
return a.workflowName === (b as { workflowName?: string }).workflowName;
case "email.sending": {
const other = b as { zoneId?: string; domain?: string };
return a.zoneId === other.zoneId && a.domain === other.domain;
}
default:
return true;
}
};
const sameEvents = (observed: readonly string[], desired: readonly string[]) =>
observed.length === desired.length &&
[...observed].sort().join(",") === [...desired].sort().join(",");
const toAttributes = (
subscription: ObservedSubscription,
accountId: string,
): SubscriptionAttributes => ({
subscriptionId: subscription.id,
accountId,
name: subscription.name,
source: toSource(subscription.source),
events: [...subscription.events],
queueId: subscription.destination.queueId,
enabled: subscription.enabled,
createdAt: subscription.createdAt,
modifiedAt: subscription.modifiedAt,
});