@visulima/pail 3.1.0 → 3.2.1

package/dist/reporter/http/abstract-http-reporter.d.ts

@@ -0,0 +1,215 @@
+import type { LiteralUnion } from "type-fest";
+import type { ExtendedRfc5424LogLevels, StringifyAwareReporter } from "../../types.d.ts";
+import type { AbstractJsonReporterOptions } from "../json/abstract-json-reporter.d.ts";
+import { AbstractJsonReporter } from "../json/abstract-json-reporter.d.ts";
+/**
+ * Configuration options for the HTTP reporter.
+ */
+export type AbstractHttpReporterOptions = AbstractJsonReporterOptions & {
+    /**
+     * Content type for batch log requests. User-specified headers take precedence.
+     * @default "application/json"
+     */
+    batchContentType?: string;
+    /**
+     * Field name to wrap batch entries in when batchMode is "field" (e.g., "batch" for Logflare)
+     * @default undefined
+     */
+    batchFieldName?: string;
+    /**
+     * Batch mode for sending multiple log entries
+     * - "delimiter": Join entries with a delimiter (default)
+     * - "field": Wrap entries in an object with a field name
+     * - "array": Send entries as a plain JSON array
+     * @default "delimiter"
+     */
+    batchMode?: "delimiter" | "field" | "array";
+    /**
+     * Delimiter to use between log entries in batch mode
+     * @default "\n"
+     */
+    batchSendDelimiter?: string;
+    /**
+     * Timeout in milliseconds for sending batches regardless of size
+     * @default 5000
+     */
+    batchSendTimeout?: number;
+    /**
+     * Number of log entries to batch before sending
+     * @default 100
+     */
+    batchSize?: number;
+    /**
+     * Whether to use gzip compression
+     * @default false
+     */
+    compression?: boolean;
+    /**
+     * Content type for single log requests. User-specified headers take precedence.
+     * @default "application/json"
+     */
+    contentType?: string;
+    /**
+     * Whether to enable Edge Runtime compatibility mode
+     * When enabled, TextEncoder and compression are disabled
+     * @default false
+     */
+    edgeCompat?: boolean;
+    /**
+     * Whether to enable batch sending
+     * @default true
+     */
+    enableBatchSend?: boolean;
+    /**
+     * Headers to include in the request. Can be an object or a function that returns headers.
+     */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Maximum size of a single log entry in bytes
+     * @default 1048576 (1MB)
+     */
+    maxLogSize?: number;
+    /**
+     * Maximum size of the payload (uncompressed) in bytes
+     * @default 5242880 (5MB)
+     */
+    maxPayloadSize?: number;
+    /**
+     * Number of retry attempts before giving up
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * HTTP method to use for requests
+     * @default "POST"
+     */
+    method?: string;
+    /**
+     * Optional callback for debugging log entries before they are sent
+     */
+    onDebug?: (entry: Record<string, unknown>) => void;
+    /**
+     * Optional callback for debugging HTTP requests and responses
+     */
+    onDebugRequestResponse?: (requestResponse: {
+        req: {
+            body: string | Uint8Array;
+            headers: Record<string, string>;
+            method: string;
+            url: string;
+        };
+        res: {
+            body: string;
+            headers: Record<string, string>;
+            status: number;
+            statusText: string;
+        };
+    }) => void;
+    /**
+     * Optional callback for error handling
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Function to transform log data into the payload format.
+     * By default, uses the JSON stringified log entry.
+     */
+    payloadTemplate?: (data: {
+        data?: Record<string, unknown>;
+        logLevel: string;
+        message: string;
+    }) => string;
+    /**
+     * Whether to respect rate limiting by waiting when a 429 response is received
+     * @default true
+     */
+    respectRateLimit?: boolean;
+    /**
+     * Base delay between retries in milliseconds
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * The URL to send logs to
+     */
+    url: string;
+};
+/**
+ * Abstract HTTP Reporter.
+ *
+ * Base class for HTTP-based reporters that sends logs to HTTP endpoints.
+ * Supports batching, compression, retries, and rate limiting.
+ * @template L - The log level type
+ */
+export declare abstract class AbstractHttpReporter<L extends string = string> extends AbstractJsonReporter<L> implements StringifyAwareReporter<L> {
+    protected url: string;
+    protected method: string;
+    protected headers: Record<string, string> | (() => Record<string, string>);
+    protected contentType: string;
+    protected batchContentType: string;
+    protected onError?: (error: Error) => void;
+    protected onDebug?: (entry: Record<string, unknown>) => void;
+    protected onDebugRequestResponse?: (requestResponse: {
+        req: {
+            body: string | Uint8Array;
+            headers: Record<string, string>;
+            method: string;
+            url: string;
+        };
+        res: {
+            body: string;
+            headers: Record<string, string>;
+            status: number;
+            statusText: string;
+        };
+    }) => void;
+    protected payloadTemplate: (data: {
+        data?: Record<string, unknown>;
+        logLevel: string;
+        message: string;
+    }) => string;
+    protected compression: boolean;
+    protected maxRetries: number;
+    protected retryDelay: number;
+    protected respectRateLimit: boolean;
+    protected enableBatchSend: boolean;
+    protected batchSize: number;
+    protected batchSendTimeout: number;
+    protected batchSendDelimiter: string;
+    protected batchMode: "delimiter" | "field" | "array";
+    protected batchFieldName?: string;
+    protected maxLogSize: number;
+    protected maxPayloadSize: number;
+    protected edgeCompat: boolean;
+    protected batchQueue: string[];
+    protected batchTimeout?: ReturnType<typeof setTimeout>;
+    protected isProcessingBatch: boolean;
+    protected currentBatchSize: number;
+    /**
+     * Creates a new instance of AbstractHttpReporter.
+     * @param config Configuration options for the reporter
+     */
+    constructor(config: AbstractHttpReporterOptions);
+    /**
+     * Processes and ships log entries to the HTTP endpoint.
+     * @param message The JSON-formatted log message
+     * @param logLevel The log level of the message
+     * @protected
+     */
+    protected _log(message: string, logLevel: LiteralUnion<ExtendedRfc5424LogLevels, L>): void;
+    /**
+     * Adds a payload to the batch queue and triggers sending if conditions are met.
+     */
+    protected addToBatch(payload: string, logEntrySize: number): void;
+    /**
+     * Processes the current batch and sends it to the HTTP endpoint.
+     */
+    protected processBatch(): Promise<void>;
+    /**
+     * Sends a batch of payloads to the HTTP endpoint.
+     */
+    protected sendBatch(batch: string[]): Promise<void>;
+    /**
+     * Sends a single payload to the HTTP endpoint.
+     */
+    protected sendPayload(payload: string, contentType?: string): Promise<void>;
+}

package/dist/reporter/http/abstract-http-reporter.js

@@ -0,0 +1,435 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  Buffer
+} = __cjs_getBuiltinModule("node:buffer");
+import { AbstractJsonReporter } from '../../packem_shared/AbstractJsonReporter-intFdT_A.js';
+const {
+  gzipSync
+} = __cjs_getBuiltinModule("node:zlib");
+
+const compressData = async (data) => {
+  const CompressionStreamClass = globalThis.CompressionStream;
+  if (CompressionStreamClass) {
+    const stream = new CompressionStreamClass("gzip");
+    const writer = stream.writable.getWriter();
+    const reader = stream.readable.getReader();
+    const encoder = new TextEncoder();
+    const chunks = [];
+    writer.write(encoder.encode(data));
+    writer.close();
+    let done = false;
+    while (!done) {
+      const result2 = await reader.read();
+      done = result2.done ?? false;
+      if (result2.value) {
+        chunks.push(result2.value);
+      }
+    }
+    const totalLength = chunks.reduce((accumulator, chunk) => accumulator + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return result;
+  }
+  return gzipSync(data);
+};
+
+class LogSizeError extends Error {
+  /**
+   * The log entry data that caused the error
+   */
+  logData;
+  /**
+   * The actual size of the log entry in bytes
+   */
+  actualSize;
+  /**
+   * The maximum allowed size in bytes
+   */
+  maxSize;
+  /**
+   * Creates a new LogSizeError instance.
+   * @param message Descriptive error message explaining the size violation
+   * @param logData The log entry data that caused the error
+   * @param actualSize Size of the log entry in bytes
+   * @param maxSize Maximum allowed size in bytes
+   * @example
+   * ```typescript
+   * throw new LogSizeError("Log too large", logData, 2000000, 1000000);
+   * ```
+   */
+  constructor(message, logData, actualSize, maxSize) {
+    super(message);
+    this.name = "LogSizeError";
+    this.logData = logData;
+    this.actualSize = actualSize;
+    this.maxSize = maxSize;
+  }
+}
+
+const calculateBackoffDelay = (baseDelay, attempt) => baseDelay * 2 ** attempt;
+const sleep = (delay) => new Promise((resolve) => {
+  setTimeout(resolve, delay);
+});
+const prepareRequestBody = (body) => {
+  if (typeof body === "string") {
+    return body;
+  }
+  return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+};
+const processResponse = async (response, url, method, headers, body, onDebugRequestResponse, onError) => {
+  const responseHeaders = {};
+  response.headers.forEach((value, key) => {
+    responseHeaders[key] = value;
+  });
+  const responseBody = await response.text();
+  const requestResponse = {
+    req: {
+      body,
+      headers,
+      method,
+      url
+    },
+    res: {
+      body: responseBody,
+      headers: responseHeaders,
+      status: response.status,
+      statusText: response.statusText
+    }
+  };
+  if (onDebugRequestResponse) {
+    onDebugRequestResponse(requestResponse);
+  }
+  if (response.ok) {
+    return false;
+  }
+  if (response.status < 500 && response.status !== 429) {
+    const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+    if (onError) {
+      onError(error);
+    }
+    throw error;
+  }
+  return true;
+};
+const handleRateLimit = (response, respectRateLimit, retryDelay, attempt, maxRetries) => {
+  if (response.status === 429 && respectRateLimit && attempt < maxRetries) {
+    const retryAfter = response.headers.get("retry-after");
+    return retryAfter ? Number.parseInt(retryAfter, 10) * 1e3 : calculateBackoffDelay(retryDelay, attempt);
+  }
+  return void 0;
+};
+const handleServerError = (response, retryDelay, attempt, maxRetries) => {
+  if (response.status >= 500 && attempt < maxRetries) {
+    return calculateBackoffDelay(retryDelay, attempt);
+  }
+  return void 0;
+};
+const calculateRetryDelay = (response, respectRateLimit, retryDelay, attempt, maxRetries) => {
+  const rateLimitDelay = handleRateLimit(response, respectRateLimit, retryDelay, attempt, maxRetries);
+  if (rateLimitDelay !== void 0) {
+    return rateLimitDelay;
+  }
+  return handleServerError(response, retryDelay, attempt, maxRetries);
+};
+const handleRetryError = async (error, attempt, maxRetries, retryDelay, onError) => {
+  if (attempt < maxRetries) {
+    const delay = calculateBackoffDelay(retryDelay, attempt);
+    await sleep(delay);
+    return true;
+  }
+  if (onError) {
+    onError(error);
+  }
+  return false;
+};
+const sendWithRetry = async (url, method, headers, body, maxRetries, retryDelay, respectRateLimit, onDebugRequestResponse, onError) => {
+  let attempt = 0;
+  while (attempt <= maxRetries) {
+    try {
+      const requestBody = prepareRequestBody(body);
+      const response = await fetch(url, {
+        body: requestBody,
+        headers,
+        method
+      });
+      const shouldRetry = await processResponse(response, url, method, headers, body, onDebugRequestResponse, onError);
+      if (!shouldRetry) {
+        return;
+      }
+      const retryDelayValue = calculateRetryDelay(response, respectRateLimit, retryDelay, attempt, maxRetries);
+      if (retryDelayValue !== void 0) {
+        await sleep(retryDelayValue);
+        attempt += 1;
+        continue;
+      }
+      if (!response.ok) {
+        const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+        if (onError) {
+          onError(error);
+        }
+        throw error;
+      }
+      return;
+    } catch (error) {
+      const shouldRetry = await handleRetryError(error, attempt, maxRetries, retryDelay, onError);
+      if (shouldRetry) {
+        attempt += 1;
+        continue;
+      }
+      throw error;
+    }
+  }
+};
+
+class AbstractHttpReporter extends AbstractJsonReporter {
+  url;
+  method;
+  headers;
+  contentType;
+  batchContentType;
+  onError;
+  onDebug;
+  onDebugRequestResponse;
+  payloadTemplate;
+  compression;
+  maxRetries;
+  retryDelay;
+  respectRateLimit;
+  enableBatchSend;
+  batchSize;
+  batchSendTimeout;
+  batchSendDelimiter;
+  batchMode;
+  batchFieldName;
+  maxLogSize;
+  maxPayloadSize;
+  edgeCompat;
+  // Batch management
+  batchQueue = [];
+  batchTimeout;
+  isProcessingBatch = false;
+  currentBatchSize = 0;
+  // Track uncompressed size of current batch
+  /**
+   * Creates a new instance of AbstractHttpReporter.
+   * @param config Configuration options for the reporter
+   */
+  constructor(config) {
+    super(config);
+    this.url = config.url;
+    this.method = config.method ?? "POST";
+    this.headers = config.headers ?? {};
+    this.contentType = config.contentType ?? "application/json";
+    this.batchContentType = config.batchContentType ?? "application/json";
+    this.onError = config.onError;
+    this.onDebug = config.onDebug;
+    this.onDebugRequestResponse = config.onDebugRequestResponse;
+    this.payloadTemplate = config.payloadTemplate ?? ((data) => JSON.stringify(data));
+    this.compression = config.compression ?? false;
+    this.maxRetries = config.maxRetries ?? 3;
+    this.retryDelay = config.retryDelay ?? 1e3;
+    this.respectRateLimit = config.respectRateLimit ?? true;
+    this.enableBatchSend = config.enableBatchSend ?? true;
+    this.batchSize = config.batchSize ?? 100;
+    this.batchSendTimeout = config.batchSendTimeout ?? 5e3;
+    this.batchSendDelimiter = config.batchSendDelimiter ?? "\n";
+    this.batchMode = config.batchMode ?? "delimiter";
+    this.batchFieldName = config.batchFieldName;
+    if (this.batchMode === "field" && !this.batchFieldName) {
+      throw new Error("batchFieldName is required when batchMode is 'field'");
+    }
+    this.maxLogSize = config.maxLogSize ?? 1048576;
+    this.maxPayloadSize = config.maxPayloadSize ?? 5242880;
+    this.edgeCompat = config.edgeCompat ?? false;
+  }
+  /**
+   * Processes and ships log entries to the HTTP endpoint.
+   * @param message The JSON-formatted log message
+   * @param logLevel The log level of the message
+   * @protected
+   */
+  // eslint-disable-next-line no-underscore-dangle
+  _log(message, logLevel) {
+    try {
+      const logData = JSON.parse(message);
+      const logLevelString = logLevel;
+      const messageString = logData.message;
+      const payloadTemplate = {
+        logLevel: logLevelString,
+        message: messageString ?? ""
+      };
+      if (logData.data) {
+        payloadTemplate["data"] = logData.data;
+      } else if (logData.context) {
+        payloadTemplate["data"] = logData.context;
+      } else {
+        const rest = { ...logData };
+        delete rest.message;
+        if (Object.keys(rest).length > 0) {
+          payloadTemplate["data"] = rest;
+        }
+      }
+      const payload = this.payloadTemplate(payloadTemplate);
+      if (this.onDebug) {
+        this.onDebug({ data: payloadTemplate.data, logLevel: logLevelString, message: messageString });
+      }
+      const logEntrySize = this.edgeCompat || typeof TextEncoder === "undefined" ? Buffer.byteLength(payload, "utf8") : new TextEncoder().encode(payload).length;
+      if (logEntrySize > this.maxLogSize) {
+        const error = new LogSizeError(
+          `Log entry exceeds maximum size of ${this.maxLogSize} bytes. Size: ${logEntrySize} bytes`,
+          { data: payloadTemplate.data, logLevel: logLevelString, message: messageString },
+          logEntrySize,
+          this.maxLogSize
+        );
+        if (this.onError) {
+          this.onError(error);
+        }
+        return;
+      }
+      if (this.enableBatchSend) {
+        this.addToBatch(payload, logEntrySize);
+      } else {
+        this.sendPayload(payload).catch((error) => {
+          if (this.onError) {
+            this.onError(error);
+          }
+        });
+      }
+    } catch (error) {
+      if (this.onError) {
+        this.onError(error);
+      }
+    }
+  }
+  /**
+   * Adds a payload to the batch queue and triggers sending if conditions are met.
+   */
+  addToBatch(payload, logEntrySize) {
+    const payloadSizeWithEntry = this.currentBatchSize + logEntrySize + this.batchSendDelimiter.length;
+    const payloadSizeThreshold = this.maxPayloadSize * 0.9;
+    if (payloadSizeWithEntry > payloadSizeThreshold && this.batchQueue.length > 0) {
+      this.processBatch();
+    }
+    this.batchQueue.push(payload);
+    this.currentBatchSize += logEntrySize + this.batchSendDelimiter.length;
+    if (!this.batchTimeout) {
+      this.batchTimeout = setTimeout(() => {
+        this.processBatch();
+      }, this.batchSendTimeout);
+    }
+    if (this.batchQueue.length >= this.batchSize) {
+      this.processBatch();
+    }
+  }
+  /**
+   * Processes the current batch and sends it to the HTTP endpoint.
+   */
+  async processBatch() {
+    if (this.isProcessingBatch || this.batchQueue.length === 0) {
+      return;
+    }
+    this.isProcessingBatch = true;
+    if (this.batchTimeout) {
+      clearTimeout(this.batchTimeout);
+      this.batchTimeout = void 0;
+    }
+    const batch = this.batchQueue.splice(0, this.batchSize);
+    this.currentBatchSize = 0;
+    for (let i = 0; i < this.batchQueue.length; i += 1) {
+      const payload = this.batchQueue[i];
+      const payloadSize = this.edgeCompat || typeof TextEncoder === "undefined" ? Buffer.byteLength(payload, "utf8") : new TextEncoder().encode(payload).length;
+      this.currentBatchSize += payloadSize + (i < this.batchQueue.length - 1 ? this.batchSendDelimiter.length : 0);
+    }
+    try {
+      await this.sendBatch(batch);
+    } catch (error) {
+      if (this.onError) {
+        this.onError(error);
+      }
+    } finally {
+      this.isProcessingBatch = false;
+      if (this.batchQueue.length > 0) {
+        this.processBatch();
+      }
+    }
+  }
+  /**
+   * Sends a batch of payloads to the HTTP endpoint.
+   */
+  async sendBatch(batch) {
+    let batchPayload;
+    switch (this.batchMode) {
+      case "array": {
+        const batchEntries = batch.map((payload) => JSON.parse(payload));
+        batchPayload = JSON.stringify(batchEntries);
+        break;
+      }
+      case "field": {
+        const fieldEntries = batch.map((payload) => JSON.parse(payload));
+        const batchObject = this.batchFieldName ? { [this.batchFieldName]: fieldEntries } : {};
+        batchPayload = JSON.stringify(batchObject);
+        break;
+      }
+      default: {
+        batchPayload = batch.join(this.batchSendDelimiter);
+        break;
+      }
+    }
+    await this.sendPayload(batchPayload, this.batchContentType);
+  }
+  /**
+   * Sends a single payload to the HTTP endpoint.
+   */
+  async sendPayload(payload, contentType) {
+    const headers = typeof this.headers === "function" ? this.headers() : { ...this.headers };
+    if (!headers["content-type"]) {
+      headers["content-type"] = contentType ?? this.contentType;
+    }
+    let finalPayload = payload;
+    if (this.compression && !this.edgeCompat) {
+      try {
+        finalPayload = await compressData(payload);
+        headers["content-encoding"] = "gzip";
+      } catch (error) {
+        if (this.onError) {
+          this.onError(new Error(`Compression failed: ${error}`));
+        }
+      }
+    }
+    await sendWithRetry(
+      this.url,
+      this.method,
+      headers,
+      finalPayload,
+      this.maxRetries,
+      this.retryDelay,
+      this.respectRateLimit,
+      this.onDebugRequestResponse,
+      this.onError
+    );
+  }
+}
+
+export { AbstractHttpReporter };

package/dist/reporter/http/http-reporter.d.ts

@@ -0,0 +1,39 @@
+import type { AbstractHttpReporterOptions } from "./abstract-http-reporter.d.ts";
+import { AbstractHttpReporter } from "./abstract-http-reporter.d.ts";
+/**
+ * HTTP Reporter.
+ *
+ * A reporter that sends logs to HTTP endpoints.
+ * Supports batching, compression, retries, and rate limiting.
+ * Works in both Node.js server and browser environments.
+ * @template L - The log level type
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ * import { HttpReporter } from "@visulima/pail/reporter/http";
+ *
+ * const logger = createPail({
+ *   reporters: [
+ *     new HttpReporter({
+ *       url: "https://api.example.com/logs",
+ *       method: "POST",
+ *       headers: {
+ *         "Authorization": "Bearer token"
+ *       },
+ *       enableBatchSend: true,
+ *       batchSize: 100
+ *     })
+ *   ]
+ * });
+ *
+ * logger.info("Application started", { version: "1.0.0" });
+ * ```
+ */
+declare class HttpReporter<L extends string = string> extends AbstractHttpReporter<L> {
+    /**
+     * Creates a new HTTP Reporter instance.
+     * @param options Configuration options for HTTP reporting
+     */
+    constructor(options: AbstractHttpReporterOptions);
+}
+export default HttpReporter;