@oneuptime/common 12.0.33 → 12.0.34

package/Tests/Utils/API.test.ts

@@ -8,9 +8,11 @@ import Route from "../../Types/API/Route";
 import URL from "../../Types/API/URL";
 import Dictionary from "../../Types/Dictionary";
 import APIException from "../../Types/Exception/ApiException";
+import BadDataException from "../../Types/Exception/BadDataException";
 import GenericObject from "../../Types/GenericObject";
 import { JSONObject } from "../../Types/JSON";
 import API from "../../Utils/API";
+import { HTTPResponseBodyBudget } from "../../Utils/HTTPResponseBodyReader";
 import { expect, jest } from "@jest/globals";
 import axios, {
   AxiosError,
@@ -20,6 +22,7 @@ import axios, {
   AxiosStatic,
   Method,
 } from "axios";
+import { Readable } from "stream";
 
 const DEFAULT_HEADERS: Headers = {
   Accept: "application/json",
@@ -519,6 +522,311 @@ describe("API instance properties", () => {
 });
 
 describe("API.fetch with options", () => {
+  test("should forward response and request byte limits and disable implicit proxies", async () => {
+    mockedAxios.mockClear();
+    mockedAxios.mockResolvedValueOnce(
+      createAxiosResponse({ data: responseData }),
+    );
+
+    await API.fetch({
+      method: HTTPMethod.GET,
+      url: new URL(Protocol.HTTPS, "api.example.com", new Route("items")),
+      options: {
+        maxContentLength: 1024,
+        maxBodyLength: 2048,
+        disableProxy: true,
+      },
+    });
+
+    expect(mockedAxios.mock.calls[0]![0]).toMatchObject({
+      maxContentLength: 1024,
+      maxBodyLength: 2048,
+      proxy: false,
+    });
+  });
+
+  test("should preserve explicit zero-byte limits", async () => {
+    mockedAxios.mockClear();
+    mockedAxios.mockResolvedValueOnce(
+      createAxiosResponse({ data: responseData }),
+    );
+
+    await API.fetch({
+      method: HTTPMethod.GET,
+      url: new URL(Protocol.HTTPS, "api.example.com", new Route("items")),
+      options: {
+        maxContentLength: 0,
+        maxBodyLength: 0,
+      },
+    });
+
+    expect(mockedAxios.mock.calls[0]![0]).toMatchObject({
+      maxContentLength: 0,
+      maxBodyLength: 0,
+    });
+  });
+
+  test("should leave byte limits and proxy routing unset by default", async () => {
+    mockedAxios.mockClear();
+    mockedAxios.mockResolvedValueOnce(
+      createAxiosResponse({ data: responseData }),
+    );
+
+    await API.fetch({
+      method: HTTPMethod.GET,
+      url: new URL(Protocol.HTTPS, "api.example.com", new Route("items")),
+    });
+
+    const requestConfig: AxiosRequestConfig = mockedAxios.mock
+      .calls[0]![0] as AxiosRequestConfig;
+    expect(requestConfig).not.toHaveProperty("maxContentLength");
+    expect(requestConfig).not.toHaveProperty("maxBodyLength");
+    expect(requestConfig).not.toHaveProperty("proxy");
+  });
+
+  test("should use an internal validated dispatch URL without normalizing its path or query", async () => {
+    mockedAxios.mockClear();
+    mockedAxios.mockResolvedValueOnce(
+      createAxiosResponse({ data: responseData }),
+    );
+    const dispatchUrl: string = "https://api.example.com/a//b?tag=one&tag=two";
+
+    await API.fetch({
+      method: HTTPMethod.GET,
+      url: new URL(Protocol.HTTPS, "api.example.com", new Route("reported")),
+      options: { dispatchUrl: dispatchUrl },
+    });
+
+    expect((mockedAxios.mock.calls[0]![0] as AxiosRequestConfig).url).toBe(
+      dispatchUrl,
+    );
+  });
+
+  test("should forward AbortSignal and normalize a budgeted JSON stream", async () => {
+    mockedAxios.mockClear();
+    const controller: AbortController = new AbortController();
+    const json: string = JSON.stringify(responseData);
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(1024);
+    mockedAxios.mockResolvedValueOnce(
+      createAxiosResponse({
+        data: Readable.from([Buffer.from(json)]),
+        status: 200,
+      }),
+    );
+
+    const response: HTTPResponse<JSONObject> = await API.fetch({
+      method: HTTPMethod.GET,
+      url: new URL(
+        Protocol.HTTPS,
+        "api.example.com",
+        new Route("streamed-json"),
+      ),
+      options: {
+        signal: controller.signal,
+        responseBodyBudget: budget,
+        limitRedirectResponseBody: true,
+      },
+    });
+
+    expect(mockedAxios.mock.calls[0]![0]).toMatchObject({
+      signal: controller.signal,
+      responseType: "stream",
+      maxContentLength: -1,
+    });
+    expect(response.data).toEqual(responseData);
+    expect(budget.remainingBytes).toBe(1024 - Buffer.byteLength(json));
+  });
+
+  test("should strip a leading UTF-8 BOM before parsing a budgeted JSON stream", async () => {
+    mockedAxios.mockClear();
+    const bodyText: string = `\uFEFF${JSON.stringify(responseData)}`;
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(1024);
+    mockedAxios.mockResolvedValueOnce(
+      createAxiosResponse({
+        data: Readable.from([Buffer.from(bodyText)]),
+        status: 200,
+      }),
+    );
+
+    const response: HTTPResponse<JSONObject> = await API.fetch({
+      method: HTTPMethod.GET,
+      url: new URL(
+        Protocol.HTTPS,
+        "api.example.com",
+        new Route("streamed-json-bom"),
+      ),
+      options: { responseBodyBudget: budget },
+    });
+
+    expect(response.data).toEqual(responseData);
+    expect(budget.remainingBytes).toBe(1024 - Buffer.byteLength(bodyText));
+  });
+
+  test("should enforce a per-response cap without lowering the shared budget", async () => {
+    mockedAxios.mockClear();
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(100);
+    const body: Readable = Readable.from([Buffer.from("12345")]);
+    mockedAxios.mockResolvedValueOnce(
+      createAxiosResponse({ data: body, status: 200 }),
+    );
+
+    await expect(
+      API.fetch({
+        method: HTTPMethod.GET,
+        url: new URL(
+          Protocol.HTTPS,
+          "api.example.com",
+          new Route("per-response-cap"),
+        ),
+        options: {
+          responseBodyBudget: budget,
+          maximumResponseBytes: 4,
+        },
+      }),
+    ).rejects.toBeInstanceOf(BadDataException);
+
+    expect(body.destroyed).toBe(true);
+    expect(budget.remainingBytes).toBe(95);
+  });
+
+  test("should allow HEAD Content-Length to describe a larger hypothetical GET body", async () => {
+    mockedAxios.mockClear();
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(4);
+    mockedAxios.mockResolvedValueOnce(
+      createAxiosResponse({
+        data: Readable.from([]),
+        status: 200,
+        headers: { "Content-Length": "1000000" },
+      }),
+    );
+
+    await expect(
+      API.fetch({
+        method: HTTPMethod.HEAD,
+        url: new URL(
+          Protocol.HTTPS,
+          "api.example.com",
+          new Route("head-content-length"),
+        ),
+        options: { responseBodyBudget: budget },
+      }),
+    ).resolves.toBeInstanceOf(HTTPResponse);
+    expect(budget.remainingBytes).toBe(4);
+  });
+
+  test("should normalize a streamed Axios error before constructing HTTPErrorResponse", async () => {
+    mockedAxios.mockClear();
+    HTTPErrorResponseMock.mockClear();
+    const errorBody: JSONObject = { message: "redirect response" };
+    const serializedBody: string = JSON.stringify(errorBody);
+    const responseHeaders: Headers = {
+      Location: "https://api.example.com/final",
+    };
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(100, 32);
+    mockedAxios.mockRejectedValueOnce(
+      createAxiosError({
+        response: createAxiosResponse({
+          status: 302,
+          data: Readable.from([Buffer.from(serializedBody)]),
+          headers: responseHeaders,
+        }),
+      }),
+    );
+
+    await API.fetch({
+      method: HTTPMethod.GET,
+      url: new URL(Protocol.HTTPS, "api.example.com", new Route("redirect")),
+      options: {
+        responseBodyBudget: budget,
+        limitRedirectResponseBody: true,
+      },
+    });
+
+    expect(HTTPErrorResponseMock).toHaveBeenCalledWith(
+      302,
+      errorBody,
+      responseHeaders,
+    );
+    expect(budget.remainingBytes).toBe(100 - Buffer.byteLength(serializedBody));
+  });
+
+  test("should preserve streamed non-JSON response text", async () => {
+    mockedAxios.mockClear();
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(20);
+    mockedAxios.mockResolvedValueOnce(
+      createAxiosResponse({
+        data: Readable.from([Buffer.from("plain response")]),
+      }),
+    );
+
+    const response: HTTPResponse<JSONObject> = await API.fetch({
+      method: HTTPMethod.GET,
+      url: new URL(
+        Protocol.HTTPS,
+        "api.example.com",
+        new Route("streamed-text"),
+      ),
+      options: { responseBodyBudget: budget },
+    });
+
+    expect(response.data).toEqual({ data: "plain response" });
+    expect(budget.remainingBytes).toBe(6);
+  });
+
+  test("should never retry a successful response whose streamed body exceeds the budget", async () => {
+    mockedAxios.mockClear();
+    const oversizedBody: Readable = Readable.from([Buffer.from("12345")]);
+    mockedAxios.mockResolvedValue(
+      createAxiosResponse({ data: oversizedBody, status: 200 }),
+    );
+
+    await expect(
+      API.fetch({
+        method: HTTPMethod.GET,
+        url: new URL(Protocol.HTTPS, "api.example.com", new Route("oversized")),
+        options: {
+          retries: 5,
+          responseBodyBudget: new HTTPResponseBodyBudget(4),
+        },
+      }),
+    ).rejects.toBeInstanceOf(BadDataException);
+
+    expect(mockedAxios).toHaveBeenCalledTimes(1);
+    expect(oversizedBody.destroyed).toBe(true);
+  });
+
+  test("should charge separate API calls against the same cumulative budget", async () => {
+    mockedAxios.mockClear();
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(6);
+    const secondBody: Readable = Readable.from([Buffer.from("defg")]);
+    mockedAxios
+      .mockResolvedValueOnce(
+        createAxiosResponse({ data: Readable.from([Buffer.from("abc")]) }),
+      )
+      .mockResolvedValueOnce(createAxiosResponse({ data: secondBody }));
+    const request: () => Promise<HTTPResponse<JSONObject>> = async (): Promise<
+      HTTPResponse<JSONObject>
+    > => {
+      return await API.fetch({
+        method: HTTPMethod.GET,
+        url: new URL(
+          Protocol.HTTPS,
+          "api.example.com",
+          new Route("cumulative"),
+        ),
+        options: { responseBodyBudget: budget },
+      });
+    };
+
+    await expect(request()).resolves.toMatchObject({
+      data: { data: "abc" },
+    });
+    expect(budget.remainingBytes).toBe(3);
+    await expect(request()).rejects.toBeInstanceOf(BadDataException);
+    expect(secondBody.destroyed).toBe(true);
+    expect(budget.remainingBytes).toBe(0);
+  });
+
   test("should make request with query parameters", async () => {
     mockedAxios.mockResolvedValueOnce(
       createAxiosResponse({ data: responseData }),

package/Tests/Utils/HTTPResponseBodyReader.test.ts

@@ -0,0 +1,323 @@
+import { describe, expect, test } from "@jest/globals";
+import BadDataException from "../../Types/Exception/BadDataException";
+import HTTPResponseBodyReader, {
+  HTTPResponseBodyBudget,
+} from "../../Utils/HTTPResponseBodyReader";
+import { Readable } from "stream";
+
+const read: (
+  body: AsyncIterable<unknown>,
+  budget: HTTPResponseBodyBudget,
+  options?: {
+    statusCode?: number;
+    limitRedirectResponseBody?: boolean;
+    headers?: unknown;
+    isHeadResponse?: boolean;
+    maximumResponseBytes?: number;
+  },
+) => Promise<Buffer> = async (
+  body: AsyncIterable<unknown>,
+  budget: HTTPResponseBodyBudget,
+  options: {
+    statusCode?: number;
+    limitRedirectResponseBody?: boolean;
+    headers?: unknown;
+    isHeadResponse?: boolean;
+    maximumResponseBytes?: number;
+  } = {},
+): Promise<Buffer> => {
+  return await HTTPResponseBodyReader.read(body, {
+    budget: budget,
+    statusCode: options.statusCode ?? 200,
+    limitRedirectResponseBody: options.limitRedirectResponseBody ?? true,
+    headers: options.headers,
+    isHeadResponse: options.isHeadResponse,
+    maximumResponseBytes: options.maximumResponseBytes,
+  });
+};
+
+describe("HTTPResponseBodyReader", () => {
+  test("charges sequential responses against one cumulative byte budget", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(6);
+
+    await expect(
+      read(Readable.from([Buffer.from("abc")]), budget),
+    ).resolves.toEqual(Buffer.from("abc"));
+    expect(budget.remainingBytes).toBe(3);
+
+    await expect(
+      read(Readable.from([Buffer.from("de")]), budget),
+    ).resolves.toEqual(Buffer.from("de"));
+    expect(budget.remainingBytes).toBe(1);
+
+    await expect(
+      read(Readable.from([Buffer.from("fg")]), budget),
+    ).rejects.toBeInstanceOf(BadDataException);
+  });
+
+  test.each([301, 302, 303, 307, 308])(
+    "applies the smaller redirect cap to status %s",
+    async (statusCode: number) => {
+      const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(100, 4);
+      const body: Readable = Readable.from([Buffer.from("12345")]);
+
+      await expect(
+        read(body, budget, {
+          statusCode: statusCode,
+          limitRedirectResponseBody: true,
+        }),
+      ).rejects.toThrow("exceeded the allowed size");
+      expect(body.destroyed).toBe(true);
+    },
+  );
+
+  test("allows a redirect body to use the full budget when redirects are not followed", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(10, 4);
+
+    await expect(
+      read(Readable.from([Buffer.from("12345")]), budget, {
+        statusCode: 302,
+        limitRedirectResponseBody: false,
+      }),
+    ).resolves.toEqual(Buffer.from("12345"));
+    expect(budget.remainingBytes).toBe(5);
+  });
+
+  test("accepts a redirect body exactly at its smaller cap and charges the shared budget", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(10, 4);
+
+    await expect(
+      read(Readable.from([Buffer.from("1234")]), budget, {
+        statusCode: 308,
+        limitRedirectResponseBody: true,
+      }),
+    ).resolves.toEqual(Buffer.from("1234"));
+    expect(budget.remainingBytes).toBe(6);
+  });
+
+  test("enforces a caller-specific per-response cap while charging the shared budget", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(100);
+    const body: Readable = Readable.from([Buffer.from("12345")]);
+
+    await expect(
+      read(body, budget, {
+        limitRedirectResponseBody: false,
+        maximumResponseBytes: 4,
+      }),
+    ).rejects.toThrow("exceeded the allowed size");
+    expect(body.destroyed).toBe(true);
+    expect(budget.remainingBytes).toBe(95);
+  });
+
+  test("counts UTF-8 bytes rather than JavaScript characters", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(2);
+
+    await expect(
+      read(Readable.from([Buffer.from("é")]), budget),
+    ).resolves.toEqual(Buffer.from("é"));
+    expect(budget.remainingBytes).toBe(0);
+  });
+
+  test("rejects an oversized Content-Length before reading the stream", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(4);
+    const body: Readable = Readable.from([Buffer.from("data")]);
+
+    await expect(
+      read(body, budget, {
+        headers: { "Content-Length": "5" },
+      }),
+    ).rejects.toThrow("exceeded the allowed size");
+    expect(body.destroyed).toBe(true);
+    expect(budget.remainingBytes).toBe(4);
+  });
+
+  test("ignores hypothetical Content-Length on HEAD while still counting actual bytes", async () => {
+    const emptyBudget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(4);
+
+    await expect(
+      read(Readable.from([]), emptyBudget, {
+        headers: { "Content-Length": "1000000" },
+        isHeadResponse: true,
+      }),
+    ).resolves.toEqual(Buffer.alloc(0));
+    expect(emptyBudget.remainingBytes).toBe(4);
+
+    const nonCompliantBudget: HTTPResponseBodyBudget =
+      new HTTPResponseBodyBudget(4);
+    await expect(
+      read(Readable.from([Buffer.from("12345")]), nonCompliantBudget, {
+        headers: { "Content-Length": "1000000" },
+        isHeadResponse: true,
+      }),
+    ).rejects.toBeInstanceOf(BadDataException);
+    expect(nonCompliantBudget.remainingBytes).toBe(0);
+  });
+
+  test.each([204, 304])(
+    "ignores hypothetical Content-Length on bodyless status %s while still counting actual bytes",
+    async (statusCode: number) => {
+      const emptyBudget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(4);
+
+      await expect(
+        read(Readable.from([]), emptyBudget, {
+          statusCode: statusCode,
+          headers: { "Content-Length": "1000000" },
+        }),
+      ).resolves.toEqual(Buffer.alloc(0));
+      expect(emptyBudget.remainingBytes).toBe(4);
+
+      const nonCompliantBudget: HTTPResponseBodyBudget =
+        new HTTPResponseBodyBudget(4);
+      await expect(
+        read(Readable.from([Buffer.from("12345")]), nonCompliantBudget, {
+          statusCode: statusCode,
+          headers: { "Content-Length": "1000000" },
+        }),
+      ).rejects.toBeInstanceOf(BadDataException);
+      expect(nonCompliantBudget.remainingBytes).toBe(0);
+    },
+  );
+
+  test("supports Axios-style headers with a get method", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(4);
+    const body: Readable = Readable.from([Buffer.from("data")]);
+
+    await expect(
+      read(body, budget, {
+        headers: {
+          get: (name: string): string | undefined => {
+            return name === "content-length" ? "5" : undefined;
+          },
+        },
+      }),
+    ).rejects.toBeInstanceOf(BadDataException);
+    expect(body.destroyed).toBe(true);
+  });
+
+  test("uses the first Content-Length value when a header collection returns an array", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(4);
+    const body: Readable = Readable.from([Buffer.from("data")]);
+
+    await expect(
+      read(body, budget, {
+        headers: { "content-length": ["5", "4"] },
+      }),
+    ).rejects.toThrow("exceeded the allowed size");
+    expect(body.destroyed).toBe(true);
+    expect(budget.remainingBytes).toBe(4);
+  });
+
+  test.each(["not-a-number", "-1", Number.POSITIVE_INFINITY])(
+    "ignores an invalid Content-Length value (%s) and enforces the stream itself",
+    async (contentLength: string | number) => {
+      const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(4);
+
+      await expect(
+        read(Readable.from([Buffer.from("data")]), budget, {
+          headers: { "content-length": contentLength },
+        }),
+      ).resolves.toEqual(Buffer.from("data"));
+      expect(budget.remainingBytes).toBe(0);
+    },
+  );
+
+  test("destroys a chunked stream as soon as it exceeds the remaining budget", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(4);
+    const body: Readable = Readable.from([
+      Buffer.from("12"),
+      Buffer.from("345"),
+      Buffer.from("unread"),
+    ]);
+
+    await expect(read(body, budget)).rejects.toBeInstanceOf(BadDataException);
+    expect(body.destroyed).toBe(true);
+    expect(budget.remainingBytes).toBe(0);
+  });
+
+  test("charges bytes received before the source stream fails", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(20);
+    let nextCallCount: number = 0;
+    const body: AsyncIterable<Buffer> = {
+      [Symbol.asyncIterator](): AsyncIterator<Buffer> {
+        return {
+          next: (): Promise<IteratorResult<Buffer>> => {
+            nextCallCount++;
+            if (nextCallCount === 1) {
+              return Promise.resolve({
+                done: false,
+                value: Buffer.from("partial"),
+              });
+            }
+
+            return Promise.reject(new Error("socket reset while reading"));
+          },
+        };
+      },
+    };
+
+    await expect(read(body, budget)).rejects.toThrow(
+      "socket reset while reading",
+    );
+    expect(budget.remainingBytes).toBe(13);
+  });
+
+  test("rejects a new response after the shared budget is exactly exhausted", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(4);
+    await read(Readable.from([Buffer.from("data")]), budget);
+    const rejectedBody: Readable = Readable.from([Buffer.alloc(0)]);
+
+    await expect(read(rejectedBody, budget)).rejects.toThrow("cumulative size");
+    expect(rejectedBody.destroyed).toBe(true);
+  });
+
+  test("rejects a non-stream body in budgeted mode", async () => {
+    await expect(
+      HTTPResponseBodyReader.read("not-a-stream", {
+        budget: new HTTPResponseBodyBudget(10),
+        statusCode: 200,
+        limitRedirectResponseBody: true,
+      }),
+    ).rejects.toThrow("could not be read");
+  });
+
+  test.each([Number.NaN, Number.POSITIVE_INFINITY, Number.NEGATIVE_INFINITY])(
+    "fails closed for a non-finite constructor limit (%s)",
+    async (invalidLimit: number) => {
+      const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(
+        invalidLimit,
+        invalidLimit,
+      );
+
+      expect(budget.remainingBytes).toBe(0);
+      expect(budget.maxRedirectResponseBytes).toBe(0);
+      await expect(
+        read(Readable.from([Buffer.alloc(0)]), budget),
+      ).rejects.toThrow("cumulative size");
+    },
+  );
+
+  test("clamps negative constructor limits and refuses any response", async () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(-10, -1);
+
+    expect(budget.remainingBytes).toBe(0);
+    expect(budget.maxRedirectResponseBytes).toBe(0);
+    await expect(
+      read(Readable.from([Buffer.alloc(0)]), budget),
+    ).rejects.toThrow("cumulative size");
+  });
+
+  test("rejects invalid direct budget consumption without changing the balance", () => {
+    const budget: HTTPResponseBodyBudget = new HTTPResponseBodyBudget(10);
+
+    expect(() => {
+      budget.consume(-1);
+    }).toThrow("cumulative size");
+    expect(() => {
+      budget.consume(11);
+    }).toThrow("cumulative size");
+    expect(() => {
+      budget.consume(Number.NaN);
+    }).toThrow("cumulative size");
+    expect(budget.remainingBytes).toBe(10);
+  });
+});