@zuplo/cli 7.7.7 → 7.7.9

package/node_modules/@posthog/core/src/metrics/index.ts

@@ -9,7 +9,10 @@ import type {
   OtlpNumberDataPoint,
 } from '@posthog/types'
 import type { Logger } from '../types'
-import { isArray, safeSetTimeout } from '../utils'
+import { isArray } from '../utils'
+import { FlushTimer } from '../utils/flush-timer'
+import { RetryAfterWindow } from '../utils/retry-after'
+import { MAX_FLUSH_BACKOFF_MS, NO_JITTER, backoffDelayMs, drawJitter } from '../utils/backoff'
 import { toOtlpKeyValueList } from '../utils/otlp-any-value'
 import {
   DEFAULT_HISTOGRAM_BOUNDS,
@@ -62,7 +65,11 @@ interface SeriesState {
  */
 export class PostHogMetrics {
   private _series = new Map<string, SeriesState>()
-  private _flushTimer?: ReturnType<typeof safeSetTimeout>
+  private readonly _flushTimer = new FlushTimer(() =>
+    this.flush().catch((e) => {
+      this._logger.error('Metrics flush failed:', e)
+    })
+  )
   // Serializes flushes — a manual flush() during an in-flight timer flush
   // queues behind it instead of racing it for the same window.
   private _flushPromise: Promise<void> | null = null
@@ -73,6 +80,9 @@ export class PostHogMetrics {
   // types under one name produces charts that blend both series.
   private _typeByName = new Map<string, MetricType>()
   private _typeCollisionWarned = new Set<string>()
+  private _retryAfter = new RetryAfterWindow()
+  private _consecutiveFlushFailures = 0
+  private _flushJitter = NO_JITTER
   // Bumped by reset(). A flush that was in flight when reset() ran (e.g. it
   // lost a shutdown race) sees a stale generation when its send settles and
   // discards its window instead of merging it back and re-arming the timer.
@@ -136,7 +146,10 @@ export class PostHogMetrics {
   /** Clears the flush timer, drops the current window, and invalidates in-flight flushes. */
   reset(): void {
     this._generation++
-    this._clearFlushTimer()
+    this._retryAfter.reset()
+    this._consecutiveFlushFailures = 0
+    this._flushJitter = NO_JITTER
+    this._flushTimer.clear()
     this._series = new Map()
     this._flushPromise = null
     this._seriesCapWarned = false
@@ -284,26 +297,35 @@ export class PostHogMetrics {
     return result
   }
 
+  // Every capture calls this, so a pending timer is left alone — re-arming on
+  // each one would push the flush out for as long as metrics keep arriving.
   private _armFlushTimer(): void {
-    if (this._flushTimer) {
+    if (this._flushTimer.pending) {
       return
     }
-    this._flushTimer = safeSetTimeout(() => {
-      this._flushTimer = undefined
-      this.flush().catch((e) => {
-        this._logger.error('Metrics flush failed:', e)
-      })
-    }, this._config.flushIntervalMs)
+    this._flushTimer.arm(this._nextFlushDelay())
   }
 
-  private _clearFlushTimer(): void {
-    if (this._flushTimer) {
-      clearTimeout(this._flushTimer)
-      this._flushTimer = undefined
-    }
+  // A floor, not a replacement: the header never retries us sooner than our own
+  // backoff would have. The backoff doubles per consecutive failure so a
+  // sustained outage is not retried every interval, and the jitter is drawn
+  // once per failure so a fleet refused together does not return together.
+  private _nextFlushDelay(): number {
+    return Math.max(
+      backoffDelayMs(
+        this._config.flushIntervalMs,
+        this._consecutiveFlushFailures,
+        this._flushJitter,
+        MAX_FLUSH_BACKOFF_MS
+      ),
+      this._retryAfter.remainingMs()
+    )
   }
 
   private async _doFlush(): Promise<void> {
+    // A flush retires the pending timer, so a delay armed for a window this
+    // flush may close cannot outlive it.
+    this._flushTimer.clear()
     if (this._series.size === 0) {
       return
     }
@@ -323,6 +345,21 @@ export class PostHogMetrics {
       // reconfigured, so this window is dropped whatever the outcome was.
       return
     }
+    this._retryAfter.record(outcome)
+    // Before any delay is taken from it, so the timer armed below is measured
+    // against this outcome rather than the one before it.
+    if (outcome.kind === 'retry-later') {
+      this._consecutiveFlushFailures++
+      this._flushJitter = drawJitter()
+    } else {
+      this._consecutiveFlushFailures = 0
+      this._flushJitter = NO_JITTER
+    }
+    // Outright, not through the ratchet: a timer a mid-flight capture armed is
+    // measured against a window this outcome may just have closed.
+    if (this._flushTimer.pending) {
+      this._flushTimer.arm(this._nextFlushDelay())
+    }
     switch (outcome.kind) {
       case 'ok':
         return
@@ -331,7 +368,7 @@ export class PostHogMetrics {
         // the next flush instead of being lost — and re-arm the timer, since
         // with no new captures nothing else would schedule that flush.
         this._mergeWindowBack(window)
-        this._armFlushTimer()
+        this._flushTimer.armNoEarlierThan(this._nextFlushDelay())
         return
       case 'too-large':
         this._logger.warn('Metrics batch exceeded the server size limit and was dropped')

package/node_modules/@posthog/core/src/metrics/metrics-utils.ts

@@ -1,6 +1,5 @@
 import type { MetricAttributeValue, OtlpMetric, OtlpMetricsPayload } from '@posthog/types'
-import { toOtlpKeyValueList } from '../utils/otlp-any-value'
-import { buildOtlpResourceAttributes } from '../utils/otlp-resource'
+import { buildOtlpResourceAttributes, toOtlpResourceKeyValueList } from '../utils/otlp-resource'
 import type { ResolvedPostHogMetricsConfig } from './types'
 
 /**
@@ -81,7 +80,7 @@ export function buildOtlpMetricsPayload(
   return {
     resourceMetrics: [
       {
-        resource: { attributes: toOtlpKeyValueList(resourceAttributes) },
+        resource: { attributes: toOtlpResourceKeyValueList(resourceAttributes) },
         scopeMetrics: [
           {
             scope: { name: scopeName, version: scopeVersion },

package/node_modules/@posthog/core/src/metrics/types.ts

@@ -20,8 +20,16 @@ import type { BeforeSendMetricFn, MetricAttributeValue, OtlpMetricsPayload } fro
 /** Same tagged outcome shape as `SendLogsBatchOutcome` — one policy for both signals. */
 export type SendMetricsBatchOutcome =
   | { kind: 'ok' }
-  | { kind: 'retry-later'; error: unknown }
-  | { kind: 'too-large' }
+  | { kind: 'retry-later'; error: unknown; retryAfterMs?: number }
+  | {
+      kind: 'too-large'
+      /**
+       * True when the SDK measured the body itself rather than the endpoint
+       * refusing it, so the caller can split this drain without lowering the
+       * batch size it keeps between them.
+       */
+      measuredLocally?: boolean
+    }
   | { kind: 'fatal'; error: unknown }
 
 /**

package/node_modules/@posthog/core/src/posthog-core-stateless.ts

@@ -1,5 +1,6 @@
-import type { OtlpLogsPayload, OtlpMetricsPayload } from '@posthog/types'
+import type { OtlpLogsPayload, OtlpMetricsPayload, OtlpTracesPayload } from '@posthog/types'
 import type { SendMetricsBatchOutcome } from './metrics/types'
+import type { SendTracesBatchOutcome } from './traces/types'
 import { SimpleEventEmitter } from './eventemitter'
 import { getFeatureFlagValue, minimizeFlagCalledEventProperties, normalizeFlagsResponse } from './featureFlagUtils'
 import { gzipCompress, isGzipSupported } from './gzip'
@@ -40,6 +41,7 @@ import {
   getEventUuid,
   safeJsonStringify,
 } from './utils'
+import { parseRetryAfterMs } from './utils/retry-after'
 import { uuidv7 } from './vendor/uuidv7'
 import {
   ErrorPropertiesBuilder,
@@ -69,6 +71,20 @@ class PostHogFetchHttpError extends Error {
     return this.response.status
   }
 
+  /**
+   * The response's `Retry-After` as milliseconds from now, when it sent a usable
+   * one, clamped to `MAX_RETRY_AFTER_MS`.
+   */
+  get retryAfterMs(): number | undefined {
+    try {
+      return parseRetryAfterMs(this.response.headers?.get('retry-after'))
+    } catch {
+      // `headers.get` is injected transport code; a throwing one must not turn a
+      // retriable failure into an unhandled rejection.
+      return undefined
+    }
+  }
+
   get bodyReadTimedOut(): boolean {
     return this._bodyReadTimedOut
   }
@@ -205,6 +221,46 @@ function isRetryableFlagsFetchError(
   return code !== 'ECONNREFUSED'
 }
 
+/**
+ * Ceiling on what the SDK will put on the wire: a body over it is reported as
+ * too large without a request being made, and a batch of one that still exceeds
+ * it is dropped. The ingestion service decompresses a `Content-Encoding: gzip`
+ * request before it applies its own `MAX_REQUEST_BODY_SIZE_BYTES`, so the size
+ * that has to stay under the limit is the uncompressed one measured here.
+ *
+ * Set to the largest limit any known deployment configures — 10 MiB, what the
+ * ingestion service runs with — rather than the 2 MB the service falls back to
+ * when nothing configures it. The ceiling only earns its place by refusing a
+ * body that no deployment would have accepted: at 2 MB it would instead refuse
+ * bodies the service takes today, dropping records with no `413` to show for
+ * them. Deployments configured lower, and proxies in front of them, are covered
+ * by the `413` path, which stays the primary mechanism.
+ */
+const OTLP_MAX_BODY_BYTES = 10 * 1024 * 1024
+
+/**
+ * A request body's size on the wire. `Buffer` where it exists, `TextEncoder`
+ * elsewhere.
+ *
+ * Total by construction: it runs on hosts that define only part of the web
+ * platform — `Blob` in particular is absent on some server runtimes — and a
+ * size that cannot be measured is reported as `0`, leaving the body to be sent
+ * rather than turning a missing global into a failed export.
+ */
+function byteLengthOf(body: string | Blob | Uint8Array): number {
+  try {
+    if (typeof body !== 'string') {
+      return body instanceof Uint8Array ? body.byteLength : body.size
+    }
+    if (typeof Buffer !== 'undefined') {
+      return Buffer.byteLength(body, STRING_FORMAT)
+    }
+    return new TextEncoder().encode(body).length
+  } catch {
+    return 0
+  }
+}
+
 export function isPostHogFetchContentTooLargeError(err: unknown): err is PostHogFetchHttpError & { status: 413 } {
   return typeof err === 'object' && err instanceof PostHogFetchHttpError && err.status === 413
 }
@@ -232,19 +288,35 @@ function isPostHogEventProperties(value: JsonType | undefined): value is PostHog
  */
 export type SendLogsBatchOutcome =
   | { kind: 'ok' }
-  | { kind: 'too-large' }
-  | { kind: 'retry-later'; error: unknown }
+  | {
+      kind: 'too-large'
+      /**
+       * True when the SDK measured the body itself rather than the endpoint
+       * refusing it, so the caller can split this drain without lowering the
+       * batch size it keeps between them.
+       */
+      measuredLocally?: boolean
+    }
+  | { kind: 'retry-later'; error: unknown; retryAfterMs?: number }
   | { kind: 'fatal'; error: unknown }
 
 /**
  * Each signal keeps its own exported outcome type because each belongs to a
- * separate host contract. The wrappers return this value directly, so one
- * drifting out of shape fails to compile.
+ * separate host contract. The wrappers return this value directly, so any of
+ * the three drifting out of shape fails to compile.
  */
 type SendOtlpBatchOutcome =
   | { kind: 'ok' }
-  | { kind: 'too-large' }
-  | { kind: 'retry-later'; error: unknown }
+  | {
+      kind: 'too-large'
+      /**
+       * True when the SDK measured the body itself rather than the endpoint
+       * refusing it, so the caller can split this drain without lowering the
+       * batch size it keeps between them.
+       */
+      measuredLocally?: boolean
+    }
+  | { kind: 'retry-later'; error: unknown; retryAfterMs?: number }
   | { kind: 'fatal'; error: unknown }
 
 export enum QuotaLimitedFeature {
@@ -1326,11 +1398,20 @@ export abstract class PostHogCoreStateless {
     if (this.pendingFlushPromise) {
       return
     }
-    void this.flush().catch(async (err) => {
+    void this.flushAutomatic().catch(async (err) => {
       await logFlushError(err)
     })
   }
 
+  /**
+   * The flush the SDK runs on its own, from the interval timer or the `flushAt`
+   * threshold. Separate from `flush()` so a host can hold back work that an
+   * endpoint has asked it to wait on, which an explicit flush overrides.
+   */
+  protected flushAutomatic(): Promise<void> {
+    return this.flush()
+  }
+
   private async waitForPendingPromises(
     maxPromiseId: number,
     ignoredPromises: (Promise<any> | null | undefined)[] = []
@@ -1642,9 +1723,9 @@ export abstract class PostHogCoreStateless {
   }
 
   /**
-   * Shared implementation behind the OTLP senders, which differ only in path.
-   * Returns a tagged outcome instead of throwing so the queue owners don't
-   * have to know the core's error class hierarchy.
+   * Shared implementation behind the three OTLP senders, which differ only in
+   * path and auth style. Returns a tagged outcome instead of throwing so the
+   * queue owners don't have to know the core's error class hierarchy.
    *
    * Exhausted 408/429/5xx stay `retry-later`, unlike the events `_flush()`
    * which drops anything that isn't a network error: every OTLP queue is
@@ -1653,27 +1734,64 @@ export abstract class PostHogCoreStateless {
    */
   private async _sendOtlpBatch({
     path,
+    auth,
     payload,
   }: {
-    path: 'logs' | 'metrics'
-    payload: OtlpLogsPayload | OtlpMetricsPayload
+    path: 'logs' | 'metrics' | 'traces'
+    auth: 'query-token' | 'bearer'
+    payload: OtlpLogsPayload | OtlpMetricsPayload | OtlpTracesPayload
   }): Promise<SendOtlpBatchOutcome> {
     if (this.disabled) {
       return { kind: 'fatal', error: new Error('The client is disabled') }
     }
 
-    const serialized = JSON.stringify(payload)
-    const url = `${this.host}/i/v1/${path}?token=${encodeURIComponent(this.apiKey)}`
+    // Serialised behind a guard: a payload too big to hold as one string throws
+    // `RangeError` here, which escapes the tagged-outcome contract and leaves the
+    // caller retrying a batch it can never send. Reported as too-large so it takes
+    // the same halve-and-isolate path as a batch that serialises but is oversized.
+    let serialized: string
+    try {
+      serialized = JSON.stringify(payload)
+    } catch (error) {
+      this.logMsgIfDebug(() =>
+        console.warn(`[PostHog] Could not serialize a ${path} batch; reporting it as too large`, error)
+      )
+      return { kind: 'too-large', measuredLocally: true }
+    }
+
+    // Measured on the uncompressed payload: the endpoint decompresses the body
+    // and applies its limit to what comes out, so one that gzips small is still
+    // refused on its decompressed size. A batch the endpoint cannot accept is
+    // reported without being sent — and before it is compressed — so the caller
+    // halves it, and ultimately isolates and drops the one oversized record,
+    // without spending a request or a gzip pass on each attempt.
+    const payloadBytes = byteLengthOf(serialized)
+    if (payloadBytes > OTLP_MAX_BODY_BYTES) {
+      this.logMsgIfDebug(() =>
+        console.warn(
+          `[PostHog] Not sending a ${path} batch of ${payloadBytes} bytes: the endpoint accepts at most ${OTLP_MAX_BODY_BYTES}`
+        )
+      )
+      return { kind: 'too-large', measuredLocally: true }
+    }
+
+    const url =
+      auth === 'bearer'
+        ? `${this.host}/i/v1/${path}`
+        : `${this.host}/i/v1/${path}?token=${encodeURIComponent(this.apiKey)}`
 
     const gzippedPayload = !this.disableCompression ? await this.compressPayload(serialized) : null
+    const body = gzippedPayload || serialized
+
     const fetchOptions: PostHogFetchOptions = {
       method: 'POST',
       headers: {
         ...this.getCustomHeaders(),
         'Content-Type': 'application/json',
+        ...(auth === 'bearer' && { Authorization: `Bearer ${this.apiKey}` }),
         ...(gzippedPayload !== null && { 'Content-Encoding': 'gzip' }),
       },
-      body: gzippedPayload || serialized,
+      body,
     }
 
     try {
@@ -1686,6 +1804,12 @@ export abstract class PostHogCoreStateless {
             if (isPostHogFetchContentTooLargeError(err)) {
               return false
             }
+            if (err instanceof PostHogFetchHttpError && err.retryAfterMs !== undefined) {
+              // The endpoint named a wait. This loop retries on a fixed short
+              // delay, so retrying here would spend every attempt inside the
+              // window; hand it to the queue's backoff instead.
+              return false
+            }
             return isPostHogFetchRetryableError(err)
           },
         }
@@ -1696,18 +1820,31 @@ export abstract class PostHogCoreStateless {
         return { kind: 'too-large' }
       }
       if (isPostHogFetchRetryableError(err)) {
-        return { kind: 'retry-later', error: err }
+        const retryAfterMs = err instanceof PostHogFetchHttpError ? err.retryAfterMs : undefined
+        return { kind: 'retry-later', error: err, ...(retryAfterMs !== undefined && { retryAfterMs }) }
       }
       return { kind: 'fatal', error: err }
     }
   }
 
   async _sendLogsBatch(payload: OtlpLogsPayload): Promise<SendLogsBatchOutcome> {
-    return this._sendOtlpBatch({ path: 'logs', payload })
+    return this._sendOtlpBatch({ path: 'logs', auth: 'query-token', payload })
   }
 
   async _sendMetricsBatch(payload: OtlpMetricsPayload): Promise<SendMetricsBatchOutcome> {
-    return this._sendOtlpBatch({ path: 'metrics', payload })
+    return this._sendOtlpBatch({ path: 'metrics', auth: 'query-token', payload })
+  }
+
+  /**
+   * The `TracesHost._sendTracesBatch` implementation, so `PostHogTraces` can
+   * use any core-based SDK as its host.
+   *
+   * Authenticates with `Authorization: Bearer` rather than the `?token=` query
+   * parameter the logs and metrics senders use: it's the service's primary auth
+   * path, and server runtimes have no CORS preflight to avoid.
+   */
+  async _sendTracesBatch(payload: OtlpTracesPayload): Promise<SendTracesBatchOutcome> {
+    return this._sendOtlpBatch({ path: 'traces', auth: 'bearer', payload })
   }
 
   private fetchWithRetry<T>(
@@ -1732,25 +1869,7 @@ export abstract class PostHogCoreStateless {
     requestTimeout?: number
   ): Promise<T | void> {
     const body = options.body ? options.body : ''
-    let reqByteLength = -1
-    try {
-      if (body instanceof Blob) {
-        reqByteLength = body.size
-      } else if (body instanceof Uint8Array) {
-        reqByteLength = body.byteLength
-      } else {
-        reqByteLength = Buffer.byteLength(body, STRING_FORMAT)
-      }
-    } catch {
-      if (body instanceof Blob) {
-        reqByteLength = body.size
-      } else if (body instanceof Uint8Array) {
-        reqByteLength = body.byteLength
-      } else {
-        const encoded = new TextEncoder().encode(body)
-        reqByteLength = encoded.length
-      }
-    }
+    const reqByteLength = byteLengthOf(body)
 
     const retriableOptions = { ...this._retryOptions, ...retryOptions }
     let attempt = 0