sailfork / t3code-github / .repos/ effect/ ai-docs/ src/ 52_graphql/ 50_errors-and-retries.ts

/**
 * @title Handling GraphQL errors, retries and rate limits
 *
 * Read rate-limit headers in a middleware, tell GraphQL errors apart by their
 * fields, and retry timeouts and rate limits with `Effect.retry`.
 */
import { Duration, Effect, Layer, Schedule } from "effect"
import { type GraphQLClientError, GraphQLMiddleware } from "effect/graphql"
import { GitHub } from "./10_basics.ts"

// Middleware see each response's HTTP `status` and `headers` on the result
// `next` returns, including responses with GraphQL `errors`. A failed call
// keeps them, and `GraphQLClientError` exposes them as `headers` and
// `status`. Attach it with `GraphQLGroup.make(...).middleware(RateLimit)`.
export class RateLimit extends GraphQLMiddleware.Service<RateLimit>()("app/RateLimit") {
  static readonly layer = Layer.succeed(RateLimit, {
    execute: ({ next, request }) =>
      Effect.tap(next(request), (result) => {
        const remaining = Number(result.headers?.["x-ratelimit-remaining"])
        return remaining < 500
          ? Effect.logWarning(`GitHub rate limit: ${remaining} points left`)
          : Effect.void
      }),
    subscribe: ({ next, request }) => next(request)
  })
}

// GraphQL errors keep fields the specification doesn't define as JSON, such
// as GitHub's top-level `type` (`NOT_FOUND`, `FORBIDDEN`, `RATE_LIMITED`).
export const hasErrorType = (error: GraphQLClientError.GraphQLClientError, type: string) =>
  error.reason._tag === "ResponseError" && error.reason.errors.every((entry) => entry.type === type)

// `isRetryable` is true for network failures, for 429 or 5xx responses, and
// for any error with a `Retry-After` header, whatever its status. That covers
// GitHub's 502 and 504 query timeouts, even with a GraphQL `errors` body, and
// its secondary rate limits (403 or 429 with `retry-after`). A primary rate
// limit can come without `retry-after`, with `x-ratelimit-remaining: 0`, so
// check that header too.
const rateLimited = (error: GraphQLClientError.GraphQLClientError) => error.headers?.["x-ratelimit-remaining"] === "0"

// Wait for `retryAfter` when it is set, and until `x-ratelimit-reset` (epoch
// seconds) on a primary rate limit. GitHub may ban an integration that keeps
// retrying while rate limited, so don't retry with a plain backoff.
const gitHubRetry = Schedule.exponential("1 second").pipe(
  Schedule.setInputType<GraphQLClientError.GraphQLClientError>(),
  Schedule.modifyDelay(({ duration, input, now }) => {
    if (input.retryAfter !== undefined) return Effect.succeed(input.retryAfter)
    if (!rateLimited(input)) return Effect.succeed(duration)
    const reset = Number(input.headers?.["x-ratelimit-reset"]) * 1000
    return Effect.succeed(Number.isFinite(reset) ? Duration.millis(Math.max(0, reset - now)) : Duration.minutes(1))
  })
)

// The client never retries queries or mutations on its own. Retry only
// mutations that are safe to send twice, and with `GraphQLClient.pages`,
// retry inside a middleware, because `Stream.retry` starts again from the
// first page. Subscriptions reconnect on their own after a retryable failure,
// on `GraphQLClient.defaultSubscriptionRetry`, which waits for `retryAfter`.
// A primary rate limit without `retry-after` isn't retryable, so it ends the
// subscription; wait until `x-ratelimit-reset` before subscribing again.
export const retryGitHub = <A, R>(effect: Effect.Effect<A, GraphQLClientError.GraphQLClientError, R>) =>
  Effect.retry(effect, {
    schedule: gitHubRetry,
    while: (error) => error.isRetryable || rateLimited(error),
    times: 5
  })

export const program = Effect.gen(function*() {
  const github = yield* GitHub
  const result = yield* retryGitHub(github.RepoIssues({ owner: "Effect-TS", name: "missing" })).pipe(
    Effect.catchIf((error) => hasErrorType(error, "NOT_FOUND"), () => Effect.succeed(null))
  )
  yield* Effect.log(result === null ? "No such repository" : `${result.repository?.issues.nodes?.length} issues`)
}).pipe(Effect.provide(GitHub.layer))