sailfork / t3code-github / .repos/ alchemy-effect/ packages/ alchemy-test/ src/ Http.ts

import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as HttpClient from "effect/http/HttpClient";
import { DecodeError, HttpClientError } from "effect/http/HttpClientError";
import * as HttpClientRequest from "effect/http/HttpClientRequest";
import type { HttpClientResponse } from "effect/http/HttpClientResponse";
import * as Layer from "effect/Layer";
import * as RpcClient from "effect/rpc/RpcClient";
import * as RpcSerialization from "effect/rpc/RpcSerialization";
import * as Schedule from "effect/Schedule";

/**
 * A freshly-deployed Cloudflare Worker is not instantly reachable over HTTP.
 * Its `workers.dev` route, the script, and each binding (R2 / D1 / DO / Secrets
 * Store) propagate to the edge independently and asynchronously, so the first
 * requests to a new URL can transiently return:
 *
 *  - `404` while the `workers.dev` subdomain / route is still propagating
 *    (Cloudflare serves its "There is nothing here yet" placeholder), or
 *  - `5xx` while the script is up but a binding it depends on isn't ready yet.
 *
 * This is ordinary eventual consistency that belongs at the call site, not in
 * the resource provider — the provider returning before every edge PoP has
 * converged is correct. Consumers ride out the window by retrying the request.
 */
export class WorkerNotReady extends Data.TaggedError("WorkerNotReady")<{ status: number }> {}

/**
 * Status codes that indicate the edge hasn't finished converging on a fresh
 * deploy. Deliberate client errors (`401`, `403`, `400`, …) are NOT in this
 * set, so assertions on those statuses still observe them immediately rather
 * than being retried away.
 */
const isColdStartStatus = (status: number): boolean => status === 404 || status >= 500;

export interface WhenReadyOptions {
  /** Max retry attempts before surfacing {@link WorkerNotReady}. Default `20`. */
  times?: number;
}

/**
 * Execute an arbitrary {@link HttpClientRequest.HttpClientRequest}, retrying
 * through the Cloudflare cold-start window ({@link isColdStartStatus}) until the
 * Worker serves a non-transient response. The returned response can carry any
 * non-cold-start status (e.g. `200`, `202`, `401`) for the caller to assert on.
 */
export const executeWhenReady = (
  request: HttpClientRequest.HttpClientRequest,
  options?: WhenReadyOptions,
): Effect.Effect<HttpClientResponse, unknown, HttpClient.HttpClient> =>
  Effect.gen(function* () {
    const client = yield* HttpClient.HttpClient;
    return yield* client.execute(request).pipe(
      Effect.flatMap((response) =>
        isColdStartStatus(response.status)
          ? Effect.fail(new WorkerNotReady({ status: response.status }))
          : Effect.succeed(response),
      ),
      Effect.retry({
        while: (error) => error instanceof WorkerNotReady,
        schedule: Schedule.max([
          Schedule.exponential("500 millis"),
          Schedule.recurs(options?.times ?? 20),
        ]),
      }),
    );
  });

/**
 * Convenience wrapper over {@link executeWhenReady} for a plain `GET`.
 */
export const getWhenReady = (
  url: string,
  options?: WhenReadyOptions,
): Effect.Effect<HttpClientResponse, unknown, HttpClient.HttpClient> =>
  executeWhenReady(HttpClientRequest.get(url), options);

/**
 * Options for the edge-transient response guard applied by
 * {@link guardContentType} / {@link rpcClientLayer}. Pass per suite via
 * `Test.make({ http: { ... } })` or per call site.
 */
export interface EdgeGuardOptions {
  /**
   * Retry schedule for edge-transient responses (and transport errors).
   * Default: exponential from 500ms capped at 3s.
   */
  schedule?: Schedule.Schedule<unknown, unknown>;
  /** Max transport-level retry attempts. Default `5`. */
  times?: number;
}

const defaultGuardSchedule = Schedule.min([
  Schedule.exponential("500 millis"),
  Schedule.spaced("3 seconds"),
]);

/**
 * Guard an `HttpClient` against edge-generated bodies on a freshly deployed
 * Worker URL.
 *
 * Protocol clients like effect RPC's `layerProtocolHttp` never inspect the
 * response status or content-type — they pipe the raw body straight into the
 * serialization parser, so every edge-generated HTML page (the workers.dev
 * placeholder, which serves with HTTP **200**; 1101/1102 error pages;
 * 429/1015 rate limits) surfaces as an opaque decode defect (e.g.
 * `RpcClientDefect: Error decoding HTTP response`).
 *
 * This transform rejects any response whose `content-type` doesn't match the
 * expected one as a typed `HttpClientError` that records the status + a body
 * snippet — so a failure names its cause — and retries the request through a
 * bounded schedule so callers ride out the cold-start window
 * ({@link WorkerNotReady} documents why this belongs at the call site).
 */
export const guardContentType =
  (contentType: string, options?: EdgeGuardOptions) =>
  (client: HttpClient.HttpClient): HttpClient.HttpClient =>
    client.pipe(
      HttpClient.transform((effect, request) =>
        Effect.flatMap(effect, (response) => {
          const observed = response.headers["content-type"] ?? "";
          if (observed.includes(contentType)) {
            return Effect.succeed(response);
          }
          return response.text.pipe(
            Effect.orElseSucceed(() => "<unreadable body>"),
            Effect.flatMap((body) =>
              Effect.fail(
                new HttpClientError({
                  reason: new DecodeError({
                    request,
                    response,
                    description: `expected "${contentType}", got "${observed}" (status ${response.status}): ${body.slice(0, 200)}`,
                  }),
                }),
              ),
            ),
          );
        }),
      ),
      HttpClient.retry({
        schedule: options?.schedule ?? defaultGuardSchedule,
        times: options?.times ?? 5,
      }),
    );

/**
 * A fetch-backed `HttpClient` layer wrapped with {@link guardContentType}.
 *
 * Deliberately a standalone layer rather than a transform of the ambient
 * test `HttpClient`: the ambient client also serves the engine's own cloud
 * API calls during `deploy`/`destroy` and distilled SDK calls in
 * `test.provider` bodies, which must NOT be subjected to this guard.
 */
export const guardedFetchLayer = (
  contentType: string,
  options?: EdgeGuardOptions,
): Layer.Layer<HttpClient.HttpClient> =>
  Layer.effect(HttpClient.HttpClient)(
    Effect.gen(function* () {
      const client = yield* HttpClient.HttpClient;
      return guardContentType(contentType, options)(client);
    }),
  ).pipe(Layer.provide(FetchHttpClient.layer));

/**
 * Complete RPC-over-HTTP client transport for driving a deployed Worker:
 * `RpcClient.layerProtocolHttp` + the given serialization (ndjson by
 * default) + a {@link guardedFetchLayer} expecting that serialization's
 * content-type.
 *
 * ```ts
 * const client = yield* RpcClient.make(WorkerRpcs);
 * // ...
 * }).pipe(Effect.scoped, Effect.provide(Test.Http.rpcClientLayer(url)));
 * ```
 */
export const rpcClientLayer = (
  url: string,
  options?: EdgeGuardOptions & {
    /** RPC wire serialization. Default {@link RpcSerialization.ndjson}. */
    serialization?: RpcSerialization.RpcSerialization["Service"];
    /**
     * Set `false` to skip the edge guard entirely and use a plain fetch
     * transport — e.g. for a test that asserts on the raw edge behavior
     * itself. Default `true`.
     */
    guard?: boolean;
  },
): Layer.Layer<RpcClient.Protocol> => {
  const serialization = options?.serialization ?? RpcSerialization.ndjson;
  return RpcClient.layerProtocolHttp({ url }).pipe(
    Layer.provide(
      options?.guard === false
        ? FetchHttpClient.layer
        : guardedFetchLayer(serialization.contentType, options),
    ),
    Layer.provide(Layer.succeed(RpcSerialization.RpcSerialization, serialization)),
  );
};