import * as mcn from "@distilled.cloud/cloudflare/magic-cloud-networking";
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";
const TypeId = "Cloudflare.MagicCloudNetworking.OnRamp" as const;
type TypeId = typeof TypeId;
/**
* The cloud provider an on-ramp connects to Magic WAN.
*/
export type OnRampCloudType = "AWS" | "AZURE" | "GOOGLE";
/**
* Topology of an on-ramp: a single VPC/VNet, or a hub (e.g. AWS Transit
* Gateway) with attached VPCs.
*/
export type OnRampType = "OnrampTypeSingle" | "OnrampTypeHub";
export interface OnRampProps {
/**
* The cloud provider this on-ramp connects to.
*
* Immutable — changing the cloud type triggers a replacement.
*/
cloudType: OnRampCloudType;
/**
* Topology of the on-ramp: `OnrampTypeSingle` connects one VPC/VNet,
* `OnrampTypeHub` provisions a hub (e.g. AWS Transit Gateway) that VPCs
* attach to.
*
* Immutable — changing the topology triggers a replacement.
*/
type: OnRampType;
/**
* Enables BGP routing. When enabled, set both `installRoutesInCloud` and
* `installRoutesInMagicWan` to `false`.
*
* Immutable — the API offers no way to change it, so a change triggers a
* replacement.
*/
dynamicRouting: boolean;
/**
* Whether Cloudflare installs Magic WAN routes into the cloud route
* tables. Mutable.
*/
installRoutesInCloud: boolean;
/**
* Whether routes to the cloud networks are installed in Magic WAN.
* Mutable.
*/
installRoutesInMagicWan: boolean;
/**
* Human readable name. Used as the on-ramp's identity for cold-state
* recovery, so it should be unique within the account. If omitted, a
* unique name is generated from the app, stage, and logical ID.
* @default ${app}-${stage}-${id}
*/
name?: string;
/**
* Cloud region the on-ramp is provisioned in (e.g. `us-east-1`).
*
* Immutable — changing the region triggers a replacement.
*/
region?: string;
/**
* The discovered VPC/VNet resource id to connect
* (`type: "OnrampTypeSingle"`). Mutable.
*/
vpc?: string;
/**
* Cloud-side ASN for BGP. If unset or zero, the cloud's default ASN
* takes effect.
*
* Immutable — the API offers no way to change it, so a change triggers a
* replacement.
*/
cloudAsn?: number;
/**
* Free-form description of the on-ramp. Mutable.
*/
description?: string;
/**
* Adopt an existing hub (e.g. an existing Transit Gateway) instead of
* provisioning one (`type: "OnrampTypeHub"`).
*
* Immutable — hub identity cannot change, so a change triggers a
* replacement.
*/
adoptedHubId?: string;
/**
* Cloud integration that owns the hub when it lives in a different
* provider account.
*
* Immutable — hub identity cannot change, so a change triggers a
* replacement.
*/
hubProviderId?: string;
/**
* Hubs attached to this on-ramp. Mutable.
*/
attachedHubs?: string[];
/**
* VPCs attached to this hub on-ramp (`type: "OnrampTypeHub"`). Mutable.
*/
attachedVpcs?: string[];
/**
* Whether Cloudflare manages hub-to-hub attachments. Mutable.
*/
manageHubToHubAttachments?: boolean;
/**
* Whether Cloudflare manages VPC-to-hub attachments. Mutable.
*/
manageVpcToHubAttachments?: boolean;
/**
* Whether deleting the on-ramp also destroys the cloud-side resources it
* provisioned (VPN gateways, Transit Gateway, …). Consumed only at
* delete time.
* @default false
*/
destroyOnDelete?: boolean;
}
export interface OnRampAttributes {
/** Cloudflare-assigned identifier of the on-ramp. */
onRampId: string;
/** The Cloudflare account the on-ramp belongs to. */
accountId: string;
/** Human readable name of the on-ramp. */
name: string;
/** The cloud provider this on-ramp connects to. */
cloudType: OnRampCloudType;
/** Topology of the on-ramp. */
type: OnRampType;
/** Whether BGP routing is enabled. */
dynamicRouting: boolean;
/** Whether Magic WAN routes are installed into the cloud route tables. */
installRoutesInCloud: boolean;
/** Whether cloud routes are installed in Magic WAN. */
installRoutesInMagicWan: boolean;
/** The connected VPC/VNet resource id, if set. */
vpc: string | undefined;
/** Cloud-side ASN, if set. */
cloudAsn: number | undefined;
/** Free-form description, if set. */
description: string | undefined;
/** Hubs attached to this on-ramp. */
attachedHubs: string[];
/** VPCs attached to this hub on-ramp. */
attachedVpcs: string[];
/** Whether Cloudflare manages hub-to-hub attachments, if reported. */
manageHubToHubAttachments: boolean | undefined;
/** Whether Cloudflare manages VPC-to-hub attachments, if reported. */
manageVpcToHubAttachments: boolean | undefined;
/** ISO8601 timestamp of the last change to the on-ramp. */
updatedAt: string;
/** Whether delete also destroys provisioned cloud-side resources. */
destroyOnDelete: boolean;
}
export type OnRamp = Resource<TypeId, OnRampProps, OnRampAttributes, never, Providers>;
/**
* A Magic Cloud Networking on-ramp — connects cloud VPCs/VNets to Magic WAN
* by provisioning VPN/Transit-Gateway constructs inside the cloud account
* registered via a `CloudIntegration`.
*
* On-ramps are heavily eventually consistent: after create/update the
* on-ramp goes through plan/apply phases that provision real cloud
* infrastructure (minutes). This resource creates and patches the on-ramp
* configuration and returns immediately; the apply lifecycle is driven by
* Cloudflare.
*
* `name`, `description`, `vpc`, route-installation flags, and attachments
* are patched in place; `cloudType`, `type`, `dynamicRouting`, `region`,
* `cloudAsn`, and hub identity force a replacement.
*
* Magic Cloud Networking is an entitlement-gated add-on (Magic WAN family).
* On accounts without the entitlement every API call fails with the typed
* `FeatureNotEnabled` error (Cloudflare code 1012, "feature not enabled").
* ### Connecting a single VPC
* **Example:** AWS VPC on-ramp
* ```typescript
* const onramp = yield* Cloudflare.MagicCloudNetworking.OnRamp("ProdVpc", {
* cloudType: "AWS",
* type: "OnrampTypeSingle",
* region: "us-east-1",
* vpc: discoveredVpcId,
* dynamicRouting: false,
* installRoutesInCloud: true,
* installRoutesInMagicWan: true,
* });
* ```
*
* ### Hub topologies
* **Example:** Transit Gateway hub with attached VPCs
* ```typescript
* yield* Cloudflare.MagicCloudNetworking.OnRamp("TgwHub", {
* cloudType: "AWS",
* type: "OnrampTypeHub",
* region: "us-east-1",
* dynamicRouting: true,
* installRoutesInCloud: false,
* installRoutesInMagicWan: false,
* attachedVpcs: [vpcA, vpcB],
* manageVpcToHubAttachments: true,
* });
* ```
*
* ### Destroy behavior
* **Example:** Tear down cloud-side resources on destroy
* ```typescript
* yield* Cloudflare.MagicCloudNetworking.OnRamp("ProdVpc", {
* cloudType: "AWS",
* type: "OnrampTypeSingle",
* region: "us-east-1",
* vpc: discoveredVpcId,
* dynamicRouting: false,
* installRoutesInCloud: true,
* installRoutesInMagicWan: true,
* destroyOnDelete: true,
* });
* ```
*
* @see https://developers.cloudflare.com/magic-cloud-networking/
*
* @resource
* @product Magic Cloud Networking
* @category Network
*/
export const OnRamp = Resource<OnRamp>(TypeId);
/**
* Returns true if the given value is an OnRamp resource.
*/
export const isOnRamp = (value: unknown): value is OnRamp =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const OnRampProvider = () =>
Provider.succeed(OnRamp, {
stables: ["onRampId", "accountId", "cloudType", "type", "dynamicRouting", "cloudAsn"],
diff: Effect.fn(function* ({ olds, news, output }) {
if (!isResolved(news)) return undefined;
const old = olds !== undefined && isResolved(olds) ? olds : undefined;
// Immutable identity/topology properties — the PATCH body accepts
// none of these, so any change is a replacement.
const oldCloudType = output?.cloudType ?? old?.cloudType;
if (oldCloudType !== undefined && oldCloudType !== news.cloudType) {
return { action: "replace" } as const;
}
const oldType = output?.type ?? old?.type;
if (oldType !== undefined && oldType !== news.type) {
return { action: "replace" } as const;
}
const oldDynamicRouting = output?.dynamicRouting ?? old?.dynamicRouting;
if (oldDynamicRouting !== undefined && oldDynamicRouting !== news.dynamicRouting) {
return { action: "replace" } as const;
}
if (old !== undefined) {
if (old.region !== news.region) {
return { action: "replace" } as const;
}
if (old.cloudAsn !== news.cloudAsn) {
return { action: "replace" } as const;
}
if (old.adoptedHubId !== news.adoptedHubId) {
return { action: "replace" } as const;
}
if (old.hubProviderId !== news.hubProviderId) {
return { action: "replace" } as const;
}
}
return undefined;
}),
read: Effect.fn(function* ({ id, output, olds }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const acct = output?.accountId ?? accountId;
const destroyOnDelete = output?.destroyOnDelete ?? olds?.destroyOnDelete ?? false;
// Owned path: refresh by our persisted on-ramp id.
if (output?.onRampId) {
const observed = yield* getOnRamp(acct, output.onRampId);
if (observed) return toAttributes(observed, acct, destroyOnDelete);
return undefined;
}
// Cold read — recover from lost state by matching the deterministic
// physical name. On-ramps carry no ownership markers, so report a
// match as Unowned and let the engine gate adoption.
const name = yield* onRampName(id, olds?.name);
const match = yield* findByName(acct, name);
return match ? Unowned(toAttributes(match, acct, destroyOnDelete)) : undefined;
}),
reconcile: Effect.fn(function* ({ id, news, output }) {
const { accountId } = yield* yield* CloudflareEnvironment;
const name = yield* onRampName(id, news.name);
const destroyOnDelete = news.destroyOnDelete ?? false;
// 1. Observe — the id cached on `output` is a hint, not a guarantee:
// a missing on-ramp falls through to the name scan and create.
let observed = output?.onRampId
? yield* getOnRamp(output.accountId ?? accountId, output.onRampId)
: 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) {
observed = yield* mcn.createOnRamp({
accountId,
name,
cloudType: news.cloudType,
type: news.type,
dynamicRouting: news.dynamicRouting,
installRoutesInCloud: news.installRoutesInCloud,
installRoutesInMagicWan: news.installRoutesInMagicWan,
region: news.region,
vpc: news.vpc,
cloudAsn: news.cloudAsn,
description: news.description,
adoptedHubId: news.adoptedHubId,
hubProviderId: news.hubProviderId,
attachedHubs: news.attachedHubs,
attachedVpcs: news.attachedVpcs,
manageHubToHubAttachments: news.manageHubToHubAttachments,
manageVpcToHubAttachments: news.manageVpcToHubAttachments,
});
return toAttributes(observed, accountId, destroyOnDelete);
}
// 3. Sync — diff observed cloud state against desired; PATCH only the
// delta and skip the call entirely on a no-op.
const patch: mcn.PatchOnRampRequest = {
accountId,
onrampId: observed.id,
};
let dirty = false;
if (observed.name !== name) {
patch.name = name;
dirty = true;
}
if (news.description !== undefined && (observed.description ?? "") !== news.description) {
patch.description = news.description;
dirty = true;
}
if (news.vpc !== undefined && (observed.vpc ?? "") !== news.vpc) {
patch.vpc = news.vpc;
dirty = true;
}
if (observed.installRoutesInCloud !== news.installRoutesInCloud) {
patch.installRoutesInCloud = news.installRoutesInCloud;
dirty = true;
}
if (observed.installRoutesInMagicWan !== news.installRoutesInMagicWan) {
patch.installRoutesInMagicWan = news.installRoutesInMagicWan;
dirty = true;
}
if (
news.attachedHubs !== undefined &&
!sameIds(observed.attachedHubs ?? [], news.attachedHubs)
) {
patch.attachedHubs = news.attachedHubs;
dirty = true;
}
if (
news.attachedVpcs !== undefined &&
!sameIds(observed.attachedVpcs ?? [], news.attachedVpcs)
) {
patch.attachedVpcs = news.attachedVpcs;
dirty = true;
}
if (
news.manageHubToHubAttachments !== undefined &&
(observed.manageHubToHubAttachments ?? false) !== news.manageHubToHubAttachments
) {
patch.manageHubToHubAttachments = news.manageHubToHubAttachments;
dirty = true;
}
if (
news.manageVpcToHubAttachments !== undefined &&
(observed.manageVpcToHubAttachments ?? false) !== news.manageVpcToHubAttachments
) {
patch.manageVpcToHubAttachments = news.manageVpcToHubAttachments;
dirty = true;
}
if (dirty) {
observed = yield* mcn.patchOnRamp(patch);
}
return toAttributes(observed, accountId, destroyOnDelete);
}),
delete: Effect.fn(function* ({ output }) {
// Deleting an on-ramp tears down cloud-side infrastructure when
// `destroy` is set — slow and eventually consistent on Cloudflare's
// side, but the DELETE call itself returns promptly.
yield* mcn
.deleteOnRamp({
accountId: output.accountId,
onrampId: output.onRampId,
destroy: output.destroyOnDelete,
})
.pipe(Effect.catchTag("OnRampNotFound", () => Effect.void));
}),
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
// Account-scoped collection: exhaustively paginate the on-ramp list,
// then hydrate each id into the exact `read` Attributes shape via
// `getOnRamp`. The list item omits some fields (`vpc`, `region`), so
// a per-item get is required for a fully-faithful Attributes object.
// Magic Cloud Networking is an entitlement-gated add-on; on accounts
// without it every call fails with `FeatureNotEnabled` — treat that
// as a non-listable account and return `[]`.
const ids = yield* mcn.listOnRamps.items({ accountId }).pipe(
Stream.map((onramp) => onramp.id),
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk)),
Effect.catchTag("FeatureNotEnabled", () => Effect.succeed([] as string[])),
);
const rows = yield* Effect.forEach(
ids,
(onRampId) =>
getOnRamp(accountId, onRampId).pipe(
Effect.map((observed) =>
observed ? toAttributes(observed, accountId, false) : undefined,
),
),
{ concurrency: 10 },
);
return rows.filter((row): row is OnRampAttributes => row !== undefined);
}),
});
type ObservedOnRamp = Pick<
mcn.GetOnRampResponse,
| "id"
| "name"
| "cloudType"
| "type"
| "dynamicRouting"
| "installRoutesInCloud"
| "installRoutesInMagicWan"
| "vpc"
| "cloudAsn"
| "description"
| "attachedHubs"
| "attachedVpcs"
| "manageHubToHubAttachments"
| "manageVpcToHubAttachments"
| "updatedAt"
| "region"
>;
/**
* Read an on-ramp by id, mapping "gone" (`OnRampNotFound`) to `undefined`.
*/
const getOnRamp = (accountId: string, onrampId: string) =>
mcn.getOnRamp({ accountId, onrampId }).pipe(
Effect.map((onramp): ObservedOnRamp | undefined => onramp),
Effect.catchTag("OnRampNotFound", () => Effect.undefined),
);
/**
* Find an on-ramp by exact name. Names are not unique on Cloudflare's side;
* if several on-ramps carry the same name, pick the lexicographically-first
* id for determinism.
*/
const findByName = (accountId: string, name: string) =>
mcn.listOnRamps.items({ accountId }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk)
.filter((onramp) => onramp.name === name)
.sort((a, b) => a.id.localeCompare(b.id))
.at(0),
),
);
const onRampName = (id: string, name: string | undefined) =>
Effect.gen(function* () {
return name ?? (yield* createPhysicalName({ id, lowercase: true }));
});
const sameIds = (observed: readonly string[], desired: readonly string[]) =>
observed.length === desired.length &&
[...observed].sort().join(",") === [...desired].sort().join(",");
const toAttributes = (
onramp: ObservedOnRamp,
accountId: string,
destroyOnDelete: boolean,
): OnRampAttributes => ({
onRampId: onramp.id,
accountId,
name: onramp.name,
// Distilled widens generated string enums to open unions (`string & {}`).
cloudType: onramp.cloudType as OnRampCloudType,
type: onramp.type as OnRampType,
dynamicRouting: onramp.dynamicRouting,
installRoutesInCloud: onramp.installRoutesInCloud,
installRoutesInMagicWan: onramp.installRoutesInMagicWan,
vpc: onramp.vpc ?? undefined,
cloudAsn: onramp.cloudAsn ?? undefined,
description: onramp.description ?? undefined,
attachedHubs: [...(onramp.attachedHubs ?? [])],
attachedVpcs: [...(onramp.attachedVpcs ?? [])],
manageHubToHubAttachments: onramp.manageHubToHubAttachments ?? undefined,
manageVpcToHubAttachments: onramp.manageVpcToHubAttachments ?? undefined,
updatedAt: onramp.updatedAt,
destroyOnDelete,
});