import * as loadBalancers from "@distilled.cloud/cloudflare/load-balancers";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
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.LoadBalancer.LoadBalancer" as const;
type TypeId = typeof TypeId;
/**
* Steering policy for a Load Balancer.
*/
export type SteeringPolicy =
| "off"
| "geo"
| "random"
| "dynamic_latency"
| "proximity"
| "least_outstanding_requests"
| "least_connections"
| "";
/**
* Session affinity mode for a Load Balancer.
*/
export type SessionAffinity = "none" | "cookie" | "ip_cookie" | "header";
/**
* Session affinity attributes for a Load Balancer.
*/
export interface SessionAffinityAttributes {
/** Seconds to drain an origin of affine sessions before removal. */
drainDuration?: number;
/** Headers to base header-mode session affinity on. */
headers?: ReadonlyArray<string>;
/** Whether all configured headers must match. */
requireAllHeaders?: boolean;
/** SameSite attribute of the affinity cookie. */
samesite?: "Auto" | "Lax" | "None" | "Strict";
/** Secure attribute of the affinity cookie. */
secure?: "Auto" | "Always" | "Never";
/** Failover behavior when an affine origin becomes unavailable. */
zeroDowntimeFailover?: "none" | "temporary" | "sticky";
}
/**
* Location strategy for non-proxied (DNS-steered) Load Balancers.
*/
export interface LocationStrategy {
/** Resolution mode used to determine the client's location. */
mode?: "pop" | "resolver_ip";
/** When to prefer the EDNS Client Subnet over the resolver IP. */
preferEcs?: "always" | "never" | "proximity" | "geo";
}
export interface Props {
/**
* Zone the load balancer lives in. Stable — changing the zone triggers
* replacement.
*/
zoneId: string;
/**
* The DNS hostname to associate with the Load Balancer (e.g.
* `lb.example.com`). If this hostname already exists as a DNS record,
* the Load Balancer takes precedence. Mutable in place.
*/
name: string;
/**
* Pool IDs ordered by their failover priority. Used by default, or when
* region/country/PoP pools are not configured for a request.
*/
defaultPools: ReadonlyArray<string>;
/**
* The pool ID to use when all other pools are detected as unhealthy.
*/
fallbackPool: string;
/**
* Object description.
*/
description?: string;
/**
* Whether the hostname is gray clouded (false) or orange clouded /
* proxied through Cloudflare (true).
* @default false
*/
proxied?: boolean;
/**
* TTL (seconds) of the DNS entry for the IP address returned by this
* load balancer. Only applies to unproxied load balancers — the API
* rejects it when `proxied: true`.
* @default 30
*/
ttl?: number;
/**
* Steering policy for this load balancer.
* @default ""
*/
steeringPolicy?: SteeringPolicy;
/**
* Type of session affinity to use.
* @default "none"
*/
sessionAffinity?: SessionAffinity;
/**
* Time, in seconds, until a client's session expires after being
* created.
* @default 82800
*/
sessionAffinityTtl?: number;
/**
* Attributes configuring session affinity behavior.
*/
sessionAffinityAttributes?: SessionAffinityAttributes;
/**
* Routing modifications in response to dynamic conditions (e.g.
* zero-downtime failover between health probes).
*/
adaptiveRouting?: { failoverAcrossPools?: boolean };
/**
* Location-based steering behavior for non-proxied requests.
*/
locationStrategy?: LocationStrategy;
/**
* Pool weights for `random` / `least_outstanding_requests` /
* `least_connections` steering.
*/
randomSteering?: {
defaultWeight?: number;
poolWeights?: Record<string, number>;
};
/**
* Region code → ordered pool IDs for that region. Regions not defined
* fall back to `defaultPools`.
*/
regionPools?: Record<string, ReadonlyArray<string>>;
/**
* Country code → ordered pool IDs for that country. Countries not
* defined fall back to the corresponding region pool mapping.
*/
countryPools?: Record<string, ReadonlyArray<string>>;
/**
* Enterprise only — Cloudflare PoP identifier → ordered pool IDs for
* that PoP.
*/
popPools?: Record<string, ReadonlyArray<string>>;
}
export interface Attributes {
/** Cloudflare-assigned load balancer identifier. */
loadBalancerId: string;
/** Zone that owns the load balancer. */
zoneId: string;
/** DNS hostname of the load balancer. */
name: string;
/** Whether the load balancer is enabled. */
enabled: boolean;
/** Whether the hostname is proxied (orange clouded). */
proxied: boolean;
/** Resolved steering policy. */
steeringPolicy: string;
/** Resolved default pool ids. */
defaultPools: ReadonlyArray<string>;
/** Resolved fallback pool id. */
fallbackPool: string;
/** ISO8601 creation timestamp. */
createdOn: string | undefined;
/** ISO8601 last-modified timestamp. */
modifiedOn: string | undefined;
}
export type LoadBalancer = Resource<TypeId, Props, Attributes, never, Providers>;
/**
* A Cloudflare Load Balancer — a zone-level DNS hostname that distributes
* traffic across {@link Pool}s with health-based failover,
* geo/latency steering, and session affinity.
*
* Requires the Load Balancing subscription to be enabled for the zone;
* without it, creation fails with the typed `LoadBalancingNotEnabledForZone`
* error.
* ### Creating a Load Balancer
* **Example:** DNS-only (unproxied) load balancer
* ```typescript
* const lb = yield* Cloudflare.LoadBalancer.LoadBalancer("ApiLb", {
* zoneId: zone.zoneId,
* name: "api.example.com",
* defaultPools: [pool.poolId],
* fallbackPool: pool.poolId,
* proxied: false,
* ttl: 30,
* });
* ```
*
* **Example:** Proxied load balancer with steering and affinity
* ```typescript
* const lb = yield* Cloudflare.LoadBalancer.LoadBalancer("AppLb", {
* zoneId: zone.zoneId,
* name: "app.example.com",
* defaultPools: [primary.poolId, secondary.poolId],
* fallbackPool: secondary.poolId,
* proxied: true,
* steeringPolicy: "random",
* sessionAffinity: "cookie",
* });
* ```
*
* ### Geo steering
* **Example:** Region pools
* ```typescript
* yield* Cloudflare.LoadBalancer.LoadBalancer("GeoLb", {
* zoneId: zone.zoneId,
* name: "geo.example.com",
* defaultPools: [us.poolId],
* fallbackPool: us.poolId,
* steeringPolicy: "geo",
* regionPools: {
* WEU: [eu.poolId],
* ENAM: [us.poolId],
* },
* });
* ```
*
* @see https://developers.cloudflare.com/load-balancing/
*
* @resource
* @product Load Balancers
* @category Performance & Reliability
*/
export const LoadBalancer = Resource<LoadBalancer>(TypeId, {
aliases: ["Cloudflare.LoadBalancer"],
});
/**
* Returns true if the given value is a LoadBalancer resource.
*/
export const isLoadBalancer = (value: unknown): value is LoadBalancer =>
Predicate.hasProperty(value, "Type") && value.Type === TypeId;
export const LoadBalancerProvider = () =>
Provider.succeed(LoadBalancer, {
stables: ["loadBalancerId", "zoneId", "createdOn"],
diff: Effect.fn(function* ({ olds, news }) {
if (!isResolved(news)) return undefined;
// zoneId is Input<string>; by diff time both sides are concrete
// strings when statically known.
if (
typeof olds.zoneId === "string" &&
typeof news.zoneId === "string" &&
olds.zoneId !== news.zoneId
) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ output, olds }) {
if (output?.loadBalancerId) {
const observed = yield* getLoadBalancer(output.zoneId, output.loadBalancerId);
return observed ? toAttributes(observed, output.zoneId) : undefined;
}
// Cold read — a load balancer's hostname is unique within its zone.
// Load balancers carry no ownership marker, so report the match as
// Unowned and let the engine gate takeover behind --adopt.
const zoneId = output?.zoneId ?? (olds?.zoneId as string | undefined);
const name = output?.name ?? olds?.name;
if (zoneId && name) {
const match = yield* findByName(zoneId, name);
if (match?.id) {
const observed = yield* getLoadBalancer(zoneId, match.id);
if (observed) return Unowned(toAttributes(observed, zoneId));
}
}
return undefined;
}),
reconcile: Effect.fn(function* ({ news, output }) {
// Inputs have been resolved to concrete strings by Plan.
const zoneId = news.zoneId as string;
const body = buildBody(news);
// 1. Observe — output.loadBalancerId is a cache hint; a 404 falls
// through to "missing" and we recreate.
const observed = output?.loadBalancerId
? yield* getLoadBalancer(output.zoneId ?? zoneId, output.loadBalancerId)
: undefined;
// 2. Ensure — missing: create with the full desired body.
if (!observed?.id) {
const created = yield* loadBalancers.createLoadBalancer({
zoneId,
...body,
});
return toAttributes(created, zoneId);
}
// 3. Sync — the update endpoint is a PUT requiring the full body;
// diff observed against desired and skip the call on a no-op.
if (!loadBalancerDirty(observed, body)) {
return toAttributes(observed, zoneId);
}
const updated = yield* loadBalancers.updateLoadBalancer({
zoneId,
loadBalancerId: observed.id,
...body,
});
return toAttributes(updated, zoneId);
}),
delete: Effect.fn(function* ({ output }) {
yield* loadBalancers
.deleteLoadBalancer({
zoneId: output.zoneId,
loadBalancerId: output.loadBalancerId,
})
.pipe(Effect.catchTag("LoadBalancerNotFound", () => Effect.void));
}),
// Load balancers are zone-scoped; enumerate every zone in the account and
// exhaustively paginate each zone's load balancers, hydrating each into the
// same Attributes shape `read` returns. Zones without the Load Balancing
// subscription reject the route (Forbidden) and are skipped.
list: Effect.fn(function* () {
const { accountId } = yield* yield* CloudflareEnvironment;
const zones = yield* listAllZones(accountId);
const rows = yield* Effect.forEach(
zones,
(zone) =>
loadBalancers.listLoadBalancers.pages({ zoneId: zone.id }).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.result ?? []).map((lb) => toAttributes(lb, zone.id)),
),
),
),
{ concurrency: 10 },
);
return rows.flat();
}),
});
type ObservedLoadBalancer =
| loadBalancers.GetLoadBalancerResponse
| loadBalancers.CreateLoadBalancerResponse
| loadBalancers.UpdateLoadBalancerResponse
| loadBalancers.ListLoadBalancersResponse["result"][number];
/**
* Read a load balancer by id, mapping "gone" (`LoadBalancerNotFound`,
* HTTP 404 code 1001) to `undefined`.
*/
const getLoadBalancer = (zoneId: string, loadBalancerId: string) =>
loadBalancers
.getLoadBalancer({ zoneId, loadBalancerId })
.pipe(Effect.catchTag("LoadBalancerNotFound", () => Effect.undefined));
/**
* Find a load balancer by exact hostname within a zone.
*/
const findByName = (zoneId: string, name: string) =>
loadBalancers.listLoadBalancers.items({ zoneId }).pipe(
Stream.filter((lb) => lb.name === name),
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).at(0)),
);
const resolvePools = (
pools: Record<string, ReadonlyArray<Input<string>>> | undefined,
): Record<string, string[]> | undefined =>
pools === undefined
? undefined
: Object.fromEntries(Object.entries(pools).map(([k, v]) => [k, Array.from(v as string[])]));
const buildBody = (news: Props) => ({
name: news.name,
defaultPools: news.defaultPools as string[],
fallbackPool: news.fallbackPool as string,
description: news.description,
proxied: news.proxied,
ttl: news.proxied === true ? undefined : news.ttl,
steeringPolicy: news.steeringPolicy,
sessionAffinity: news.sessionAffinity,
sessionAffinityTtl: news.sessionAffinityTtl,
sessionAffinityAttributes:
news.sessionAffinityAttributes === undefined
? undefined
: {
...news.sessionAffinityAttributes,
headers:
news.sessionAffinityAttributes.headers === undefined
? undefined
: Array.from(news.sessionAffinityAttributes.headers),
},
adaptiveRouting: news.adaptiveRouting,
locationStrategy: news.locationStrategy,
randomSteering: news.randomSteering,
regionPools: resolvePools(news.regionPools),
countryPools: resolvePools(news.countryPools),
popPools: resolvePools(news.popPools),
});
/**
* Compare desired (explicitly set) fields against observed cloud state.
* Unset desired fields defer to whatever the cloud already has.
*/
const loadBalancerDirty = (
observed: ObservedLoadBalancer,
body: ReturnType<typeof buildBody>,
): boolean => {
const scalarDirty = (
desired: string | number | boolean | undefined,
actual: string | number | boolean | null | undefined,
) => desired !== undefined && desired !== (actual ?? undefined);
const structDirty = (desired: unknown, actual: unknown) =>
desired !== undefined && JSON.stringify(desired) !== JSON.stringify(actual ?? {});
return (
(observed.name ?? "") !== body.name ||
JSON.stringify(observed.defaultPools ?? []) !== JSON.stringify(body.defaultPools) ||
(observed.fallbackPool ?? "") !== body.fallbackPool ||
scalarDirty(body.description, observed.description) ||
scalarDirty(body.proxied, observed.proxied) ||
scalarDirty(body.ttl, observed.ttl) ||
scalarDirty(body.steeringPolicy, observed.steeringPolicy) ||
scalarDirty(body.sessionAffinity, observed.sessionAffinity) ||
scalarDirty(body.sessionAffinityTtl, observed.sessionAffinityTtl) ||
structDirty(body.sessionAffinityAttributes, observed.sessionAffinityAttributes) ||
structDirty(body.adaptiveRouting, observed.adaptiveRouting) ||
structDirty(body.locationStrategy, observed.locationStrategy) ||
structDirty(body.randomSteering, observed.randomSteering) ||
structDirty(body.regionPools, observed.regionPools) ||
structDirty(body.countryPools, observed.countryPools) ||
structDirty(body.popPools, observed.popPools)
);
};
const toAttributes = (lb: ObservedLoadBalancer, zoneId: string): Attributes => ({
loadBalancerId: lb.id ?? "",
zoneId,
name: lb.name ?? "",
enabled: lb.enabled ?? true,
proxied: lb.proxied ?? false,
steeringPolicy: lb.steeringPolicy ?? "",
defaultPools: [...(lb.defaultPools ?? [])],
fallbackPool: lb.fallbackPool ?? "",
createdOn: lb.createdOn ?? undefined,
modifiedOn: lb.modifiedOn ?? undefined,
});