import * as schemaValidation from "@distilled.cloud/cloudflare/schema-validation";
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 * 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.SchemaValidation.Schema" as const;
type TypeId = typeof TypeId;
export interface SchemaProps {
/**
* Zone the schema is uploaded to.
*
* Immutable — moving a schema between zones triggers a replacement.
*/
zoneId: string;
/**
* Human-readable name for the schema. Cloudflare does not enforce
* uniqueness, but Alchemy uses the name as the cold-read identity, so it
* should be unique within the zone. 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}-${stage}-${id}
*/
name?: string;
/**
* The kind of the schema. Only OpenAPI v3 is supported.
*
* Immutable — changing the kind triggers a replacement.
* @default "openapi_v3"
*/
kind?: "openapi_v3";
/**
* The raw OpenAPI v3 schema, as a JSON or YAML string. Cloudflare
* validates the document on upload and rejects invalid specs.
*
* Immutable — the uploaded source cannot be modified, so changing it
* triggers a replacement (a new schema is uploaded, then the old one is
* deleted).
*/
source: string;
/**
* Whether the schema is enabled for validation.
*
* Enabling a disabled schema is an in-place update, but Cloudflare does
* not allow disabling an enabled schema ("delete schema instead"), so
* changing `true` → `false` triggers a replacement.
* @default true
*/
validationEnabled?: boolean;
}
export interface SchemaAttributes {
/** Cloudflare-assigned UUID of the schema. */
schemaId: string;
/** Zone the schema is uploaded to. */
zoneId: string;
/** Human-readable name of the schema. */
name: string;
/** The kind of the schema. */
kind: "openapi_v3" | (string & {});
/** The raw schema source as stored by Cloudflare. */
source: string;
/** Whether the schema is enabled for validation. */
validationEnabled: boolean;
/** When the schema was uploaded. */
createdAt: string;
}
export type SchemaValidationSchema = Resource<
TypeId,
SchemaProps,
SchemaAttributes,
never,
Providers
>;
/**
* An OpenAPI v3 schema uploaded to a zone for API Shield schema validation
* (`/zones/{zone_id}/schema_validation/schemas`).
*
* Uploading a schema registers the endpoints it describes as API Shield
* operations (a server-side side effect — deleting the schema does not
* delete those operations). The schema body is immutable: changing `source`
* uploads a new schema and deletes the old one (replacement). Only the
* `validationEnabled` flag is mutable in place.
* ### Uploading a Schema
* **Example:** Upload an OpenAPI v3 schema
* ```typescript
* const schema = yield* Cloudflare.SchemaValidation.SchemaValidationSchema("ApiSchema", {
* zoneId: zone.zoneId,
* source: JSON.stringify({
* openapi: "3.0.0",
* info: { title: "my-api", version: "1.0.0" },
* servers: [{ url: "https://api.example.com" }],
* paths: {
* "/users": {
* get: {
* operationId: "listUsers",
* responses: { "200": { description: "ok" } },
* },
* },
* },
* }),
* });
* ```
*
* **Example:** Upload a schema without enabling validation
* ```typescript
* const schema = yield* Cloudflare.SchemaValidation.SchemaValidationSchema("DraftSchema", {
* zoneId: zone.zoneId,
* source: openApiDocument,
* validationEnabled: false,
* });
* ```
*
* ### Toggling validation
* **Example:** Enable a previously-disabled schema in place
* ```typescript
* // Enabling (false → true) patches the schema in place. Disabling an
* // enabled schema is rejected by Cloudflare, so `true` → `false` (like a
* // `source` change) replaces the schema instead.
* yield* Cloudflare.SchemaValidation.SchemaValidationSchema("DraftSchema", {
* zoneId: zone.zoneId,
* source: openApiDocument,
* validationEnabled: true,
* });
* ```
*
* @see https://developers.cloudflare.com/api-shield/security/schema-validation/
*
* @resource
* @product Schema Validation
* @category Application Security
*/
export const SchemaValidationSchema = Resource<SchemaValidationSchema>(TypeId);
/**
* Returns true if the given value is a SchemaValidationSchema resource.
*/
export const isSchema = (value: unknown): value is SchemaValidationSchema =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const SchemaProvider = () =>
Provider.succeed(SchemaValidationSchema, {
stables: ["schemaId", "zoneId", "name", "kind", "source", "createdAt"],
diff: Effect.fn(function* ({ olds, news, output }) {
if (!isResolved(news)) return undefined;
// zoneId is a path param — moving zones is a replacement.
if (
output?.zoneId !== undefined &&
typeof news.zoneId === "string" &&
news.zoneId !== output.zoneId
) {
return { action: "replace" } as const;
}
// kind is immutable.
const oldKind = output?.kind ?? olds?.kind ?? "openapi_v3";
if ((news.kind ?? "openapi_v3") !== oldKind) {
return { action: "replace" } as const;
}
// There is no rename API. A generated name (news.name undefined) is
// deterministic and therefore never drifts.
const oldName = output?.name ?? olds?.name;
if (news.name !== undefined && oldName !== undefined && news.name !== oldName) {
return { action: "replace" } as const;
}
// The uploaded source is immutable. Prefer the previously-passed
// props as the baseline (what the user last declared) over the
// stored copy, in case Cloudflare ever normalizes the document.
const oldSource = olds?.source ?? output?.source;
if (oldSource !== undefined && news.source !== oldSource) {
return { action: "replace" } as const;
}
// Cloudflare rejects disabling an enabled schema in place
// ("Disabling a schema is not allowed, delete schema instead.") —
// converge by replacing: upload a new, disabled copy and delete the
// old one. Enabling (false → true) is a plain in-place update.
const oldEnabled = output?.validationEnabled ?? olds?.validationEnabled ?? true;
if (oldEnabled && news.validationEnabled === false) {
return { action: "replace" } as const;
}
return undefined;
}),
read: Effect.fn(function* ({ id, output, olds }) {
const zoneId = output?.zoneId ?? (typeof olds?.zoneId === "string" ? olds.zoneId : undefined);
if (zoneId === undefined) return undefined;
if (output?.schemaId) {
const observed = yield* getSchema(zoneId, output.schemaId);
return observed ? toAttributes(zoneId, observed) : undefined;
}
// Cold read — recover from lost state by matching the deterministic
// name. Names are not unique server-side and carry no ownership
// marker, so brand the match `Unowned` and let the engine gate
// takeover behind adoption.
const name = yield* createSchemaName(id, olds?.name);
const match = yield* findByName(zoneId, name);
if (match === undefined) return undefined;
const observed = yield* getSchema(zoneId, match.schemaId);
return observed ? Unowned(toAttributes(zoneId, observed)) : 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 = yield* createSchemaName(id, news.name);
const desiredEnabled = news.validationEnabled ?? true;
// 1. Observe — the cached schemaId is a hint, not a guarantee: a
// SchemaNotFound falls through to "missing" and we re-upload.
const observed = output?.schemaId ? yield* getSchema(zoneId, output.schemaId) : undefined;
// 2. Ensure — upload when missing. Names are not unique server-side,
// so there is no AlreadyExists race to tolerate.
if (observed === undefined) {
const created = yield* schemaValidation.createSchema({
zoneId,
kind: news.kind ?? "openapi_v3",
name,
source: news.source,
validationEnabled: desiredEnabled,
});
return toAttributes(zoneId, created);
}
// 3. Sync — `validationEnabled` is the only mutable aspect; the
// source/name/kind are immutable and disabling is rejected by the
// API, so diff replaces on those changes. Skip the API call
// entirely on a no-op.
if ((observed.validationEnabled ?? false) === desiredEnabled) {
return toAttributes(zoneId, observed);
}
const patched = yield* schemaValidation.patchSchema({
zoneId,
schemaId: observed.schemaId,
validationEnabled: desiredEnabled,
});
// The PATCH response omits the stored source (returns "") — keep the
// observed copy so the attributes stay faithful.
return toAttributes(zoneId, { ...patched, source: observed.source });
}),
delete: Effect.fn(function* ({ output }) {
// Idempotent — a schema already deleted out-of-band is success.
yield* schemaValidation
.deleteSchema({ zoneId: output.zoneId, schemaId: output.schemaId })
.pipe(Effect.catchTag("SchemaNotFound", () => Effect.void));
}),
// Zone-scoped collection: schemas live under `/zones/{zone_id}/...`, so
// enumerate every zone in the account and list its schemas, paginating
// each exhaustively. `omitSource: false` hydrates the full `read`
// Attributes shape. Zones whose route is invalid (deleted/partial) reject
// with the typed `InvalidRoute` — skip them rather than failing the whole
// enumeration.
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const zones = yield* listAllZones(accountId);
const rows = yield* Effect.forEach(
zones,
(zone) =>
schemaValidation.listSchemas.pages({ zoneId: zone.id, omitSource: false }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? []).map((schema) => toAttributes(zone.id, schema)),
),
),
// Skip zones schema-validation can't enumerate: `InvalidRoute`
// (feature not available on the zone), `ZonePurged` (the
// account-wide zone listing can momentarily include a zone that
// has since been purged), and `Forbidden` (the scoped token /
// zone plan doesn't grant schema-validation access).
Effect.catchTag(["InvalidRoute", "ZonePurged", "Forbidden"], () =>
Effect.succeed<SchemaAttributes[]>([]),
),
),
{ concurrency: 10 },
);
return rows.flat();
}),
});
/**
* Read a schema by id, mapping "gone" (`SchemaNotFound`, Cloudflare error
* code 19400) to `undefined`.
*/
const getSchema = (zoneId: string, schemaId: string) =>
schemaValidation
.getSchema({ zoneId, schemaId, omitSource: false })
.pipe(Effect.catchTag("SchemaNotFound", () => Effect.undefined));
/**
* Find a schema by exact name (meta-data only — sources omitted). If several
* schemas carry the same name, pick the oldest for determinism.
*/
const findByName = (zoneId: string, name: string) =>
schemaValidation.listSchemas.items({ zoneId, omitSource: true }).pipe(
Stream.filter((s) => s.name === name),
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk)
.sort((a, b) => a.createdAt.localeCompare(b.createdAt))
.at(0),
),
);
const createSchemaName = (id: string, name: string | undefined) =>
Effect.gen(function* () {
return name ?? (yield* createPhysicalName({ id, lowercase: true }));
});
const toAttributes = (
zoneId: string,
schema:
| schemaValidation.GetSchemaResponse
| schemaValidation.CreateSchemaResponse
| schemaValidation.PatchSchemaResponse
| schemaValidation.ListSchemasResponse["result"][number],
): SchemaAttributes => ({
schemaId: schema.schemaId,
zoneId,
name: schema.name,
kind: schema.kind,
source: schema.source,
validationEnabled: schema.validationEnabled ?? false,
createdAt: schema.createdAt,
});