@clickup/rest-client 2.10.294 → 2.11.0

package/src/__tests__/RestFetchReader.test.ts

@@ -0,0 +1,150 @@
+import delay from "delay";
+import range from "lodash/range";
+import {
+  BINARY_BUF,
+  consumeIterable,
+  createFetchReader,
+  server,
+  serverAssertConnectionsCount,
+  TimeoutError,
+  UTF8_BUF,
+} from "./helpers";
+
+let ORIGIN: string;
+
+beforeAll(async () => {
+  ORIGIN = await new Promise((resolve) => {
+    server.listen(0, () =>
+      resolve("http://127.0.0.1:" + (server.address() as any).port),
+    );
+  });
+});
+
+beforeEach(async () => {
+  await serverAssertConnectionsCount(0);
+});
+
+test("small_response", async () => {
+  const reader = createFetchReader(`${ORIGIN}/small`);
+  await reader.preload(1024);
+
+  expect(reader.textFetched).toEqual("ok");
+  expect(reader.textIsPartial).toBeFalsy();
+  expect(reader.charsRead).toEqual(reader.textFetched.length);
+
+  for await (const _ of reader) {
+    throw "Must not return any more data";
+  }
+
+  await serverAssertConnectionsCount(0);
+});
+
+test("large_response", async () => {
+  const reader = createFetchReader(`${ORIGIN}/large`);
+  await reader.preload(42);
+  await serverAssertConnectionsCount(1);
+
+  expect(reader.textFetched.length).toBeGreaterThan(1);
+  expect(reader.textFetched.length).toBeLessThan(1024 * 10);
+  expect(reader.textIsPartial).toBeTruthy();
+  expect(reader.charsRead).toEqual(reader.textFetched.length);
+
+  const rest = await consumeIterable(reader);
+  await serverAssertConnectionsCount(0);
+  expect(rest.length).toBeGreaterThan(1);
+  expect(reader.textIsPartial).toBeTruthy();
+  expect(reader.charsRead).toEqual(reader.textFetched.length + rest.length);
+});
+
+test("slow_response", async () => {
+  const reader = createFetchReader(`${ORIGIN}/slow`);
+  await reader.preload(42);
+  await delay(300);
+  await serverAssertConnectionsCount(1);
+  await reader[Symbol.asyncIterator]().return();
+  await serverAssertConnectionsCount(0);
+});
+
+test("small_slow_utf8_response", async () => {
+  const reader = createFetchReader(`${ORIGIN}/small_slow_utf8`);
+  await reader.preload(1);
+  await serverAssertConnectionsCount(1);
+  expect(reader.textFetched.length).toEqual(1);
+  expect(reader.charsRead).toEqual(1);
+  const rest = await consumeIterable(reader);
+  expect(reader.textFetched + rest).toEqual(UTF8_BUF.toString());
+  await serverAssertConnectionsCount(0);
+});
+
+test("too_big_response", async () => {
+  const reader = createFetchReader(`${ORIGIN}/large`, {
+    onAfterRead: (reader) => {
+      if (reader.charsRead > 1024 * 64) {
+        throw Error("too large");
+      }
+    },
+  });
+  await reader.preload(42);
+  await serverAssertConnectionsCount(1);
+  await expect(async () => consumeIterable(reader, 10)).rejects.toThrow(
+    "too large",
+  );
+  await serverAssertConnectionsCount(0);
+});
+
+test("timeout_response_no_preload_long_read_delay", async () => {
+  const reader = createFetchReader(`${ORIGIN}/slow`, { timeoutMs: 200 });
+  await expect(async () => consumeIterable(reader, 500)).rejects.toThrow(
+    TimeoutError,
+  );
+  await serverAssertConnectionsCount(0);
+});
+
+test("timeout_response_no_preload_short_read_delay", async () => {
+  const reader = createFetchReader(`${ORIGIN}/slow`, { timeoutMs: 200 });
+  await expect(async () => consumeIterable(reader, 10)).rejects.toThrow(
+    TimeoutError,
+  );
+  await serverAssertConnectionsCount(0);
+});
+
+test("timeout_in_preload", async () => {
+  const reader = createFetchReader(`${ORIGIN}/slow`, { timeoutMs: 200 });
+  await expect(async () => reader.preload(10000000)).rejects.toThrow(
+    TimeoutError,
+  );
+  await serverAssertConnectionsCount(0);
+});
+
+test("timeout_in_stream_after_preload_succeeded", async () => {
+  const reader = createFetchReader(`${ORIGIN}/slow`, { timeoutMs: 200 });
+  await reader.preload(42);
+  await serverAssertConnectionsCount(1);
+  await expect(async () => consumeIterable(reader, 10)).rejects.toThrow(
+    TimeoutError,
+  );
+  await serverAssertConnectionsCount(0);
+});
+
+test("timeout_after_reader_waited_for_too_long", async () => {
+  const reader = createFetchReader(`${ORIGIN}/slow`, { timeoutMs: 200 });
+  await reader.preload(42);
+  await serverAssertConnectionsCount(1);
+  await delay(500);
+  await expect(async () => consumeIterable(reader, 10)).rejects.toThrow(
+    TimeoutError,
+  );
+  await serverAssertConnectionsCount(0);
+});
+
+test("read_binary_data", async () => {
+  const reader = createFetchReader(`${ORIGIN}/binary`, { timeoutMs: 2000 });
+  await reader.preload(42);
+  const preload = reader.textFetched;
+  expect(reader.textIsPartial).toBeTruthy();
+  const data = await consumeIterable(reader, 10);
+  expect(Buffer.from(preload + data, "binary")).toEqual(
+    Buffer.concat(range(10).map(() => BINARY_BUF)),
+  );
+  await serverAssertConnectionsCount(0);
+});

package/src/__tests__/RestRequest.test.ts

@@ -0,0 +1,262 @@
+import { FetchError, Headers } from "node-fetch";
+import {
+  DEFAULT_OPTIONS,
+  RestClient,
+  RestRateLimitError,
+  RestResponseError,
+  RestTokenInvalidError,
+} from "..";
+import calcRetryDelay from "../internal/calcRetryDelay";
+import throwIfErrorResponse from "../internal/throwIfErrorResponse";
+import RestResponse from "../RestResponse";
+
+const REQUEST = new RestClient().get("https://example.com");
+const SUCCESS_RESPONSE = new RestResponse(
+  REQUEST,
+  null,
+  200,
+  new Headers(),
+  "",
+  false,
+);
+const ERROR_RESPONSE = new RestResponse(
+  REQUEST,
+  null,
+  500,
+  new Headers(),
+  "",
+  false,
+);
+const NOT_FOUND_RESPONSE = new RestResponse(
+  REQUEST,
+  null,
+  404,
+  new Headers(),
+  "",
+  false,
+);
+const TOO_MANY_REQUESTS_RESPONSE = new RestResponse(
+  REQUEST,
+  null,
+  429,
+  new Headers(),
+  "",
+  false,
+);
+
+test("isSuccessResponse", () => {
+  expect(
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isSuccessResponse: () => "SUCCESS" },
+      ERROR_RESPONSE,
+    ),
+  ).toBeUndefined();
+
+  expect(() =>
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isSuccessResponse: () => "BEST_EFFORT" },
+      NOT_FOUND_RESPONSE,
+    ),
+  ).toThrow(/404/);
+
+  expect(
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isSuccessResponse: () => "BEST_EFFORT" },
+      SUCCESS_RESPONSE,
+    ),
+  ).toBeUndefined();
+
+  expect(() =>
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isSuccessResponse: () => "THROW" },
+      SUCCESS_RESPONSE,
+    ),
+  ).toThrow(/isSuccessResponse/);
+});
+
+test("isRateLimitError", () => {
+  expect(() =>
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isRateLimitError: () => "RATE_LIMIT" },
+      SUCCESS_RESPONSE,
+    ),
+  ).toThrow(RestRateLimitError);
+
+  expect(
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isRateLimitError: () => "BEST_EFFORT" },
+      SUCCESS_RESPONSE,
+    ),
+  ).toBeUndefined();
+
+  expect(() =>
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isRateLimitError: () => "BEST_EFFORT" },
+      TOO_MANY_REQUESTS_RESPONSE,
+    ),
+  ).toThrow(RestRateLimitError);
+
+  expect(
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isRateLimitError: () => "SOMETHING_ELSE" },
+      SUCCESS_RESPONSE,
+    ),
+  ).toBeUndefined();
+});
+
+test("isTokenInvalidError", () => {
+  expect(() =>
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isTokenInvalidError: () => true },
+      SUCCESS_RESPONSE,
+    ),
+  ).toThrow(RestTokenInvalidError);
+
+  expect(
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isTokenInvalidError: () => false },
+      SUCCESS_RESPONSE,
+    ),
+  ).toBeUndefined();
+});
+
+test("isRetriableError", () => {
+  expect(() =>
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isRetriableError: () => "RETRY" },
+      SUCCESS_RESPONSE,
+    ),
+  ).toThrow(RestResponseError);
+
+  expect(
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isRetriableError: () => "BEST_EFFORT" },
+      SUCCESS_RESPONSE,
+    ),
+  ).toBeUndefined();
+
+  expect(() =>
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isRetriableError: () => "BEST_EFFORT" },
+      NOT_FOUND_RESPONSE,
+    ),
+  ).toThrow(RestResponseError);
+
+  expect(
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isRateLimitError: () => "SOMETHING_ELSE" },
+      SUCCESS_RESPONSE,
+    ),
+  ).toBeUndefined();
+
+  expect(() =>
+    throwIfErrorResponse(
+      { ...DEFAULT_OPTIONS, isRetriableError: () => "NEVER_RETRY" },
+      NOT_FOUND_RESPONSE,
+    ),
+  ).toThrow(RestResponseError);
+});
+
+test("calcRetryDelay", () => {
+  expect(
+    calcRetryDelay(
+      new RestRateLimitError("", 42, SUCCESS_RESPONSE),
+      DEFAULT_OPTIONS,
+      SUCCESS_RESPONSE,
+      0,
+    ),
+  ).toEqual(42);
+
+  expect(
+    calcRetryDelay(
+      new RestTokenInvalidError("", ERROR_RESPONSE),
+      DEFAULT_OPTIONS,
+      ERROR_RESPONSE,
+      0,
+    ),
+  ).toEqual("no_retry");
+
+  expect(
+    calcRetryDelay(
+      new RestTokenInvalidError("", ERROR_RESPONSE),
+      { ...DEFAULT_OPTIONS, isRetriableError: () => "RETRY" },
+      ERROR_RESPONSE,
+      42,
+    ),
+  ).toEqual(42);
+
+  expect(
+    calcRetryDelay(
+      new RestResponseError("", ERROR_RESPONSE),
+      { ...DEFAULT_OPTIONS, isRetriableError: () => "BEST_EFFORT" },
+      ERROR_RESPONSE,
+      42,
+    ),
+  ).toEqual(42);
+
+  expect(
+    calcRetryDelay(
+      new RestResponseError("", NOT_FOUND_RESPONSE),
+      { ...DEFAULT_OPTIONS, isRetriableError: () => "BEST_EFFORT" },
+      NOT_FOUND_RESPONSE,
+      42,
+    ),
+  ).toEqual("no_retry");
+
+  expect(
+    calcRetryDelay(
+      new RestRateLimitError("", 42, NOT_FOUND_RESPONSE),
+      { ...DEFAULT_OPTIONS, isRetriableError: () => "BEST_EFFORT" },
+      NOT_FOUND_RESPONSE,
+      0,
+    ),
+  ).toEqual(42);
+
+  expect(
+    calcRetryDelay(
+      new FetchError("test", "some"),
+      {
+        ...DEFAULT_OPTIONS,
+        isRetriableError: (_: any, error: any) =>
+          error instanceof FetchError ? "NEVER_RETRY" : "RETRY",
+      },
+      NOT_FOUND_RESPONSE,
+      0,
+    ),
+  ).toEqual("no_retry");
+
+  expect(
+    calcRetryDelay(
+      new FetchError("test", "max-size"),
+      { ...DEFAULT_OPTIONS, isRetriableError: () => "BEST_EFFORT" },
+      NOT_FOUND_RESPONSE,
+      0,
+    ),
+  ).toEqual("no_retry");
+});
+
+test("when isRateLimitError=YES, isRetriableError=NO doesn't matter, and the request is always retriable", () => {
+  expect(() =>
+    throwIfErrorResponse(
+      {
+        ...DEFAULT_OPTIONS,
+        isRateLimitError: () => "RATE_LIMIT",
+        isRetriableError: () => "NEVER_RETRY",
+      },
+      SUCCESS_RESPONSE,
+    ),
+  ).toThrow(RestRateLimitError);
+
+  expect(
+    calcRetryDelay(
+      new RestRateLimitError("", 42, SUCCESS_RESPONSE),
+      {
+        ...DEFAULT_OPTIONS,
+        isRateLimitError: () => "RATE_LIMIT",
+        isRetriableError: () => "NEVER_RETRY",
+      },
+      SUCCESS_RESPONSE,
+      0,
+    ),
+  ).toEqual(42);
+});

package/src/__tests__/RestStream.test.ts

@@ -0,0 +1,63 @@
+import Stream from "stream";
+import {
+  consumeReadable,
+  createRestStream,
+  server,
+  serverAssertConnectionsCount,
+} from "./helpers";
+
+let ORIGIN: string;
+
+beforeAll(async () => {
+  ORIGIN = await new Promise((resolve) => {
+    server.listen(0, () =>
+      resolve("http://127.0.0.1:" + (server.address() as any).port),
+    );
+  });
+});
+
+beforeEach(async () => {
+  await serverAssertConnectionsCount(0);
+});
+
+test("prefix", async () => {
+  const stream = await createRestStream(`${ORIGIN}/large`);
+  const prefix = await stream.consumeReturningPrefix(42);
+  expect(prefix.length).toEqual(42);
+  await serverAssertConnectionsCount(0);
+});
+
+test("stream_readable_proxy_closes_connection", async () => {
+  const stream = await createRestStream(`${ORIGIN}/large`);
+  const readable = Stream.Readable.from(stream);
+  expect((await consumeReadable(readable)).length).toBeGreaterThan(1024 * 10);
+  await serverAssertConnectionsCount(0);
+});
+
+test("read_cancelled_after_reading_preloaded_chunk_closes_connection", async () => {
+  const stream = await createRestStream(`${ORIGIN}/large`, 42);
+  await serverAssertConnectionsCount(1);
+
+  for await (const chunk of stream) {
+    expect(chunk).toEqual(stream.res.text);
+    await serverAssertConnectionsCount(1);
+    break;
+  }
+
+  await serverAssertConnectionsCount(0);
+});
+
+test("read_thrown_after_reading_preloaded_chunk_closes_connection", async () => {
+  const stream = await createRestStream(`${ORIGIN}/large`, 42);
+  await serverAssertConnectionsCount(1);
+
+  await expect(async () => {
+    for await (const chunk of stream) {
+      await serverAssertConnectionsCount(1);
+      expect(chunk).toEqual(stream.res.text);
+      throw Error("bailout");
+    }
+  }).rejects.toThrowError("bailout");
+
+  await serverAssertConnectionsCount(0);
+});

package/src/__tests__/helpers.ts

@@ -0,0 +1,173 @@
+import http from "http";
+import type { Readable } from "stream";
+import delay from "delay";
+import range from "lodash/range";
+import { Headers } from "node-fetch";
+import { DEFAULT_OPTIONS, RestRequest, RestResponse, RestStream } from "..";
+import type { RestFetchReaderOptions } from "../internal/RestFetchReader";
+import RestFetchReader from "../internal/RestFetchReader";
+
+// Two European Euro symbols in UTF-8.
+export const UTF8_BUF = Buffer.from([0xe2, 0x82, 0xac, 0xe2, 0x82, 0xac]);
+
+// Binary data, all possible bytes.
+export const BINARY_BUF = Buffer.from(range(256));
+
+// eslint-disable-next-line @typescript-eslint/no-misused-promises
+export const server = http.createServer(async (req, res) => {
+  res.setHeader("Content-Type", "text/plain; charset=utf-8");
+
+  // In node-fetch 2.6.13+, they stopped sending "Connection: close" by default:
+  // https://github.com/node-fetch/node-fetch/pull/1736 - which is a good thing:
+  // we can now send multiple requests through the same connection sequentially
+  // (it seems to be broken before). Since RestFetchReader calls
+  // controller.abort() when the client wants to interrupt the request, the
+  // connection is physically closed only if there is currently an active
+  // request (e.g. "/slow" below), and it's not closed when the request is
+  // successfully processed (which is, again, a good thing). So to be able to
+  // use serverAssertConnectionsCount() helper, we force the server to close the
+  // connection after each request, so serverAssertConnectionsCount() can work.
+  res.setHeader("Connection", "close");
+
+  // Returns a small response.
+  if (req.url === "/small") {
+    res.writeHead(200);
+    return res.end("ok");
+  }
+
+  // Returns a large, but quick response.
+  if (req.url === "/large") {
+    res.writeHead(200);
+    await write(res, 1024);
+    await delay(100);
+    await write(res, 1024 * 100);
+    return res.end("x".repeat(1024 * 200));
+  }
+
+  // Returns a large response, does it slowly.
+  if (req.url === "/slow") {
+    res.writeHead(200);
+    for (let timeStart = Date.now(); Date.now() - timeStart < 20000; ) {
+      const error = await write(res, 1024);
+      if (error) {
+        break;
+      } else {
+        await delay(10);
+      }
+    }
+
+    return res.end();
+  }
+
+  // Returns slow response as UTF-8 bytes, one after another.
+  if (req.url === "/small_slow_utf8") {
+    res.writeHead(200);
+    for (const byte of UTF8_BUF) {
+      await write(res, Buffer.from([byte]));
+      await delay(500);
+    }
+
+    return res.end();
+  }
+
+  // Returns a binary response.
+  if (req.url === "/binary") {
+    res.setHeader("Content-Type", "application/octet-stream");
+    res.writeHead(200);
+    for (const _ in range(10)) {
+      await write(res, BINARY_BUF);
+      await delay(50);
+    }
+
+    return res.end();
+  }
+
+  res.writeHead(404);
+  return res.end("not found");
+});
+
+export async function serverAssertConnectionsCount(expect: number) {
+  let got: number = 0;
+  for (let timeStart = Date.now(); Date.now() - timeStart < 10000; ) {
+    got = await new Promise((resolve) =>
+      server.getConnections((_, count) => resolve(count)),
+    );
+    if (got === expect) {
+      return;
+    }
+
+    await delay(50);
+  }
+
+  throw Error(`Expected ${expect} connections, but got ${got}`);
+}
+
+export class TimeoutError extends Error {}
+
+export function createFetchReader(
+  url: string,
+  options: RestFetchReaderOptions = {},
+) {
+  return new RestFetchReader(
+    url,
+    {},
+    {
+      onTimeout: () => {
+        throw new TimeoutError("timed out");
+      },
+      ...options,
+    },
+  );
+}
+
+export async function createRestStream(url: string, preloadBytes?: number) {
+  const reader = createFetchReader(url);
+  if (preloadBytes) {
+    await reader.preload(preloadBytes);
+  }
+
+  return new RestStream(
+    new RestResponse(
+      new RestRequest(DEFAULT_OPTIONS, "GET", "dummy", new Headers(), ""),
+      reader.agent,
+      reader.status,
+      reader.headers,
+      reader.textFetched.toString(),
+      reader.textIsPartial,
+    ),
+    reader[Symbol.asyncIterator](),
+  );
+}
+
+export async function consumeIterable(
+  iterable: AsyncIterable<string>,
+  delayMs?: number,
+) {
+  let rest = "";
+  for await (const chunk of iterable) {
+    rest += chunk;
+    if (delayMs) {
+      await delay(delayMs);
+    }
+  }
+
+  return rest;
+}
+
+export async function consumeReadable(stream: Readable) {
+  return new Promise<string>((resolve) => {
+    const chunks: string[] = [];
+    stream.on("data", (chunk) => {
+      chunks.push(chunk);
+    });
+    stream.on("end", () => {
+      resolve(chunks.join(""));
+    });
+  });
+}
+
+async function write(res: http.ServerResponse, bytes: number | Buffer) {
+  return new Promise((r) =>
+    res.write(typeof bytes === "number" ? "x".repeat(bytes) : bytes, r),
+  );
+}

package/src/errors/RestRateLimitError.ts

@@ -2,7 +2,11 @@ import type RestResponse from "../RestResponse";
 import RestResponseError from "./RestResponseError";
 
 export default class RestRateLimitError extends RestResponseError {
-  constructor(message: string, public delayMs: number, res: RestResponse) {
+  constructor(
+    message: string,
+    public delayMs: number,
+    res: RestResponse,
+  ) {
     super(message, res);
   }
 }

package/src/errors/RestResponseError.ts

@@ -21,8 +21,8 @@ export default class RestResponseError extends RestError {
       `HTTP ${res.status}: ` +
         (message ? `${message}: ` : "") +
         prependNewlineIfMultiline(
-          inspectPossibleJSON(res.headers, res.text, RESPONSE_MAX_LEN_IN_ERROR)
-        )
+          inspectPossibleJSON(res.headers, res.text, RESPONSE_MAX_LEN_IN_ERROR),
+        ),
     );
     Object.defineProperty(this, "res", { value: res, enumerable: false }); // hidden from inspect()
     const url = new URL(res.req.url);
@@ -34,7 +34,7 @@ export default class RestResponseError extends RestError {
     this.requestBody = inspectPossibleJSON(
       res.headers,
       res.req.body,
-      RESPONSE_MAX_LEN_IN_ERROR
+      RESPONSE_MAX_LEN_IN_ERROR,
     );
     this.responseHeaders = [...res.headers]
       .map(([name, value]) => `${name}: ${value}`)

package/src/errors/RestRetriableError.ts

@@ -2,7 +2,11 @@ import type RestResponse from "../RestResponse";
 import RestResponseError from "./RestResponseError";
 
 export default class RestRetriableError extends RestResponseError {
-  constructor(message: string, public delayMs: number, res: RestResponse) {
+  constructor(
+    message: string,
+    public delayMs: number,
+    res: RestResponse,
+  ) {
     super(message, res);
   }
 }

package/src/errors/RestTokenInvalidError.ts

@@ -2,7 +2,10 @@ import type RestResponse from "../RestResponse";
 import RestResponseError from "./RestResponseError";
 
 export default class RestTokenInvalidError extends RestResponseError {
-  constructor(public readonly humanReason: string, res: RestResponse) {
+  constructor(
+    public readonly humanReason: string,
+    res: RestResponse,
+  ) {
     super(humanReason, res);
   }
 }