import * as apiGateway from "@distilled.cloud/cloudflare/api-gateway";
import { Unowned } from "alchemy/AdoptPolicy";
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";
import { listAllZones } from "../Zone/lookup.ts";
const TypeId = "Cloudflare.ApiShield.UserSchema" as const;
type TypeId = typeof TypeId;
export interface UserSchemaProps {
/**
* Zone the schema is uploaded to.
*
* Immutable — moving a schema between zones triggers a replacement.
*/
zoneId: string;
/**
* Name of the schema. If omitted, a unique name is generated from the
* app, stage, and logical ID.
*
* Immutable — there is no rename API, so changing the name triggers a
* replacement.
* @default ${app}-${id}-${stage}-${suffix}
*/
name?: string;
/**
* The OpenAPI v3 schema source (JSON or YAML) to upload.
*
* Immutable — Cloudflare offers no API to update an uploaded schema's
* contents, so changing the source triggers a replacement.
*/
schema: string;
/**
* Whether the schema is enabled for (legacy "classic") schema
* validation. Enabling is an in-place update; Cloudflare forbids
* disabling an enabled schema (error 20400), so turning this back off
* triggers a replacement.
* @default false
*/
validationEnabled?: boolean;
}
export interface UserSchemaAttributes {
/** Cloudflare-assigned UUID of the schema. */
schemaId: string;
/** Zone the schema is uploaded to. */
zoneId: string;
/** Name of the schema. */
name: string;
/** Kind of schema. Always `openapi_v3`. */
kind: "openapi_v3" | (string & {});
/** The schema source as stored by Cloudflare. */
source: string;
/** Whether the schema is enabled for validation. */
validationEnabled: boolean;
/** ISO8601 creation timestamp. */
createdAt: string;
}
export type UserSchema = Resource<TypeId, UserSchemaProps, UserSchemaAttributes, never, Providers>;
/**
* A Cloudflare API Shield user schema — an OpenAPI v3 document uploaded to
* a zone for (legacy "classic") schema validation of API traffic.
*
* An uploaded schema's contents cannot be modified, so changing the
* `schema` source (or the `name`) triggers a replacement. The only in-place
* update is enabling validation; Cloudflare forbids disabling an enabled
* schema, so turning validation back off also triggers a replacement.
*
* For current zone-level schema validation (v2), prefer the
* `Cloudflare.SchemaValidation` resources.
* ### Uploading a Schema
* **Example:** Upload an OpenAPI v3 schema
* ```typescript
* const fs = yield* FileSystem.FileSystem;
* const source = yield* fs.readFileString("./openapi.json");
*
* const schema = yield* Cloudflare.ApiShield.UserSchema("PetstoreSchema", {
* zoneId: zone.zoneId,
* name: "petstore",
* schema: source,
* });
* // schema.schemaId is the Cloudflare-assigned UUID
* ```
*
* **Example:** Upload and enable validation
* ```typescript
* yield* Cloudflare.ApiShield.UserSchema("PetstoreSchema", {
* zoneId: zone.zoneId,
* schema: source,
* validationEnabled: true,
* });
* ```
*
* @see https://developers.cloudflare.com/api-shield/security/schema-validation/
*
* @resource
* @product API Shield
* @category Application Security
*/
export const UserSchema = Resource<UserSchema>(TypeId);
/**
* Returns true if the given value is an UserSchema resource.
*/
export const isUserSchema = (value: unknown): value is UserSchema =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const UserSchemaProvider = () =>
Provider.succeed(UserSchema, {
stables: ["zoneId", "name", "kind"],
diff: Effect.fn(function* ({ id, olds, news, output }) {
const o = olds as UserSchemaProps | undefined;
const n = news as UserSchemaProps;
if (o === undefined) return undefined;
// The name is part of the schema's identity — compare the resolved
// physical names (an omitted name resolves deterministically).
const oldName = output?.name ?? (yield* createSchemaName(id, o.name));
// Auto-generated names are engine-owned: the deployed name stays
// authoritative even if the generator would name this id differently
// today. Only an explicit user-provided name can force a replace.
const newName = n.name ?? oldName;
if (oldName !== newName) {
return { action: "replace" } as const;
}
// The uploaded source cannot be modified in place.
if (o.schema !== n.schema) {
return { action: "replace" } as const;
}
// Cloudflare forbids disabling validation on an enabled schema.
if ((o.validationEnabled ?? false) && !(n.validationEnabled ?? false)) {
return { action: "replace" } as const;
}
// zoneId is Input<string>; compare only once both are concrete.
if (typeof o.zoneId === "string" && typeof n.zoneId === "string" && o.zoneId !== n.zoneId) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ id, output, olds }) {
const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
if (zoneId === undefined) return undefined;
// Owned path: refresh by the persisted schema id.
if (output?.schemaId) {
const observed = yield* getSchema(zoneId, output.schemaId);
return observed ? toAttributes(observed, zoneId) : undefined;
}
// Cold path: recover from lost state via the deterministic name.
// Schemas carry no ownership markers, so an existing schema is
// reported as `Unowned` and adoption is gated by the adopt policy.
const name = yield* createSchemaName(id, olds?.name);
const observed = yield* findByName(zoneId, name);
return observed ? Unowned(toAttributes(observed, zoneId)) : undefined;
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
// Inputs have been resolved to concrete strings by Plan.
const zoneId = news.zoneId as string;
const name = output?.name ?? (yield* createSchemaName(id, news.name));
const desiredEnabled = news.validationEnabled ?? false;
// 1. Observe — the schema id cached on `output` is a hint, not a
// guarantee: a missing schema falls through to ensure.
let observed = output?.schemaId ? yield* getSchema(zoneId, output.schemaId) : undefined;
// An adopted (or drifted) schema whose stored source no longer
// matches the desired one cannot be updated in place — converge by
// recreating it.
if (observed && (observed.source ?? "") !== news.schema) {
yield* apiGateway
.deleteUserSchema({ zoneId, schemaId: observed.schemaId })
.pipe(Effect.catchTag("SchemaNotFound", () => Effect.void));
observed = undefined;
}
// 2. Ensure — upload when missing. Names are not unique, so there is
// no AlreadyExists race to tolerate.
if (!observed) {
const file = yield* Effect.sync(() => new File([news.schema], `${name}.json`));
const created = yield* apiGateway.createUserSchema({
zoneId,
file,
kind: "openapi_v3",
name,
validationEnabled: desiredEnabled,
});
observed = created.schema;
}
// 3. Sync — enabling validation is the only in-place update (the
// disable direction is a replacement, handled by diff). Skip the
// patch entirely on a no-op.
if (desiredEnabled && !(observed.validationEnabled ?? false)) {
const patched = yield* apiGateway.patchUserSchema({
zoneId,
schemaId: observed.schemaId,
validationEnabled: true,
});
// The patch response omits the source — keep the observed one.
observed = { ...patched, source: observed.source };
}
return toAttributes(observed, zoneId);
}),
delete: Effect.fn(function* ({ output }) {
yield* apiGateway
.deleteUserSchema({
zoneId: output.zoneId,
schemaId: output.schemaId,
})
.pipe(Effect.catchTag("SchemaNotFound", () => Effect.void));
}),
// Schemas live inside a zone; there is no account-wide list. Fan out
// over every zone in the account and exhaustively paginate each zone's
// schemas, hydrating into the same `Attributes` shape `read` produces.
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const zones = yield* listAllZones(accountId);
const rows = yield* Effect.forEach(
zones,
(zone) =>
apiGateway.listUserSchemas.pages({ zoneId: zone.id }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? []).map((schema) => toAttributes(schema, zone.id)),
),
),
// Zones without the API Shield entitlement reject the listing
// route; skip them rather than failing the whole enumeration.
Effect.catchTags({
Forbidden: () => Effect.succeed([] as UserSchemaAttributes[]),
// A zone purged (deleted) out-of-band mid-enumeration — it was in
// the zone list but no longer exists; drop it.
ZonePurged: () => Effect.succeed([] as UserSchemaAttributes[]),
}),
),
{ concurrency: 10 },
);
return rows.flat();
}),
});
type ObservedSchema = Pick<
apiGateway.GetUserSchemaResponse,
"schemaId" | "name" | "kind" | "source" | "validationEnabled" | "createdAt"
>;
/**
* Read a schema by id, mapping "gone" (`SchemaNotFound`, Cloudflare error
* code 19400) to `undefined`.
*/
const getSchema = (zoneId: string, schemaId: string) =>
apiGateway.getUserSchema({ zoneId, schemaId }).pipe(
Effect.map((schema): ObservedSchema | undefined => schema),
Effect.catchTag("SchemaNotFound", () => Effect.undefined),
);
/**
* Find a schema by name. Cloudflare does not enforce name uniqueness, so
* the first match wins — cold recovery only ever races with itself here
* because generated names are deterministic per logical ID.
*/
const findByName = (zoneId: string, name: string) =>
apiGateway.listUserSchemas.items({ zoneId }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).find(
(schema): schema is ObservedSchema & typeof schema => schema.name === name,
),
),
);
/**
* Resolve the schema's physical name: the explicit prop wins; otherwise a
* deterministic name is generated from the app, stage, and logical ID.
*/
const createSchemaName = (id: string, name: string | undefined) =>
Effect.gen(function* () {
return name ?? (yield* createPhysicalName({ id, lowercase: true }));
});
const toAttributes = (schema: ObservedSchema, zoneId: string): UserSchemaAttributes => ({
schemaId: schema.schemaId,
zoneId,
name: schema.name,
kind: schema.kind,
source: schema.source ?? "",
validationEnabled: schema.validationEnabled ?? false,
createdAt: schema.createdAt,
});