alchemy 2.0.0-beta.74 → 2.0.0-beta.76

package/src/Railway/HeadObject.ts

@@ -0,0 +1,46 @@
+import type * as S3 from "@distilled.cloud/aws/s3";
+import type * as Config from "effect/Config";
+import type * as Effect from "effect/Effect";
+import * as Binding from "../Binding.ts";
+import type { RuntimeContext } from "../RuntimeContext.ts";
+import type { Bucket } from "./Bucket.ts";
+import type { RailwayS3CredentialsMissing } from "./BucketBinding.ts";
+
+export interface HeadObjectRequest extends Omit<
+  S3.HeadObjectRequest,
+  "Bucket"
+> {}
+
+/**
+ * Runtime binding for Railway `HeadObject` over the S3 API.
+ *
+ * Bind this operation to a {@link Bucket} in Service init. Provide
+ * {@link HeadObjectHttp}.
+ *
+ *
+ * ### Inspecting Objects
+ * **Example:** Check an Object's Metadata
+ * ```typescript
+ * const headObject = yield* Railway.HeadObject(Data);
+ * const head = yield* headObject({ Key: "hello.txt" });
+ * ```
+ *
+ * @binding
+ */
+export interface HeadObject extends Binding.Service<
+  HeadObject,
+  "Railway.HeadObject",
+  (
+    bucket: Bucket,
+  ) => Effect.Effect<
+    (
+      request?: HeadObjectRequest,
+    ) => Effect.Effect<
+      S3.HeadObjectOutput,
+      S3.HeadObjectError | Config.ConfigError | RailwayS3CredentialsMissing,
+      RuntimeContext
+    >
+  >
+> {}
+
+export const HeadObject = Binding.Service<HeadObject>("Railway.HeadObject");

package/src/Railway/HeadObjectHttp.ts

@@ -0,0 +1,19 @@
+import * as S3 from "@distilled.cloud/aws/s3";
+import * as Layer from "effect/Layer";
+import { makeRailwayS3Binding } from "./BucketBinding.ts";
+import { HeadObject } from "./HeadObject.ts";
+
+/**
+ * HTTP implementation of {@link HeadObject}. Calls distilled S3
+ * `headObject` against the Railway endpoint with the bucket's credentials.
+ *
+ * @layer
+ * @provides Railway.HeadObject
+ */
+export const HeadObjectHttp = Layer.effect(
+  HeadObject,
+  makeRailwayS3Binding({
+    tag: "Railway.HeadObject",
+    operation: S3.headObject,
+  }),
+);

package/src/Railway/InferEnv.ts

@@ -0,0 +1,32 @@
+import type * as Effect from "effect/Effect";
+
+/**
+ * Typed `env` for an async (non-Effect) {@link Function}. Railway
+ * bindings are environment variables, so every entry is a `string` —
+ * the same object the handler receives as its second argument
+ * (`process.env` keys declared on `env`).
+ *
+ * Analogous to `Cloudflare.InferEnv`, which maps env entries onto native
+ * Worker bindings. Railway has only env vars, so the mapping is 1:1 to
+ * `string`.
+ *
+ * @example
+ * ```typescript
+ * export const Ping = Railway.Function("Ping", {
+ *   project: Site,
+ *   main: "./src/ping.ts",
+ *   env: { DATABASE_URL: db.connectionUri },
+ * });
+ * export type PingEnv = Railway.InferEnv<typeof Ping>;
+ * ```
+ */
+export type InferEnv<F> =
+  F extends Effect.Effect<infer A, infer _E, infer _R>
+    ? InferEnv<A>
+    : F extends { readonly Props: { readonly env?: infer E } }
+      ? InferEnvRecord<Exclude<E, undefined>>
+      : InferEnvRecord<F>;
+
+type InferEnvRecord<E> = {
+  readonly [K in keyof E]: string;
+};

package/src/Railway/ListObjectsV2.ts

@@ -0,0 +1,48 @@
+import type * as S3 from "@distilled.cloud/aws/s3";
+import type * as Config from "effect/Config";
+import type * as Effect from "effect/Effect";
+import * as Binding from "../Binding.ts";
+import type { RuntimeContext } from "../RuntimeContext.ts";
+import type { Bucket } from "./Bucket.ts";
+import type { RailwayS3CredentialsMissing } from "./BucketBinding.ts";
+
+export interface ListObjectsV2Request extends Omit<
+  S3.ListObjectsV2Request,
+  "Bucket"
+> {}
+
+/**
+ * Runtime binding for Railway `ListObjectsV2` over the S3 API.
+ *
+ * Bind this operation to a {@link Bucket} in Service init. Provide
+ * {@link ListObjectsV2Http}.
+ *
+ *
+ * ### Listing Objects
+ * **Example:** List Objects Under a Prefix
+ * ```typescript
+ * const listObjects = yield* Railway.ListObjectsV2(Data);
+ * const result = yield* listObjects({ Prefix: "jobs/", MaxKeys: 100 });
+ * ```
+ *
+ * @binding
+ */
+export interface ListObjectsV2 extends Binding.Service<
+  ListObjectsV2,
+  "Railway.ListObjectsV2",
+  (
+    bucket: Bucket,
+  ) => Effect.Effect<
+    (
+      request?: ListObjectsV2Request,
+    ) => Effect.Effect<
+      S3.ListObjectsV2Output,
+      S3.ListObjectsV2Error | Config.ConfigError | RailwayS3CredentialsMissing,
+      RuntimeContext
+    >
+  >
+> {}
+
+export const ListObjectsV2 = Binding.Service<ListObjectsV2>(
+  "Railway.ListObjectsV2",
+);

package/src/Railway/ListObjectsV2Http.ts

@@ -0,0 +1,19 @@
+import * as S3 from "@distilled.cloud/aws/s3";
+import * as Layer from "effect/Layer";
+import { makeRailwayS3Binding } from "./BucketBinding.ts";
+import { ListObjectsV2 } from "./ListObjectsV2.ts";
+
+/**
+ * HTTP implementation of {@link ListObjectsV2}. Calls distilled S3
+ * `listObjectsV2` against the Railway endpoint with the bucket's credentials.
+ *
+ * @layer
+ * @provides Railway.ListObjectsV2
+ */
+export const ListObjectsV2Http = Layer.effect(
+  ListObjectsV2,
+  makeRailwayS3Binding({
+    tag: "Railway.ListObjectsV2",
+    operation: S3.listObjectsV2,
+  }),
+);

package/src/Railway/LoginSession.ts

@@ -0,0 +1,105 @@
+import * as railway from "@distilled.cloud/railway";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schedule from "effect/Schedule";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+
+/** Dashboard host used by `railway login --browserless` pairing URLs. */
+export const RAILWAY_CLI_LOGIN_HOST = "https://railway.com";
+
+/**
+ * Build the Railway CLI pairing URL for a {@link railway.loginSessionCreate}
+ * code.
+ *
+ * Mirrors `railway login --browserless`: the payload is
+ * `wordCode={code}&hostname={hostname}` (URL-safe base64) on
+ * `https://railway.com/cli-login?d=…`. The user confirms the pairing code
+ * in the browser; {@link railway.loginSessionAuth} is the dashboard-side
+ * mutation that marks the session authorized. {@link railway.loginSessionVerify}
+ * is a liveness check (true while the pairing session exists). The CLI then
+ * polls {@link railway.loginSessionConsume} until a token is returned.
+ *
+ * Alchemy's AuthProvider `method: "oauth"` runs this flow: create → print
+ * the pairing URL → poll consume → store the token.
+ *
+ * ### Pairing URL
+ * **Example:** From a session code
+ * ```typescript
+ * const code = yield* railway.loginSessionCreate({});
+ * const url = loginSessionUrl(code, { hostname: "dev-box" });
+ * ```
+ */
+export const loginSessionUrl = (
+  code: string,
+  options?: { hostname?: string; host?: string },
+): string => {
+  const hostname = options?.hostname ?? "alchemy";
+  const host = (options?.host ?? RAILWAY_CLI_LOGIN_HOST).replace(/\/+$/, "");
+  const payload = `wordCode=${code}&hostname=${hostname}`;
+  const encoded = Buffer.from(payload)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_");
+  return `${host}/cli-login?d=${encoded}`;
+};
+
+/**
+ * Credentials layer that sends no `Authorization` header. Login-session
+ * mutations are public: they run before the user has a token.
+ */
+const anonymousRailwayCredentials = (apiBaseUrl?: string) =>
+  railway.CredentialsFromToken({
+    token: "",
+    tokenKind: "account",
+    apiBaseUrl,
+  });
+
+const anonymousRailway = (apiBaseUrl?: string) =>
+  Layer.mergeAll(
+    anonymousRailwayCredentials(apiBaseUrl),
+    FetchHttpClient.layer,
+  );
+
+export const provideAnonymousRailway = <A, E>(
+  effect: Effect.Effect<A, E, railway.RailwayOpContext>,
+  apiBaseUrl?: string,
+): Effect.Effect<A, E> =>
+  effect.pipe(Effect.provide(anonymousRailway(apiBaseUrl)));
+
+const LOGIN_POLL_TIMES = 300;
+
+/**
+ * Poll {@link railway.loginSessionVerify} then
+ * {@link railway.loginSessionConsume} until a token is returned, or 5 minutes
+ * elapse. Mirrors `railway login --browserless`: consume is the token source;
+ * verify is a liveness check. Does not cancel the session — the caller should
+ * cancel on timeout or interrupt.
+ *
+ * Exhaustion returns `undefined` (not a failure) so the AuthProvider can
+ * surface a timeout rather than a poll error.
+ */
+const missingSession = ["RailwayNotFound", "NotFound"] as const;
+
+export const pollLoginSessionToken = (
+  code: string,
+): Effect.Effect<
+  string | undefined,
+  railway.RailwayOpError,
+  railway.RailwayOpContext
+> =>
+  railway.loginSessionVerify({ code }).pipe(
+    Effect.catchTag(missingSession, () => Effect.succeed(false)),
+    Effect.flatMap(() =>
+      railway
+        .loginSessionConsume({ code })
+        .pipe(Effect.catchTag(missingSession, () => Effect.succeed(null))),
+    ),
+    Effect.map((token) =>
+      token != null && token.length > 0 ? token : undefined,
+    ),
+    Effect.repeat({
+      schedule: Schedule.spaced("1 second"),
+      while: (token) => token == null,
+      times: LOGIN_POLL_TIMES,
+    }),
+  );

package/src/Railway/Metadata.ts

@@ -0,0 +1,105 @@
+import * as Effect from "effect/Effect";
+import { createPhysicalName } from "../PhysicalName.ts";
+
+/**
+ * Railway has no labels. Ownership is stamped into the physical name via
+ * `createPhysicalName` (lowercase, max 32, leading letter). Railway's
+ * `projectCreate` rejects longer generated names (`Invalid project name`).
+ * `list()` filters with {@link matchesAlchemyPhysicalName} so nuke does
+ * not enumerate the whole workspace.
+ */
+export const RAILWAY_NAME_MAX_LENGTH = 32;
+
+/**
+ * Railway generates `{serviceName}-{environmentName}.up.railway.app` on
+ * `serviceDomainCreate`. That first DNS label must be ≤ 63 characters
+ * (`32 + 1 + 32 = 65` fails with "please try again"). Extra environments
+ * stay shorter so a 32-char service name still fits.
+ */
+export const RAILWAY_ENVIRONMENT_NAME_MAX_LENGTH = 24;
+
+const clipName = (raw: string, maxLength: number) => {
+  const clipped = raw.length > maxLength ? raw.slice(0, maxLength) : raw;
+  const forced = /^[a-z]/.test(clipped)
+    ? clipped
+    : `r${clipped}`.slice(0, maxLength);
+  return forced.replace(/-+$/g, "") || "r";
+};
+
+/**
+ * Railway Project / Service / Volume / Variable physical names:
+ * `createPhysicalName({ lowercase: true, maxLength: 32 })`, then force a
+ * leading letter (`r` prefix if needed). Unique per workspace.
+ */
+export const createRailwayName = Effect.fn(function* (id: string) {
+  const raw = yield* createPhysicalName({
+    id,
+    lowercase: true,
+    maxLength: RAILWAY_NAME_MAX_LENGTH,
+  });
+  return clipName(raw, RAILWAY_NAME_MAX_LENGTH);
+});
+
+/** Extra-environment names. See {@link RAILWAY_ENVIRONMENT_NAME_MAX_LENGTH}. */
+export const createRailwayEnvironmentName = Effect.fn(function* (id: string) {
+  const raw = yield* createPhysicalName({
+    id,
+    lowercase: true,
+    maxLength: RAILWAY_ENVIRONMENT_NAME_MAX_LENGTH,
+  });
+  return clipName(raw, RAILWAY_ENVIRONMENT_NAME_MAX_LENGTH);
+});
+
+/**
+ * Sanitize a user-supplied Railway name: lowercase, DNS-compatible
+ * (`[a-z0-9-]`), force a leading letter, max 32 chars.
+ */
+const sanitizeTo = (name: string, maxLength: number): string => {
+  const lowered = name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return clipName(lowered.length === 0 ? "r" : lowered, maxLength);
+};
+
+export const sanitizeRailwayName = (name: string): string =>
+  sanitizeTo(name, RAILWAY_NAME_MAX_LENGTH);
+
+export const sanitizeRailwayEnvironmentName = (name: string): string =>
+  sanitizeTo(name, RAILWAY_ENVIRONMENT_NAME_MAX_LENGTH);
+
+export const sanitize = sanitizeRailwayName;
+
+/**
+ * True when `name` matches the `createPhysicalName` + leading-letter shape
+ * used for alchemy-owned Railway resources.
+ *
+ * Untruncated names end with a hyphen plus an 8–16 char RFC4648 base32
+ * instance suffix. Truncated 32-char names keep that suffix (the human
+ * prefix is what gets cut).
+ */
+export const matchesAlchemyPhysicalName = (
+  name: string | undefined,
+): boolean => {
+  if (
+    name === undefined ||
+    name.length === 0 ||
+    name.length > RAILWAY_NAME_MAX_LENGTH
+  ) {
+    return false;
+  }
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) return false;
+  const parts = name.split("-");
+  const last = parts.at(-1) ?? "";
+  if (
+    parts.length >= 2 &&
+    last.length >= 8 &&
+    last.length <= 16 &&
+    /^[a-z2-7]+$/.test(last)
+  ) {
+    return true;
+  }
+  const compact = name.replaceAll("-", "");
+  return /[a-z2-7]{16}$/.test(compact);
+};