feat(http-recorder): default mode to "auto" (#26719)

packages/http-recorder/src/effect.ts

@@ -12,12 +12,12 @@ import {
 } from "effect/unstable/http"
 import * as CassetteService from "./cassette"
 import { defaultMatcher, selectMatch, selectSequential, type RequestMatcher } from "./matching"
-import { appendOrFail, makeReplayState } from "./recorder"
+import { appendOrFail, makeReplayState, resolveAutoMode } from "./recorder"
 import { defaults, type Redactor } from "./redactor"
 import { redactUrl } from "./redaction"
 import { httpInteractions, type CassetteMetadata, type HttpInteraction, type ResponseSnapshot } from "./schema"
 
-export type RecordReplayMode = "record" | "replay" | "passthrough"
+export type RecordReplayMode = "auto" | "record" | "replay" | "passthrough"
 
 export interface RecordReplayOptions {
   readonly mode?: RecordReplayMode
@@ -69,7 +69,8 @@ export const recordingLayer = (
       const cassetteService = yield* CassetteService.Service
       const redactor = options.redactor ?? defaults()
       const match = options.match ?? defaultMatcher
-      const mode = options.mode ?? "replay"
+      const requested = options.mode ?? "auto"
+      const mode = requested === "auto" ? yield* resolveAutoMode(cassetteService, name) : requested
       const sequential = options.dispatch === "sequential"
       const replay = yield* makeReplayState(cassetteService, name, httpInteractions)
 
@@ -114,7 +115,12 @@ export const recordingLayer = (
         return Effect.gen(function* () {
           const incoming = yield* snapshotRequest(request)
           const interactions = yield* replay.load.pipe(
-            Effect.mapError(() => transportError(request, `Fixture "${name}" not found.`)),
+            Effect.mapError(() =>
+              transportError(
+                request,
+                `Fixture "${name}" not found. Run locally to record it (CI=true forces replay).`,
+              ),
+            ),
           )
           const result = sequential
             ? selectSequential(interactions, incoming, match, yield* replay.cursor)

packages/http-recorder/src/recorder.ts

@@ -17,6 +17,22 @@ export class UnsafeCassetteError extends Error {
   }
 }
 
+export type ResolvedMode = "record" | "replay" | "passthrough"
+
+const isCI = () => {
+  const value = process.env.CI
+  return value !== undefined && value !== "" && value !== "false" && value !== "0"
+}
+
+export const resolveAutoMode = (
+  cassette: CassetteService.Interface,
+  name: string,
+): Effect.Effect<ResolvedMode> =>
+  Effect.gen(function* () {
+    if (isCI()) return "replay"
+    return (yield* cassette.exists(name)) ? "replay" : "record"
+  })
+
 export const appendOrFail = (
   cassette: CassetteService.Interface,
   name: string,

packages/http-recorder/src/websocket.ts

@@ -2,7 +2,8 @@ import { Effect, Option, Ref, Scope, Stream } from "effect"
 import type { Headers } from "effect/unstable/http"
 import * as CassetteService from "./cassette"
 import { canonicalizeJson, decodeJson } from "./matching"
-import { appendOrFail, makeReplayState } from "./recorder"
+import { appendOrFail, makeReplayState, resolveAutoMode } from "./recorder"
+import type { RecordReplayMode } from "./effect"
 import { defaults, type Redactor } from "./redactor"
 import { webSocketInteractions, type CassetteMetadata, type WebSocketFrame } from "./schema"
 
@@ -23,7 +24,7 @@ export interface WebSocketExecutor<E> {
 
 export interface WebSocketRecordReplayOptions<E> {
   readonly name: string
-  readonly mode?: "record" | "replay" | "passthrough"
+  readonly mode?: RecordReplayMode
   readonly metadata?: CassetteMetadata
   readonly cassette: CassetteService.Interface
   readonly live: WebSocketExecutor<E>
@@ -71,7 +72,8 @@ export const makeWebSocketExecutor = <E>(
   options: WebSocketRecordReplayOptions<E>,
 ): Effect.Effect<WebSocketExecutor<E>, never, Scope.Scope> =>
   Effect.gen(function* () {
-    const mode = options.mode ?? "replay"
+    const requested = options.mode ?? "auto"
+    const mode = requested === "auto" ? yield* resolveAutoMode(options.cassette, options.name) : requested
     const redactor = options.redactor ?? defaults()
     const openSnapshot = (request: WebSocketRequest) => {
       const redacted = redactor.request({