sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ MagicTransit/ StaticRoute.ts

import * as magicTransit from "@distilled.cloud/cloudflare/magic-transit";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.MagicTransit.StaticRoute" as const;
type TypeId = typeof TypeId;

/**
 * Scope of an ECMP static route — restricts the route to specific
 * Cloudflare colos or regions.
 */
export interface MagicStaticRouteScope {
  /** List of colo names the route applies to. */
  coloNames?: string[];
  /** List of colo regions the route applies to. */
  coloRegions?: string[];
}

export interface MagicStaticRouteProps {
  /**
   * IP prefix in CIDR notation that this route matches.
   */
  prefix: string;
  /**
   * The next-hop IP address for the static route — typically a Magic
   * tunnel's customer-side interface address.
   */
  nexthop: string;
  /**
   * Priority of the static route. Lower values are preferred.
   * @default 100
   */
  priority?: number;
  /**
   * An optional human-provided description of the static route.
   */
  description?: string;
  /**
   * Optional weight for ECMP routes.
   */
  weight?: number;
  /**
   * Used only for ECMP routes — restrict the route to colos/regions.
   */
  scope?: MagicStaticRouteScope;
}

export interface MagicStaticRouteAttributes {
  /** Cloudflare-assigned identifier of the static route. */
  routeId: string;
  /** The Cloudflare account the route belongs to. */
  accountId: string;
  /** IP prefix in CIDR notation. */
  prefix: string;
  /** The next-hop IP address. */
  nexthop: string;
  /** Priority of the static route. */
  priority: number;
  /** The route description, if set. */
  description: string | undefined;
  /** ECMP weight, if set. */
  weight: number | undefined;
  /** ECMP scope, if set. */
  scope: MagicStaticRouteScope | undefined;
  /** ISO8601 creation timestamp. */
  createdOn: string | undefined;
  /** ISO8601 last-modified timestamp. */
  modifiedOn: string | undefined;
}

export type MagicStaticRoute = Resource<
  TypeId,
  MagicStaticRouteProps,
  MagicStaticRouteAttributes,
  never,
  Providers
>;

/**
 * A Magic Transit / Magic WAN static route — steers traffic for a prefix
 * to a next-hop (usually a Magic tunnel interface address).
 *
 * Requires a Magic Transit or Magic WAN subscription on the account —
 * accounts that are not onboarded receive a typed
 * `MagicTransitNotOnboarded` error (Cloudflare code 1012).
 *
 * All properties are mutable in place via PUT. A route's practical
 * identity is the `(prefix, nexthop, priority)` triple — when state is
 * lost, `read` scans for a matching route and reports it as `Unowned` so
 * takeover is gated behind `--adopt`.
 * ### Creating a static route
 * **Example:** Route a prefix over a GRE tunnel
 * ```typescript
 * const tunnel = yield* Cloudflare.MagicTransit.GreTunnel("office", {
 *   name: "office-gre-1",
 *   cloudflareGreEndpoint: "203.0.113.1",
 *   customerGreEndpoint: "198.51.100.1",
 *   interfaceAddress: "10.213.0.8/31",
 * });
 *
 * yield* Cloudflare.MagicTransit.MagicStaticRoute("office-route", {
 *   prefix: "10.100.0.0/24",
 *   nexthop: "10.213.0.9",
 *   priority: 100,
 * });
 * ```
 *
 * **Example:** ECMP route scoped to a region
 * ```typescript
 * yield* Cloudflare.MagicTransit.MagicStaticRoute("ecmp-route", {
 *   prefix: "10.100.0.0/24",
 *   nexthop: "10.213.0.9",
 *   priority: 100,
 *   weight: 50,
 *   scope: { coloRegions: ["ENAM"] },
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/magic-transit/how-to/configure-static-routes/
 *
 * @resource
 * @product Magic Transit
 * @category Network
 */
export const MagicStaticRoute = Resource<MagicStaticRoute>(TypeId);

/**
 * Returns true if the given value is a MagicStaticRoute resource.
 */
export const isMagicStaticRoute = (value: unknown): value is MagicStaticRoute =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

const DEFAULT_PRIORITY = 100;

export const MagicStaticRouteProvider = () =>
  Provider.succeed(MagicStaticRoute, {
    stables: ["routeId", "accountId", "createdOn"],

    read: Effect.fn(function* ({ output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      if (output?.routeId) {
        const observed = yield* getRoute(acct, output.routeId);
        if (observed) return toAttributes(observed, acct);
      }
      // Cold read — match on the (prefix, nexthop, priority) triple.
      // Routes carry no ownership markers; report as Unowned so takeover
      // is gated behind the adopt policy.
      const prefix = output?.prefix ?? olds?.prefix;
      const nexthop =
        output?.nexthop ??
        (olds?.nexthop !== undefined && isResolved(olds.nexthop) ? olds.nexthop : undefined);
      if (prefix && nexthop) {
        const priority = output?.priority ?? olds?.priority ?? DEFAULT_PRIORITY;
        const observed = yield* findRoute(acct, prefix, nexthop, priority);
        if (observed) return Unowned(toAttributes(observed, acct));
      }
      return undefined;
    }),

    reconcile: Effect.fn(function* ({ news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Inputs have been resolved to concrete strings by Plan.
      const nexthop = news.nexthop as string;
      const priority = news.priority ?? DEFAULT_PRIORITY;

      // Observe — the id on `output` is a hint; fall back to scanning for
      // the identity triple when it is gone.
      let observed = output?.routeId ? yield* getRoute(accountId, output.routeId) : undefined;
      if (!observed) {
        observed = yield* findRoute(accountId, news.prefix, nexthop, priority);
      }

      // Ensure — create when missing.
      if (!observed) {
        const created = yield* magicTransit.createRoute({
          accountId,
          prefix: news.prefix,
          nexthop,
          priority,
          description: news.description,
          weight: news.weight,
          scope: news.scope,
        });
        return toAttributes(created, accountId);
      }

      // Sync — diff observed cloud state against desired; full PUT, skip
      // on no-op.
      const dirty =
        observed.prefix !== news.prefix ||
        observed.nexthop !== nexthop ||
        observed.priority !== priority ||
        (news.description !== undefined &&
          (observed.description ?? undefined) !== news.description) ||
        (news.weight !== undefined && (observed.weight ?? undefined) !== news.weight) ||
        scopeDirty(observed.scope, news.scope);
      if (dirty) {
        const updated = yield* magicTransit.updateRoute({
          accountId,
          routeId: observed.id,
          prefix: news.prefix,
          nexthop,
          priority,
          description: news.description,
          weight: news.weight,
          scope: news.scope,
        });
        observed = updated.modifiedRoute ?? (yield* getRoute(accountId, observed.id)) ?? observed;
      }

      return toAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* magicTransit
        .deleteRoute({
          accountId: output.accountId,
          routeId: output.routeId,
        })
        .pipe(Effect.catchTag("RouteNotFound", () => Effect.void));
    }),

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Account-scoped collection — the list API already returns the full
      // route shape, so each item maps directly to the `read` Attributes.
      return yield* magicTransit.listRoutes({ accountId }).pipe(
        Effect.map((response) =>
          (response.routes ?? []).map((route) => toAttributes(route, accountId)),
        ),
        // Accounts without a Magic Transit / Magic WAN subscription can't
        // enumerate routes — treat as empty rather than failing the list.
        Effect.catchTag("MagicTransitNotOnboarded", () => Effect.succeed([])),
      );
    }),
  });

interface ObservedRoute {
  id: string;
  nexthop: string;
  prefix: string;
  priority: number;
  description?: string | null;
  weight?: number | null;
  scope?: {
    coloNames?: string[] | null;
    coloRegions?: string[] | null;
  } | null;
  createdOn?: string | null;
  modifiedOn?: string | null;
}

/**
 * Read a route by id, mapping "gone" (`RouteNotFound`, Cloudflare error
 * code 1020) to `undefined`.
 */
const getRoute = (accountId: string, routeId: string) =>
  magicTransit.getRoute({ accountId, routeId }).pipe(
    Effect.map((r): ObservedRoute | undefined => r.route ?? undefined),
    Effect.catchTag("RouteNotFound", () => Effect.undefined),
  );

/**
 * Find a route by its (prefix, nexthop, priority) identity triple.
 */
const findRoute = (accountId: string, prefix: string, nexthop: string, priority: number) =>
  magicTransit
    .listRoutes({ accountId })
    .pipe(
      Effect.map((r): ObservedRoute | undefined =>
        (r.routes ?? []).find(
          (route) =>
            route.prefix === prefix && route.nexthop === nexthop && route.priority === priority,
        ),
      ),
    );

const sameList = (a: string[] | null | undefined, b: string[] | undefined): boolean =>
  [...(a ?? [])].sort().join(",") === [...(b ?? [])].sort().join(",");

const scopeDirty = (
  observed: ObservedRoute["scope"],
  desired: MagicStaticRouteScope | undefined,
): boolean => {
  if (desired === undefined) return false;
  return (
    !sameList(observed?.coloNames, desired.coloNames) ||
    !sameList(observed?.coloRegions, desired.coloRegions)
  );
};

const toAttributes = (route: ObservedRoute, accountId: string): MagicStaticRouteAttributes => ({
  routeId: route.id,
  accountId,
  prefix: route.prefix,
  nexthop: route.nexthop,
  priority: route.priority,
  description: route.description ?? undefined,
  weight: route.weight ?? undefined,
  scope: route.scope
    ? {
        coloNames: route.scope.coloNames ?? undefined,
        coloRegions: route.scope.coloRegions ?? undefined,
      }
    : undefined,
  createdOn: route.createdOn ?? undefined,
  modifiedOn: route.modifiedOn ?? undefined,
});