Skip to content

Context7 Platform -- Up-to-date docs for AI agents

17.2 KB
Raw Blame
import { describe, test, expect, vi, afterEach } from "vitest";
import { HttpClient } from "./index";
import { Context7Error, Context7JSONParseError, Context7UrlError } from "@error";

function newClient(): HttpClient {
  return new HttpClient({
    baseUrl: "https://example.com/api",
    retry: false,
  });
}

function mockFetch(response: Response) {
  vi.stubGlobal(
    "fetch",
    vi.fn(() => Promise.resolve(response))
  );
}

describe("HttpClient error handling", () => {
  afterEach(() => {
    vi.unstubAllGlobals();
    vi.useRealTimers();
  });

  test("does not retry network errors when retries are disabled", async () => {
    const fetchMock = vi.fn().mockRejectedValue(new Error("network unavailable"));
    vi.stubGlobal("fetch", fetchMock);

    const error = await newClient()
      .request({ path: ["search"] })
      .catch((e) => e);

    expect(error).toBeInstanceOf(Context7Error);
    expect(error).toMatchObject({
      message: "network unavailable",
      code: "network_error",
      retryable: true,
    });
    expect(error.cause).toBeInstanceOf(Error);
    expect(fetchMock).toHaveBeenCalledOnce();
  });

  test("retries transient HTTP responses and reports every attempt", async () => {
    const onResponse = vi.fn();
    const fetchMock = vi
      .fn()
      .mockResolvedValueOnce(new Response("unavailable", { status: 503 }))
      .mockResolvedValueOnce(
        new Response(JSON.stringify({ ok: true }), {
          status: 200,
          headers: { "content-type": "application/json", "x-request-id": "req-success" },
        })
      );
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      fetch: fetchMock,
      retry: { retries: 1, backoff: () => 0 },
      onResponse,
    });

    await expect(client.request({ method: "GET", path: ["search"] })).resolves.toEqual({
      result: { ok: true },
    });
    expect(fetchMock).toHaveBeenCalledTimes(2);
    expect(onResponse).toHaveBeenNthCalledWith(1, { status: 503, attempt: 0 });
    expect(onResponse).toHaveBeenNthCalledWith(2, {
      status: 200,
      attempt: 1,
      requestId: "req-success",
    });
  });

  test("resolves a fresh auth token for every retry attempt", async () => {
    const authToken = vi
      .fn<() => Promise<string>>()
      .mockResolvedValueOnce("oidc-token-1")
      .mockResolvedValueOnce("oidc-token-2");
    const fetchMock = vi
      .fn()
      .mockResolvedValueOnce(new Response("unavailable", { status: 503 }))
      .mockResolvedValueOnce(new Response("ok"));
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      authToken,
      fetch: fetchMock,
      retry: { retries: 1, backoff: () => 0 },
    });

    await expect(client.request({ method: "GET", path: ["search"] })).resolves.toEqual({
      result: "ok",
      headers: undefined,
    });

    expect(authToken).toHaveBeenCalledTimes(2);
    expect(fetchMock.mock.calls[0]?.[1]).toMatchObject({
      headers: expect.objectContaining({ Authorization: "Bearer oidc-token-1" }),
    });
    expect(fetchMock.mock.calls[1]?.[1]).toMatchObject({
      headers: expect.objectContaining({ Authorization: "Bearer oidc-token-2" }),
    });
  });

  test("honors Retry-After before retrying a rate-limited request", async () => {
    vi.useFakeTimers();
    const fetchMock = vi
      .fn()
      .mockResolvedValueOnce(
        new Response("rate limited", { status: 429, headers: { "retry-after": "1" } })
      )
      .mockResolvedValueOnce(new Response("ok"));
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      fetch: fetchMock,
      retry: { retries: 1, backoff: () => 0 },
      timeout: false,
    });

    const request = client.request({ method: "GET", path: ["search"] });
    await vi.advanceTimersByTimeAsync(999);
    expect(fetchMock).toHaveBeenCalledOnce();
    await vi.advanceTimersByTimeAsync(1);

    await expect(request).resolves.toEqual({ result: "ok", headers: undefined });
    expect(fetchMock).toHaveBeenCalledTimes(2);
  });

  test("times out while an auth token provider is still pending", async () => {
    vi.useFakeTimers();
    const authToken = vi.fn(() => new Promise<string>(() => {}));
    const fetchMock = vi.fn();
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      authToken,
      fetch: fetchMock,
      timeout: 25,
    });
    const onError = vi.fn();
    const request = client.request({ method: "GET" }).catch(onError);

    await vi.advanceTimersByTimeAsync(25);

    expect(onError).toHaveBeenCalledWith(
      expect.objectContaining({ code: "request_timeout", retryable: true })
    );
    await request;
    expect(authToken).toHaveBeenCalledOnce();
    expect(fetchMock).not.toHaveBeenCalled();
    expect(vi.getTimerCount()).toBe(0);
  });

  test.each(["resolve", "reject"] as const)(
    "cancels a pending token wait and handles a late provider %s",
    async (settlement) => {
      vi.useFakeTimers();
      const controller = new AbortController();
      let resolveToken!: (token: string) => void;
      let rejectToken!: (error: Error) => void;
      const authToken = vi.fn(
        () =>
          new Promise<string>((resolve, reject) => {
            resolveToken = resolve;
            rejectToken = reject;
          })
      );
      const fetchMock = vi.fn();
      const client = new HttpClient({
        baseUrl: "https://example.com/api",
        authToken,
        fetch: fetchMock,
        timeout: false,
      });
      const onError = vi.fn();
      const request = client.request({ method: "GET", signal: controller.signal }).catch(onError);
      const reason = new Error("User cancelled");
      controller.abort(reason);
      await vi.advanceTimersByTimeAsync(0);

      expect(onError).toHaveBeenCalledWith(
        expect.objectContaining({ code: "request_aborted", retryable: false, cause: reason })
      );
      await request;

      if (settlement === "resolve") resolveToken("late-token");
      else rejectToken(new Error("Late provider failure"));
      await vi.advanceTimersByTimeAsync(0);

      expect(onError).toHaveBeenCalledOnce();
      expect(authToken).toHaveBeenCalledOnce();
      expect(fetchMock).not.toHaveBeenCalled();
    }
  );

  test("handles cancellation triggered synchronously by the token provider", async () => {
    const controller = new AbortController();
    const fetchMock = vi.fn();
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      authToken: () => {
        controller.abort();
        return Promise.reject(new Error("Provider failed after cancellation"));
      },
      fetch: fetchMock,
    });

    await expect(client.request({ signal: controller.signal })).rejects.toMatchObject({
      code: "request_aborted",
      retryable: false,
    });
    expect(fetchMock).not.toHaveBeenCalled();
  });

  test.each([true, false])("preserves token provider errors with timeout=%s", async (timeout) => {
    const providerError = new Error("Token service unavailable");
    const authToken = vi.fn().mockRejectedValue(providerError);
    const fetchMock = vi.fn();
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      authToken,
      fetch: fetchMock,
      timeout: timeout ? 25 : false,
    });

    await expect(client.request({ method: "GET" })).rejects.toBe(providerError);
    expect(authToken).toHaveBeenCalledOnce();
    expect(fetchMock).not.toHaveBeenCalled();
  });

  test("uses the last failure when a retry later fails on the network", async () => {
    const fetchMock = vi
      .fn()
      .mockResolvedValueOnce(new Response("unavailable", { status: 503 }))
      .mockRejectedValueOnce(new Error("connection reset"));
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      fetch: fetchMock,
      retry: { retries: 1, backoff: () => 0 },
    });

    const error = await client.request({ method: "GET", path: ["search"] }).catch((e) => e);

    expect(error).toMatchObject({ code: "network_error", message: "connection reset" });
  });

  test("does not retry POST requests", async () => {
    const fetchMock = vi.fn().mockResolvedValue(new Response("unavailable", { status: 503 }));
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      fetch: fetchMock,
      retry: { retries: 3, backoff: () => 0 },
    });

    await expect(client.request({ method: "POST", path: ["refresh"] })).rejects.toMatchObject({
      status: 503,
      retryable: true,
    });
    expect(fetchMock).toHaveBeenCalledOnce();
  });

  test("times out a request without retrying after the abort", async () => {
    vi.useFakeTimers();
    const fetchMock = vi.fn((_url: string | URL, init?: RequestInit) => {
      return new Promise<Response>((_resolve, reject) => {
        init?.signal?.addEventListener("abort", () => reject(init.signal?.reason), { once: true });
      });
    });
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      fetch: fetchMock,
      timeout: 25,
    });

    const request = client.request({ path: ["search"] }).catch((e) => e);
    await vi.advanceTimersByTimeAsync(25);
    const error = await request;

    expect(error).toMatchObject({
      code: "request_timeout",
      message: "Request timed out",
      retryable: true,
    });
    expect(fetchMock).toHaveBeenCalledOnce();
  });

  test("reports a timeout when the deadline expires during retry backoff", async () => {
    vi.useFakeTimers();
    const fetchMock = vi.fn().mockResolvedValue(new Response("unavailable", { status: 503 }));
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      fetch: fetchMock,
      retry: { retries: 1, backoff: () => 1_000 },
      timeout: 25,
    });

    const request = client.request({ method: "GET", path: ["search"] }).catch((e) => e);
    await vi.advanceTimersByTimeAsync(25);
    const error = await request;

    expect(error).toMatchObject({
      code: "request_timeout",
      message: "Request timed out",
      retryable: true,
    });
    expect(fetchMock).toHaveBeenCalledOnce();
  });

  test("honors a per-request abort signal", async () => {
    const controller = new AbortController();
    const fetchMock = vi.fn((_url: string | URL, init?: RequestInit) => {
      return new Promise<Response>((_resolve, reject) => {
        init?.signal?.addEventListener("abort", () => reject(init.signal?.reason), { once: true });
      });
    });
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      fetch: fetchMock,
      timeout: false,
    });

    const request = client.request({ path: ["search"], signal: controller.signal }).catch((e) => e);
    controller.abort();
    const error = await request;

    expect(error).toMatchObject({
      code: "request_aborted",
      message: "Request was aborted",
      retryable: false,
    });
    expect(fetchMock).toHaveBeenCalledOnce();
  });

  test("does not call fetch for a signal that is already aborted", async () => {
    const controller = new AbortController();
    controller.abort();
    const fetchMock = vi.fn();
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      fetch: fetchMock,
      timeout: false,
    });

    const error = await client
      .request({ path: ["search"], signal: controller.signal })
      .catch((e) => e);

    expect(error).toMatchObject({ code: "request_aborted" });
    expect(fetchMock).not.toHaveBeenCalled();
  });

  test("does not treat response observer failures as network failures", async () => {
    const observerError = new Error("observer failed");
    const fetchMock = vi.fn().mockResolvedValue(new Response("ok"));
    const client = new HttpClient({
      baseUrl: "https://example.com/api",
      fetch: fetchMock,
      retry: { retries: 3, backoff: () => 0 },
      onResponse: () => {
        throw observerError;
      },
    });

    await expect(client.request({ path: ["search"] })).rejects.toBe(observerError);
    expect(fetchMock).toHaveBeenCalledOnce();
  });

  test("throws Context7Error with message from JSON error body", async () => {
    mockFetch(
      new Response(JSON.stringify({ error: "rate limit exceeded" }), {
        status: 429,
        headers: { "content-type": "application/json" },
      })
    );

    const error = await newClient()
      .request({ path: ["search"] })
      .catch((e) => e);

    expect(error).toBeInstanceOf(Context7Error);
    expect(error).toMatchObject({
      message: "rate limit exceeded",
      code: "rate limit exceeded",
      status: 429,
      retryable: true,
    });
  });

  test("falls back to message field when error field is absent", async () => {
    mockFetch(
      new Response(JSON.stringify({ message: "something went wrong" }), {
        status: 400,
        headers: { "content-type": "application/json" },
      })
    );

    const error = await newClient()
      .request({ path: ["search"] })
      .catch((e) => e);

    expect(error).toBeInstanceOf(Context7Error);
    expect(error.message).toBe("something went wrong");
  });

  test("includes status, error code, request ID, and rate limits on API errors", async () => {
    mockFetch(
      new Response(JSON.stringify({ error: "rate_limit_exceeded", message: "Try again later" }), {
        status: 429,
        headers: {
          "content-type": "application/json",
          "x-request-id": "req-123",
          "ratelimit-limit": "100",
          "ratelimit-remaining": "0",
          "ratelimit-reset": "1700000000",
          "retry-after": "12",
        },
      })
    );

    const error = await newClient()
      .request({ path: ["search"] })
      .catch((e) => e);

    expect(error).toMatchObject({
      message: "Try again later",
      code: "rate_limit_exceeded",
      status: 429,
      requestId: "req-123",
      rateLimit: {
        limit: 100,
        remaining: 0,
        reset: 1700000000,
        retryAfter: 12,
      },
    });
  });

  test("throws Context7Error (not SyntaxError) on non-JSON error body", async () => {
    mockFetch(
      new Response("<html><body>502 Bad Gateway</body></html>", {
        status: 502,
        statusText: "Bad Gateway",
        headers: { "content-type": "text/html" },
      })
    );

    const error = await newClient()
      .request({ path: ["search"] })
      .catch((e) => e);

    expect(error).toBeInstanceOf(Context7Error);
    expect(error).not.toBeInstanceOf(SyntaxError);
    expect(error.message).toBe("Bad Gateway");
  });

  test("throws a structured parse error for malformed JSON responses", async () => {
    const body = "{" + "x".repeat(250);
    mockFetch(
      new Response(body, {
        status: 200,
        headers: { "content-type": "application/json", "x-request-id": "req-json" },
      })
    );

    const error = await newClient()
      .request({ path: ["search"] })
      .catch((e) => e);

    expect(error).toBeInstanceOf(Context7JSONParseError);
    expect(error).toMatchObject({
      code: "invalid_json_response",
      status: 200,
      requestId: "req-json",
    });
    expect(error.message).toHaveLength("Unable to parse response body: ".length + 203);
    expect(error.cause).toBeInstanceOf(SyntaxError);
  });

  test("keeps HTTP metadata when an error response contains malformed JSON", async () => {
    mockFetch(
      new Response("{invalid", {
        status: 502,
        headers: { "content-type": "application/json", "x-request-id": "req-bad-json" },
      })
    );

    const error = await newClient()
      .request({ path: ["search"] })
      .catch((e) => e);

    expect(error).toBeInstanceOf(Context7JSONParseError);
    expect(error).toMatchObject({
      code: "invalid_json_response",
      status: 502,
      requestId: "req-bad-json",
      retryable: true,
    });
  });

  test("rejects invalid base URLs", () => {
    expect(() => new HttpClient({ baseUrl: "example.com" })).toThrow(Context7UrlError);
    expect(() => new HttpClient({ baseUrl: "ftp://example.com" })).toThrow(Context7UrlError);
    expect(() => new HttpClient({ baseUrl: " https://example.com" })).toThrow(Context7UrlError);
    expect(() => new HttpClient({ baseUrl: "https://example.com\n" })).toThrow(Context7UrlError);
  });

  test("falls back to statusText on empty error body", async () => {
    mockFetch(new Response("", { status: 503, statusText: "Service Unavailable" }));

    const error = await newClient()
      .request({ path: ["search"] })
      .catch((e) => e);

    expect(error).toBeInstanceOf(Context7Error);
    expect(error.message).toBe("Service Unavailable");
  });

  test("falls back to statusText when a JSON error body is null", async () => {
    mockFetch(
      new Response("null", {
        status: 500,
        statusText: "Internal Server Error",
        headers: { "content-type": "application/json" },
      })
    );

    const error = await newClient()
      .request({ method: "GET", path: ["search"] })
      .catch((e) => e);

    expect(error).toBeInstanceOf(Context7Error);
    expect(error).toMatchObject({
      message: "Internal Server Error",
      code: "http_error",
      status: 500,
    });
  });

  test("validates timeout and retry configuration", () => {
    expect(() => new HttpClient({ baseUrl: "https://example.com", timeout: 0 })).toThrowError(
      "timeout must be a positive number or false"
    );
    expect(
      () => new HttpClient({ baseUrl: "https://example.com", retry: { retries: -1 } })
    ).toThrowError("retry.retries must be a non-negative integer");
  });
});