import type { Docker } from "@alchemy.run/docker/Docker";
import type { FlyMachineService } from "@distilled.cloud/fly-io/machines";
import * as machines from "@distilled.cloud/fly-io/machines";
import * as Bundle from "alchemy/Bundle/Bundle";
import {
matchesPackageRoot,
normalizeInstallTargets,
resolvePackageInstallIdentity,
type PackageInstall,
} from "alchemy/Bundle/InstalledPackages";
import { findCwdForBundle, getStableContextDir, resolveMainPath } from "alchemy/Bundle/TempRoot";
import { safeHttpEffect } from "alchemy/Http";
import type { ResourceBinding } from "alchemy/Resource";
import { createContainerRuntimeContext, type HostRuntimeContext } from "alchemy/Runtime/Process";
import {
copyExtraFiles,
contextRootOf,
extraFileDestination,
hashExtraFiles,
isContextRootDest,
posixRelUnder,
resolveExtraSource,
type ExtraFile,
} from "alchemy/Util/extraFiles";
import { sha256, sha256Object } from "alchemy/Util/sha256";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Path from "effect/Path";
import * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import type * as rolldown from "rolldown";
import { buildOnRemoteBuilder } from "./internal/RemoteBuilder.ts";
import type { BoundTarget, DiskSpec, ServiceBinding } from "./MountVolume.ts";
import { rpcMethodsOf, serveFlyRpc } from "./rpc.ts";
export type FlyHostRuntimeContext = HostRuntimeContext;
/**
* Container runtime context for Fly hosts. It also serves the program's RPC
* methods to bound callers (see {@link serveFlyRpc}) and boots the HTTP
* server for a program that exposes methods but no `fetch`.
*/
export const createFlyHostRuntimeContext =
(type: string) =>
(id: string): HostRuntimeContext => {
const base = createContainerRuntimeContext(type)(id);
const serveBase = base.serve;
const serve: HostRuntimeContext["serve"] = (handler, options) => {
const shape = options?.shape;
const methods = rpcMethodsOf(shape);
// `safeHttpEffect` also resolves a `fetch` given as an Effect that
// builds the handler.
const wrapped = serveFlyRpc(methods, safeHttpEffect(handler));
const boots =
shape === undefined || shape.fetch !== undefined || Object.keys(methods).length > 0;
return serveBase(
wrapped,
boots ? { shape: { ...shape, fetch: shape?.fetch ?? wrapped } } : options,
) as Effect.Effect<void, never, any>;
};
return Object.assign(base, { serve });
};
export const FLY_REGISTRY = "registry.fly.io";
export const DEFAULT_BASE_IMAGE = "node:26-slim";
export const DEFAULT_PORT = 3000;
export const MACHINE_PLATFORM = "linux/amd64";
export interface FlyBuildOptions extends Bundle.BundleConfig {
/**
* Native or Node-only packages to install into the Machine image with
* `npm install` instead of bundling them. Same `build.install` shape as
* Lambda.
*
* @example
* ```typescript
* build: { install: ["sharp"] }
* ```
*/
readonly install?: PackageInstall;
/**
* Build the image on Fly's remote builders (Depot), as `fly deploy` does,
* instead of with the local Docker engine. Only the build context is
* uploaded; the builder pulls the base image and pushes the result to
* `registry.fly.io` next to it. Set `false` to build and push locally.
* Either way, the local `docker buildx` client drives the build.
*
* @default true
*/
readonly remote?: boolean;
}
export type { ExtraFile };
export interface HostedProgramProps {
main: string;
handler?: string;
port?: number;
image?: string;
env?: Record<string, any>;
isExternal?: boolean;
build?: FlyBuildOptions;
/**
* Extra host directories baked into the image (framework client
* assets, Next.js `.next`, …). Hashed into `code.hash` so asset
* changes rebuild the image.
*/
extraFiles?: ReadonlyArray<ExtraFile>;
}
export { extraFileDestination };
const matchesConfiguredExternal = (
external: rolldown.InputOptions["external"],
moduleId: string,
parentId: string | undefined,
isResolved: boolean,
): boolean => {
if (external === undefined) return false;
if (typeof external === "function") {
return external(moduleId, parentId, isResolved) === true;
}
const matchers = Array.isArray(external) ? external : [external];
return matchers.some((matcher) =>
typeof matcher === "string" ? matcher === moduleId : matcher.test(moduleId),
);
};
export class DeployTokenMissing extends Data.TaggedError("Fly.DeployTokenMissing")<{
appName: string;
}> {}
/**
* The generated entry for `Fly.Service` / `Fly.Sprite` machines: a shim
* importing only `@alchemy.run/fly/Bootstrap` plus the user's `main` —
* see that module for why the entry never imports alchemy's own
* dependencies. The runtime flag is raised BEFORE the user's module is
* evaluated (hence the dynamic import) so its module-scope code sees it.
*/
const makeBunBootstrap =
(handler: string) =>
(importPath: string): string =>
`
import { bootstrap } from "@alchemy.run/fly/Bootstrap";
globalThis.__ALCHEMY_RUNTIME__ = true;
const { ${handler}: entrypoint } = await import(${JSON.stringify(importPath)});
await bootstrap(entrypoint);
`;
/** Unwrap env inputs while preserving serialized RuntimeContext markers. */
export const plainEnvValue = (value: unknown): string | undefined => {
if (value === undefined || value === null) return undefined;
if (Redacted.isRedacted(value)) return value.pipe(Redacted.value, plainEnvValue);
if (typeof value === "string") {
return value.length > 0 ? value : undefined;
}
if (typeof value === "number" || typeof value === "boolean") {
return String(value);
}
return undefined;
};
export const toEnvRecord = (env: Record<string, any> | undefined): Record<string, string> =>
Object.fromEntries(
Object.entries(env ?? {}).flatMap(([key, value]) => {
const raw = plainEnvValue(value);
return raw === undefined ? [] : [[key, raw]];
}),
);
const coerceBindingName = (value: unknown): string | undefined => {
const direct = plainEnvValue(value);
if (direct !== undefined) return direct;
if (value != null && typeof value === "object") {
const record = value as { name?: unknown; id?: unknown; addOnId?: unknown };
return (
coerceBindingName(record.name) ??
coerceBindingName(record.id) ??
coerceBindingName(record.addOnId)
);
}
return undefined;
};
export const collectBindingState = (bindings: readonly ResourceBinding<ServiceBinding>[]) => {
const active = bindings.filter(
(binding: ResourceBinding<ServiceBinding> & { action?: string }) => binding.action !== "delete",
);
const env = toEnvRecord(
active
.map((binding) => binding?.data?.env)
.reduce<Record<string, any>>((acc, value) => ({ ...acc, ...value }), {}),
);
const mounts: DiskSpec[] = [];
const seen = new Set<string>();
const redis: { name: string; id?: string }[] = [];
const buckets: { name: string; id?: string; values?: Record<string, string> }[] = [];
const postgres: { clusterId: string; variableName?: string }[] = [];
const targets: BoundTarget[] = [];
for (const binding of active) {
const target = binding?.data?.target;
if (target !== undefined) targets.push(target);
for (const mount of binding?.data?.mounts ?? []) {
if (seen.has(mount.path)) continue;
seen.add(mount.path);
mounts.push(mount);
}
const attached = binding?.data?.redis;
const redisName = coerceBindingName(attached?.name);
const redisId = coerceBindingName(attached?.id);
if (redisName !== undefined || redisId !== undefined) {
redis.push({ name: redisName ?? "", id: redisId });
}
const bucket = binding?.data?.bucket as
| {
name?: unknown;
id?: unknown;
addOnId?: unknown;
bucketName?: unknown;
accessKeyId?: unknown;
secretAccessKey?: unknown;
endpoint?: unknown;
region?: unknown;
}
| undefined;
const bucketName = coerceBindingName(bucket?.name);
const bucketId = coerceBindingName(bucket?.id) ?? coerceBindingName(bucket?.addOnId);
if (bucketName !== undefined || bucketId !== undefined) {
// The bound Bucket's attributes carry the create-time Tigris
// credentials, which Fly's add-on lookup often returns empty.
const values: Record<string, string> = {};
for (const [key, value] of [
["BUCKET_NAME", bucket?.bucketName],
["AWS_ACCESS_KEY_ID", bucket?.accessKeyId],
["AWS_SECRET_ACCESS_KEY", bucket?.secretAccessKey],
["AWS_ENDPOINT_URL_S3", bucket?.endpoint],
["AWS_REGION", bucket?.region],
] as const) {
const plain = plainEnvValue(value);
if (plain !== undefined) values[key] = plain;
}
buckets.push({ name: bucketName ?? "", id: bucketId, values });
}
const pg = binding?.data?.postgres;
const clusterId = coerceBindingName(pg?.clusterId);
if (clusterId !== undefined) {
postgres.push({
clusterId,
variableName:
typeof pg?.variableName === "string" && pg.variableName.length > 0
? pg.variableName
: undefined,
});
}
}
return { env, mounts, redis, buckets, postgres, targets };
};
/**
* HTTP 80 → HTTPS redirect plus HTTPS 443 for public Services. Private
* (Flycast-only) Services publish plain HTTP on 80: Fly issues no
* certificate for `.flycast`, so a redirect to HTTPS would break callers.
*/
export const defaultHttpServices = (
port: number,
count = 1,
isPublic = true,
): FlyMachineService[] => [
{
protocol: "tcp",
internal_port: port,
autostart: true,
autostop: "off",
min_machines_running: count,
ports: isPublic
? [
{ port: 80, handlers: ["http"], force_https: true },
{ port: 443, handlers: ["tls", "http"] },
]
: [{ port: 80, handlers: ["http"] }],
// Wait until the process is listening before the proxy sends traffic.
// Without this, fly.dev hangs (status 0) while Node is still booting.
checks: [{ type: "tcp", port, interval: "10s", timeout: "2s", grace_period: "30s" }],
},
];
const sanitizeImageRepo = (id: string): string => {
const lowered = id
.toLowerCase()
.replace(/[^a-z0-9_.-]+/g, "-")
.replace(/^-+|-+$/g, "");
return lowered.length === 0 ? "service" : lowered;
};
const generateDockerfile = (
props: HostedProgramProps,
hasChunks: boolean,
install?: Record<string, string>,
entryRel?: string,
) => {
const port = props.port ?? DEFAULT_PORT;
const lines = [`FROM ${props.image ?? DEFAULT_BASE_IMAGE}`, `WORKDIR /app`];
if (install !== undefined && Object.keys(install).length > 0) {
lines.push(
`COPY package.json /app/package.json`,
`RUN npm install --omit=dev --no-fund --no-audit`,
);
}
if (props.isExternal === true) {
lines.push(`COPY . /app`);
const entry = entryRel !== undefined && entryRel.length > 0 ? entryRel : "serve-node.mjs";
lines.push(
`ENV PORT=${String(port)}`,
`ENV HOST=0.0.0.0`,
`EXPOSE ${String(port)}`,
`ENTRYPOINT ["node", ${JSON.stringify(`/app/${entry}`)}]`,
);
return `${lines.join("\n")}\n`;
}
lines.push(`COPY index.mjs /app/index.mjs`);
if (hasChunks) {
lines.push(`COPY *.js /app/`);
}
const seen = new Set<string>();
for (const extra of props.extraFiles ?? []) {
const dest = extraFileDestination(extra.dest);
if (isContextRootDest(dest) || seen.has(dest)) continue;
seen.add(dest);
lines.push(`COPY ${dest} /app/${dest}`);
}
lines.push(
`ENV PORT=${String(port)}`,
`ENV HOST=0.0.0.0`,
`EXPOSE ${String(port)}`,
`ENTRYPOINT ["node", "/app/index.mjs"]`,
);
return `${lines.join("\n")}\n`;
};
const installManifest = (dependencies: Record<string, string>) =>
`${JSON.stringify({ private: true, type: "module", dependencies }, null, 2)}\n`;
export const createFlyHostedSupport = ({
stackName,
stage,
virtualEntryPlugin,
docker,
dotAlchemy,
}: {
stackName: string;
stage: string;
virtualEntryPlugin: (content: (importPath: string) => string) => rolldown.Plugin;
docker: Docker["Service"];
dotAlchemy: string;
}) => {
const alchemyEnv = {
ALCHEMY_STACK_NAME: stackName,
ALCHEMY_STAGE: stage,
ALCHEMY_PHASE: "runtime",
HOST: "0.0.0.0",
};
const bundleProgram = Effect.fn(function* (props: HostedProgramProps) {
const handler = props.handler ?? "default";
const realMain = yield* resolveMainPath(props.main);
const cwd = yield* findCwdForBundle(realMain);
const bootstrap = makeBunBootstrap(handler);
const requested = yield* normalizeInstallTargets(props.build?.install);
const installRoots = new Set(Object.keys(requested));
const configuredExternal = props.build?.input?.external;
const buildBundle = Effect.fn(function* (
entry: string,
plugins?: rolldown.RolldownPluginOption,
) {
return yield* Bundle.build(
{
...props.build?.input,
input: entry,
cwd,
platform: "node",
external: (moduleId, parentId, isResolved) => {
if (moduleId === "bun" || moduleId.startsWith("bun:")) return true;
for (const root of installRoots) {
if (matchesPackageRoot(moduleId, root)) return true;
}
return matchesConfiguredExternal(configuredExternal, moduleId, parentId, isResolved);
},
resolve: {
conditionNames: [...Bundle.NODE_CONDITION_NAMES],
...props.build?.input?.resolve,
},
plugins: [props.build?.input?.plugins, plugins],
},
{
...props.build?.output,
format: "esm",
sourcemap: props.build?.output?.sourcemap ?? false,
entryFileNames: "index.mjs",
strictExecutionOrder: true,
keepNames: true,
},
props.build,
);
});
if (props.isExternal === true) {
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const bytes = yield* fs.readFile(realMain);
const hash = yield* sha256(bytes);
return { files: [{ path: path.basename(realMain), content: bytes }], hash };
}
const bundleOutput = yield* buildBundle(realMain, virtualEntryPlugin(bootstrap));
const files = bundleOutput.files.map((file) => ({
path: file.path,
content:
typeof file.content === "string" ? new TextEncoder().encode(file.content) : file.content,
}));
return { files, hash: bundleOutput.hash };
});
const computeCodeHash = Effect.fn(function* (props: HostedProgramProps) {
const bundled = yield* bundleProgram(props);
const realMain = yield* resolveMainPath(props.main);
const cwd = yield* findCwdForBundle(realMain);
const path = yield* Path.Path;
const requested = yield* normalizeInstallTargets(props.build?.install);
const identity =
Object.keys(requested).length > 0
? yield* resolvePackageInstallIdentity({ cwd, requested })
: undefined;
const install =
identity !== undefined && Object.keys(identity.resolved).length > 0
? identity.resolved
: undefined;
const packageJson = install === undefined ? undefined : installManifest(install);
const extras = (props.extraFiles ?? []).map((file) => ({
source: file.source,
dest: file.dest,
}));
const root = contextRootOf(realMain, extras, path, (source) =>
resolveExtraSource(source, path),
);
const entryRel =
props.isExternal === true
? (posixRelUnder(root, realMain, path) ?? path.basename(realMain))
: undefined;
const dockerfile = generateDockerfile(props, bundled.files.length > 1, install, entryRel);
const extraFiles = yield* hashExtraFiles(props.extraFiles);
const codeHash = (yield* sha256Object({
bundleHash: bundled.hash,
dockerfile,
packageJson,
extraFiles,
extraFilesIncludesNodeModules: true,
})).slice(0, 16);
return { bundled, dockerfile, codeHash, packageJson, entryRel };
});
const imageExists = (imageRef: string) =>
docker.image.inspect(imageRef).pipe(
Effect.map(() => true),
Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(false)),
);
const pushBackoff = Schedule.exponential("2 seconds");
/**
* Bundle `main`, content-hash the image, build it when missing, and
* push to `registry.fly.io/{appName}:{logicalId}-{hash}` using an
* app deploy token. When `previousHash` matches, skip build and push.
*
* Fly's registry is app-scoped (`/v2/{app}/...`). A nested
* `{app}/{image}` repository 404s on blob upload.
*/
const resolveImage = Effect.fn(function* (input: {
id: string;
appName: string;
props: HostedProgramProps;
previousHash?: string;
session?: { note: (message: string) => Effect.Effect<void> };
}) {
const note = input.session?.note ?? ((_message: string) => Effect.void);
yield* note(`Bundling ${input.id} program...`);
const { bundled, dockerfile, codeHash, packageJson } = yield* computeCodeHash(input.props);
yield* note(`Hashed ${input.id} (${codeHash})`);
const repo = sanitizeImageRepo(input.id);
const imageRef = `${FLY_REGISTRY}/${input.appName}:${repo}-${codeHash}`;
if (input.previousHash === codeHash) {
return { imageRef, codeHash };
}
const minted = yield* machines.createAppDeployToken({ app_name: input.appName });
const token =
minted.token === undefined || Redacted.isRedacted(minted.token)
? minted.token
: Redacted.make(minted.token);
if (token === undefined || Redacted.value(token).length === 0) {
return yield* new DeployTokenMissing({ appName: input.appName });
}
const registry = { server: FLY_REGISTRY, username: "x", password: token };
const materialize = Effect.gen(function* () {
const realMain = yield* resolveMainPath(input.props.main);
const contextDir = yield* getStableContextDir(realMain, dotAlchemy, `${input.id}-image`);
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const files =
input.props.isExternal === true
? packageJson !== undefined
? [{ path: "package.json", content: new TextEncoder().encode(packageJson) }]
: []
: [
...bundled.files.map((file, index) => ({
path: index === 0 ? "index.mjs" : file.path,
content: file.content,
})),
...(packageJson !== undefined
? [{ path: "package.json", content: new TextEncoder().encode(packageJson) }]
: []),
];
yield* docker.materialize({ context: contextDir, dockerfile, files });
yield* copyExtraFiles(contextDir, input.props.extraFiles);
if (input.props.isExternal === true) {
const extras = (input.props.extraFiles ?? []).map((file) => ({
source: file.source,
dest: file.dest,
}));
const root = contextRootOf(realMain, extras, path, (source) =>
resolveExtraSource(source, path),
);
const entryRel = posixRelUnder(root, realMain, path) ?? path.basename(realMain);
const dest = path.join(contextDir, entryRel);
if (!(yield* fs.exists(dest).pipe(Effect.orElseSucceed(() => false)))) {
yield* fs.makeDirectory(path.dirname(dest), { recursive: true });
yield* fs.copy(realMain, dest, { overwrite: true });
}
}
return contextDir;
});
if (input.props.build?.remote !== false) {
const contextDir = yield* materialize;
yield* note(`Building ${imageRef} on a Fly remote builder...`);
yield* buildOnRemoteBuilder({
docker,
appName: input.appName,
contextDir,
imageRef,
platform: MACHINE_PLATFORM,
registry,
note,
});
yield* note(`Pushed ${imageRef}`);
return { imageRef, codeHash };
}
if (!(yield* imageExists(imageRef))) {
const contextDir = yield* materialize;
yield* note(`Building container image ${imageRef}...`);
yield* docker.image.build({ context: contextDir, tag: imageRef, platform: MACHINE_PLATFORM });
yield* note(`Built ${imageRef}`);
}
yield* note(`Pushing ${imageRef}...`);
yield* docker.image
.push(imageRef, registry)
.pipe(Effect.retry({ times: 3, schedule: pushBackoff }));
yield* note(`Pushed ${imageRef}`);
return { imageRef, codeHash };
});
const hash = Effect.fn(function* (props: HostedProgramProps) {
const { codeHash } = yield* computeCodeHash(props);
return codeHash;
});
return { alchemyEnv, bundleProgram, computeCodeHash, resolveImage, hash };
};
/**
* Bundle a Sprite program the same way {@link createFlyHostedSupport}
* bundles a Service — rolldown + Node bootstrap — without building a
* Docker image. The provider writes the files onto the Sprite.
*/
export const createSpriteHostedSupport = ({
stackName,
stage,
virtualEntryPlugin,
}: {
stackName: string;
stage: string;
virtualEntryPlugin: (content: (importPath: string) => string) => rolldown.Plugin;
}) => {
const alchemyEnv = {
ALCHEMY_STACK_NAME: stackName,
ALCHEMY_STAGE: stage,
ALCHEMY_PHASE: "runtime",
HOST: "0.0.0.0",
};
const bundleProgram = Effect.fn(function* (props: HostedProgramProps) {
const handler = props.handler ?? "default";
const realMain = yield* resolveMainPath(props.main);
const cwd = yield* findCwdForBundle(realMain);
const bootstrap = makeBunBootstrap(handler);
const buildBundle = Effect.fn(function* (
entry: string,
plugins?: rolldown.RolldownPluginOption,
) {
return yield* Bundle.build(
{
...props.build?.input,
input: entry,
cwd,
platform: "node",
external: [
"bun",
"bun:*",
...((props.build?.input?.external as string[] | undefined) ?? []),
],
resolve: {
conditionNames: [...Bundle.NODE_CONDITION_NAMES],
...props.build?.input?.resolve,
},
plugins: [props.build?.input?.plugins, plugins],
},
{
...props.build?.output,
format: "esm",
sourcemap: props.build?.output?.sourcemap ?? false,
minify: props.build?.output?.minify ?? false,
entryFileNames: "index.mjs",
},
props.build,
);
});
const bundleOutput = props.isExternal
? yield* buildBundle(realMain)
: yield* buildBundle(realMain, virtualEntryPlugin(bootstrap));
const files = bundleOutput.files.map((file) => ({
path: file.path,
content:
typeof file.content === "string" ? new TextEncoder().encode(file.content) : file.content,
}));
return { files, hash: bundleOutput.hash };
});
const hash = Effect.fn(function* (props: HostedProgramProps) {
const bundled = yield* bundleProgram(props);
return (yield* sha256Object({ bundleHash: bundled.hash })).slice(0, 16);
});
return { alchemyEnv, bundleProgram, hash };
};