small internal refactors

Author: toptobes

src/api/constants.ts

@@ -22,11 +22,11 @@ export const CLIENT_USER_AGENT = LIB_NAME + '/' + LIB_VERSION;
 /**
  * @internal
  */
-export const enum HTTP_METHODS {
-  Get = 'GET',
-  Post = 'POST',
-  Delete = 'DELETE',
-}
+export const HttpMethods = {
+  Get: 'GET',
+  Post: 'POST',
+  Delete: 'DELETE',
+} as const;
 
 /**
  * @internal

src/api/data-api-http-client.ts

@@ -12,14 +12,15 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { DEFAULT_NAMESPACE, DEFAULT_TIMEOUT, HTTP_METHODS, HttpClient, RawDataApiResponse } from '@/src/api';
+import { DEFAULT_NAMESPACE, DEFAULT_TIMEOUT, HttpClient, HttpMethods, RawDataApiResponse } from '@/src/api';
 import { DataAPIResponseError, DataAPITimeout, mkRespErrorFromResponse, ObjectId, UUID } from '@/src/data-api';
 import { logger } from '@/src/logger';
 import {
   MkTimeoutError,
   MultiCallTimeoutManager,
   SingleCallTimeoutManager,
-  TimeoutManager, TimeoutOptions,
+  TimeoutManager,
+  TimeoutOptions,
 } from '@/src/api/timeout-managers';
 
 interface DataApiRequestInfo {
@@ -71,7 +72,7 @@ export class DataApiHttpClient extends HttpClient {
         url: url,
         data: JSON.stringify(info.command, replacer),
         timeoutManager: info.timeoutManager,
-        method: HTTP_METHODS.Post,
+        method: HttpMethods.Post,
         reviver: reviver,
       });
 
@@ -109,7 +110,7 @@ const mkTimeoutManager = (constructor: new (maxMs: number, mkTimeoutError: MkTim
 }
 
 const mkTimeoutErrorMaker = (timeout: number): MkTimeoutError => {
-  return (info) => new DataAPITimeout(info.data!, timeout)
+  return (info) => new DataAPITimeout(info.data!, timeout);
 }
 
 const mkFauxErroredResponse = (message: string): RawDataApiResponse => {

src/api/devops-api-http-client.ts

@@ -13,9 +13,8 @@
 // limitations under the License.
 
 import { HttpClient } from '@/src/api/http-client';
-import { HTTP_METHODS } from '@/src/api/constants';
 import { AxiosError, AxiosResponse } from 'axios';
-import { HTTPClientOptions } from '@/src/api/types';
+import { HTTPClientOptions, HttpMethodStrings } from '@/src/api/types';
 import { HTTP1AuthHeaderFactories, HTTP1Strategy } from '@/src/api/http1';
 import { DevopsApiResponseError, DevopsApiTimeout, DevopsUnexpectedStateError } from '@/src/devops/errors';
 import { AdminBlockingOptions, PollBlockingOptions } from '@/src/devops/types';
@@ -26,10 +25,11 @@ import {
   TimeoutManager,
   TimeoutOptions,
 } from '@/src/api/timeout-managers';
+import { HttpMethods } from '@/src/api/constants';
 
 interface DevopsApiRequestInfo {
   path: string,
-  method: HTTP_METHODS,
+  method: HttpMethodStrings,
   data?: Record<string, any>,
   params?: Record<string, any>,
 }
@@ -86,7 +86,7 @@ export class DevopsApiHttpClient extends HttpClient {
   private async _awaitStatus(id: string, target: string, legalStates: string[], options: PollBlockingOptions | undefined, defaultPollInterval: number, timeoutManager: TimeoutManager): Promise<void> {
     for (;;) {
       const resp = await this.request({
-        method: HTTP_METHODS.Get,
+        method: HttpMethods.Get,
         path: `/databases/${id}`,
       }, {
         timeoutManager: timeoutManager,

src/api/timeout-managers.ts

@@ -14,6 +14,13 @@
 
 import { InternalHTTPRequestInfo } from '@/src/api/types';
 
+/**
+ * Internal representation of timeout options, allowing a shorthand for a single call timeout manager via
+ * `maxTimeMS`, with an explicit {@link TimeoutManager} being allowed to be passed if necessary, generally
+ * for multi-call timeout management.
+ *
+ * @internal
+ */
 export type TimeoutOptions = {
   maxTimeMS?: number,
   timeoutManager?: never,
@@ -22,13 +29,48 @@ export type TimeoutOptions = {
   maxTimeMS?: never,
 }
 
+/**
+ * Represents a function that creates a timeout error for a given request context.
+ *
+ * @example
+ * ```typescript
+ * const mkTimeoutError: MkTimeoutError = (info) => {
+ *   return new DevopsApiTimeout(info.url, timeout);
+ * }
+ * ```
+ *
+ * @internal
+ */
 export type MkTimeoutError = (ctx: InternalHTTPRequestInfo) => Error;
 
+/**
+ * Represents a timeout manager, which is responsible for tracking the remaining time before a timeout occurs.
+ *
+ * See {@link SingleCallTimeoutManager} and {@link MultiCallTimeoutManager} for concrete implementations.
+ *
+ * @internal
+ */
 export interface TimeoutManager {
+  /**
+   * The remaining time before a timeout occurs, in milliseconds. May return `Infinity`, which
+   * the underlying http request strategies should interpret as no timeout.
+   *
+   * However, the implementing TimeoutManager classes should accept `0` to also indicate no timeout,
+   * just translating it to `Infinity` for the purposes of the `msRemaining` getter, so it's easier to
+   * reason about.
+   */
   msRemaining: number,
+  /**
+   * A function that creates a timeout error for the given request context ({@link InternalHTTPRequestInfo}).
+   */
   mkTimeoutError: MkTimeoutError,
 }
 
+/**
+ * A basic timeout manager that only holds a fixed timeout value, intended for, of course, single-request operations.
+ *
+ * @internal
+ */
 export class SingleCallTimeoutManager implements TimeoutManager {
   public readonly msRemaining: number;
 
@@ -37,6 +79,13 @@ export class SingleCallTimeoutManager implements TimeoutManager {
   }
 }
 
+/**
+ * A more complex timeout manager that tracks the remaining time for multiple calls, starting from the first call.
+ * This is useful for scenarios where multiple calls are made in sequence, and the timeout should be shared among them,
+ * e.g. {@link Collection.insertMany}.
+ *
+ * @internal
+ */
 export class MultiCallTimeoutManager implements TimeoutManager {
   private _deadline!: number;
   private _started: boolean;

src/api/types.ts

@@ -12,9 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { HTTP_METHODS } from '@/src/api/index';
 import { Caller } from '@/src/client';
 import { TimeoutManager } from '@/src/api/timeout-managers';
+import { HttpMethods } from '@/src/api/constants';
 
 /**
  * @internal
@@ -44,14 +44,19 @@ export interface GuaranteedAPIResponse {
   status: number,
 }
 
+/**
+ * @internal
+ */
+export type HttpMethodStrings = typeof HttpMethods[keyof typeof HttpMethods];
+
 /**
  * @internal
  */
 export interface HTTPRequestInfo {
   url: string,
   data?: unknown,
   params?: Record<string, string>,
-  method: HTTP_METHODS,
+  method: HttpMethodStrings,
   reviver?: (key: string, value: any) => any,
   timeoutManager: TimeoutManager,
 }
@@ -61,7 +66,7 @@ export interface HTTPRequestInfo {
  */
 export interface InternalHTTPRequestInfo extends HTTPRequestInfo {
   token: string,
-  method: HTTP_METHODS,
+  method: HttpMethodStrings,
   userAgent: string,
 }
 

src/common/types.ts

@@ -12,6 +12,16 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/**
+ * Represents options related to timeouts. Note that this means "the max time the client will wait for a response
+ * from the server"—**an operation timing out does not necessarily mean the operation failed on the server**.
+ *
+ * On paginated operations, the timeout applies across all network requests. For example, if you set a timeout of 5
+ * seconds and the operation requires 3 network requests, each request must complete in less than 5 seconds total.
+ */
 export interface WithTimeout {
+  /**
+   * The maximum time to wait for a response from the server, in milliseconds.
+   */
   maxTimeMS?: number;
 }