import type { IPAssignment as FlyIPAssignment } from "@distilled.cloud/fly-io/machines";
import * as machines from "@distilled.cloud/fly-io/machines";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import { listOwnedApps } from "./App.ts";
import type { App } from "./App.ts";
import type { Providers } from "./Providers.ts";
/**
* A resource-valued prop: the resource itself, or an Effect that produces
* it (so `yield* App(...)` and `App(...)` both type-check).
*/
type Ref<T> = T | Effect.Effect<T, never, Providers>;
/**
* Fly IP family allocated onto an App. Dedicated `v4` is billed and may
* be rejected when the org has no IPv4 quota. Prefer `v6` (free) or
* `shared_v4` (free) in tests. `private_v6` is a Flycast address: it is
* reachable only from the organization's private network.
*/
export type IpAssignmentType = "v4" | "v6" | "shared_v4" | "private_v6";
export interface IpAssignmentProps {
/**
* Parent Fly App. Accepts a `Fly.App` resource or an Effect that
* produces one. Changing the App replaces the assignment.
*/
app: Ref<App>;
/**
* Address family to allocate. `v6` is a dedicated IPv6 (free).
* `shared_v4` is a shared Anycast IPv4 (free). `v4` is a dedicated
* IPv4 (billed; may 400 when the org is over quota). `private_v6` is
* a Flycast IPv6 (free) that Fly's proxy serves only inside the
* private network. Changing type replaces the assignment.
*/
type: IpAssignmentType;
/**
* Region for a dedicated address. Changing it replaces the assignment.
*/
region?: string;
/**
* Private network a `private_v6` address is reachable from. Defaults
* to the organization's network. Create-only; changing it replaces.
*/
network?: string;
/**
* Organization slug. Defaults to the current token's org. Not a
* replacement key.
*/
orgSlug?: string;
/**
* Fly proxy service this address is bound to. Changing it replaces
* the assignment.
*/
serviceName?: string;
}
export type IpAssignment = Resource<
"Fly.IpAssignment",
IpAssignmentProps,
{
/** Physical Fly App name the address is assigned to. */
appName: string;
/** Allocated address. Identity of the assignment. */
ip: string;
/** Observed address family. */
type: IpAssignmentType;
/** Region for a dedicated address, if set. */
region: string | undefined;
/** Fly proxy service this address is bound to, if set. */
serviceName: string | undefined;
/** Whether the address is a shared Anycast IPv4. */
shared: boolean;
/**
* Named private network a `private_v6` address is reachable from.
* `undefined` for the organization's default network and for public
* addresses.
*/
network: string | undefined;
/** RFC3339 creation timestamp, if the API returned one. */
createdAt: string | undefined;
},
never,
Providers
>;
const resolveIpAssignmentProps = (
props: IpAssignmentProps | Effect.Effect<IpAssignmentProps, never, Providers>,
): Effect.Effect<IpAssignmentProps, never, Providers> =>
Effect.gen(function* () {
const resolved = Effect.isEffect(props) ? yield* props : props;
if (globalThis.__ALCHEMY_RUNTIME__) return resolved;
const app = Effect.isEffect(resolved.app)
? yield* resolved.app as Effect.Effect<App, never, Providers>
: resolved.app;
return { ...resolved, app };
});
const IpAssignmentResource = Resource<IpAssignment>("Fly.IpAssignment");
/**
* A Fly.IpAssignment is an address on an {@link App}. A {@link Service}
* publishes ports. Fly's proxy load-balances `{app}.fly.dev` across
* Machines that publish a proxy service.
*
* Identity is the allocated `ip`. There is no in-place update.
*
* @see https://fly.io/docs/networking/services/
*
* ### Shared IPv4
* `shared_v4` is a shared Anycast IPv4. It is free. This is what you
* want for fly.dev over IPv4. Yield it next to the Service.
*
* **Example:** Allocate shared_v4
* ```typescript
* export const PublicIp = Fly.IpAssignment("Shared", {
* app: Site,
* type: "shared_v4",
* });
* ```
*
* :::caution[Changing `type` or `app` replaces the assignment]
* A new address is allocated. The old one is released.
* :::
*
* ### Dedicated IPv6
* `v6` is a dedicated IPv6. It is free.
*
* **Example:** Allocate v6
* ```typescript
* export const V6 = Fly.IpAssignment("V6", {
* app: Site,
* type: "v6",
* });
* ```
*
* ### Dedicated IPv4
* `v4` is a billed dedicated IPv4. It may 400 if the org has no
* quota. Prefer `shared_v4` or `v6` in tests.
*
* **Example:** Allocate v4
* ```typescript
* export const Dedicated = Fly.IpAssignment("Dedicated", {
* app: Site,
* type: "v4",
* });
* ```
*
* ### Flycast (private IPv6)
* `private_v6` is a Flycast address. Fly's proxy serves it only inside
* the organization's private network, at `{app}.flycast`. It is free.
* Use it for a backend that another App calls and the internet must
* not reach. Requests still go through the proxy, so blue/green
* cordoning, `autostart`, and `autostop` keep working. Allocate no
* public address on the same App.
*
* **Example:** Allocate private_v6
* ```typescript
* export const Private = Fly.IpAssignment("Private", {
* app: Backend,
* type: "private_v6",
* });
* ```
*
* ### Region
* `region` pins a dedicated address. Shared Anycast ignores it. See
* [Regions](/fly/compute/regions) for the list of codes.
*
* **Example:** Dedicated IPv4 in iad
* ```typescript
* export const Dedicated = Fly.IpAssignment("Dedicated", {
* app: Site,
* type: "v4",
* region: "iad",
* });
* ```
*
* :::caution[Changing `region` replaces the assignment]
* A new address is allocated in the new region.
* :::
*
* ### Service name
* `serviceName` binds the address to a Fly proxy service. Changing it
* replaces the assignment.
*
* **Example:** Bind to a named service
* ```typescript
* export const PublicIp = Fly.IpAssignment("Shared", {
* app: Site,
* type: "shared_v4",
* serviceName: "http",
* });
* ```
*
* :::caution[Changing `serviceName` replaces the assignment]
* A new address is allocated bound to the new service.
* :::
*
* ### Isolated network
* `network` names the private network a `private_v6` address is
* reachable from. Create-only.
*
* **Example:** Custom network
* ```typescript
* export const Private = Fly.IpAssignment("Private", {
* app: Backend,
* type: "private_v6",
* network: "tenant-a",
* });
* ```
*
* :::caution[Changing `network` replaces the assignment]
* A new address is allocated on the new network.
* :::
*
* ### Organization
* `orgSlug` defaults to the current token's org. It is not a
* replacement key.
*
* **Example:** Pin an org
* ```typescript
* export const PublicIp = Fly.IpAssignment("Shared", {
* app: Site,
* type: "shared_v4",
* orgSlug: "my-org",
* });
* ```
*
* ### Yield with a Service
* Allocate the address on the same App as the Service. `api.url` is
* `https://{appName}.fly.dev`.
*
* **Example:** Stack outputs
* ```typescript
* export default Alchemy.Stack(
* "MyApp",
* { providers: Fly.providers(), state: Alchemy.localState() },
* Effect.gen(function* () {
* const api = yield* Api;
* const ip = yield* PublicIp;
* return { url: api.url, ip: ip.ip };
* }),
* );
* ```
*
* @resource
* @product App
*/
export const IpAssignment: typeof IpAssignmentResource = Object.assign(
(id: string, props: IpAssignmentProps | Effect.Effect<IpAssignmentProps, never, Providers>) =>
IpAssignmentResource(id, resolveIpAssignmentProps(props)),
IpAssignmentResource,
);
export class IpAssignmentNotCreated extends Data.TaggedError("Fly.IpAssignmentNotCreated")<{
appName: string;
type: IpAssignmentType;
}> {}
export class IpAssignmentAppMissing extends Data.TaggedError("Fly.IpAssignmentAppMissing")<{
type: IpAssignmentType;
}> {}
const appNameOf = (value: unknown): string | undefined => {
if (value === null || typeof value !== "object") return undefined;
const rec = value as { appName?: unknown; name?: unknown };
if (typeof rec.appName === "string" && rec.appName.length > 0) {
return rec.appName;
}
if (typeof rec.name === "string" && rec.name.length > 0) {
return rec.name;
}
return undefined;
};
const asType = (value: string | undefined): IpAssignmentType | undefined =>
value === "v4" || value === "v6" || value === "shared_v4" || value === "private_v6"
? value
: undefined;
/**
* Fly omits `type` from IP assignment responses. Only Flycast addresses carry
* a `network` (its name is empty for the organization's default network).
*/
const isFlycast = (assignment: FlyIPAssignment) =>
assignment.network !== undefined && assignment.network !== null;
const networkOf = (assignment: FlyIPAssignment) => assignment.network?.name || undefined;
const inferType = (assignment: FlyIPAssignment, fallback?: IpAssignmentType): IpAssignmentType => {
const wire = asType(assignment.type);
if (wire !== undefined) return wire;
if (assignment.shared === true) return "shared_v4";
if (isFlycast(assignment)) return "private_v6";
const ip = assignment.ip ?? "";
if (ip.includes(":")) return "v6";
if (fallback !== undefined) return fallback;
return ip.length > 0 ? "v4" : (fallback ?? "v4");
};
const toAttrs = (
appName: string,
assignment: FlyIPAssignment,
fallbackType?: IpAssignmentType,
): IpAssignment["Attributes"] => {
const type = inferType(assignment, fallbackType);
return {
appName,
ip: assignment.ip ?? "",
type,
region: assignment.region,
serviceName: assignment.service_name,
shared: type === "shared_v4" || assignment.shared === true,
network: networkOf(assignment),
createdAt: assignment.created_at,
};
};
const matchesDesired = (
assignment: FlyIPAssignment,
news: Pick<IpAssignmentProps, "type" | "region" | "serviceName" | "network">,
): boolean => {
if (inferType(assignment, news.type) !== news.type) return false;
if (news.type === "private_v6" && networkOf(assignment) !== news.network) return false;
if (news.region !== undefined && assignment.region !== news.region) {
return false;
}
if (news.serviceName !== undefined && assignment.service_name !== news.serviceName) {
return false;
}
return true;
};
const listAssignments = (appName: string) =>
machines.listAppIPAssignments({ app_name: appName }).pipe(
Effect.map((res) => res.ips ?? []),
Effect.catchTag(["NotFound", "Forbidden"], () => Effect.succeed([] as FlyIPAssignment[])),
);
const findByIp = (appName: string, ip: string) =>
listAssignments(appName).pipe(Effect.map((ips) => ips.find((item) => item.ip === ip)));
const findMatching = (
appName: string,
news: Pick<IpAssignmentProps, "type" | "region" | "serviceName" | "network">,
) =>
listAssignments(appName).pipe(
Effect.map((ips) => ips.find((item) => matchesDesired(item, news))),
);
const waitUntilGone = (appName: string, ip: string) =>
findByIp(appName, ip).pipe(
Effect.map((found) => found === undefined),
Effect.repeat({ schedule: Schedule.spaced("1 second"), until: (gone) => gone, times: 8 }),
);
/** Whether the App has any address reachable from the internet. */
export const hasPublicAddress = (appName: string) =>
listAssignments(appName).pipe(
Effect.map((ips) => ips.some((item) => inferType(item) !== "private_v6")),
);
/**
* Converge the addresses of an App a {@link Service} owns. Every owned App
* gets a Flycast address on its private network (the organization's
* default network when `network` is omitted). A public App also gets a
* shared IPv4 and an IPv6; a private one has every public address
* released. All three types are free.
*/
export const syncOwnedAppAddresses = Effect.fn(function* (
appName: string,
isPublic: boolean,
network?: string,
) {
const observed = yield* listAssignments(appName);
const isDesiredFlycast = (item: FlyIPAssignment) =>
inferType(item) === "private_v6" && networkOf(item) === network;
if (!observed.some(isDesiredFlycast)) {
yield* machines
.createAppIPAssignment({ app_name: appName, type: "private_v6", network })
.pipe(Effect.catchTag("Conflict", () => Effect.undefined));
}
if (isPublic) {
for (const type of ["shared_v4", "v6"] as const) {
if (observed.some((item) => inferType(item) === type)) continue;
yield* machines
.createAppIPAssignment({ app_name: appName, type })
.pipe(Effect.catchTag("Conflict", () => Effect.undefined));
}
}
// Release public addresses of a private Service and Flycast addresses
// on any other network.
for (const item of observed) {
if (item.ip === undefined || isDesiredFlycast(item)) continue;
if (isPublic && inferType(item) !== "private_v6") continue;
yield* machines
.deleteAppIPAssignment({ app_name: appName, ip: item.ip })
.pipe(Effect.catchTag("NotFound", () => Effect.void));
yield* waitUntilGone(appName, item.ip);
}
});
/**
* Add a Flycast address on `network` to an App a {@link Service} shares,
* so bound callers can reach it. Only ever adds; the address is removed
* with the App.
*/
export const ensureFlycastAddress = Effect.fn(function* (appName: string, network?: string) {
const observed = yield* listAssignments(appName);
if (observed.some((item) => inferType(item) === "private_v6" && networkOf(item) === network))
return;
yield* machines
.createAppIPAssignment({ app_name: appName, type: "private_v6", network })
.pipe(Effect.catchTag("Conflict", () => Effect.undefined));
});
export const IpAssignmentProvider = () =>
Provider.succeed(IpAssignment, {
stables: ["ip", "appName", "type", "region"],
nuke: { dependsOn: ["Fly.App"] },
diff: Effect.fn(function* ({ news, olds, output }) {
if (news === undefined || !isResolved(news)) return undefined;
if (output === undefined) return undefined;
const appName = appNameOf(news.app);
const appChanged = appName !== undefined && appName !== output.appName;
const typeChanged = news.type !== output.type;
const regionChanged = news.region !== undefined && news.region !== output.region;
const serviceChanged =
news.serviceName !== undefined && news.serviceName !== output.serviceName;
const networkChanged = news.network !== (olds !== undefined ? olds.network : output.network);
if (appChanged || typeChanged || regionChanged || serviceChanged || networkChanged) {
return { action: "replace" as const };
}
return undefined;
}),
read: Effect.fn(function* ({ olds, output }) {
const appName = output?.appName ?? appNameOf(olds?.app);
if (appName === undefined) return undefined;
const found =
output?.ip !== undefined && output.ip.length > 0
? yield* findByIp(appName, output.ip)
: olds !== undefined
? yield* findMatching(appName, olds)
: undefined;
if (found === undefined || found.ip === undefined) return undefined;
return toAttrs(appName, found, output?.type ?? olds?.type);
}),
list: Effect.fn(function* () {
const apps = yield* listOwnedApps();
const rows = yield* Effect.forEach(
apps,
(app) =>
listAssignments(app.appName).pipe(
Effect.map((ips) =>
ips
.filter((item) => item.ip !== undefined && item.ip.length > 0)
.map((item) => toAttrs(app.appName, item)),
),
),
{ concurrency: 8 },
);
return rows.flat();
}),
reconcile: Effect.fn(function* ({ news, output }) {
const props = news ?? ({} as IpAssignmentProps);
const appName = appNameOf(props.app) ?? output?.appName;
if (appName === undefined) {
return yield* new IpAssignmentAppMissing({ type: props.type });
}
// Observe by cached ip, then by desired type/region/service.
let current =
output?.ip !== undefined && output.ip.length > 0
? yield* findByIp(appName, output.ip)
: undefined;
if (current === undefined) {
current = yield* findMatching(appName, props);
}
if (current === undefined) {
const created = yield* machines
.createAppIPAssignment({
app_name: appName,
type: props.type,
region: props.region,
network: props.network,
org_slug: props.orgSlug,
service_name: props.serviceName,
})
.pipe(Effect.catchTag("Conflict", () => Effect.undefined));
if (created !== undefined && created.ip !== undefined) {
current = created;
} else {
current = yield* findMatching(appName, props);
}
}
if (current === undefined || current.ip === undefined) {
return yield* new IpAssignmentNotCreated({ appName, type: props.type });
}
return toAttrs(appName, current, props.type);
}),
delete: Effect.fn(function* ({ output }) {
const appName = output.appName;
const ip = output.ip;
if (appName.length === 0 || ip.length === 0) return;
yield* machines
.deleteAppIPAssignment({ app_name: appName, ip })
.pipe(Effect.catchTag("NotFound", () => Effect.void));
yield* waitUntilGone(appName, ip);
}),
});