feat(flags): Add guardrails and error backoff to local evaluation poller (#408)

* feat(flags): Add guardrails and error backoff to local evaluation poller

* tweak

* tweak

* add tests

* bump version and update changelog

* tweak

* tweak

* Update posthog-node/src/feature-flags.ts

Co-authored-by: Dylan Martin <[email protected]>

* fix linter

---------

Co-authored-by: Dylan Martin <[email protected]>

Author: havenbarnes

posthog-node/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Next
 
+# 4.8.0 - 2025-02-26
+
+1. Add guardrails and exponential error backoff in the feature flag local evaluation poller to prevent high rates of 401/403 traffic towards `/local_evaluation`
+
 # 4.7.0 - 2025-02-20
 
 ## Added

posthog-node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthog-node",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "description": "PostHog Node.js integration",
   "repository": {
     "type": "git",

posthog-node/src/feature-flags.ts

@@ -3,6 +3,7 @@ import { FeatureFlagCondition, FlagProperty, PostHogFeatureFlag, PropertyGroup }
 import { JsonType, PostHogFetchOptions, PostHogFetchResponse } from 'posthog-core/src'
 import { safeSetTimeout } from 'posthog-core/src/utils'
 import fetch from './fetch'
+import { SIXTY_SECONDS } from './posthog-node'
 
 // eslint-disable-next-line
 const LONG_SCALE = 0xfffffffffffffff
@@ -57,6 +58,8 @@ class FeatureFlagsPoller {
   debugMode: boolean = false
   onError?: (error: Error) => void
   customHeaders?: { [key: string]: string }
+  lastRequestWasAuthenticationError: boolean = false
+  authenticationErrorCount: number = 0
 
   constructor({
     pollingInterval,
@@ -78,7 +81,6 @@ class FeatureFlagsPoller {
     this.projectApiKey = projectApiKey
     this.host = host
     this.poller = undefined
-    // NOTE: as any is required here as the AbortSignal typing is slightly misaligned but works just fine
     this.fetch = options.fetch || fetch
     this.onError = options.onError
     this.customHeaders = customHeaders
@@ -375,19 +377,44 @@ class FeatureFlagsPoller {
     }
   }
 
+  /**
+   * If a client is misconfigured with an invalid or improper API key, the polling interval is doubled each time
+   * until a successful request is made, up to a maximum of 60 seconds.
+   *
+   * @returns The polling interval to use for the next request.
+   */
+  private getPollingInterval(): number {
+    if (!this.lastRequestWasAuthenticationError) {
+      return this.pollingInterval
+    }
+
+    return Math.min(SIXTY_SECONDS, this.pollingInterval * 2 ** this.authenticationErrorCount)
+  }
+
   async _loadFeatureFlags(): Promise<void> {
     if (this.poller) {
       clearTimeout(this.poller)
       this.poller = undefined
     }
-    this.poller = setTimeout(() => this._loadFeatureFlags(), this.pollingInterval)
+
+    this.poller = setTimeout(() => this._loadFeatureFlags(), this.getPollingInterval())
 
     try {
       const res = await this._requestFeatureFlagDefinitions()
 
       if (res && res.status === 401) {
+        this.lastRequestWasAuthenticationError = true
+        this.authenticationErrorCount += 1
+        throw new ClientError(
+          `Your project key or personal API key is invalid. Setting next polling interval to ${this.getPollingInterval()}ms. More information: https://posthog.com/docs/api#rate-limiting`
+        )
+      }
+
+      if (res && res.status === 403) {
+        this.lastRequestWasAuthenticationError = true
+        this.authenticationErrorCount += 1
         throw new ClientError(
-          `Your personalApiKey is invalid. Are you sure you're not using your Project API key? More information: https://posthog.com/docs/api/overview`
+          `Your personal API key does not have permission to fetch feature flag definitions for local evaluation. Setting next polling interval to ${this.getPollingInterval()}ms. Are you sure you're using the correct personal and Project API key pair? More information: https://posthog.com/docs/api/overview`
         )
       }
 
@@ -410,6 +437,8 @@ class FeatureFlagsPoller {
       this.groupTypeMapping = responseJson.group_type_mapping || {}
       this.cohorts = responseJson.cohorts || []
       this.loadedSuccessfullyOnce = true
+      this.lastRequestWasAuthenticationError = false
+      this.authenticationErrorCount = 0
     } catch (err) {
       // if an error that is not an instance of ClientError is thrown
       // we silently ignore the error when reloading feature flags

posthog-node/src/posthog-node.ts

@@ -28,7 +28,11 @@ export type PostHogOptions = PostHogCoreOptions & {
   fetch?: (url: string, options: PostHogFetchOptions) => Promise<PostHogFetchResponse>
 }
 
-const THIRTY_SECONDS = 30 * 1000
+// Standard local evaluation rate limit is 600 per minute (10 per second),
+// so the fastest a poller should ever be set is 100ms.
+export const MINIMUM_POLLING_INTERVAL = 100
+export const THIRTY_SECONDS = 30 * 1000
+export const SIXTY_SECONDS = 60 * 1000
 const MAX_CACHE_SIZE = 50 * 1000
 
 // The actual exported Nodejs API.
@@ -47,12 +51,20 @@ export class PostHog extends PostHogCoreStateless implements PostHogNodeV1 {
 
     this.options = options
 
+    this.options.featureFlagsPollingInterval =
+      typeof options.featureFlagsPollingInterval === 'number'
+        ? Math.max(options.featureFlagsPollingInterval, MINIMUM_POLLING_INTERVAL)
+        : THIRTY_SECONDS
+
     if (options.personalApiKey) {
+      if (options.personalApiKey.includes('phc_')) {
+        throw new Error(
+          'Your Personal API key is invalid. These keys are prefixed with "phx_" and can be created in PostHog project settings.'
+        )
+      }
+
       this.featureFlagsPoller = new FeatureFlagsPoller({
-        pollingInterval:
-          typeof options.featureFlagsPollingInterval === 'number'
-            ? options.featureFlagsPollingInterval
-            : THIRTY_SECONDS,
+        pollingInterval: this.options.featureFlagsPollingInterval,
         personalApiKey: options.personalApiKey,
         projectApiKey: apiKey,
         timeout: options.requestTimeout ?? 10000, // 10 seconds

posthog-node/test/posthog-node.spec.ts

@@ -1,9 +1,9 @@
-import { PostHog as PostHog } from '../src/posthog-node'
-jest.mock('../src/fetch')
+import { MINIMUM_POLLING_INTERVAL, PostHog as PostHog, THIRTY_SECONDS } from '../src/posthog-node'
 import fetch from '../src/fetch'
 import { anyDecideCall, anyLocalEvalCall, apiImplementation } from './test-utils'
 import { waitForPromises, wait } from '../../posthog-core/test/test-utils/test-utils'
 import { randomUUID } from 'crypto'
+jest.mock('../src/fetch')
 
 jest.mock('../package.json', () => ({ version: '1.2.3' }))
 
@@ -666,6 +666,38 @@ describe('PostHog Node.js', () => {
       )
     })
 
+    it('should use minimum featureFlagsPollingInterval of 100ms if set less to less than 100', async () => {
+      posthog = new PostHog('TEST_API_KEY', {
+        host: 'http://example.com',
+        fetchRetryCount: 0,
+        personalApiKey: 'TEST_PERSONAL_API_KEY',
+        featureFlagsPollingInterval: 98,
+      })
+
+      expect(posthog.options.featureFlagsPollingInterval).toEqual(MINIMUM_POLLING_INTERVAL)
+    })
+
+    it('should use default featureFlagsPollingInterval of 30000ms if none provided', async () => {
+      posthog = new PostHog('TEST_API_KEY', {
+        host: 'http://example.com',
+        fetchRetryCount: 0,
+        personalApiKey: 'TEST_PERSONAL_API_KEY',
+      })
+
+      expect(posthog.options.featureFlagsPollingInterval).toEqual(THIRTY_SECONDS)
+    })
+
+    it('should throw an error when creating SDK if a project key is passed in as personalApiKey', async () => {
+      expect(() => {
+        posthog = new PostHog('TEST_API_KEY', {
+          host: 'http://example.com',
+          fetchRetryCount: 0,
+          personalApiKey: 'phc_abc123',
+          featureFlagsPollingInterval: 100,
+        })
+      }).toThrow(Error)
+    })
+
     it('captures feature flags with locally evaluated flags', async () => {
       mockedFetch.mockClear()
       mockedFetch.mockClear()