import { createHash } from "node:crypto";
import { Query, type UnwrapPlan } from "@distilled.cloud/core/query";
import {
Railway,
type Service as RailwayService,
type ServiceCreateInput,
type ServiceInstance as RailwayServiceInstance,
type ServiceInstanceUpdateInput,
type VariableUpsertInput,
} from "@distilled.cloud/railway";
import { Unowned } from "alchemy/AdoptPolicy";
import * as Bundle from "alchemy/Bundle/Bundle";
import { isResolved, stripEffects } from "alchemy/Diff";
import type { InputProps } from "alchemy/Input";
import { Platform, type Main, type MainRpc, type PlatformProps } from "alchemy/Platform";
import * as Provider from "alchemy/Provider";
import type { Resource } from "alchemy/Resource";
import type { ServerHost } from "alchemy/Runtime/Process";
import { Stack } from "alchemy/Stack";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import type * as Redacted from "effect/Redacted";
import * as Schedule from "effect/Schedule";
import type * as Types from "effect/Types";
import {
environmentServiceInstances,
waitUntilDeleted,
projectServices as fetchProjectServices,
} from "./GraphQL.ts";
import {
collectBindingState,
createRailwayFunctionSupport,
createRailwayFunctionRuntimeContext,
DEFAULT_PORT,
plainEnvValue,
toEnvRecord,
type HostedProgramProps,
type RailwayBuildOptions,
type RailwayHostRuntimeContext,
} from "./hosted.ts";
import { createRailwayName, matchesAlchemyPhysicalName } from "./Metadata.ts";
import { assertHostDisk, type MountSpec, type ServiceBinding } from "./MountVolume.ts";
import { ownedProjects, projectEnvironmentIds, type Project } from "./Project.ts";
import type { Providers } from "./Providers.ts";
import { mintRpcToken, RPC_TOKEN_ENV } from "./rpc-token.ts";
import { ensureServiceDomain, type ServiceDomainRecord } from "./ServiceDomain.ts";
import { readServiceRegion, syncServiceRegion } from "./ServiceRegion.ts";
import { attachVolumeToService } from "./Volume.ts";
const serviceFields = <E>(service: Query<RailwayService, E>) => ({
id: service.id,
name: service.name,
deletedAt: service.deletedAt,
});
type CloudService = UnwrapPlan<ReturnType<typeof serviceFields>>;
const attributeInstanceFields = <E>(instance: Query<RailwayServiceInstance, E>) => ({
source: instance.source.pipe(Query.map((s) => ({ image: s.image }))),
region: instance.region,
numReplicas: instance.numReplicas,
sleepApplication: instance.sleepApplication,
latestDeployment: instance.latestDeployment.pipe(
Query.map((d) => ({ id: d.id, status: d.status })),
),
cronSchedule: instance.cronSchedule,
nextCronRunAt: instance.nextCronRunAt,
});
const instanceFields = <E>(instance: Query<RailwayServiceInstance, E>) => ({
...attributeInstanceFields(instance),
deletedAt: instance.deletedAt,
startCommand: instance.startCommand,
});
type AttributeInstance = UnwrapPlan<ReturnType<typeof attributeInstanceFields>>;
type ServiceInstanceResponse = UnwrapPlan<ReturnType<typeof instanceFields>>;
export { FunctionBundleNotSingleFile } from "./hosted.ts";
export type { InferEnv } from "./InferEnv.ts";
/**
* A resource-valued prop: the resource itself, or an Effect that produces
* it (so `yield* Project(...)` and `Project(...)` both type-check).
*/
type Ref<T> = T | Effect.Effect<T, never, Providers>;
/**
* Environment identity a Function is deployed into. Accepts a
* `Railway.Project` (its primary environment), a `Railway.Environment`,
* or an `{ environmentId }` stub.
*/
export type FunctionEnvironment = { readonly environmentId: string };
/** Canvas Functions run on the Bun function runtime. */
export const FUNCTION_RUNTIME_NAME = "bun" as const;
/** Start-command prefix the Bun function runtime uses to decode source. */
export const FUNCTION_START_PREFIX = "./run.sh ";
/**
* Canvas Functions are capped at 96KB (the encoded start command, which
* includes `./run.sh ` plus standard base64 of the TypeScript file).
*/
export const FUNCTION_MAX_BYTES = 96 * 1024;
/**
* Railway function-runtime images (`ghcr.io/railwayapp/function-*`).
* Canvas Functions are ordinary Services whose `source.image` uses this
* prefix — the same check the Railway CLI uses.
*/
export const isFunctionImage = (image: string | null | undefined): boolean =>
image != null && image.startsWith("ghcr.io/railwayapp/function");
export interface FunctionProps<
Env extends Record<string, any> = Record<string, any>,
> extends PlatformProps {
/**
* Parent Railway Project. Accepts a `Railway.Project` or an Effect
* that produces one. Changing the Project replaces the Function.
*/
project: Ref<Project>;
/**
* Environment to deploy the function instance into. Accepts a
* `Railway.Project` (primary environment), a `Railway.Environment`, or
* `{ environmentId }`. Defaults to the project's primary environment.
* Changing it replaces the Function.
*/
environment?: Ref<FunctionEnvironment>;
/**
* Service name. Unique per Project. If omitted, a unique name is
* generated from the stack, stage and logical ID. Changing it updates
* in place via `serviceUpdate`.
*/
name?: string;
/**
* Module entrypoint bundled with rolldown into a **single file** and
* deployed as a canvas Function. Typically `import.meta.url`. No
* Docker. No registry — that is {@link Service}. Mutually exclusive
* with {@link source} / {@link path}.
*/
main?: string;
/**
* Named export to load from {@link main}.
*
* @default "default"
*/
handler?: string;
/**
* Bundler configuration for {@link main}: rolldown `input`/`output`
* overrides, plus `install` for packages Railway should `bun install`
* from the function's imports (`pg`).
*/
build?: RailwayBuildOptions;
/**
* Inline TypeScript source (one file). Mutually preferred over
* {@link path}. Max 96KB once base64-encoded into the start command.
*/
source?: string;
/**
* Path to a single TypeScript file (`railway functions new --path`).
* Read at plan/reconcile time. Distinct from Effect-native
* {@link main}, which bundles first, and from `Service({ main })`,
* which pushes a Docker image.
*/
path?: string;
/**
* Cron expression (`cronSchedule`). Observed as `cronSchedule` /
* `nextCronRunAt`. `railway functions new --cron`.
*/
cronSchedule?: string;
/**
* Create a generated `*.up.railway.app` domain (`--http`). Defaults
* to `true` when {@link cronSchedule} is omitted, `false` otherwise.
*/
http?: boolean;
/**
* Sleep the application when idle (`--serverless` /
* `sleepApplication`). Updates in place.
*/
sleepApplication?: boolean;
/**
* Region the function runs in (`us-west2`, `europe-west4-drams3a`, …).
* Railway places replicas with `deploy.multiRegionConfig`. Omit this
* and the current placement is left alone (the workspace default on
* first create). Updating it moves the replicas in place and keeps
* the current replica count.
*/
region?: string;
/**
* Port published on the generated service domain. Passed as
* `serviceDomainCreate.targetPort`. Omit to let Railway detect it.
*/
port?: number;
/**
* Additional environment variables. Merged after binding-injected
* `env`. Upserted as service-scoped Railway variables with
* `skipDeploys: true`; this Function owns the subsequent deploy.
*
* On an async Function, {@link InferEnv} types the handler's second
* argument from these keys. Railway has no native bindings — every
* value is a `string` at runtime (`process.env`).
*/
env?: Env;
/**
* Private-mesh RPC token. Minted by a child `Alchemy.Random`
* (`{logicalId}RpcToken`) and persisted in state. Set automatically.
*/
rpcToken?: Redacted.Redacted<string>;
}
export type Function<Env extends Record<string, any> = Record<string, any>> = Resource<
"Railway.Function",
FunctionProps<Env>,
{
/** Railway service id. */
serviceId: string;
/** Physical service name (unique per project). */
name: string;
/** Parent Railway project id. */
projectId: string;
/** Environment the instance is deployed in. */
environmentId: string;
/** Observed function-runtime image. */
image: string;
/** Function runtime name (`bun`). */
runtime: typeof FUNCTION_RUNTIME_NAME;
/** Observed cron schedule, if set. */
cronSchedule: string | undefined;
/** Observed `sleepApplication`. */
sleepApplication: boolean | undefined;
/**
* Region the function is placed in. Set when
* `deploy.multiRegionConfig` has replicas in exactly one region.
*/
region: string | undefined;
/** Port published on the generated service domain. */
port: number | undefined;
/**
* Internal DNS name on the default private mesh
* (`{name}.railway.internal`). Derived from the service name.
*/
dnsName: string;
/**
* Shared token for private schemaless RPC. Value of the child
* `Alchemy.Random` resource. Packed onto callers by
* {@link bindFunction}; never send this to the public internet.
*/
rpcToken: string;
/** Public `https://{domain}` URL (`*.up.railway.app`). */
url: string | undefined;
/** Generated Railway service domain hostname. */
domain: string | undefined;
/** Railway service domain id. */
domainId: string | undefined;
/** Latest deployment id, if one exists. */
deploymentId: string | undefined;
/** Latest deployment status (`SUCCESS`, `DEPLOYING`, …). */
deploymentStatus: string | undefined;
/** Next cron fire time, if scheduled. */
nextCronRunAt: string | undefined;
/** Content hash of the TypeScript source. */
code: { hash: string };
},
ServiceBinding,
Providers
>;
export const isFunction = (value: unknown): value is Function =>
typeof value === "object" &&
value !== null &&
(value as { Type?: string }).Type === "Railway.Function";
export type FunctionServices = ServerHost;
export type FunctionShape = Main<FunctionServices> & MainRpc<FunctionServices>;
export type FunctionRuntimeContext = RailwayHostRuntimeContext;
const resolveFunctionProps = (
id: string,
props: FunctionProps | Effect.Effect<FunctionProps, never, Providers>,
) =>
Effect.gen(function* () {
const resolved = Effect.isEffect(props) ? yield* props : props;
if (globalThis.__ALCHEMY_RUNTIME__) return resolved;
const project = Effect.isEffect(resolved.project)
? yield* resolved.project as Effect.Effect<Project, never, Providers>
: resolved.project;
const environment =
resolved.environment === undefined
? undefined
: Effect.isEffect(resolved.environment)
? yield* resolved.environment as Effect.Effect<FunctionEnvironment, never, Providers>
: resolved.environment;
const rpcToken = yield* mintRpcToken(id);
return { ...resolved, project, environment, rpcToken };
});
/**
* A Railway.Function is a **single TypeScript file** on Railway's Bun
* canvas runtime. No GitHub repo. No Docker. No registry. Alchemy
* queries `functionRuntime(bun)`, creates the Service with that image,
* and writes the source as `startCommand` (`./run.sh` + base64).
*
* There are two ways to define a Function. Prefer **async** (`main` +
* `export default { fetch }`, no Effect) — Effect-native canvas
* Functions pull the Effect runtime into the 96KB encoded start-command
* cap and fail {@link FunctionTooLarge} for anything non-trivial. Use
* {@link Service} when you need an Effect program or a real image.
*
* Distinct from Effect-native {@link Service} (`main`), which bundles
* with Rolldown and uploads a generated Dockerfile for Railway to
* build.
*
* @see https://docs.railway.com/reference/functions
*
* ### Async Functions
* You don't have to use Effect. Declare the Function with `main`
* pointing at a file and **no** `Effect.gen` implementation — Alchemy
* bundles that file as-is (no Effect runtime) and deploys it as a
* canvas Function. The handler is a plain `async fetch`. Use the `env`
* prop to declare variables, and {@link InferEnv} to type the second
* argument (Railway bindings are environment variables).
*
* **Example:** Defining an async Function in your stack
* ```typescript
* const db = yield* Railway.Postgres("Db", { project: site });
*
* export const Ping = Railway.Function("Ping", {
* project: site,
* main: "./src/ping.ts",
* env: { DATABASE_URL: db.connectionUri },
* });
*
* export type PingEnv = Railway.InferEnv<typeof Ping>;
* ```
*
* **Example:** Writing the async handler
* ```typescript
* import type { PingEnv } from "../alchemy.run.ts";
*
* export default {
* async fetch(_request: Request, env: PingEnv) {
* return new Response(env.DATABASE_URL ? "ok" : "missing");
* },
* };
* ```
*
* ### Effect-native Function
* A Function is a class. Props describe the canvas Function. The Effect
* is the program that runs in it. `main: import.meta.url` is the bundle
* entrypoint — Alchemy bundles this file into one JS file and deploys
* it. No `registry`. Stay tiny: the encoded start command maxes out at
* 96KB (`effect` plus handlers overflows it).
*
* **Example:** Class + Project + main
* ```typescript
* export default class Ping extends Railway.Function<Ping>()(
* "Ping",
* {
* project: Site,
* main: import.meta.url,
* },
* Effect.gen(function* () {
* return {
* fetch: Effect.succeed(HttpServerResponse.text("ok")),
* };
* }),
* ) {}
* ```
*
* :::caution[Changing `project` replaces the Function]
* The Function is created in the new Project. The old Function is deleted.
* :::
*
* ### Inline source
* Pass inline `source` (or `path` to a `.ts` file) instead of `main`
* when the Function is not an Effect class. Alchemy generates a
* `*.up.railway.app` domain unless `http: false` or a cron schedule is
* set.
*
* **Example:** Inline source
* ```typescript
* const site = yield* Railway.Project("Site");
* const ping = yield* Railway.Function("Ping", {
* project: site,
* source: `
* Bun.serve({
* hostname: "0.0.0.0",
* port: Number(process.env.PORT ?? 3000),
* fetch() { return new Response("ok"); },
* });
* `,
* });
* ```
*
* ### File path
* `path` is the CLI `--path` equivalent. The file is read at
* plan/reconcile. Content changes update in place.
*
* **Example:** Path
* ```typescript
* const ping = yield* Railway.Function("Ping", {
* project: site,
* path: "./fn.ts",
* });
* ```
*
* ### Cron
* `cronSchedule` runs the Function on a cron expression (`--cron`).
* HTTP domains are skipped unless `http: true` is set explicitly.
*
* **Example:** Cron schedule
* ```typescript
* const job = yield* Railway.Function("Cleanup", {
* project: site,
* source: `console.log("tick");`,
* cronSchedule: "0 * * * *",
* });
* ```
*
* ### Serverless
* `sleepApplication` sleeps the Function when idle (`--serverless`).
*
* **Example:** Sleep when idle
* ```typescript
* const ping = yield* Railway.Function("Ping", {
* project: site,
* source: `console.log("hi");`,
* http: false,
* sleepApplication: true,
* });
* ```
*
* ### Schemaless RPC
* Return methods next to `fetch`. Call `enableRailwayRpc()` in init
* (canvas Functions are capped at 96KB; the dispatcher is opt-in).
* Another Function or Service binds this class and calls them over
* `{name}.railway.internal` with a shared token. Public
* `*.up.railway.app` requests to `/__rpc__/*` get 401.
*
* **Example:** Bind a Function
* ```typescript
* export default class Query extends Railway.Function<Query>()(
* "Query",
* { project: Site, main: import.meta.url },
* Effect.gen(function* () {
* Railway.enableRailwayRpc();
* return {
* greet: (name: string) => Effect.succeed(`hello ${name}`),
* };
* }),
* ) {}
*
* export default class Api extends Railway.Service<Api>()(
* "Api",
* { project: Site, main: import.meta.url },
* Effect.gen(function* () {
* const query = yield* Railway.bindFunction(Query);
* return {
* fetch: query
* .greet("sam")
* .pipe(Effect.map((greeting) => HttpServerResponse.text(greeting))),
* };
* }),
* ) {}
* ```
*
* ### Module-scope declarations
* Resource-valued props accept the resource or an Effect producing it.
*
* **Example:** Module-scope Function
* ```typescript
* // src/ping.ts
* import * as Railway from "@alchemy.run/railway";
*
* export const Site = Railway.Project("Site");
* export const Ping = Railway.Function("Ping", {
* project: Site,
* source: `console.log("hello");`,
* http: false,
* });
* ```
*
* @resource
* @product Function
*/
export const Function: Platform<
Function,
FunctionServices,
FunctionShape,
FunctionRuntimeContext
> & {
/**
* Async (no-impl) constructor — captures the `env` literal so
* {@link InferEnv} types the handler's second argument.
*/
<const Env extends Record<string, any>, PropsReq = never>(
id: string,
props:
| InputProps<FunctionProps<Env>>
| Effect.Effect<InputProps<FunctionProps<Env>>, never, PropsReq>,
): Effect.Effect<Function<Env>, never, Providers | PropsReq>;
} = Platform("Railway.Function", {
createRuntimeContext: createRailwayFunctionRuntimeContext("Railway.Function"),
transformProps: (id, props) => resolveFunctionProps(id, props),
});
export class FunctionNotCreated extends Data.TaggedError("Railway.FunctionNotCreated")<{
resourceName: string;
projectId: string;
}> {}
export class FunctionProjectRequired extends Data.TaggedError("Railway.FunctionProjectRequired")<{
message: string;
}> {}
export class FunctionSourceRequired extends Data.TaggedError("Railway.FunctionSourceRequired")<{
message: string;
}> {}
export class FunctionTooLarge extends Data.TaggedError("Railway.FunctionTooLarge")<{
bytes: number;
maxBytes: number;
}> {
get message() {
return `canvas Function is ${this.bytes} bytes (max ${this.maxBytes})`;
}
}
export class FunctionRuntimeImageMissing extends Data.TaggedError(
"Railway.FunctionRuntimeImageMissing",
)<{ message: string }> {}
export class FunctionDeployFailed extends Data.TaggedError("Railway.FunctionDeployFailed")<{
serviceId: string;
status: string;
deploymentId: string | undefined;
logs: string;
}> {
override get message() {
return this.logs.length > 0
? `Function deploy ${this.status}: ${this.logs}`
: `Function deploy ${this.status}`;
}
}
class FunctionPending extends Data.TaggedError("Railway.FunctionPending")<{
serviceId: string;
status: string;
}> {}
class FunctionDeployPending extends Data.TaggedError("Railway.FunctionDeployPending")<{
serviceId: string;
status: string;
}> {}
const projectIdOf = (value: unknown): string | undefined => {
if (value === null || typeof value !== "object") return undefined;
const rec = value as { projectId?: unknown };
return typeof rec.projectId === "string" && rec.projectId.length > 0 ? rec.projectId : undefined;
};
const environmentIdOf = (value: unknown): string | undefined => {
if (value === null || typeof value !== "object") return undefined;
const rec = value as { environmentId?: unknown };
return typeof rec.environmentId === "string" && rec.environmentId.length > 0
? rec.environmentId
: undefined;
};
const isGoneService = (service: CloudService | undefined) =>
service === undefined || service.deletedAt != null;
const isGoneInstance = (instance: ServiceInstanceResponse | undefined) =>
instance === undefined || instance.deletedAt != null;
const resolveName = (id: string, name: string | undefined, existing?: string) =>
Effect.gen(function* () {
if (name !== undefined) return name;
if (existing !== undefined) return existing;
return yield* createRailwayName(id);
});
const wantsHttp = (props: FunctionProps) =>
props.http === true || (props.http !== false && props.cronSchedule === undefined);
const hashSource = (source: string) =>
Effect.sync(() => createHash("sha256").update(source).digest("hex"));
const startCommandOf = (source: string) =>
Effect.gen(function* () {
const encoded = yield* Effect.sync(() => Buffer.from(source, "utf8").toString("base64"));
const cmd = `${FUNCTION_START_PREFIX}${encoded}`;
if (cmd.length > FUNCTION_MAX_BYTES) {
return yield* new FunctionTooLarge({ bytes: cmd.length, maxBytes: FUNCTION_MAX_BYTES });
}
return cmd;
});
const resolveSource = (props: FunctionProps) =>
Effect.gen(function* () {
if (props.source !== undefined && props.source.length > 0) {
return props.source;
}
if (props.path !== undefined && props.path.length > 0) {
const fs = yield* FileSystem.FileSystem;
return yield* fs.readFileString(props.path);
}
return yield* new FunctionSourceRequired({
message:
"Railway.Function requires `source` (inline TypeScript), `path` to a single file, or `main` (Effect-native).",
});
});
const readRuntimeImage = Query.fn(() => ({
image: Railway.functionRuntime({ name: FUNCTION_RUNTIME_NAME }).latestVersion.image,
}));
const latestRuntimeImage = () =>
readRuntimeImage().pipe(
Effect.flatMap(({ image }) => {
if (image.length === 0) {
return new FunctionRuntimeImageMissing({
message: "functionRuntime(bun) returned an empty latestVersion.image",
});
}
return Effect.succeed(image);
}),
);
const sameImage = (observed: string | null | undefined, desired: string) => {
if (observed == null || observed.length === 0) return false;
if (observed === desired) return true;
if (observed === `${desired}:latest` || desired === `${observed}:latest`) {
return true;
}
return observed.endsWith(`/${desired}`) || observed.endsWith(`/${desired}:latest`);
};
const deployReady = (status: string | undefined) => status === "SUCCESS" || status === "SLEEPING";
const deployFailed = (status: string | undefined) =>
status === "FAILED" || status === "CRASHED" || status === "REMOVED";
const readService = Query.fn((id: string) => serviceFields(Railway.service({ id })));
const getById = (serviceId: string) =>
readService(serviceId).pipe(
Effect.map((service) => (isGoneService(service) ? undefined : service)),
Effect.catchTag("RailwayNotFound", () => Effect.undefined),
);
const readInstance = Query.fn((environmentId: string, serviceId: string) =>
instanceFields(Railway.serviceInstance({ environmentId, serviceId })),
);
const getInstance = (environmentId: string, serviceId: string) =>
readInstance(environmentId, serviceId).pipe(
Effect.map((instance) => (isGoneInstance(instance) ? undefined : instance)),
Effect.catchTag("RailwayNotFound", () => Effect.undefined),
);
const listProjectServices = (projectId: string) =>
fetchProjectServices(projectId, serviceFields).pipe(
Effect.map((services) => services.filter((node) => !isGoneService(node))),
Effect.catchTag("RailwayNotFound", () => Effect.succeed([] as CloudService[])),
);
const findByName = (projectId: string, name: string) =>
listProjectServices(projectId).pipe(
Effect.map((services) => services.find((service) => service.name === name)),
);
const waitForInstance = (environmentId: string, serviceId: string) =>
getInstance(environmentId, serviceId).pipe(
Effect.flatMap((instance) => {
if (instance === undefined) {
return Effect.fail(new FunctionPending({ serviceId, status: "creating" }));
}
return Effect.succeed(instance);
}),
Effect.retry({
while: (e) => e._tag === "Railway.FunctionPending",
times: 10,
schedule: Schedule.spaced("2 seconds"),
}),
Effect.catchTag("Railway.FunctionPending", () => getInstance(environmentId, serviceId)),
);
const readDeployLogs = Query.fn((deploymentId: string) =>
Railway.deploymentLogs({ deploymentId, limit: 80 }).pipe(
Query.map((row) => ({ severity: row.severity, message: row.message })),
),
);
const fetchDeployLogs = (deploymentId: string | undefined) =>
deploymentId === undefined || deploymentId.length === 0
? Effect.succeed("")
: readDeployLogs(deploymentId).pipe(
Effect.map((rows) =>
rows
.map((row) => (row.severity != null ? `[${row.severity}] ${row.message}` : row.message))
.join("\n"),
),
Effect.orElseSucceed(() => ""),
);
const waitForDeployment = (environmentId: string, serviceId: string) =>
Effect.gen(function* () {
const instance = yield* getInstance(environmentId, serviceId);
const latest = instance?.latestDeployment;
const status = latest?.status;
if (status !== undefined && deployFailed(status)) {
const logs = yield* fetchDeployLogs(latest?.id);
return yield* new FunctionDeployFailed({ serviceId, status, deploymentId: latest?.id, logs });
}
if (instance !== undefined && deployReady(status)) {
return instance;
}
return yield* new FunctionDeployPending({ serviceId, status: status ?? "pending" });
}).pipe(
Effect.retry({
while: (e) => e._tag === "Railway.FunctionDeployPending",
// Queued builds under full-suite load can exceed 3 minutes — allow ~8.
times: 10,
schedule: Schedule.spaced("5 seconds"),
}),
);
const asVariableMap = (value: unknown): Record<string, string> => {
if (value === null || typeof value !== "object" || Array.isArray(value)) {
return {};
}
const out: Record<string, string> = {};
for (const [key, item] of Object.entries(value)) {
if (typeof item === "string") {
out[key] = item;
}
}
return out;
};
const readVariables = Query.fn((projectId: string, environmentId: string, serviceId: string) =>
Railway.variables({ projectId, environmentId, serviceId, unrendered: true }),
);
const variableUpsert = Query.fn((input: VariableUpsertInput) => Railway.variableUpsert({ input }));
const listVariableMap = (projectId: string, environmentId: string, serviceId: string) =>
readVariables(projectId, environmentId, serviceId).pipe(
Effect.map(asVariableMap),
Effect.catchTag("RailwayNotFound", () => Effect.succeed({} as Record<string, string>)),
);
const upsertVariable = (input: {
projectId: string;
environmentId: string;
serviceId: string;
name: string;
value: string;
}) =>
variableUpsert({
projectId: input.projectId,
environmentId: input.environmentId,
serviceId: input.serviceId,
name: input.name,
value: input.value,
skipDeploys: true,
});
const serviceCreate = Query.fn((input: ServiceCreateInput) =>
serviceFields(Railway.serviceCreate({ input })),
);
const serviceUpdate = Query.fn((id: string, name: string) =>
serviceFields(Railway.serviceUpdate({ id, input: { name } })),
);
const serviceInstanceUpdate = Query.fn(
(environmentId: string, serviceId: string, input: ServiceInstanceUpdateInput) =>
Railway.serviceInstanceUpdate({ environmentId, serviceId, input }),
);
const serviceInstanceDeploy = Query.fn((environmentId: string, serviceId: string) =>
Railway.serviceInstanceDeployV2({ environmentId, serviceId }),
);
const serviceDelete = Query.fn((id: string) => Railway.serviceDelete({ id }));
const hostedProgramProps = (
props: FunctionProps,
port: number | undefined,
): HostedProgramProps | undefined => {
if (props.main === undefined || props.main.length === 0) return undefined;
return {
main: props.main,
handler: props.handler,
port,
env: props.env,
isExternal: props.isExternal,
build: props.build,
};
};
const syncEnv = Effect.fn(function* (input: {
projectId: string;
environmentId: string;
serviceId: string;
desired: Record<string, string>;
}) {
if (Object.keys(input.desired).length === 0) return false;
const observed = yield* listVariableMap(input.projectId, input.environmentId, input.serviceId);
let changed = false;
for (const [name, value] of Object.entries(input.desired)) {
if (observed[name] !== value) {
yield* upsertVariable({
projectId: input.projectId,
environmentId: input.environmentId,
serviceId: input.serviceId,
name,
value,
});
changed = true;
}
}
return changed;
});
const syncMounts = Effect.fn(function* (input: {
environmentId: string;
projectId: string;
serviceId: string;
mounts: MountSpec[];
}) {
for (const mount of input.mounts) {
yield* attachVolumeToService({
environmentId: input.environmentId,
projectId: input.projectId,
serviceId: input.serviceId,
volumeId: mount.volumeId,
mountPath: mount.path,
});
}
});
const toAttrs = (input: {
service: CloudService;
instance: AttributeInstance | undefined;
domain: ServiceDomainRecord | undefined;
projectId: string;
environmentId: string;
image: string;
port: number | undefined;
codeHash: string;
rpcToken: string;
region: string | undefined;
}): Function["Attributes"] => ({
serviceId: input.service.id,
name: input.service.name,
projectId: input.projectId,
environmentId: input.environmentId,
image: input.instance?.source?.image ?? input.image,
runtime: FUNCTION_RUNTIME_NAME,
cronSchedule: input.instance?.cronSchedule ?? undefined,
sleepApplication: input.instance?.sleepApplication ?? undefined,
region: input.region,
port: input.port ?? input.domain?.targetPort,
dnsName: `${input.service.name}.railway.internal`,
rpcToken: input.rpcToken,
url: input.domain?.url,
domain: input.domain?.domain,
domainId: input.domain?.id,
deploymentId: input.instance?.latestDeployment?.id,
deploymentStatus: input.instance?.latestDeployment?.status,
nextCronRunAt: input.instance?.nextCronRunAt ?? undefined,
code: { hash: input.codeHash },
});
const instanceSettingsDelta = (input: {
instance: ServiceInstanceResponse | undefined;
sourceImage: string;
startCommand: string;
props: FunctionProps;
}): ServiceInstanceUpdateInput | undefined => {
const instance = input.instance;
const delta: Types.Mutable<ServiceInstanceUpdateInput> = {};
let changed = false;
if (!sameImage(instance?.source?.image, input.sourceImage)) {
delta.source = { image: input.sourceImage };
changed = true;
}
if ((instance?.startCommand ?? undefined) !== input.startCommand) {
delta.startCommand = input.startCommand;
changed = true;
}
if (
input.props.cronSchedule !== undefined &&
(instance?.cronSchedule ?? undefined) !== input.props.cronSchedule
) {
delta.cronSchedule = input.props.cronSchedule;
changed = true;
}
if (
input.props.sleepApplication !== undefined &&
instance?.sleepApplication !== input.props.sleepApplication
) {
delta.sleepApplication = input.props.sleepApplication;
changed = true;
}
return changed ? delta : undefined;
};
export const FunctionProvider = () =>
Provider.effect(
Function,
Effect.gen(function* () {
const stack = yield* Stack;
const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
const hosted = createRailwayFunctionSupport({
stackName: stack.name,
stage: stack.stage,
virtualEntryPlugin,
});
return Function.Provider.of({
stables: ["serviceId", "projectId", "environmentId"],
nuke: { dependsOn: ["Railway.Project"] },
diff: Effect.fn(function* ({ news: desired, output }) {
// Runtime exports are covered by the bundle hash, not evaluated
// as infrastructure inputs during planning.
const news = stripEffects(desired);
if (news === undefined || !isResolved(news)) return undefined;
if (output === undefined) return undefined;
const nextProject = projectIdOf(news.project);
const projectChanged = nextProject !== undefined && nextProject !== output.projectId;
const nextEnv = environmentIdOf(news.environment);
const environmentChanged = nextEnv !== undefined && nextEnv !== output.environmentId;
if (projectChanged || environmentChanged) {
return { action: "replace" as const };
}
const program = hostedProgramProps(news, news.port);
if (program !== undefined) {
const hash = yield* hosted.hash(program);
if (hash !== output.code.hash) {
return { action: "update" as const };
}
return undefined;
}
const hasSource =
(news.source !== undefined && news.source.length > 0) ||
(news.path !== undefined && news.path.length > 0);
if (hasSource) {
const source = yield* resolveSource(news);
const hash = yield* hashSource(source);
if (hash !== output.code.hash) {
return { action: "update" as const };
}
}
return undefined;
}),
read: Effect.fn(function* ({ id, olds, output }) {
const projectId =
output?.projectId ?? (olds !== undefined ? projectIdOf(olds.project) : undefined);
const environmentId =
output?.environmentId ??
(olds !== undefined
? (environmentIdOf(olds.environment) ?? environmentIdOf(olds.project))
: undefined);
const name = yield* resolveName(id, olds?.name, output?.name);
const byId =
output?.serviceId !== undefined && output.serviceId.length > 0
? yield* getById(output.serviceId)
: undefined;
const found =
byId ?? (projectId !== undefined ? yield* findByName(projectId, name) : undefined);
if (found === undefined) return undefined;
const resolvedProjectId = projectIdOf(found) ?? projectId ?? "";
const resolvedEnvId =
environmentId ?? environmentIdOf(olds?.project) ?? output?.environmentId ?? "";
const instance =
resolvedEnvId.length > 0 ? yield* getInstance(resolvedEnvId, found.id) : undefined;
const region =
resolvedEnvId.length > 0
? yield* readServiceRegion({
environmentId: resolvedEnvId,
projectId: resolvedProjectId,
serviceId: found.id,
legacy: instance?.region,
})
: undefined;
const attrs = toAttrs({
service: found,
instance,
domain: undefined,
projectId: resolvedProjectId,
environmentId: resolvedEnvId,
image: instance?.source?.image ?? output?.image ?? "",
port: output?.port ?? olds?.port,
codeHash: output?.code.hash ?? "",
rpcToken: output?.rpcToken ?? "",
region,
});
if (output !== undefined) return attrs;
return matchesAlchemyPhysicalName(found.name) ? attrs : Unowned(attrs);
}),
list: Effect.fn(function* () {
const projects = yield* ownedProjects();
const rows = yield* Effect.forEach(projects, (project) =>
Effect.gen(function* () {
const services = new Map(
(yield* listProjectServices(project.projectId))
.filter((service) => matchesAlchemyPhysicalName(service.name))
.map((service) => [service.id, service]),
);
if (services.size === 0) return [];
const envIds = yield* projectEnvironmentIds(project);
const items = yield* Effect.forEach(envIds, (environmentId) =>
environmentServiceInstances(environmentId, project.projectId, (instance) => ({
...attributeInstanceFields(instance),
serviceId: instance.serviceId,
deletedAt: instance.deletedAt,
})).pipe(
Effect.map((instances) =>
instances.flatMap((instance) => {
const service = services.get(instance.serviceId);
const image = instance.source?.image;
if (
instance.deletedAt != null ||
service === undefined ||
!isFunctionImage(image)
)
return [];
return [
toAttrs({
service,
instance,
domain: undefined,
projectId: project.projectId,
environmentId,
image: image ?? "",
port: undefined,
codeHash: "",
rpcToken: "",
region: instance.region ?? undefined,
}),
];
}),
),
),
);
return items.flat();
}),
);
return rows.flat();
}),
// Circular Service↔Function RPC binds `dnsName` / `port` / `rpcToken`.
// Those are knowable from the physical name and props; the cloud
// service is created in reconcile (and re-synced in converge).
precreate: Effect.fn(function* ({ id, news }) {
const name = yield* resolveName(
id,
typeof news.name === "string" ? news.name : undefined,
);
const port = typeof news.port === "number" ? news.port : DEFAULT_PORT;
return {
serviceId: "",
name,
projectId: "",
environmentId: "",
image: "",
runtime: FUNCTION_RUNTIME_NAME,
cronSchedule: undefined,
sleepApplication: undefined,
region: undefined,
port,
dnsName: `${name}.railway.internal`,
rpcToken: plainEnvValue(news.rpcToken) ?? "",
url: undefined,
domain: undefined,
domainId: undefined,
deploymentId: undefined,
deploymentStatus: undefined,
nextCronRunAt: undefined,
code: { hash: "" },
} satisfies Function["Attributes"];
}),
reconcile: Effect.fn(function* ({ id, news, output, bindings }) {
const props = news ?? ({} as FunctionProps);
const projectId = projectIdOf(props.project) ?? output?.projectId;
if (projectId === undefined) {
return yield* new FunctionProjectRequired({
message: "Function requires a resolved Railway.Project",
});
}
const environmentId =
environmentIdOf(props.environment) ??
environmentIdOf(props.project) ??
output?.environmentId;
if (environmentId === undefined) {
return yield* new FunctionProjectRequired({
message:
"Function requires a Railway environment (pass environment or a Project with environmentId)",
});
}
const name = yield* resolveName(id, props.name, output?.name);
const bound = collectBindingState(bindings ?? []);
yield* assertHostDisk({ name, mounts: bound.mounts });
const program = hostedProgramProps(
props,
props.port ?? (props.main !== undefined ? DEFAULT_PORT : undefined),
);
let source: string;
let codeHash: string;
if (program !== undefined) {
const bundled = yield* hosted.bundleToSource(program);
source = bundled.source;
codeHash = bundled.hash;
} else {
source = yield* resolveSource(props);
codeHash = yield* hashSource(source);
}
const startCommand = yield* startCommandOf(source);
const image = yield* latestRuntimeImage();
// Effect-native Functions listen on PORT (canvas default 3000).
// Pin PORT and the generated domain's targetPort together so
// private-mesh RPC and public HTTP hit the same listener.
const port = program !== undefined ? (props.port ?? DEFAULT_PORT) : props.port;
const rpcToken = plainEnvValue(props.rpcToken) ?? output?.rpcToken ?? "";
const env = {
...bound.env,
...(program !== undefined ? hosted.alchemyEnv : {}),
...(port !== undefined ? { PORT: String(port) } : {}),
...toEnvRecord(props.env),
[RPC_TOKEN_ENV]: rpcToken,
};
let current: CloudService | undefined =
output?.serviceId !== undefined && output.serviceId.length > 0
? yield* getById(output.serviceId)
: undefined;
if (current === undefined) {
current = yield* findByName(projectId, name);
}
if (current === undefined) {
const created = yield* serviceCreate({
projectId,
environmentId,
name,
source: { image },
}).pipe(Effect.catchTag("RailwayValidationError", () => Effect.undefined));
current = created ?? (yield* findByName(projectId, name));
}
if (current === undefined || isGoneService(current)) {
return yield* new FunctionNotCreated({ resourceName: name, projectId });
}
if (current.name !== name) {
current = yield* serviceUpdate(current.id, name);
}
// The service instance must exist in this environment before a
// domain can be generated. Extra non-fork environments lag.
let instance = yield* waitForInstance(environmentId, current.id);
// Domain before PORT — Railway refuses serviceDomainCreate on a
// service that already has PORT set ("please try again").
let domain = wantsHttp(props)
? yield* ensureServiceDomain({ projectId, environmentId, serviceId: current.id })
: undefined;
let needsDeploy = false;
const instanceDelta = instanceSettingsDelta({
instance,
sourceImage: image,
startCommand,
props,
});
if (instanceDelta !== undefined) {
yield* serviceInstanceUpdate(environmentId, current.id, instanceDelta);
needsDeploy = true;
instance = (yield* getInstance(environmentId, current.id)) ?? instance;
}
// Pin `deploy.multiRegionConfig` before the build, then again after,
// in case the deploy wrote the workspace default back.
const serviceId = current.id;
const placeRegion = () =>
syncServiceRegion({
environmentId,
projectId,
serviceId,
region: props.region,
legacy: instance?.region,
fallbackReplicas: instance?.numReplicas,
});
let region = yield* placeRegion();
const envChanged = yield* syncEnv({
projectId,
environmentId,
serviceId: current.id,
desired: env,
});
if (envChanged) needsDeploy = true;
if (wantsHttp(props) && port !== undefined) {
domain = yield* ensureServiceDomain({
projectId,
environmentId,
serviceId: current.id,
targetPort: port,
});
}
yield* syncMounts({
environmentId,
projectId,
serviceId: current.id,
mounts: bound.mounts,
});
if (needsDeploy || instance?.latestDeployment == null) {
yield* serviceInstanceDeploy(environmentId, current.id).pipe(
Effect.catchTag("RailwayValidationError", () => Effect.void),
);
}
// Cron-only Functions sleep until the schedule. Waiting for
// SUCCESS queues behind sibling Docker builds and can sit in
// QUEUED/BUILDING for the full retry budget. HTTP Functions
// still wait — they have a public URL to serve.
if (wantsHttp(props)) {
instance = (yield* waitForDeployment(environmentId, current.id)) ?? instance;
} else {
instance = (yield* getInstance(environmentId, current.id)) ?? instance;
const status = instance?.latestDeployment?.status;
if (status !== undefined && deployFailed(status)) {
const logs = yield* fetchDeployLogs(instance?.latestDeployment?.id);
return yield* new FunctionDeployFailed({
serviceId: current.id,
status,
deploymentId: instance?.latestDeployment?.id,
logs,
});
}
}
region = yield* placeRegion();
return toAttrs({
service: current,
instance,
domain,
projectId,
environmentId,
image,
port,
codeHash,
rpcToken,
region,
});
}),
delete: Effect.fn(function* ({ output }) {
const serviceId = output.serviceId;
if (serviceId.length === 0) return;
yield* serviceDelete(serviceId).pipe(
Effect.catchTag("RailwayNotFound", () => Effect.void),
);
yield* waitUntilDeleted(
"Service",
serviceId,
getById(serviceId).pipe(Effect.map((service) => service === undefined)),
);
}),
});
}),
);