@atproto/bsky 0.0.250 → 0.0.253

package/src/feature-gates/index.ts

@@ -1,235 +0,0 @@
-import { GrowthBookClient } from '@growthbook/growthbook'
-import type express from 'express'
-import { featureGatesLogger } from '../logger.js'
-import { Gate, IGNORE_METRICS_FOR_GATES } from './gates.js'
-import { MetricsClient } from './metrics.js'
-import {
-  CheckedFeatureGatesMap,
-  ScopedFeatureGatesClient,
-  UserContext,
-} from './types.js'
-import {
-  extractUserContextFromGrowthbookUserContext,
-  mergeUserContexts,
-  normalizeUserContext,
-  parsedUserContextToTrackingMetadata,
-} from './utils.js'
-
-/**
- * We want this to be sufficiently high that we don't time out under
- * normal conditions, but not so high that it takes too long to boot
- * the server.
- */
-const FETCH_TIMEOUT = 3e3 // 3 seconds
-
-/**
- * StatSig used to default to every 10s, but I think 1m is fine
- */
-const REFETCH_INTERVAL = 60e3 // 1 minute
-
-/**
- * These need to match what the client sends
- */
-const ANALYTICS_HEADER_DEVICE_ID = 'X-Bsky-Device-Id'
-const ANALYTICS_HEADER_SESSION_ID = 'X-Bsky-Session-Id'
-
-export { type ScopedFeatureGatesClient } from './types.js'
-
-export class FeatureGatesClient {
-  private ready = false
-  private client: GrowthBookClient | undefined = undefined
-  private refreshInterval: NodeJS.Timeout | undefined = undefined
-  private metrics: MetricsClient
-
-  /**
-   * Easy access to the `Gate` enum for consumers of this class, so they don't
-   * need to import it separately.
-   */
-  Gate = Gate
-
-  constructor(
-    private config: {
-      growthBookApiHost?: string
-      growthBookClientKey?: string
-      eventProxyTrackingEndpoint?: string
-    },
-  ) {
-    this.metrics = new MetricsClient({
-      trackingEndpoint: config.eventProxyTrackingEndpoint,
-    })
-  }
-
-  async start() {
-    if (!this.config.growthBookApiHost || !this.config.growthBookClientKey) {
-      featureGatesLogger.info(
-        {},
-        'feature gates not configured, skipping initialization',
-      )
-      return
-    }
-
-    try {
-      this.client = new GrowthBookClient({
-        apiHost: this.config.growthBookApiHost,
-        clientKey: this.config.growthBookClientKey,
-        onFeatureUsage: async (feature, result, userContext) => {
-          if (IGNORE_METRICS_FOR_GATES.has(feature as Gate)) return
-
-          await this.metrics.track(
-            'feature:viewed',
-            {
-              featureId: feature,
-              featureResultValue: result.value,
-              experimentId: result.experiment?.key,
-              variationId: result.experimentResult?.key,
-            },
-            parsedUserContextToTrackingMetadata(
-              extractUserContextFromGrowthbookUserContext(userContext),
-            ),
-          )
-        },
-        trackingCallback: async (experiment, result, userContext) => {
-          /**
-           * Experiments are only fired in a feature gate has an Experiment
-           * attached in Growthbook. Howerver, we want to be extra sure that a
-           * misconfigured experiment doesn't result in a huge increase in events, so we
-           * protect this here.
-           */
-          if (
-            result.featureId &&
-            IGNORE_METRICS_FOR_GATES.has(result.featureId as Gate)
-          )
-            return
-
-          await this.metrics.track(
-            'experiment:viewed',
-            {
-              experimentId: experiment.key,
-              variationId: result.key,
-            },
-            parsedUserContextToTrackingMetadata(
-              extractUserContextFromGrowthbookUserContext(userContext),
-            ),
-          )
-        },
-      })
-
-      const { source, error } = await this.client.init({
-        timeout: FETCH_TIMEOUT,
-      })
-
-      /**
-       * This does not necessarily mean that the client completely failed,
-       * since it could just be that the request timed out. It may succeed
-       * after the timeout, or later during refreshes.
-       *
-       * @see https://docs.growthbook.io/lib/node#error-handling
-       */
-      if (error) {
-        featureGatesLogger.error(
-          { err: error, source },
-          'Client failed to initialize normally',
-        )
-      }
-
-      /**
-       * Set up periodic refresh of feature definitions
-       *
-       * @see https://docs.growthbook.io/lib/node#refreshing-features
-       */
-      this.refreshInterval = setInterval(async () => {
-        try {
-          await this.client?.refreshFeatures({
-            timeout: FETCH_TIMEOUT,
-          })
-        } catch (err) {
-          featureGatesLogger.error({ err }, 'Failed to refresh features')
-        }
-      }, REFETCH_INTERVAL)
-
-      /* Ready or not, here we come */
-      this.ready = true
-    } catch (err) {
-      featureGatesLogger.error({ err }, 'Client initialization failed')
-    }
-  }
-
-  async destroy() {
-    if (this.ready) {
-      this.ready = false
-      if (this.refreshInterval) {
-        clearInterval(this.refreshInterval)
-      }
-    }
-    await this.metrics.stop()
-  }
-
-  async [Symbol.asyncDispose]() {
-    await this.destroy()
-  }
-
-  /**
-   * Evaluate multiple feature gates for a given user, returning a map of gate
-   * ID to boolean result.
-   */
-  private checkGates(
-    gates: Gate[],
-    userContext: UserContext,
-  ): CheckedFeatureGatesMap {
-    const gb = this.client
-    const attributes = normalizeUserContext(userContext)
-    if (!gb || !this.ready) return new Map(gates.map((g) => [g, false]))
-    return new Map(gates.map((g) => [g, gb.isOn(g, { attributes })]))
-  }
-
-  scope(scopedUserContext: UserContext): ScopedFeatureGatesClient {
-    /*
-     * Create initial deviceId and sessionId values for the scoped client, to
-     * be used throughout this request lifecycle.
-     */
-    const base = normalizeUserContext(scopedUserContext)
-    return {
-      Gate: this.Gate,
-      checkGates: (
-        gates: Gate[],
-        userContextOverrides?: Pick<UserContext, 'did'>,
-      ) => {
-        const userContext = mergeUserContexts(base, userContextOverrides)
-        return this.checkGates(gates, userContext)
-      },
-      checkGate: (gate: Gate, userContextOverrides?: UserContext) => {
-        const userContext = mergeUserContexts(base, userContextOverrides)
-        return this.checkGates([gate], userContext).get(gate) || false
-      },
-    }
-  }
-
-  /**
-   * Parse properties available in XRPC handlers to `UserContext`. The returned
-   * proeprties are used as GrowthBook `attributes` as well as the metadata
-   * payload for our analytics events. This ensures that the same user properties
-   * are used for both feature gate targeting and analytics.
-   */
-  parseUserContextFromHandler({
-    viewer,
-    req,
-  }: {
-    /**
-     * The user's DID
-     */
-    viewer: string | null
-    /**
-     * The express request object, used to extract analytics headers for the user context
-     */
-    req: express.Request
-  }): UserContext {
-    const deviceId = req.header(ANALYTICS_HEADER_DEVICE_ID)
-    const sessionId = req.header(ANALYTICS_HEADER_SESSION_ID)
-
-    return normalizeUserContext({
-      did: viewer,
-      deviceId,
-      sessionId,
-    })
-  }
-}

package/src/feature-gates/metrics.test.ts

@@ -1,196 +0,0 @@
-import { Mock, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { featureGatesLogger } from '../logger.js'
-import { MetricsClient } from './metrics.js'
-
-vi.mock('../logger', () => ({
-  featureGatesLogger: {
-    error: vi.fn(),
-  },
-}))
-
-type TestEvents = {
-  click: { button: string }
-  view: { screen: string }
-}
-
-// Helper to flush promises and timers
-const flushPromises = () => new Promise((r) => setImmediate(r))
-
-describe('MetricsClient', () => {
-  let fetchMock: Mock
-  let fetchRequests: { body: any }[]
-  let client: MetricsClient<TestEvents>
-
-  beforeEach(() => {
-    vi.useFakeTimers({ toFake: ['setTimeout', 'setInterval'] })
-    fetchRequests = []
-    fetchMock = vi.fn().mockImplementation(async (_url, options) => {
-      const body = JSON.parse(options.body)
-      fetchRequests.push({ body })
-      return { ok: true, status: 200, text: async () => '' }
-    })
-    global.fetch = fetchMock
-  })
-
-  afterEach(async () => {
-    await client?.stop()
-    vi.useRealTimers()
-    vi.clearAllMocks()
-  })
-
-  it('flushes events on interval', async () => {
-    client = new MetricsClient<TestEvents>({
-      trackingEndpoint: 'https://test.metrics.api',
-    })
-    await client.track('click', { button: 'submit' })
-    await client.track('view', { screen: 'home' })
-
-    expect(fetchRequests).toHaveLength(0)
-
-    // Advance past the 10 second interval
-    vi.advanceTimersByTime(10_000)
-    await flushPromises()
-
-    expect(fetchRequests).toHaveLength(1)
-    expect(fetchRequests[0].body.events).toHaveLength(2)
-    expect(fetchRequests[0].body.events[0].event).toBe('click')
-    expect(fetchRequests[0].body.events[1].event).toBe('view')
-  })
-
-  it('flushes when maxBatchSize is exceeded', async () => {
-    client = new MetricsClient<TestEvents>({
-      trackingEndpoint: 'https://test.metrics.api',
-    })
-    client.maxBatchSize = 5
-
-    // Add events up to maxBatchSize (should not flush yet)
-    for (let i = 0; i < 5; i++) {
-      await client.track('click', { button: `btn-${i}` })
-    }
-
-    expect(fetchRequests).toHaveLength(0)
-
-    // One more event should trigger flush (> maxBatchSize)
-    await client.track('click', { button: 'btn-trigger' })
-    await flushPromises()
-
-    expect(fetchRequests).toHaveLength(1)
-    expect(fetchRequests[0].body.events).toHaveLength(6)
-  })
-
-  it('logs error on failed request', async () => {
-    fetchMock.mockImplementation(async () => {
-      return {
-        ok: false,
-        status: 500,
-        text: async () => 'Internal Server Error',
-      }
-    })
-
-    client = new MetricsClient<TestEvents>({
-      trackingEndpoint: 'https://test.metrics.api',
-    })
-    await client.track('click', { button: 'submit' })
-
-    // Trigger flush via interval
-    vi.advanceTimersByTime(10_000)
-    await flushPromises()
-
-    expect(fetchMock).toHaveBeenCalledTimes(1)
-    expect(featureGatesLogger.error).toHaveBeenCalledWith(
-      expect.objectContaining({
-        err: expect.any(Error),
-      }),
-      'Failed to send metrics',
-    )
-  })
-
-  it('handles fetch text() error gracefully', async () => {
-    fetchMock.mockImplementation(async () => {
-      return {
-        ok: false,
-        status: 500,
-        text: async () => {
-          throw new Error('Failed to read response')
-        },
-      }
-    })
-
-    client = new MetricsClient<TestEvents>({
-      trackingEndpoint: 'https://test.metrics.api',
-    })
-    await client.track('click', { button: 'submit' })
-
-    // Trigger flush - should not throw
-    vi.advanceTimersByTime(10_000)
-    await flushPromises()
-
-    expect(fetchMock).toHaveBeenCalledTimes(1)
-    expect(featureGatesLogger.error).toHaveBeenCalledWith(
-      expect.objectContaining({
-        err: expect.objectContaining({
-          message: expect.stringContaining('Unknown error'),
-        }),
-      }),
-      'Failed to send metrics',
-    )
-  })
-
-  it('flushes when stop() is called', async () => {
-    client = new MetricsClient<TestEvents>({
-      trackingEndpoint: 'https://test.metrics.api',
-    })
-    await client.track('click', { button: 'submit' })
-
-    expect(fetchRequests).toHaveLength(0)
-
-    // Stop should flush remaining events
-    await client.stop()
-    await flushPromises()
-
-    expect(fetchRequests).toHaveLength(1)
-    expect(fetchRequests[0].body.events).toHaveLength(1)
-    expect(fetchRequests[0].body.events[0].event).toBe('click')
-  })
-
-  it('does not send if trackingEndpoint is not configured', async () => {
-    client = new MetricsClient<TestEvents>({})
-    await client.track('click', { button: 'submit' })
-
-    // Trigger flush via interval
-    vi.advanceTimersByTime(10_000)
-    await flushPromises()
-
-    expect(fetchMock).not.toHaveBeenCalled()
-  })
-
-  it('start() is idempotent', async () => {
-    client = new MetricsClient<TestEvents>({
-      trackingEndpoint: 'https://test.metrics.api',
-    })
-
-    // track() calls start() internally
-    await client.track('click', { button: 'submit' })
-    client.start()
-    client.start()
-
-    // Advance past interval - should only flush once
-    vi.advanceTimersByTime(10_000)
-    await flushPromises()
-
-    expect(fetchRequests).toHaveLength(1)
-  })
-
-  it('does not flush if queue is empty', async () => {
-    client = new MetricsClient<TestEvents>({
-      trackingEndpoint: 'https://test.metrics.api',
-    })
-    client.start()
-
-    // Advance past interval with empty queue
-    vi.advanceTimersByTime(10_000)
-    await flushPromises()
-
-    expect(fetchMock).not.toHaveBeenCalled()
-  })
-})

package/src/feature-gates/metrics.ts

@@ -1,107 +0,0 @@
-import { featureGatesLogger } from '../logger.js'
-
-type Events = {
-  'experiment:viewed': {
-    experimentId: string
-    variationId: string
-  }
-  'feature:viewed': {
-    featureId: string
-    featureResultValue: unknown
-    /** Only available if feature has experiment rules applied */
-    experimentId?: string
-    /** Only available if feature has experiment rules applied */
-    variationId?: string
-  }
-}
-
-type Event<M extends Record<string, any>> = {
-  time: number
-  event: keyof M
-  payload: M[keyof M]
-  metadata: Record<string, any>
-}
-
-export type Config = {
-  trackingEndpoint?: string
-}
-
-export class MetricsClient<M extends Record<string, any> = Events> {
-  maxBatchSize = 100
-
-  private started: boolean = false
-  private queue: Event<M>[] = []
-  private flushInterval: NodeJS.Timeout | null = null
-  constructor(private config: Config) {}
-
-  start() {
-    if (this.started) return
-    this.started = true
-    this.flushInterval = setInterval(() => {
-      void this.flush()
-    }, 10_000)
-  }
-
-  async stop() {
-    if (this.flushInterval) {
-      clearInterval(this.flushInterval)
-      this.flushInterval = null
-    }
-    await this.flush()
-  }
-
-  async track<E extends keyof M>(
-    event: E,
-    payload: M[E],
-    metadata: Record<string, any> = {},
-  ) {
-    await this.start()
-
-    const e = {
-      source: 'appview',
-      time: Date.now(),
-      event,
-      payload,
-      metadata,
-    }
-    this.queue.push(e)
-
-    if (this.queue.length > this.maxBatchSize) {
-      await this.flush()
-    }
-  }
-
-  async flush() {
-    if (!this.queue.length) return
-    const events = this.queue.splice(0, this.queue.length)
-    await this.sendBatch(events)
-  }
-
-  private async sendBatch(events: Event<M>[]) {
-    if (!this.config.trackingEndpoint) return
-
-    try {
-      const res = await fetch(this.config.trackingEndpoint, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({ events }),
-        keepalive: true,
-      })
-
-      if (!res.ok) {
-        const errorText = await res.text().catch(() => 'Unknown error')
-        featureGatesLogger.error(
-          { err: new Error(`${res.status} Failed to fetch - ${errorText}`) },
-          'Failed to send metrics',
-        )
-      } else {
-        // Drain response body to allow connection reuse.
-        await res.text().catch(() => {})
-      }
-    } catch (err) {
-      featureGatesLogger.error({ err }, 'Failed to send metrics')
-    }
-  }
-}

package/src/feature-gates/types.ts

@@ -1,62 +0,0 @@
-import { Gate } from './gates.js'
-
-/**
- * The user context passed to the feature gates client for evaluation and
- * tracking purposes.
- */
-export type UserContext = {
-  did?: string | null
-  deviceId?: string | null
-  sessionId?: string | null
-}
-
-/**
- * User context that has been normalized to ensure all required properties are
- * present and have fallback values. This is the format that we expect to use
- * for all feature gate evaluations and analytics tracking.
- */
-export type NormalizedUserContext = {
-  did?: string
-  deviceId: string
-  sessionId: string
-}
-
-/**
- * This loosely matches the metadata we send from the client for analytics
- * events. We want to make sure we have the same properties in both places so
- * that we can correlate feature gate evaluations with analytics events.
- *
- * @see https://github.com/bluesky-social/social-app/blob/76109a58dc7aafccdfbd07a81cbd9925e065d1c0/src/analytics/metadata.ts
- */
-export type TrackingMetadata = {
-  base: {
-    deviceId: string
-    sessionId: string
-  }
-  session: {
-    did: string | undefined
-  }
-}
-
-/**
- * Pre-evaluated feature gates map, the result of
- * `ctx.FeatureGatesClient.checkGates()`
- */
-export type CheckedFeatureGatesMap = Map<Gate, boolean>
-
-/**
- * The primary interface for interacting with feature gates in the system. This
- * client is designed to be used in the context of an XRPC handler, where we
- * can parse the user context from the request and then create a scoped client
- * for that request lifecycle. The client provides methods for checking multiple
- * gates at once, as well as checking individual gates with optional user
- * context overrides.
- */
-export type ScopedFeatureGatesClient = {
-  Gate: typeof Gate
-  checkGates(
-    gates: Gate[],
-    userContextOverrides?: UserContext,
-  ): CheckedFeatureGatesMap
-  checkGate(gate: Gate, userContextOverrides?: UserContext): boolean
-}

package/src/feature-gates/utils.test.ts

@@ -1,66 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { mergeUserContexts, normalizeUserContext } from './utils.js'
-
-describe('normalizeUserContext', () => {
-  it('defaults', () => {
-    const ctx = normalizeUserContext({})
-    expect(ctx.did).toBeUndefined()
-    expect(ctx.deviceId).toMatch(/^anon-/)
-    expect(ctx.sessionId).toMatch(/^anon-/)
-  })
-
-  it('with did', () => {
-    const ctx = normalizeUserContext({
-      did: 'did:example:123',
-    })
-    expect(ctx.did).toBe('did:example:123')
-    expect(ctx.deviceId).toBe('did:example:123')
-    expect(ctx.sessionId).toMatch(/^anon-/)
-  })
-
-  it('with did and deviceId', () => {
-    const ctx = normalizeUserContext({
-      did: 'did:example:123',
-      deviceId: 'device-456',
-    })
-    expect(ctx.did).toBe('did:example:123')
-    expect(ctx.deviceId).toBe('device-456')
-    expect(ctx.sessionId).toMatch(/^anon-/)
-  })
-
-  it('with only deviceId and sessionId', () => {
-    const ctx = normalizeUserContext({
-      deviceId: 'device-456',
-      sessionId: 'session-789',
-    })
-    expect(ctx.did).toBeUndefined()
-    expect(ctx.deviceId).toBe('device-456')
-    expect(ctx.sessionId).toBe('session-789')
-  })
-})
-
-describe('mergeUserContexts', () => {
-  it('anonymous base context, override with did', () => {
-    const base = normalizeUserContext({})
-    const merged = mergeUserContexts(base, { did: 'did:example:123' })
-    expect(merged.did).toBe('did:example:123')
-    expect(merged.deviceId).toBe('did:example:123')
-    expect(merged.sessionId).toBe(base.sessionId)
-  })
-
-  it('base context with did, override with different did', () => {
-    const base = normalizeUserContext({ did: 'did:example:123' })
-    const merged = mergeUserContexts(base, { did: 'did:example:456' })
-    expect(merged.did).toBe('did:example:456')
-    expect(merged.deviceId).toBe('did:example:456')
-    expect(merged.sessionId).toMatch(/^anon-/)
-  })
-
-  it('base context with did, override with same did', () => {
-    const base = normalizeUserContext({ did: 'did:example:123' })
-    const merged = mergeUserContexts(base, { did: 'did:example:123' })
-    expect(merged.did).toBe('did:example:123')
-    expect(merged.deviceId).toBe('did:example:123')
-    expect(merged.sessionId).toBe(base.sessionId)
-  })
-})