@algolia/client-common 4.14.2 → 5.0.0-alpha.11

package/src/transporter/createTransporter.ts

@@ -0,0 +1,350 @@
+import type {
+  EndRequest,
+  Host,
+  Request,
+  RequestOptions,
+  Response,
+  StackFrame,
+  TransporterOptions,
+  Transporter,
+  QueryParameters,
+} from '../types';
+
+import { createStatefulHost } from './createStatefulHost';
+import { RetryError } from './errors';
+import {
+  deserializeFailure,
+  deserializeSuccess,
+  serializeData,
+  serializeHeaders,
+  serializeUrl,
+} from './helpers';
+import { isRetryable, isSuccess } from './responses';
+import {
+  stackTraceWithoutCredentials,
+  stackFrameWithoutCredentials,
+} from './stackTrace';
+
+type RetryableOptions = {
+  hosts: Host[];
+  getTimeout: (retryCount: number, timeout: number) => number;
+};
+
+export function createTransporter({
+  hosts,
+  hostsCache,
+  baseHeaders,
+  baseQueryParameters,
+  algoliaAgent,
+  timeouts,
+  requester,
+  requestsCache,
+  responsesCache,
+}: TransporterOptions): Transporter {
+  async function createRetryableOptions(
+    compatibleHosts: Host[]
+  ): Promise<RetryableOptions> {
+    const statefulHosts = await Promise.all(
+      compatibleHosts.map((compatibleHost) => {
+        return hostsCache.get(compatibleHost, () => {
+          return Promise.resolve(createStatefulHost(compatibleHost));
+        });
+      })
+    );
+    const hostsUp = statefulHosts.filter((host) => host.isUp());
+    const hostsTimedOut = statefulHosts.filter((host) => host.isTimedOut());
+
+    // Note, we put the hosts that previously timed out on the end of the list.
+    const hostsAvailable = [...hostsUp, ...hostsTimedOut];
+    const compatibleHostsAvailable =
+      hostsAvailable.length > 0 ? hostsAvailable : compatibleHosts;
+
+    return {
+      hosts: compatibleHostsAvailable,
+      getTimeout(timeoutsCount: number, baseTimeout: number): number {
+        /**
+         * Imagine that you have 4 hosts, if timeouts will increase
+         * on the following way: 1 (timed out) > 4 (timed out) > 5 (200).
+         *
+         * Note that, the very next request, we start from the previous timeout.
+         *
+         *  5 (timed out) > 6 (timed out) > 7 ...
+         *
+         * This strategy may need to be reviewed, but is the strategy on the our
+         * current v3 version.
+         */
+        const timeoutMultiplier =
+          hostsTimedOut.length === 0 && timeoutsCount === 0
+            ? 1
+            : hostsTimedOut.length + 3 + timeoutsCount;
+
+        return timeoutMultiplier * baseTimeout;
+      },
+    };
+  }
+
+  async function retryableRequest<TResponse>(
+    request: Request,
+    requestOptions: RequestOptions,
+    isRead = true
+  ): Promise<TResponse> {
+    const stackTrace: StackFrame[] = [];
+
+    /**
+     * First we prepare the payload that do not depend from hosts.
+     */
+    const data = serializeData(request, requestOptions);
+    const headers = serializeHeaders(
+      baseHeaders,
+      request.headers,
+      requestOptions.headers
+    );
+
+    // On `GET`, the data is proxied to query parameters.
+    const dataQueryParameters: QueryParameters =
+      request.method === 'GET'
+        ? {
+            ...request.data,
+            ...requestOptions.data,
+          }
+        : {};
+
+    const queryParameters: QueryParameters = {
+      ...baseQueryParameters,
+      ...request.queryParameters,
+      ...dataQueryParameters,
+    };
+
+    if (algoliaAgent.value) {
+      queryParameters['x-algolia-agent'] = algoliaAgent.value;
+    }
+
+    if (requestOptions && requestOptions.queryParameters) {
+      for (const key of Object.keys(requestOptions.queryParameters)) {
+        // We want to keep `undefined` and `null` values,
+        // but also avoid stringifying `object`s, as they are
+        // handled in the `serializeUrl` step right after.
+        if (
+          !requestOptions.queryParameters[key] ||
+          Object.prototype.toString.call(
+            requestOptions.queryParameters[key]
+          ) === '[object Object]'
+        ) {
+          queryParameters[key] = requestOptions.queryParameters[key];
+        } else {
+          queryParameters[key] = requestOptions.queryParameters[key].toString();
+        }
+      }
+    }
+
+    let timeoutsCount = 0;
+
+    const retry = async (
+      retryableHosts: Host[],
+      getTimeout: (timeoutsCount: number, timeout: number) => number
+    ): Promise<TResponse> => {
+      /**
+       * We iterate on each host, until there is no host left.
+       */
+      const host = retryableHosts.pop();
+      if (host === undefined) {
+        throw new RetryError(stackTraceWithoutCredentials(stackTrace));
+      }
+
+      let responseTimeout = requestOptions.timeout;
+      if (responseTimeout === undefined) {
+        responseTimeout = isRead ? timeouts.read : timeouts.write;
+      }
+
+      const payload: EndRequest = {
+        data,
+        headers,
+        method: request.method,
+        url: serializeUrl(host, request.path, queryParameters),
+        connectTimeout: getTimeout(timeoutsCount, timeouts.connect),
+        responseTimeout: getTimeout(timeoutsCount, responseTimeout),
+      };
+
+      /**
+       * The stackFrame is pushed to the stackTrace so we
+       * can have information about onRetry and onFailure
+       * decisions.
+       */
+      const pushToStackTrace = (response: Response): StackFrame => {
+        const stackFrame: StackFrame = {
+          request: payload,
+          response,
+          host,
+          triesLeft: retryableHosts.length,
+        };
+
+        stackTrace.push(stackFrame);
+
+        return stackFrame;
+      };
+
+      const response = await requester.send(payload);
+
+      if (isRetryable(response)) {
+        const stackFrame = pushToStackTrace(response);
+
+        // If response is a timeout, we increase the number of timeouts so we can increase the timeout later.
+        if (response.isTimedOut) {
+          timeoutsCount++;
+        }
+        /**
+         * Failures are individually sent to the logger, allowing
+         * the end user to debug / store stack frames even
+         * when a retry error does not happen.
+         */
+        // eslint-disable-next-line no-console -- this will be fixed by exposing a `logger` to the transporter
+        console.log(
+          'Retryable failure',
+          stackFrameWithoutCredentials(stackFrame)
+        );
+
+        /**
+         * We also store the state of the host in failure cases. If the host, is
+         * down it will remain down for the next 2 minutes. In a timeout situation,
+         * this host will be added end of the list of hosts on the next request.
+         */
+        await hostsCache.set(
+          host,
+          createStatefulHost(host, response.isTimedOut ? 'timed out' : 'down')
+        );
+
+        return retry(retryableHosts, getTimeout);
+      }
+
+      if (isSuccess(response)) {
+        return deserializeSuccess(response);
+      }
+
+      pushToStackTrace(response);
+      throw deserializeFailure(response, stackTrace);
+    };
+
+    /**
+     * Finally, for each retryable host perform request until we got a non
+     * retryable response. Some notes here:
+     *
+     * 1. The reverse here is applied so we can apply a `pop` later on => more performant.
+     * 2. We also get from the retryable options a timeout multiplier that is tailored
+     * for the current context.
+     */
+    const compatibleHosts = hosts.filter(
+      (host) =>
+        host.accept === 'readWrite' ||
+        (isRead ? host.accept === 'read' : host.accept === 'write')
+    );
+    const options = await createRetryableOptions(compatibleHosts);
+
+    return retry([...options.hosts].reverse(), options.getTimeout);
+  }
+
+  function createRequest<TResponse>(
+    request: Request,
+    requestOptions: RequestOptions = {}
+  ): Promise<TResponse> {
+    /**
+     * A read request is either a `GET` request, or a request that we make
+     * via the `read` transporter (e.g. `search`).
+     */
+    const isRead = request.useReadTransporter || request.method === 'GET';
+    if (!isRead) {
+      /**
+       * On write requests, no cache mechanisms are applied, and we
+       * proxy the request immediately to the requester.
+       */
+      return retryableRequest<TResponse>(request, requestOptions, isRead);
+    }
+
+    const createRetryableRequest = (): Promise<TResponse> => {
+      /**
+       * Then, we prepare a function factory that contains the construction of
+       * the retryable request. At this point, we may *not* perform the actual
+       * request. But we want to have the function factory ready.
+       */
+      return retryableRequest<TResponse>(request, requestOptions);
+    };
+
+    /**
+     * Once we have the function factory ready, we need to determine of the
+     * request is "cacheable" - should be cached. Note that, once again,
+     * the user can force this option.
+     */
+    const cacheable = requestOptions.cacheable || request.cacheable;
+
+    /**
+     * If is not "cacheable", we immediately trigger the retryable request, no
+     * need to check cache implementations.
+     */
+    if (cacheable !== true) {
+      return createRetryableRequest();
+    }
+
+    /**
+     * If the request is "cacheable", we need to first compute the key to ask
+     * the cache implementations if this request is on progress or if the
+     * response already exists on the cache.
+     */
+    const key = {
+      request,
+      requestOptions,
+      transporter: {
+        queryParameters: baseQueryParameters,
+        headers: baseHeaders,
+      },
+    };
+
+    /**
+     * With the computed key, we first ask the responses cache
+     * implementation if this request was been resolved before.
+     */
+    return responsesCache.get(
+      key,
+      () => {
+        /**
+         * If the request has never resolved before, we actually ask if there
+         * is a current request with the same key on progress.
+         */
+        return requestsCache.get(key, () =>
+          /**
+           * Finally, if there is no request in progress with the same key,
+           * this `createRetryableRequest()` will actually trigger the
+           * retryable request.
+           */
+          requestsCache
+            .set(key, createRetryableRequest())
+            .then(
+              (response) => Promise.all([requestsCache.delete(key), response]),
+              (err) =>
+                Promise.all([requestsCache.delete(key), Promise.reject(err)])
+            )
+            .then(([_, response]) => response)
+        );
+      },
+      {
+        /**
+         * Of course, once we get this response back from the server, we
+         * tell response cache to actually store the received response
+         * to be used later.
+         */
+        miss: (response) => responsesCache.set(key, response),
+      }
+    );
+  }
+
+  return {
+    hostsCache,
+    requester,
+    timeouts,
+    algoliaAgent,
+    baseHeaders,
+    baseQueryParameters,
+    hosts,
+    request: createRequest,
+    requestsCache,
+    responsesCache,
+  };
+}

package/src/transporter/errors.ts

@@ -0,0 +1,51 @@
+import type { Response, StackFrame } from '../types';
+
+export class AlgoliaError extends Error {
+  name: string = 'AlgoliaError';
+
+  constructor(message: string, name: string) {
+    super(message);
+
+    if (name) {
+      this.name = name;
+    }
+  }
+}
+
+export class ErrorWithStackTrace extends AlgoliaError {
+  stackTrace: StackFrame[];
+
+  constructor(message: string, stackTrace: StackFrame[], name: string) {
+    super(message, name);
+    // the array and object should be frozen to reflect the stackTrace at the time of the error
+    this.stackTrace = stackTrace;
+  }
+}
+
+export class RetryError extends ErrorWithStackTrace {
+  constructor(stackTrace: StackFrame[]) {
+    super(
+      'Unreachable hosts - your application id may be incorrect. If the error persists, contact support@algolia.com.',
+      stackTrace,
+      'RetryError'
+    );
+  }
+}
+
+export class ApiError extends ErrorWithStackTrace {
+  status: number;
+
+  constructor(message: string, status: number, stackTrace: StackFrame[]) {
+    super(message, stackTrace, 'ApiError');
+    this.status = status;
+  }
+}
+
+export class DeserializationError extends AlgoliaError {
+  response: Response;
+
+  constructor(message: string, response: Response) {
+    super(message, 'DeserializationError');
+    this.response = response;
+  }
+}

package/src/transporter/helpers.ts

@@ -0,0 +1,119 @@
+import type {
+  Headers,
+  Host,
+  QueryParameters,
+  Request,
+  RequestOptions,
+  Response,
+  StackFrame,
+} from '../types';
+
+import { ApiError, DeserializationError } from './errors';
+
+export function shuffle<TData>(array: TData[]): TData[] {
+  const shuffledArray = array;
+
+  for (let c = array.length - 1; c > 0; c--) {
+    const b = Math.floor(Math.random() * (c + 1));
+    const a = array[c];
+
+    shuffledArray[c] = array[b];
+    shuffledArray[b] = a;
+  }
+
+  return shuffledArray;
+}
+
+export function serializeUrl(
+  host: Host,
+  path: string,
+  queryParameters: QueryParameters
+): string {
+  const queryParametersAsString = serializeQueryParameters(queryParameters);
+  let url = `${host.protocol}://${host.url}/${
+    path.charAt(0) === '/' ? path.substr(1) : path
+  }`;
+
+  if (queryParametersAsString.length) {
+    url += `?${queryParametersAsString}`;
+  }
+
+  return url;
+}
+
+export function serializeQueryParameters(parameters: QueryParameters): string {
+  const isObjectOrArray = (value: any): boolean =>
+    Object.prototype.toString.call(value) === '[object Object]' ||
+    Object.prototype.toString.call(value) === '[object Array]';
+
+  return Object.keys(parameters)
+    .map(
+      (key) =>
+        `${key}=${
+          isObjectOrArray(parameters[key])
+            ? JSON.stringify(parameters[key])
+            : parameters[key]
+        }`
+    )
+    .join('&');
+}
+
+export function serializeData(
+  request: Request,
+  requestOptions: RequestOptions
+): string | undefined {
+  if (
+    request.method === 'GET' ||
+    (request.data === undefined && requestOptions.data === undefined)
+  ) {
+    return undefined;
+  }
+
+  const data = Array.isArray(request.data)
+    ? request.data
+    : { ...request.data, ...requestOptions.data };
+
+  return JSON.stringify(data);
+}
+
+export function serializeHeaders(
+  baseHeaders: Headers,
+  requestHeaders: Headers,
+  requestOptionsHeaders?: Headers
+): Headers {
+  const headers: Headers = {
+    Accept: 'application/json',
+    ...baseHeaders,
+    ...requestHeaders,
+    ...requestOptionsHeaders,
+  };
+  const serializedHeaders: Headers = {};
+
+  Object.keys(headers).forEach((header) => {
+    const value = headers[header];
+    serializedHeaders[header.toLowerCase()] = value;
+  });
+
+  return serializedHeaders;
+}
+
+export function deserializeSuccess<TObject>(response: Response): TObject {
+  try {
+    return JSON.parse(response.content);
+  } catch (e) {
+    throw new DeserializationError((e as Error).message, response);
+  }
+}
+
+export function deserializeFailure(
+  { content, status }: Response,
+  stackFrame: StackFrame[]
+): Error {
+  let message = content;
+  try {
+    message = JSON.parse(content).message;
+  } catch (e) {
+    // ..
+  }
+  return new ApiError(message, status, stackFrame);
+}

package/src/transporter/index.ts

@@ -0,0 +1,6 @@
+export * from './createTransporter';
+export * from './createStatefulHost';
+export * from './errors';
+export * from './helpers';
+export * from './responses';
+export * from './stackTrace';

package/src/transporter/responses.ts

@@ -0,0 +1,23 @@
+import type { Response } from '../types';
+
+export function isNetworkError({
+  isTimedOut,
+  status,
+}: Omit<Response, 'content'>): boolean {
+  return !isTimedOut && ~~status === 0;
+}
+
+export function isRetryable({
+  isTimedOut,
+  status,
+}: Omit<Response, 'content'>): boolean {
+  return (
+    isTimedOut ||
+    isNetworkError({ isTimedOut, status }) ||
+    (~~(status / 100) !== 2 && ~~(status / 100) !== 4)
+  );
+}
+
+export function isSuccess({ status }: Pick<Response, 'status'>): boolean {
+  return ~~(status / 100) === 2;
+}

package/src/transporter/stackTrace.ts

@@ -0,0 +1,30 @@
+import type { Headers, StackFrame } from '../types';
+
+export function stackTraceWithoutCredentials(
+  stackTrace: StackFrame[]
+): StackFrame[] {
+  return stackTrace.map((stackFrame) =>
+    stackFrameWithoutCredentials(stackFrame)
+  );
+}
+
+export function stackFrameWithoutCredentials(
+  stackFrame: StackFrame
+): StackFrame {
+  const modifiedHeaders: Headers = stackFrame.request.headers[
+    'x-algolia-api-key'
+  ]
+    ? { 'x-algolia-api-key': '*****' }
+    : {};
+
+  return {
+    ...stackFrame,
+    request: {
+      ...stackFrame.request,
+      headers: {
+        ...stackFrame.request.headers,
+        ...modifiedHeaders,
+      },
+    },
+  };
+}

package/src/types/cache.ts

@@ -0,0 +1,61 @@
+export type Cache = {
+  /**
+   * Gets the value of the given `key`.
+   */
+  get: <TValue>(
+    key: Record<string, any> | string,
+    defaultValue: () => Promise<TValue>,
+    events?: CacheEvents<TValue>
+  ) => Promise<TValue>;
+
+  /**
+   * Sets the given value with the given `key`.
+   */
+  set: <TValue>(
+    key: Record<string, any> | string,
+    value: TValue
+  ) => Promise<TValue>;
+
+  /**
+   * Deletes the given `key`.
+   */
+  delete: (key: Record<string, any> | string) => Promise<void>;
+
+  /**
+   * Clears the cache.
+   */
+  clear: () => Promise<void>;
+};
+
+export type CacheEvents<TValue> = {
+  /**
+   * The callback when the given `key` is missing from the cache.
+   */
+  miss: (value: TValue) => Promise<any>;
+};
+
+export type MemoryCacheOptions = {
+  /**
+   * If keys and values should be serialized using `JSON.stringify`.
+   */
+  serializable?: boolean;
+};
+
+export type BrowserLocalStorageOptions = {
+  /**
+   * The cache key.
+   */
+  key: string;
+
+  /**
+   * The native local storage implementation.
+   */
+  localStorage?: Storage;
+};
+
+export type FallbackableCacheOptions = {
+  /**
+   * List of caches order by priority.
+   */
+  caches: Cache[];
+};

package/src/types/createClient.ts

@@ -0,0 +1,23 @@
+import type { AlgoliaAgentOptions, TransporterOptions } from './transporter';
+
+export type AuthMode = 'WithinHeaders' | 'WithinQueryParameters';
+
+type OverriddenTransporterOptions =
+  | 'baseHeaders'
+  | 'baseQueryParameters'
+  | 'hosts';
+
+export type CreateClientOptions = Omit<
+  TransporterOptions,
+  OverriddenTransporterOptions | 'algoliaAgent'
+> &
+  Partial<Pick<TransporterOptions, OverriddenTransporterOptions>> & {
+    appId: string;
+    apiKey: string;
+    authMode?: AuthMode;
+    algoliaAgents: AlgoliaAgentOptions[];
+  };
+
+export type ClientOptions = Partial<
+  Omit<CreateClientOptions, 'apiKey' | 'appId'>
+>;

package/src/types/createIterablePromise.ts

@@ -0,0 +1,40 @@
+export type IterableOptions<TResponse> = Partial<{
+  /**
+   * The function that runs right after the API call has been resolved, allows you to do anything with the response before `validate`.
+   */
+  aggregator: (response: TResponse) => void;
+
+  /**
+   * The `validate` condition to throw an error and its message.
+   */
+  error: {
+    /**
+     * The function to validate the error condition.
+     */
+    validate: (response: TResponse) => boolean;
+
+    /**
+     * The error message to throw.
+     */
+    message: (response: TResponse) => string;
+  };
+
+  /**
+   * The function to decide how long to wait between iterations.
+   */
+  timeout: () => number;
+}>;
+
+export type CreateIterablePromise<TResponse> = IterableOptions<TResponse> & {
+  /**
+   * The function to run, which returns a promise.
+   *
+   * The `previousResponse` parameter (`undefined` on the first call) allows you to build your request with incremental logic, to iterate on `page` or `cursor` for example.
+   */
+  func: (previousResponse?: TResponse) => Promise<TResponse>;
+
+  /**
+   * The validator function. It receive the resolved return of the API call.
+   */
+  validate: (response: TResponse) => boolean;
+};