alchemy 2.0.0-beta.77 → 2.0.0-beta.78

package/src/Railway/transient.ts

@@ -1,63 +1,29 @@
 import * as railway from "@distilled.cloud/railway";
-import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Schedule from "effect/Schedule";
 import * as Semaphore from "effect/Semaphore";
 
-/**
- * Railway API errors that are safe to retry: throttles plus gateway
- * disconnects (`ServiceUnavailable` "upstream connect error", 502, 504).
- */
-export const isRailwayTransient = (e: { _tag: string }): boolean =>
-  e._tag === "RailwayRateLimited" ||
-  e._tag === "TooManyRequests" ||
-  e._tag === "ServiceUnavailable" ||
-  e._tag === "BadGateway" ||
-  e._tag === "GatewayTimeout";
-
-const createRateLimitWait = Duration.seconds(31);
-
-/** Extra 0..max so concurrent waiters don't share a wake-up. */
-const jitterUpTo = (max: Duration.Duration) =>
-  Duration.millis(Math.random() * Duration.toMillis(max));
+/** Known throttling responses and transport failures safe for read-only callers to retry. */
+export const isRailwayTransient = (error: unknown): boolean =>
+  railway.isErrorTag(error, [
+    "RailwayRateLimited",
+    "RailwayOperationInProgress",
+  ]) ||
+  (error instanceof railway.GraphQLTransportError &&
+    (error.status === 429 ||
+      error.status === 502 ||
+      error.status === 503 ||
+      error.status === 504));
+
+/** Space bulk read retries without exceeding the factory retry window. */
+export const conservativeSpacing = Schedule.spaced("5 seconds");
 
-/**
- * 30s plus 0–30s jitter. Railway's public API is ~10k requests/hour;
- * concurrent suite retries have to stay sparse.
- */
-export const conservativeSpacing = Schedule.spaced("30 seconds").pipe(
-  Schedule.addDelay(() => Effect.sync(() => jitterUpTo(Duration.seconds(30)))),
-);
-
-/**
- * One in-flight project/environment create per process. Railway meters
- * those at 1 per 30s per user; concurrent waiters otherwise stampede
- * the cap and distilled's inner Retry-After loop (8 × ~31s).
- */
 const projectAndEnvironmentCreateGate = Semaphore.makeUnsafe(1);
 
-const retryCreateRateLimit = <A, E, R>(
-  effect: Effect.Effect<A, E, R>,
-): Effect.Effect<A, E, R> =>
-  effect.pipe(
-    Effect.catch((error) =>
-      error instanceof railway.RailwayRateLimited
-        ? Effect.sleep(
-            Duration.sum(
-              error.retryAfter ?? createRateLimitWait,
-              jitterUpTo(Duration.seconds(30)),
-            ),
-          ).pipe(Effect.andThen(retryCreateRateLimit(effect)))
-        : Effect.fail(error),
-    ),
-  );
-
 /**
- * Railway meters project and environment creates at 1 per 30s per user.
- * Distilled tags those as `RailwayRateLimited`. Sleep the hinted delay
- * (or 31s) plus 0–30s jitter and retry until the cap opens. Unbounded.
- * The gate is held across the sleep so the next waiter does not fire
- * another create into a closed window.
+ * Railway rejects project/environment creation within its 30-second creation
+ * window. Serialize these calls and retry a typed rejection once after 31s.
+ * Other mutation failures propagate so an ambiguous create is never replayed.
  */
 export const waitOutCreateRateLimit = <A, E, R>(
   effect: Effect.Effect<A, E, R>,
@@ -65,7 +31,15 @@ export const waitOutCreateRateLimit = <A, E, R>(
   Semaphore.withPermits(
     projectAndEnvironmentCreateGate,
     1,
-  )(retryCreateRateLimit(effect));
+  )(
+    effect.pipe(
+      Effect.retry({
+        while: (error) => railway.isErrorTag(error, "RailwayRateLimited"),
+        times: 1,
+        schedule: Schedule.spaced("31 seconds"),
+      }),
+    ),
+  );
 
 /**
  * One in-flight environment-config mutation per environment. Railway's

package/src/Rpc.ts

@@ -221,15 +221,67 @@ export const decodeRpcValue = (value: unknown) => {
   return value;
 };
 
+/**
+ * A tagged-error class an RPC surface can declare (e.g. a Durable Object's
+ * `errors` prop) so failures crossing the RPC boundary are reconstructed as
+ * real class instances instead of the plain `{ _tag, ...fields }` objects
+ * {@link encodeRpcError} produces. `identifier` is the static tag that
+ * `Schema.TaggedError` classes carry; other classes match by class `name`.
+ */
+export interface RpcErrorClass {
+  new (props: never): unknown;
+  readonly identifier?: string;
+}
+
+/**
+ * Build a reviver from declared error classes: a failure shaped
+ * `{ _tag, ...fields }` whose tag matches a declared class is
+ * reconstructed via that class's constructor (both sides of the RPC import
+ * the same class declaration, so the schema is shared by construction).
+ * Unmatched or already-revived errors pass through untouched.
+ */
+export const makeRpcErrorReviver = (
+  errors: ReadonlyArray<RpcErrorClass> | undefined,
+): ((error: unknown) => unknown) => {
+  if (errors === undefined || errors.length === 0) {
+    return (error) => error;
+  }
+  const byTag = new Map<string, RpcErrorClass>();
+  for (const cls of errors) {
+    byTag.set(cls.identifier ?? cls.name, cls);
+  }
+  return (error) => {
+    if (typeof error !== "object" || error === null || !("_tag" in error)) {
+      return error;
+    }
+    const cls = byTag.get((error as { _tag: string })._tag);
+    if (cls === undefined || error instanceof cls) {
+      return error;
+    }
+    try {
+      return new (cls as new (props: unknown) => unknown)(error);
+    } catch {
+      // A malformed wire object must not turn into a defect here — the
+      // caller still sees the raw envelope error.
+      return error;
+    }
+  };
+};
+
 /**
  * Decode an RPC return value, lifting error envelopes into the Effect
  * error channel so that remote `Effect.fail(...)` values are recoverable.
+ * When `revive` is given (see {@link makeRpcErrorReviver}), envelope errors
+ * are reconstructed as their declared error classes.
  */
 export const decodeRpcResult = (
   value: unknown,
+  revive?: (error: unknown) => unknown,
 ): Effect.Effect<unknown, unknown> => {
   if (isRpcErrorEnvelope(value)) {
-    return Effect.fail(value.error);
+    return Effect.fail(
+      revive === undefined ? value.error : revive(value.error),
+    );
   }
   return Effect.succeed(decodeRpcValue(value));
 };

package/src/Runtime/Bootstrap/Process.ts

@@ -49,8 +49,8 @@ export const stackFromEnv: Layer.Layer<Stack, Config.ConfigError> =
   Layer.effect(
     Stack,
     Effect.all([
-      Config.string("ALCHEMY_STACK_NAME"),
-      Config.string("ALCHEMY_STAGE"),
+      Config.String("ALCHEMY_STACK_NAME"),
+      Config.String("ALCHEMY_STAGE"),
     ]).pipe(
       Effect.map(([name, stage]) => ({
         name,

package/src/Runtime.ts

@@ -92,7 +92,7 @@ const reifyEnvString = (raw: string): string => {
  * marker. The interceptor's runtime branch reifies those markers for reads
  * during Init, but effects that run later (request handlers, nested
  * layers) resolve `Config` against the raw env-backed provider — without
- * this wrapper, `Config.number("PORT")` inside a handler sees the marker
+ * this wrapper, `Config.Number("PORT")` inside a handler sees the marker
  * JSON instead of the source value and fails with a schema error.
  *
  * Two behaviors:

package/src/RuntimeContext.ts

@@ -136,7 +136,7 @@ export const packEnvValueKeepRedacted = (
  *
  * Runtime `get` accessors MUST feed this from the raw environment
  * (`process.env[key]` / the platform env object) — never through
- * `Config.string`: the ambient runtime `ConfigProvider` reifies bound
+ * `Config.String`: the ambient runtime `ConfigProvider` reifies bound
  * values (unwrapping the marker before it could be detected here), and
  * during init the ambient provider is the interceptor installed in
  * `Platform.ts`, whose runtime branch calls back into `ctx.get(key)` —

package/src/SQL/Postgres.ts

@@ -6,6 +6,7 @@ import type * as Redacted from "effect/Redacted";
 import * as Sql from "effect/unstable/sql/SqlClient";
 import { makeExecutionMemo } from "../Runtime/ExecutionMemo.ts";
 import { proxyChain } from "../Util/proxy-chain.ts";
+import { resolveConnectionOptions } from "./PostgresTls.ts";
 
 /**
  * Options for {@link Postgres}: `@effect/sql-pg`'s pool configuration, with
@@ -55,7 +56,10 @@ export const Postgres = <E = never, R = never>(config: PostgresConfig<E, R>) =>
         const { url, ...pool } = config;
         const resolved = Effect.isEffect(url) ? yield* url : url;
         const pgCtx = yield* Layer.build(
-          PgClient.layer({ ...pool, url: resolved }),
+          PgClient.layer({
+            ...pool,
+            ...resolveConnectionOptions(resolved, pool.ssl),
+          }),
         );
         return Context.get(pgCtx, PgClient.PgClient);
       }),

package/src/SQL/PostgresTls.ts

@@ -0,0 +1,70 @@
+import type * as PgClient from "@effect/sql-pg/PgClient";
+import * as Redacted from "effect/Redacted";
+
+type PgSsl = PgClient.PgPoolConfig["ssl"];
+
+/**
+ * `sslmode` values `@effect/sql-pg` (≥ 4.0.0-rc.113, still as of rc.115)
+ * refuses unless `ssl` is set explicitly: `sslmode "prefer" is not
+ * supported: set ssl explicitly to true or false`. node-postgres treated both
+ * as "TLS on" (aliases of `verify-full`), and URLs carry them by default in
+ * places — Hyperdrive's local `dev` origin passthrough hands the worker
+ * `?sslmode=prefer`, and `prefer` is libpq's own default.
+ */
+const OPPORTUNISTIC_SSL_MODES: ReadonlySet<string> = new Set([
+  "prefer",
+  "allow",
+]);
+
+/**
+ * Resolve the `ssl` option to hand `@effect/sql-pg` for a connection URL.
+ *
+ * When the caller left `ssl` implicit and the URL's `sslmode` is `prefer` or
+ * `allow`, returns `ssl: true` so the connection is TLS-on exactly as it was
+ * under node-postgres. Railway's `no-verify` mode defaults to TLS without
+ * certificate verification. Explicit caller settings take precedence, and
+ * other URL modes keep driving the decision inside `@effect/sql-pg`.
+ *
+ * (`@effect/sql-pg` < rc.115 also sent no TLS SNI; that was fixed upstream in
+ * Effect-TS/effect#8174, so this helper no longer sets `servername`.)
+ */
+export const resolveSsl = (
+  url: Redacted.Redacted<string>,
+  ssl: PgSsl,
+): PgSsl => {
+  if (ssl !== undefined) return ssl;
+  let parsed: URL;
+  try {
+    parsed = new URL(Redacted.value(url));
+  } catch {
+    // Let `@effect/sql-pg` report the malformed URL.
+    return ssl;
+  }
+  const sslmode = parsed.searchParams.get("sslmode");
+  if (sslmode === "no-verify") return { rejectUnauthorized: false };
+  return sslmode !== null && OPPORTUNISTIC_SSL_MODES.has(sslmode) ? true : ssl;
+};
+
+/**
+ * Normalize the URL and TLS settings together for Effect's Postgres driver.
+ * Translate node-postgres's `sslmode=no-verify` to `require` with explicit
+ * TLS options so it also works with stricter URL parsers. Retain its verification
+ * choice in the TLS options. Other URL parameters and explicit TLS settings
+ * remain intact; credentials stay redacted.
+ */
+export const resolveConnectionOptions = (
+  url: Redacted.Redacted<string>,
+  ssl?: PgSsl,
+): { url: Redacted.Redacted<string>; ssl: PgSsl } => {
+  const resolvedSsl = resolveSsl(url, ssl);
+  try {
+    const parsed = new URL(Redacted.value(url));
+    if (parsed.searchParams.get("sslmode") === "no-verify") {
+      parsed.searchParams.set("sslmode", "require");
+      return { url: Redacted.make(parsed.toString()), ssl: resolvedSsl };
+    }
+  } catch {
+    // The driver owns malformed URL diagnostics.
+  }
+  return { url, ssl: resolvedSsl };
+};

package/src/Server/Process.ts

@@ -84,7 +84,7 @@ export const createHostRuntimeContext =
         }),
       get: <T>(key: string) =>
         // Read straight from `process.env` — see `unpackEnvValue` for why
-        // this must never resolve through `Config.string`.
+        // this must never resolve through `Config.String`.
         Effect.sync(() => unpackEnvValue<T>(process.env[key]) as T),
       run: (effect: Effect.Effect<void, never, any>) =>
         Effect.sync(() => {

package/src/Server/index.ts

@@ -1,3 +1 @@
 export * from "./Process.ts";
-export * from "./S3BucketEventSource.ts";
-export * from "./SQSQueueEventSource.ts";

package/src/Stack.ts

@@ -19,7 +19,7 @@ import { AuthProviders } from "./Auth/AuthProvider.ts";
 import { CredentialsStore, CredentialsStoreLive } from "./Auth/Credentials.ts";
 import { ProfileStore, ProfileStoreLive } from "./Auth/Profile.ts";
 // Type-only: with verbatimModuleSyntax a value import would survive emit and
-// drag the terminal helpers (node:tty, string-width) into every unbundled
+// drag the terminal helpers (node:tty, Sigil's ansi helpers) into every unbundled
 // child process that loads Stack.ts.
 import type { Interaction } from "./Interaction.ts";
 import type { Input, InputProps } from "./Input.ts";
@@ -27,6 +27,7 @@ import * as Output from "./Output.ts";
 import type { Provider, ProviderCollectionLike } from "./Provider.ts";
 import type { ResourceBinding, ResourceLike } from "./Resource.ts";
 import { Stage } from "./Stage.ts";
+import { StackContext } from "./StackContext.ts";
 import type { State } from "./State/State.ts";
 import { loadConfigProvider } from "./Util/ConfigProvider.ts";
 import { effectClass, taggedFunction } from "./Util/effect.ts";
@@ -142,7 +143,7 @@ export const Stack: Context.ServiceClass<
   ): Effect.Effect<CompiledStack<A>, ConfigError>;
 } = Object.assign(
   taggedFunction(
-    Context.Service<Stack, Omit<StackSpec, "output">>()("Stack"),
+    StackContext,
     <A, Req>(
       stackName?: string,
       options?: StackProps<NoInfer<Req>>,

package/src/StackContext.ts

@@ -0,0 +1,6 @@
+import * as Context from "effect/Context";
+import type { Stack, StackSpec } from "./Stack.ts";
+
+export const StackContext = Context.Service<Stack, Omit<StackSpec, "output">>()(
+  "Stack",
+);

package/src/State/HttpStateStore.ts

@@ -2,8 +2,10 @@ import * as Effect from "effect/Effect";
 import { identity } from "effect/Function";
 import * as Schedule from "effect/Schedule";
 import * as HttpClient from "effect/unstable/http/HttpClient";
+import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
+import * as HttpApiError from "effect/unstable/httpapi/HttpApiError";
 import { profileCommandHint } from "../Util/interactive.ts";
 import { StateApi } from "./HttpStateApi.ts";
 
@@ -233,57 +235,42 @@ const retryTransient = <A, Err, Req>(eff: Effect.Effect<A, Err, Req>) =>
   });
 
 /**
- * Human-readable description of a state-store client failure.
- *
- * Several of the errors the HTTP client can raise carry an empty
- * `message` (e.g. the no-content `Unauthorized` the store returns on a
- * bad bearer token), which used to surface as a blank
- * `StateStoreError` with nothing to act on. Always produce a
- * non-empty message: prefer the error's own message, fall back to its
- * `_tag`/name, and append the HTTP status and any distinct `cause`
- * message when available.
+ * Describe a state-store failure using only its known kind and HTTP status.
+ * Client/decoder messages and causes can contain serialized state, including
+ * secrets unwrapped by encodeState, so they must not become diagnostics.
  */
 export const describeStateStoreFailure = (
   e: unknown,
   profileCommand = "alchemy profile edit",
 ): string => {
-  if (!(e instanceof Error)) return String(e);
-  const tag = (e as { _tag?: unknown })._tag;
-  let message =
-    e.message.trim() ||
-    (typeof tag === "string" ? tag : undefined) ||
-    e.name ||
-    "Unknown error";
-  if (typeof tag === "string" && tag.startsWith("Unauthorized")) {
-    message =
+  if (e instanceof HttpApiError.Unauthorized) {
+    return (
       "State store rejected the request as unauthorized. " +
-      `The stored state-store credentials may be stale. Run \`${profileCommand}\` to reconfigure them.`;
-  }
-  const status = (e as { response?: { status?: unknown } }).response?.status;
-  if (typeof status === "number" && !message.includes(String(status))) {
-    message += ` (HTTP ${status})`;
+      `The stored state-store credentials may be stale. Run \`${profileCommand}\` to reconfigure them.`
+    );
   }
-  if (e.cause instanceof Error) {
-    const causeMessage = e.cause.message.trim();
-    if (causeMessage && !message.includes(causeMessage)) {
-      message += ` — caused by: ${causeMessage}`;
-    }
+  if (HttpClientError.isHttpClientError(e)) {
+    const status = e.response?.status;
+    return `State store request failed (${e.reason._tag}${status === undefined ? "" : `, HTTP ${status}`}).`;
   }
-  return message;
+  return "State store request failed.";
 };
 
 /** Collapse any client failure into a {@link StateStoreError}. */
 const mapStateStoreError = <A, E, R>(eff: Effect.Effect<A, E, R>) =>
   eff.pipe(
     retryTransient,
-    Effect.tapError(Effect.log),
     Effect.catch((e: E) =>
       Effect.gen(function* () {
         const command = yield* profileCommandHint("alchemy profile edit");
         return yield* Effect.fail(
           new StateStoreError({
             message: describeStateStoreFailure(e, command),
-            cause: e instanceof Error ? e : undefined,
+            http: HttpClientError.isHttpClientError(e)
+              ? { status: e.response?.status }
+              : e instanceof HttpApiError.Unauthorized
+                ? { status: 401 }
+                : undefined,
           }),
         );
       }),

package/src/State/PostgresState.ts

@@ -7,6 +7,7 @@ import * as Scope from "effect/Scope";
 import * as Semaphore from "effect/Semaphore";
 import type * as SqlClient from "effect/unstable/sql/SqlClient";
 import type * as SqlError from "effect/unstable/sql/SqlError";
+import { resolveConnectionOptions } from "../SQL/PostgresTls.ts";
 import { recordStateStoreInit } from "../Telemetry/Metrics.ts";
 import { STATE_STORE_VERSION } from "./HttpStateApi.ts";
 import type { ReplacedResourceState } from "./ResourceState.ts";
@@ -47,7 +48,7 @@ export interface PostgresStateOptions<E = never, R = never> {
   client?: SqlClient.SqlClient;
   /**
    * Postgres connection URL, as a `Redacted` value or an Effect yielding one
-   * — `Config.redacted("STATE_DATABASE_URL")` is itself an Effect, so it can
+   * — `Config.Redacted("STATE_DATABASE_URL")` is itself an Effect, so it can
    * be passed directly. The store creates its own `@effect/sql-pg` pool from
    * the URL and closes that pool when the state layer is released.
    */
@@ -142,7 +143,7 @@ interface Lease {
  *   "my-stack",
  *   {
  *     providers: myProviders(),
- *     state: postgresState({ url: Config.redacted("STATE_DATABASE_URL") }),
+ *     state: postgresState({ url: Config.Redacted("STATE_DATABASE_URL") }),
  *   },
  *   Effect.gen(function* () {
  *     // ...
@@ -158,11 +159,11 @@ interface Lease {
  * // A pool, not `PgClient.makeClient`: the store needs a second connection
  * // to verify the advisory lock held on the reserved one.
  * const sql = yield* PgClient.make({
- *   url: yield* Config.redacted("STATE_DATABASE_URL"),
+ *   url: yield* Config.Redacted("STATE_DATABASE_URL"),
  * });
  * const state = postgresState({
  *   client: sql,
- *   lockKeyPrefix: yield* Config.string("STATE_LOCK_PREFIX"),
+ *   lockKeyPrefix: yield* Config.String("STATE_LOCK_PREFIX"),
  * });
  * ```
  */
@@ -274,7 +275,7 @@ export const makePostgresState = <E = never, R = never>(
           ? yield* Effect.provideContext(url, context).pipe(stateError)
           : url;
         const built = yield* Layer.build(
-          PgClient.layer({ url: resolved }),
+          PgClient.layer(resolveConnectionOptions(resolved)),
         ).pipe(Scope.provide(scope), stateError);
         return Context.get(built, PgClient.PgClient);
       });

package/src/State/State.ts

@@ -21,6 +21,11 @@ export const isResourceState = (
 export class StateStoreError extends Data.TaggedError("StateStoreError")<{
   message: string;
   cause?: Error;
+  /** HTTP failure metadata without the request, response body, or credentials. */
+  http?: {
+    /** Undefined when the HTTP client failed before receiving a response. */
+    status?: number;
+  };
 }> {}
 
 export class State extends Context.Service<