@logbrew/sdk 0.1.38 → 0.1.40

package/automatic-delivery.cjs

@@ -0,0 +1,271 @@
+const { incrementBounded } = require("./bounded-number.cjs");
+const { propertyOf } = require("./error-details.cjs");
+const { automaticRetryDelayMs, rateLimitWaitMs } = require("./retry-delay.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+
+/**
+ * @typedef {"none" | "authentication" | "rate_limit" | "non_retryable"} PauseReason
+ * @typedef {Readonly<{ pausedReason: PauseReason, retryDelayMs: number }>} FailurePlan
+ * @typedef {Readonly<{ code: string, retryAfterMs: number | undefined, retryable: boolean | undefined }>} DeliveryFailure
+ * @typedef {Readonly<{
+ *   canDeliver: () => boolean,
+ *   isOpen: () => boolean,
+ *   queueLength: () => number,
+ *   flush: () => Promise<unknown>,
+ *   serialize: (operation: () => Promise<void>) => Promise<void>,
+ *   deliveryIntervalMs: number,
+ *   deliveryQueueThreshold: number
+ * }>} DeliveryHost
+ */
+
+const NO_DELAY = 0;
+/** @type {FailurePlan} */
+const NON_RETRYABLE = { pausedReason: "non_retryable", retryDelayMs: NO_DELAY };
+const NO_EVENTS = 0;
+
+/**
+ * @param {unknown} timer
+ * @returns {void}
+ */
+function unrefTimer(timer) {
+  const unref = typeof timer === "object" ? propertyOf(timer, "unref") : undefined;
+  if (typeof unref === "function") {
+    Reflect.apply(unref, timer, []);
+  }
+}
+
+/**
+ * @param {unknown} reason
+ * @returns {DeliveryFailure | undefined}
+ */
+function deliveryFailure(reason) {
+  if (!(reason instanceof SdkError)) {
+    return undefined;
+  }
+  return { code: reason.code, retryAfterMs: reason.retryAfterMs, retryable: reason.retryable };
+}
+
+/**
+ * @param {DeliveryFailure} reason
+ * @param {number} retryDelayMs
+ * @returns {FailurePlan}
+ */
+function sdkFailurePlan(reason, retryDelayMs) {
+  if (reason.code === "unauthenticated") {
+    return { pausedReason: "authentication", retryDelayMs: NO_DELAY };
+  }
+  if (reason.code === "rate_limited") {
+    return reason.retryable === true
+      ? { pausedReason: "none", retryDelayMs: rateLimitWaitMs(reason.retryAfterMs ?? retryDelayMs) }
+      : { pausedReason: "rate_limit", retryDelayMs: NO_DELAY };
+  }
+  return reason.retryable === true
+    ? { pausedReason: "none", retryDelayMs }
+    : { pausedReason: "non_retryable", retryDelayMs: NO_DELAY };
+}
+
+class AutomaticDelivery {
+  /**
+   * @param {DeliveryHost} host
+   */
+  constructor(host) {
+    this.host = host;
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    this.deliveryTimer = undefined;
+    this.automaticFlushActive = false;
+    this.automaticFlushPending = false;
+    /** @type {PauseReason} */
+    this.automaticPauseReason = "none";
+    this.consecutiveDeliveryFailures = 0;
+    this.retryDelayMs = 0;
+  }
+
+  /**
+   * @returns {boolean}
+   */
+  ready() {
+    return this.host.canDeliver() && this.automaticPauseReason === "none";
+  }
+
+  /**
+   * @returns {void}
+   */
+  schedule() {
+    if (!this.ready()) {
+      return;
+    }
+    if (this.automaticFlushActive) {
+      this.automaticFlushPending = true;
+    } else if (this.retryDelayMs > NO_DELAY) {
+      this.armTimer(this.retryDelayMs);
+    } else if (this.host.queueLength() >= this.host.deliveryQueueThreshold) {
+      this.requestFlush();
+    } else {
+      this.armTimer(this.host.deliveryIntervalMs);
+    }
+  }
+
+  /**
+   * @param {number} delayMs
+   * @returns {void}
+   */
+  armTimer(delayMs) {
+    if (!this.ready() || this.deliveryTimer !== undefined) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      if (this.deliveryTimer !== timer) {
+        return;
+      }
+      this.deliveryTimer = undefined;
+      this.retryDelayMs = 0;
+      this.requestFlush();
+    }, delayMs);
+    this.deliveryTimer = timer;
+    unrefTimer(timer);
+  }
+
+  /**
+   * @returns {void}
+   */
+  clearTimer() {
+    if (this.deliveryTimer === undefined) {
+      return;
+    }
+    globalThis.clearTimeout(this.deliveryTimer);
+    this.deliveryTimer = undefined;
+  }
+
+  /**
+   * @returns {void}
+   */
+  requestFlush() {
+    if (!this.ready()) {
+      return;
+    }
+    this.clearTimer();
+    if (this.automaticFlushActive) {
+      this.automaticFlushPending = true;
+      return;
+    }
+    this.automaticFlushActive = true;
+    queueMicrotask(() => {
+      void this.runFlush();
+    });
+  }
+
+  /**
+   * @returns {Promise<void>}
+   */
+  async runFlush() {
+    if (this.stopWhenClosed()) {
+      return;
+    }
+    await this.host.serialize(async () => {
+      let succeeded = false;
+      try {
+        await this.host.flush();
+        this.recordSuccess();
+        succeeded = true;
+      } catch (error) {
+        this.recordFailure(error);
+      } finally {
+        this.automaticFlushActive = false;
+        this.afterFlush(succeeded);
+      }
+    });
+  }
+
+  /**
+   * @returns {boolean}
+   */
+  stopWhenClosed() {
+    if (this.host.isOpen()) {
+      return false;
+    }
+    this.automaticFlushActive = false;
+    this.automaticFlushPending = false;
+    return true;
+  }
+
+  /**
+   * @param {boolean} succeeded
+   * @returns {void}
+   */
+  afterFlush(succeeded) {
+    if (!this.host.isOpen()) {
+      this.automaticFlushPending = false;
+      return;
+    }
+    const drainCoalesced = succeeded && this.automaticFlushPending && this.host.queueLength() > NO_EVENTS;
+    this.automaticFlushPending = false;
+    if (drainCoalesced) {
+      this.requestFlush();
+    } else if (succeeded) {
+      this.schedule();
+    } else {
+      this.resume();
+    }
+  }
+
+  /**
+   * @returns {void}
+   */
+  recordSuccess() {
+    this.automaticPauseReason = "none";
+    this.consecutiveDeliveryFailures = 0;
+    this.retryDelayMs = 0;
+  }
+
+  /**
+   * @param {unknown} reason
+   * @returns {void}
+   */
+  recordFailure(reason) {
+    this.consecutiveDeliveryFailures = incrementBounded(this.consecutiveDeliveryFailures);
+    this.retryDelayMs = 0;
+    const failure = deliveryFailure(reason);
+    const plan = failure === undefined ? NON_RETRYABLE : sdkFailurePlan(failure, this.backoffDelayMs(failure));
+    this.automaticPauseReason = plan.pausedReason;
+    this.retryDelayMs = plan.retryDelayMs;
+  }
+
+  /**
+   * @param {DeliveryFailure} reason
+   * @returns {number}
+   */
+  backoffDelayMs(reason) {
+    const backoff = reason.code !== "unauthenticated" && reason.retryable === true
+      && (reason.code !== "rate_limited" || reason.retryAfterMs === undefined);
+    return backoff ? automaticRetryDelayMs(this.host.deliveryIntervalMs, this.consecutiveDeliveryFailures) : NO_DELAY;
+  }
+
+  /**
+   * @returns {void}
+   */
+  resume() {
+    if (this.automaticPauseReason !== "none") {
+      return;
+    }
+    if (this.retryDelayMs > NO_DELAY) {
+      this.armTimer(this.retryDelayMs);
+      return;
+    }
+    this.schedule();
+  }
+
+  /**
+   * @returns {Readonly<{ scheduled: boolean, coalesced: boolean, pausedReason: PauseReason, consecutiveFailures: number, retryDelayMs: number }>}
+   */
+  health() {
+    return {
+      coalesced: this.automaticFlushPending,
+      consecutiveFailures: this.consecutiveDeliveryFailures,
+      pausedReason: this.automaticPauseReason,
+      retryDelayMs: this.retryDelayMs,
+      scheduled: this.deliveryTimer !== undefined
+    };
+  }
+}
+
+module.exports = { AutomaticDelivery };

package/batch-sender.cjs

@@ -0,0 +1,164 @@
+const { incrementBounded, nextBoundedTimestamp } = require("./bounded-number.cjs");
+const { propertyOf } = require("./error-details.cjs");
+const { SdkError, retryAfterMsOrUndefined } = require("./sdk-error.cjs");
+const { TransportError } = require("./transport-error.cjs");
+const { isRecord } = require("./validation.cjs");
+
+/**
+ * @typedef {"none" | "transport_error" | "invalid_response" | "network_error" | "success" | "client_error" | "server_error" | "other_status"} StatusClass
+ * @typedef {Readonly<{ send: (apiKey: string, body: string) => unknown }>} BatchTransport
+ * @typedef {Readonly<{ statusCode: number, attempts: number }>} SendResult
+ * @typedef {Readonly<{ apiKey: () => string, maxRetries: number }>} SenderConfig
+ */
+
+const FIRST_ATTEMPT = 1;
+const MIN_STATUS = 100;
+const MAX_STATUS = 599;
+const MIN_SUCCESS = 200;
+const MIN_REDIRECT = 300;
+const MIN_CLIENT_ERROR = 400;
+const MIN_SERVER_ERROR = 500;
+const UNAUTHORIZED = 401;
+const REQUEST_TIMEOUT = 408;
+const TOO_MANY_REQUESTS = 429;
+
+/**
+ * @param {number} statusCode
+ * @returns {StatusClass}
+ */
+function statusClass(statusCode) {
+  if (statusCode >= MIN_SUCCESS && statusCode < MIN_REDIRECT) {
+    return "success";
+  }
+  if (statusCode >= MIN_CLIENT_ERROR && statusCode < MIN_SERVER_ERROR) {
+    return "client_error";
+  }
+  return statusCode >= MIN_SERVER_ERROR ? "server_error" : "other_status";
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} response
+ * @returns {number | undefined}
+ */
+function validStatusCode(response) {
+  const { statusCode } = response;
+  if (typeof statusCode !== "number" || !Number.isSafeInteger(statusCode)) {
+    return undefined;
+  }
+  return statusCode >= MIN_STATUS && statusCode <= MAX_STATUS ? statusCode : undefined;
+}
+
+/**
+ * @param {unknown} response
+ * @param {number} statusCode
+ * @returns {void}
+ */
+function rejectRefusal(response, statusCode) {
+  if (statusCode === UNAUTHORIZED) {
+    throw new SdkError("unauthenticated", "transport rejected the API key");
+  }
+  if (statusCode === TOO_MANY_REQUESTS) {
+    const retryAfterMs = propertyOf(response, "retryAfterMs");
+    const errorCode = propertyOf(response, "errorCode");
+    throw new SdkError("rate_limited", "transport rate limited the batch", {
+      retryAfterMs,
+      retryable: errorCode !== "usage_limit_exceeded"
+        && (retryAfterMsOrUndefined(retryAfterMs) !== undefined || errorCode === "rate_limited")
+    });
+  }
+}
+
+class BatchSender {
+  /**
+   * @param {SenderConfig} config
+   */
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.maxRetries = config.maxRetries;
+    this.deliveryAttemptCount = 0;
+    this.lastAttemptAtUnixMs = 0;
+    /** @type {StatusClass} */
+    this.lastStatusClass = "none";
+  }
+
+  /**
+   * @param {BatchTransport} transport
+   * @param {string} body
+   * @returns {Promise<SendResult>}
+   */
+  async send(transport, body) {
+    const maxAttempts = this.maxRetries + FIRST_ATTEMPT;
+    for (let attempts = FIRST_ATTEMPT; attempts <= maxAttempts; attempts += FIRST_ATTEMPT) {
+      this.beginAttempt();
+      const canRetry = attempts < maxAttempts;
+      try {
+        const statusCode = this.acceptedStatus(await transport.send(this.apiKey(), body), canRetry);
+        if (statusCode !== undefined) {
+          return { attempts, statusCode };
+        }
+      } catch (error) {
+        this.recover(error, canRetry);
+      }
+    }
+    throw new SdkError("transport_error", "exhausted retries");
+  }
+
+  /**
+   * @returns {void}
+   */
+  beginAttempt() {
+    this.deliveryAttemptCount = incrementBounded(this.deliveryAttemptCount);
+    this.lastAttemptAtUnixMs = nextBoundedTimestamp(this.lastAttemptAtUnixMs);
+    this.lastStatusClass = "transport_error";
+  }
+
+  /**
+   * @param {unknown} response
+   * @param {boolean} canRetry
+   * @returns {number | undefined}
+   */
+  acceptedStatus(response, canRetry) {
+    const statusCode = this.classifiedStatus(response);
+    rejectRefusal(response, statusCode);
+    if (statusCode >= MIN_SUCCESS && statusCode < MIN_REDIRECT) {
+      return statusCode;
+    }
+    const retryableStatus = statusCode === REQUEST_TIMEOUT || statusCode >= MIN_SERVER_ERROR;
+    if (retryableStatus && canRetry) {
+      return undefined;
+    }
+    throw new SdkError("transport_error", `unexpected transport status ${statusCode}`, { retryable: retryableStatus });
+  }
+
+  /**
+   * @param {unknown} response
+   * @returns {number}
+   */
+  classifiedStatus(response) {
+    const statusCode = isRecord(response) ? validStatusCode(response) : undefined;
+    if (statusCode === undefined) {
+      this.lastStatusClass = "invalid_response";
+      throw new SdkError("transport_error", "invalid transport response");
+    }
+    this.lastStatusClass = statusClass(statusCode);
+    return statusCode;
+  }
+
+  /**
+   * @param {unknown} reason
+   * @param {boolean} canRetry
+   * @returns {void}
+   */
+  recover(reason, canRetry) {
+    if (reason instanceof SdkError || !(reason instanceof TransportError)) {
+      throw reason;
+    }
+    this.lastStatusClass = "network_error";
+    if (reason.retryable && canRetry) {
+      return;
+    }
+    throw new SdkError(reason.code, reason.message, { retryable: reason.retryable });
+  }
+}
+
+module.exports = { BatchSender };

package/bounded-number.cjs

@@ -0,0 +1,34 @@
+const STEP = 1;
+const EPOCH_MS = 0;
+
+/**
+ * @param {number} current
+ * @param {number} increment
+ * @returns {number}
+ */
+function addBounded(current, increment) {
+  return Math.min(Number.MAX_SAFE_INTEGER, current + increment);
+}
+
+/**
+ * @param {number} value
+ * @returns {number}
+ */
+function incrementBounded(value) {
+  return value >= Number.MAX_SAFE_INTEGER ? Number.MAX_SAFE_INTEGER : value + STEP;
+}
+
+/**
+ * @param {number} previous
+ * @returns {number}
+ */
+function nextBoundedTimestamp(previous) {
+  const now = Date.now();
+  if (!Number.isFinite(now)) {
+    return previous;
+  }
+  const bounded = Math.min(Number.MAX_SAFE_INTEGER, Math.max(EPOCH_MS, Math.floor(now)));
+  return Math.max(previous, bounded);
+}
+
+module.exports = { addBounded, incrementBounded, nextBoundedTimestamp };