@atproto/bsky 0.0.215 → 0.0.217

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

@@ -0,0 +1,196 @@
+/// <reference types="jest" />
+import { featureGatesLogger } from '../logger'
+import { MetricsClient } from './metrics'
+
+jest.mock('../logger', () => ({
+  featureGatesLogger: {
+    error: jest.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: jest.Mock
+  let fetchRequests: { body: any }[]
+  let client: MetricsClient<TestEvents>
+
+  beforeEach(() => {
+    jest.useFakeTimers({ doNotFake: ['setImmediate', 'performance'] })
+    fetchRequests = []
+    fetchMock = jest.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(() => {
+    client?.stop()
+    jest.useRealTimers()
+    jest.clearAllMocks()
+  })
+
+  it('flushes events on interval', async () => {
+    client = new MetricsClient<TestEvents>({
+      trackingEndpoint: 'https://test.metrics.api',
+    })
+    client.track('click', { button: 'submit' })
+    client.track('view', { screen: 'home' })
+
+    expect(fetchRequests).toHaveLength(0)
+
+    // Advance past the 10 second interval
+    jest.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++) {
+      client.track('click', { button: `btn-${i}` })
+    }
+
+    expect(fetchRequests).toHaveLength(0)
+
+    // One more event should trigger flush (> maxBatchSize)
+    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',
+    })
+    client.track('click', { button: 'submit' })
+
+    // Trigger flush via interval
+    jest.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',
+    })
+    client.track('click', { button: 'submit' })
+
+    // Trigger flush - should not throw
+    jest.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',
+    })
+    client.track('click', { button: 'submit' })
+
+    expect(fetchRequests).toHaveLength(0)
+
+    // Stop should flush remaining events
+    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>({})
+    client.track('click', { button: 'submit' })
+
+    // Trigger flush via interval
+    jest.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
+    client.track('click', { button: 'submit' })
+    client.start()
+    client.start()
+
+    // Advance past interval - should only flush once
+    jest.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
+    jest.advanceTimersByTime(10_000)
+    await flushPromises()
+
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+})

package/src/feature-gates/metrics.ts

@@ -0,0 +1,107 @@
+import { featureGatesLogger } from '../logger'
+
+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(() => {
+      this.flush()
+    }, 10_000)
+  }
+
+  stop() {
+    if (this.flushInterval) {
+      clearInterval(this.flushInterval)
+      this.flushInterval = null
+    }
+    this.flush()
+  }
+
+  track<E extends keyof M>(
+    event: E,
+    payload: M[E],
+    metadata: Record<string, any> = {},
+  ) {
+    this.start()
+
+    const e = {
+      source: 'appview',
+      time: Date.now(),
+      event,
+      payload,
+      metadata,
+    }
+    this.queue.push(e)
+
+    if (this.queue.length > this.maxBatchSize) {
+      this.flush()
+    }
+  }
+
+  flush() {
+    if (!this.queue.length) return
+    const events = this.queue.splice(0, this.queue.length)
+    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

@@ -0,0 +1,52 @@
+import type express from 'express'
+import { FeatureGate } from './gates'
+
+/**
+ * The user context passed to the feature gates client for evaluation and
+ * tracking purposes.
+ */
+export type RawUserContext = {
+  /**
+   * The user's DID
+   */
+  viewer: string | null
+  /**
+   * The express request object, used to extract analytics headers for the user context
+   */
+  req: express.Request
+}
+
+/**
+ * Extracted values from the `RawUserContext`. These values should match the
+ * `attributes` we've configured for GrowthBook in our GB dashboard. We also
+ * send these same values as properties in our analytics events, so we want to
+ * make sure they are consistent.
+ */
+export type ParsedUserContext = {
+  did?: string | null
+  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<FeatureGate, boolean>

package/src/feature-gates/utils.ts

@@ -0,0 +1,90 @@
+import crypto from 'node:crypto'
+import { type UserContext as GrowthBookUserContext } from '@growthbook/growthbook'
+import { ParsedUserContext, RawUserContext, TrackingMetadata } from './types'
+
+/**
+ * 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'
+
+/**
+ * Parse the `RawUserContext` into a `ParsedUserContext` that is 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.
+ */
+export function parseRawUserContext(
+  userContext: RawUserContext,
+): ParsedUserContext {
+  const did = userContext.viewer
+
+  // prioritize passthrough header
+  let deviceId = userContext.req.header(ANALYTICS_HEADER_DEVICE_ID)
+  if (!deviceId) {
+    if (did) {
+      /*
+       * If we don't have a device header, fall back to the DID. Our event
+       * proxy ensures ordering based on this deviceId (also called a stableId
+       * in the proxy), so if we have a DID, we want to use it to ensure client
+       * and server events are properly ordered.
+       */
+      deviceId = did
+    } else {
+      /*
+       * Without any better option for identifying the user, we generate a
+       * random deviceId.
+       */
+      deviceId = `anon-${crypto.randomUUID()}`
+    }
+  }
+
+  // prioritize passthrough header
+  let sessionId = userContext.req.header(ANALYTICS_HEADER_SESSION_ID)
+  if (!sessionId) {
+    /*
+     * Without any better option for identifying the user, we generate a
+     * random deviceId.
+     */
+    sessionId = `anon-${crypto.randomUUID()}`
+  }
+
+  return {
+    did,
+    deviceId,
+    sessionId,
+  }
+}
+
+/**
+ * Extract the `ParsedUserContext` from the GrowthBook `UserContext`, which we
+ * passed into `isOn` as `attributes`.
+ */
+export function extractParsedUserContextFromGrowthBookUserContext(
+  userContext: GrowthBookUserContext,
+): ParsedUserContext {
+  return {
+    did: userContext.attributes?.did,
+    deviceId: userContext.attributes?.deviceId,
+    sessionId: userContext.attributes?.sessionId,
+  }
+}
+
+/**
+ * Convert the `ParsedUserContext` into the `TrackingMetadata` format that we
+ * use for our analytics events. This ensures that we have the same user
+ * properties as we do for events from our client app.
+ */
+export function parsedUserContextToTrackingMetadata(
+  parsedUserContext: ParsedUserContext,
+): TrackingMetadata {
+  return {
+    base: {
+      deviceId: parsedUserContext.deviceId,
+      sessionId: parsedUserContext.sessionId,
+    },
+    session: {
+      did: parsedUserContext.did ?? undefined,
+    },
+  }
+}

package/src/hydration/hydrator.ts

@@ -2,7 +2,7 @@ import assert from 'node:assert'
 import { mapDefined } from '@atproto/common'
 import { AtUri } from '@atproto/syntax'
 import { DataPlaneClient } from '../data-plane/client'
-import { type CheckedFeatureGatesMap, FeatureGateID } from '../feature-gates'
+import { type CheckedFeatureGatesMap } from '../feature-gates/types'
 import { ids } from '../lexicon/lexicons'
 import { Record as ProfileRecord } from '../lexicon/types/app/bsky/actor/profile'
 import { isMain as isEmbedRecord } from '../lexicon/types/app/bsky/embed/record'
@@ -83,7 +83,13 @@ export class HydrateCtx {
   overrideIncludeTakedownsForActor = this.vals.overrideIncludeTakedownsForActor
   include3pBlocks = this.vals.include3pBlocks
   includeDebugField = this.vals.includeDebugField
-  featureGates: CheckedFeatureGatesMap = this.vals.featureGates || new Map()
+  /**
+   * Cache of evaluated feature gates to be used in a given request lifecycle.
+   * The actual evaluations happen at the top of the route handler and the
+   * results are stored in this map.
+   */
+  featureGatesMap: CheckedFeatureGatesMap =
+    this.vals.featureGatesMap || new Map()
   constructor(private vals: HydrateCtxVals) {}
   // Convenience with use with dataplane.getActors cache control
   get skipCacheForViewer() {
@@ -102,7 +108,7 @@ export type HydrateCtxVals = {
   overrideIncludeTakedownsForActor?: boolean
   include3pBlocks?: boolean
   includeDebugField?: boolean
-  featureGates?: CheckedFeatureGatesMap
+  featureGatesMap?: CheckedFeatureGatesMap
 }
 
 export type HydrationState = {
@@ -746,8 +752,8 @@ export class Hydrator {
     ctx: HydrateCtx,
   ): Promise<HydrationState> {
     const postsState = await this.hydratePosts(refs, ctx, undefined, {
-      processDynamicTagsForView: ctx.featureGates.get(
-        FeatureGateID.ThreadsReplyRankingExplorationEnable,
+      processDynamicTagsForView: ctx.featureGatesMap.get(
+        'threads:reply_ranking_exploration:enable',
       )
         ? 'thread'
         : undefined,
@@ -1331,7 +1337,7 @@ export class Hydrator {
       includeTakedowns: vals.includeTakedowns,
       include3pBlocks: vals.include3pBlocks,
       includeDebugField,
-      featureGates: vals.featureGates,
+      featureGatesMap: vals.featureGatesMap,
     })
   }
 

package/src/index.ts

@@ -23,7 +23,7 @@ import {
   createDataPlaneClient,
 } from './data-plane/client'
 import * as error from './error'
-import { FeatureGates } from './feature-gates'
+import { FeatureGatesClient } from './feature-gates'
 import { Hydrator } from './hydration/hydrator'
 import * as imageServer from './image/server'
 import { ImageUriBuilder } from './image/uri'
@@ -181,9 +181,10 @@ export class BskyAppView {
       entrywayJwtPublicKey,
     })
 
-    const featureGates = new FeatureGates({
-      apiHost: config.growthBookApiHost,
-      clientKey: config.growthBookClientKey,
+    const featureGatesClient = new FeatureGatesClient({
+      growthBookApiHost: config.growthBookApiHost,
+      growthBookClientKey: config.growthBookClientKey,
+      eventProxyTrackingEndpoint: config.eventProxyTrackingEndpoint,
     })
 
     const blobDispatcher = createBlobDispatcher(config)
@@ -205,7 +206,7 @@ export class BskyAppView {
       courierClient,
       rolodexClient,
       authVerifier,
-      featureGates,
+      featureGatesClient,
       blobDispatcher,
       kwsClient,
     })
@@ -241,7 +242,7 @@ export class BskyAppView {
     if (this.ctx.dataplaneHostList instanceof EtcdHostList) {
       await this.ctx.dataplaneHostList.connect()
     }
-    await this.ctx.featureGates.start()
+    this.ctx.featureGatesClient.start() // lazy, no await
     const server = this.app.listen(this.ctx.cfg.port)
     this.server = server
     server.keepAliveTimeout = 90000
@@ -253,7 +254,7 @@ export class BskyAppView {
   }
 
   async destroy(): Promise<void> {
-    this.ctx.featureGates.destroy()
+    this.ctx.featureGatesClient.destroy()
     await this.terminator?.terminate()
     await this.ctx.etcd?.close()
   }

package/src/lexicon/index.ts

@@ -91,13 +91,13 @@ import * as AppBskyUnspeccedGetAgeAssuranceState from './types/app/bsky/unspecce
 import * as AppBskyUnspeccedGetConfig from './types/app/bsky/unspecced/getConfig.js'
 import * as AppBskyUnspeccedGetOnboardingSuggestedStarterPacks from './types/app/bsky/unspecced/getOnboardingSuggestedStarterPacks.js'
 import * as AppBskyUnspeccedGetOnboardingSuggestedStarterPacksSkeleton from './types/app/bsky/unspecced/getOnboardingSuggestedStarterPacksSkeleton.js'
+import * as AppBskyUnspeccedGetOnboardingSuggestedUsersSkeleton from './types/app/bsky/unspecced/getOnboardingSuggestedUsersSkeleton.js'
 import * as AppBskyUnspeccedGetPopularFeedGenerators from './types/app/bsky/unspecced/getPopularFeedGenerators.js'
 import * as AppBskyUnspeccedGetPostThreadOtherV2 from './types/app/bsky/unspecced/getPostThreadOtherV2.js'
 import * as AppBskyUnspeccedGetPostThreadV2 from './types/app/bsky/unspecced/getPostThreadV2.js'
 import * as AppBskyUnspeccedGetSuggestedFeeds from './types/app/bsky/unspecced/getSuggestedFeeds.js'
 import * as AppBskyUnspeccedGetSuggestedFeedsSkeleton from './types/app/bsky/unspecced/getSuggestedFeedsSkeleton.js'
 import * as AppBskyUnspeccedGetSuggestedOnboardingUsers from './types/app/bsky/unspecced/getSuggestedOnboardingUsers.js'
-import * as AppBskyUnspeccedGetSuggestedOnboardingUsersSkeleton from './types/app/bsky/unspecced/getSuggestedOnboardingUsersSkeleton.js'
 import * as AppBskyUnspeccedGetSuggestedStarterPacks from './types/app/bsky/unspecced/getSuggestedStarterPacks.js'
 import * as AppBskyUnspeccedGetSuggestedStarterPacksSkeleton from './types/app/bsky/unspecced/getSuggestedStarterPacksSkeleton.js'
 import * as AppBskyUnspeccedGetSuggestedUsers from './types/app/bsky/unspecced/getSuggestedUsers.js'
@@ -1386,6 +1386,18 @@ export class AppBskyUnspeccedNS {
     return this._server.xrpc.method(nsid, cfg)
   }
 
+  getOnboardingSuggestedUsersSkeleton<A extends Auth = void>(
+    cfg: MethodConfigOrHandler<
+      A,
+      AppBskyUnspeccedGetOnboardingSuggestedUsersSkeleton.QueryParams,
+      AppBskyUnspeccedGetOnboardingSuggestedUsersSkeleton.HandlerInput,
+      AppBskyUnspeccedGetOnboardingSuggestedUsersSkeleton.HandlerOutput
+    >,
+  ) {
+    const nsid = 'app.bsky.unspecced.getOnboardingSuggestedUsersSkeleton' // @ts-ignore
+    return this._server.xrpc.method(nsid, cfg)
+  }
+
   getPopularFeedGenerators<A extends Auth = void>(
     cfg: MethodConfigOrHandler<
       A,
@@ -1458,18 +1470,6 @@ export class AppBskyUnspeccedNS {
     return this._server.xrpc.method(nsid, cfg)
   }
 
-  getSuggestedOnboardingUsersSkeleton<A extends Auth = void>(
-    cfg: MethodConfigOrHandler<
-      A,
-      AppBskyUnspeccedGetSuggestedOnboardingUsersSkeleton.QueryParams,
-      AppBskyUnspeccedGetSuggestedOnboardingUsersSkeleton.HandlerInput,
-      AppBskyUnspeccedGetSuggestedOnboardingUsersSkeleton.HandlerOutput
-    >,
-  ) {
-    const nsid = 'app.bsky.unspecced.getSuggestedOnboardingUsersSkeleton' // @ts-ignore
-    return this._server.xrpc.method(nsid, cfg)
-  }
-
   getSuggestedStarterPacks<A extends Auth = void>(
     cfg: MethodConfigOrHandler<
       A,