@atproto/bsky 0.0.216 → 0.0.217

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/bsky",
-  "version": "0.0.216",
+  "version": "0.0.217",
   "license": "MIT",
   "description": "Reference implementation of app.bsky App View (Bluesky API)",
   "keywords": [
@@ -51,18 +51,18 @@
     "uint8arrays": "3.0.0",
     "undici": "^6.19.8",
     "zod": "3.23.8",
-    "@atproto-labs/fetch-node": "^0.2.0",
     "@atproto-labs/xrpc-utils": "^0.0.24",
-    "@atproto/api": "^0.18.21",
-    "@atproto/common": "^0.5.11",
+    "@atproto-labs/fetch-node": "^0.2.0",
+    "@atproto/api": "^0.19.0",
     "@atproto/crypto": "^0.4.5",
-    "@atproto/identity": "^0.4.11",
-    "@atproto/lexicon": "^0.6.1",
-    "@atproto/repo": "^0.8.12",
     "@atproto/did": "^0.3.0",
+    "@atproto/identity": "^0.4.12",
+    "@atproto/common": "^0.5.13",
+    "@atproto/repo": "^0.8.12",
     "@atproto/sync": "^0.1.39",
     "@atproto/syntax": "^0.4.3",
-    "@atproto/xrpc-server": "^0.10.12"
+    "@atproto/lexicon": "^0.6.1",
+    "@atproto/xrpc-server": "^0.10.14"
   },
   "devDependencies": {
     "@bufbuild/buf": "^1.28.1",
@@ -78,9 +78,9 @@
     "jest": "^28.1.2",
     "ts-node": "^10.8.2",
     "typescript": "^5.6.3",
-    "@atproto/api": "^0.18.21",
+    "@atproto/api": "^0.19.0",
     "@atproto/lex-cli": "^0.9.8",
-    "@atproto/pds": "^0.4.209",
+    "@atproto/pds": "^0.4.212",
     "@atproto/xrpc": "^0.7.7"
   },
   "scripts": {

package/src/api/app/bsky/feed/searchPosts.ts

@@ -7,7 +7,6 @@ import {
   PostSearchQuery,
   parsePostSearchQuery,
 } from '../../../../data-plane/server/util'
-import { FeatureGateID } from '../../../../feature-gates'
 import { HydrateCtx, Hydrator } from '../../../../hydration/hydrator'
 import { parseString } from '../../../../hydration/util'
 import { Server } from '../../../../lexicon'
@@ -39,9 +38,12 @@ export default function (server: Server, ctx: AppContext) {
       const hydrateCtx = await ctx.hydrator.createContext({
         labelers,
         viewer,
-        featureGates: ctx.featureGates.checkGates(
-          [ctx.featureGates.ids.SearchFilteringExplorationEnable],
-          ctx.featureGates.userContext({ did: viewer }),
+        featureGatesMap: ctx.featureGatesClient.checkGates(
+          ['search:filtering_exploration:enable'],
+          {
+            viewer,
+            req,
+          },
         ),
       })
       const results = await searchPosts(
@@ -109,8 +111,8 @@ const hydration = async (
     params.hydrateCtx,
     undefined,
     {
-      processDynamicTagsForView: params.hydrateCtx.featureGates.get(
-        FeatureGateID.SearchFilteringExplorationEnable,
+      processDynamicTagsForView: params.hydrateCtx.featureGatesMap.get(
+        'search:filtering_exploration:enable',
       )
         ? 'search'
         : undefined,
@@ -139,8 +141,8 @@ const noBlocksOrTagged = (inputs: RulesFnInput<Context, Params, Skeleton>) => {
 
     let tagged = false
     if (
-      params.hydrateCtx.featureGates.get(
-        FeatureGateID.SearchFilteringExplorationEnable,
+      params.hydrateCtx.featureGatesMap.get(
+        'search:filtering_exploration:enable',
       )
     ) {
       tagged = post.tags.has(ctx.cfg.visibilityTagHide)

package/src/api/app/bsky/graph/getSuggestedFollowsByActor.ts

@@ -131,7 +131,6 @@ type Context = {
   hydrator: Hydrator
   views: Views
   suggestionsAgent: AtpAgent | undefined
-  featureGates: AppContext['featureGates']
 }
 
 type Params = QueryParams & {

package/src/api/app/bsky/unspecced/getPostThreadV2.ts

@@ -33,9 +33,9 @@ export default function (server: Server, ctx: AppContext) {
         viewer,
         includeTakedowns,
         include3pBlocks,
-        featureGates: ctx.featureGates.checkGates(
-          [ctx.featureGates.ids.ThreadsReplyRankingExplorationEnable],
-          ctx.featureGates.userContext({ did: viewer }),
+        featureGatesMap: ctx.featureGatesClient.checkGates(
+          ['threads:reply_ranking_exploration:enable'],
+          { viewer, req },
         ),
       })
 

package/src/api/app/bsky/unspecced/getSuggestedOnboardingUsers.ts

@@ -2,7 +2,6 @@ import AtpAgent from '@atproto/api'
 import { dedupeStrs, mapDefined, noUndefinedVals } from '@atproto/common'
 import { InternalServerError } from '@atproto/xrpc-server'
 import { AppContext } from '../../../../context'
-import { FeatureGates } from '../../../../feature-gates'
 import {
   HydrateCtx,
   Hydrator,
@@ -31,7 +30,17 @@ export default function (server: Server, ctx: AppContext) {
     handler: async ({ auth, params, req }) => {
       const viewer = auth.credentials.iss
       const labelers = ctx.reqLabelers(req)
-      const hydrateCtx = await ctx.hydrator.createContext({ labelers, viewer })
+      const hydrateCtx = await ctx.hydrator.createContext({
+        labelers,
+        viewer,
+        featureGatesMap: ctx.featureGatesClient.checkGates(
+          ['suggested_onboarding_users:discover_agent:enable'],
+          {
+            viewer,
+            req,
+          },
+        ),
+      })
       const headers = noUndefinedVals({
         'accept-language': req.headers['accept-language'],
         'x-bsky-topics': Array.isArray(req.headers['x-bsky-topics'])
@@ -100,9 +109,8 @@ const skeletonFromTopics = async (input: SkeletonFnInput<Context, Params>) => {
 }
 
 const skeleton = async (input: SkeletonFnInput<Context, Params>) => {
-  const useDiscover = input.ctx.featureGates.check(
-    input.ctx.featureGates.ids.SuggestedOnboardingUsersDiscoverAgentEnable,
-    input.ctx.featureGates.userContext({ did: input.params.hydrateCtx.viewer }),
+  const useDiscover = input.params.hydrateCtx.featureGatesMap.get(
+    'suggested_onboarding_users:discover_agent:enable',
   )
   const skeletonFn = useDiscover ? skeletonFromDiscover : skeletonFromTopics
   return skeletonFn(input)
@@ -161,7 +169,6 @@ type Context = {
   views: Views
   topicsAgent: AtpAgent | undefined
   suggestionsAgent: AtpAgent | undefined
-  featureGates: FeatureGates
 }
 
 type Params = QueryParams & {

package/src/api/app/bsky/unspecced/getSuggestedUsers.ts

@@ -2,7 +2,6 @@ import AtpAgent from '@atproto/api'
 import { dedupeStrs, mapDefined, noUndefinedVals } from '@atproto/common'
 import { InternalServerError } from '@atproto/xrpc-server'
 import { AppContext } from '../../../../context'
-import { FeatureGates } from '../../../../feature-gates'
 import {
   HydrateCtx,
   Hydrator,
@@ -31,7 +30,17 @@ export default function (server: Server, ctx: AppContext) {
     handler: async ({ auth, params, req }) => {
       const viewer = auth.credentials.iss
       const labelers = ctx.reqLabelers(req)
-      const hydrateCtx = await ctx.hydrator.createContext({ labelers, viewer })
+      const hydrateCtx = await ctx.hydrator.createContext({
+        labelers,
+        viewer,
+        featureGatesMap: ctx.featureGatesClient.checkGates(
+          ['suggested_users:discover_agent:enable'],
+          {
+            viewer,
+            req,
+          },
+        ),
+      })
       const headers = noUndefinedVals({
         'accept-language': req.headers['accept-language'],
         'x-bsky-topics': Array.isArray(req.headers['x-bsky-topics'])
@@ -98,9 +107,8 @@ const skeletonFromTopics = async (input: SkeletonFnInput<Context, Params>) => {
 }
 
 const skeleton = async (input: SkeletonFnInput<Context, Params>) => {
-  const useDiscover = input.ctx.featureGates.check(
-    input.ctx.featureGates.ids.SuggestedUsersDiscoverAgentEnable,
-    input.ctx.featureGates.userContext({ did: input.params.hydrateCtx.viewer }),
+  const useDiscover = input.params.hydrateCtx.featureGatesMap.get(
+    'suggested_users:discover_agent:enable',
   )
   const skeletonFn = useDiscover ? skeletonFromDiscover : skeletonFromTopics
   return skeletonFn(input)
@@ -159,7 +167,6 @@ type Context = {
   views: Views
   topicsAgent: AtpAgent | undefined
   suggestionsAgent: AtpAgent | undefined
-  featureGates: FeatureGates
 }
 
 type Params = QueryParams & {

package/src/config.ts

@@ -81,6 +81,7 @@ export interface ServerConfigValues {
   indexedAtEpoch?: Date
   // misc/dev
   blobCacheLocation?: string
+  eventProxyTrackingEndpoint?: string
   growthBookApiHost?: string
   growthBookClientKey?: string
   // threads
@@ -213,6 +214,8 @@ export class ServerConfig {
     const modServiceDid = process.env.MOD_SERVICE_DID
     assert(modServiceDid)
 
+    const eventProxyTrackingEndpoint =
+      process.env.BSKY_EVENT_PROXY_TRACKING_ENDPOINT || undefined
     const growthBookApiHost = process.env.BSKY_GROWTHBOOK_API_HOST || undefined
     const growthBookClientKey =
       process.env.NODE_ENV === 'test'
@@ -369,6 +372,7 @@ export class ServerConfig {
       blobRateLimitBypassHostname,
       adminPasswords,
       modServiceDid,
+      eventProxyTrackingEndpoint,
       growthBookApiHost,
       growthBookClientKey,
       clientCheckEmailConfirmed,
@@ -570,6 +574,10 @@ export class ServerConfig {
     return this.cfg.blobCacheLocation
   }
 
+  get eventProxyTrackingEndpoint() {
+    return this.cfg.eventProxyTrackingEndpoint
+  }
+
   get growthBookApiHost() {
     return this.cfg.growthBookApiHost
   }

package/src/context.ts

@@ -10,7 +10,7 @@ import { BsyncClient } from './bsync'
 import { ServerConfig } from './config'
 import { CourierClient } from './courier'
 import { DataPlaneClient, HostList } from './data-plane/client'
-import { FeatureGates } from './feature-gates'
+import { FeatureGatesClient } from './feature-gates'
 import { Hydrator } from './hydration/hydrator'
 import { KwsClient } from './kws'
 import { httpLogger as log } from './logger'
@@ -42,7 +42,7 @@ export class AppContext {
       courierClient: CourierClient | undefined
       rolodexClient: RolodexClient | undefined
       authVerifier: AuthVerifier
-      featureGates: FeatureGates
+      featureGatesClient: FeatureGatesClient
       blobDispatcher: Dispatcher
       kwsClient: KwsClient | undefined
     },
@@ -116,8 +116,8 @@ export class AppContext {
     return this.opts.authVerifier
   }
 
-  get featureGates(): FeatureGates {
-    return this.opts.featureGates
+  get featureGatesClient(): FeatureGatesClient {
+    return this.opts.featureGatesClient
   }
 
   get blobDispatcher(): Dispatcher {

package/src/feature-gates/README.md

@@ -0,0 +1,47 @@
+# Feature Gates
+
+A thin wrapper around [GrowthBook](https://www.growthbook.io/) for feature flag
+evaluation and experiment tracking.
+
+## Usage
+
+Call `checkGates` at the **top of each request handler** to evaluate feature
+gates for the current user. This ensures consistent targeting throughout the
+request lifecycle.
+
+> [!NOTE]
+> Only pass in the gates you wish to check for this endpoint. Passing in more
+> will result in extraneous calls to our exposures endpoint, which could skew
+> experiment results in unexpected ways.
+
+```ts
+const hydrateCtx = await ctx.hydrator.createContext({
+  // ...
+  featureGatesMap: ctx.featureGatesClient.checkGates(
+    ['threads:reply_ranking_exploration:enable'],
+    { viewer, req },
+  ),
+})
+```
+
+The returned `CheckedFeatureGatesMap` can then be passed through context and
+accessed wherever needed.
+
+## User Identification
+
+If the user is authenticated, we use their DID as the identifier for feature
+targeting via the `viewer` param of the `checkGates` call.
+
+For unauthenticated users, and for experiments that don't require DID-level
+targeting, we rely on identifiers passed from the client as headers:
+
+- `X-Bsky-Stable-Id` - persistent device/client identifier
+- `X-Bsky-Session-Id` - current session identifier
+
+> [!WARNING]
+> If both `stableId` and `did` are missing, all gates return `false`. This
+> prevents untargeted users from being enrolled in experiments.
+
+## Adding New Gates
+
+Add new gate IDs to the `FeatureGate` type in `gates.ts`.

package/src/feature-gates/gates.ts

@@ -0,0 +1,9 @@
+/**
+ * ADD ALL FEATURE GATES HERE.
+ */
+
+export type FeatureGate =
+  | 'suggested_users:discover_agent:enable'
+  | 'suggested_onboarding_users:discover_agent:enable'
+  | 'threads:reply_ranking_exploration:enable'
+  | 'search:filtering_exploration:enable'

package/src/feature-gates/index.ts

@@ -0,0 +1,146 @@
+import { GrowthBookClient } from '@growthbook/growthbook'
+import { featureGatesLogger } from '../logger'
+import { FeatureGate } from './gates'
+import { MetricsClient } from './metrics'
+import { CheckedFeatureGatesMap, RawUserContext } from './types'
+import {
+  extractParsedUserContextFromGrowthBookUserContext,
+  parseRawUserContext,
+  parsedUserContextToTrackingMetadata,
+} from './utils'
+
+/**
+ * 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
+
+export class FeatureGatesClient {
+  ready = false
+  client: GrowthBookClient | undefined = undefined
+  refreshInterval: NodeJS.Timeout | undefined = undefined
+  metrics: MetricsClient
+
+  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: (feature, result, userContext) => {
+          this.metrics.track(
+            'feature:viewed',
+            {
+              featureId: feature,
+              featureResultValue: result.value,
+              experimentId: result.experiment?.key,
+              variationId: result.experimentResult?.key,
+            },
+            parsedUserContextToTrackingMetadata(
+              extractParsedUserContextFromGrowthBookUserContext(userContext),
+            ),
+          )
+        },
+        trackingCallback: (experiment, result, userContext) => {
+          this.metrics.track(
+            'experiment:viewed',
+            {
+              experimentId: experiment.key,
+              variationId: result.key,
+            },
+            parsedUserContextToTrackingMetadata(
+              extractParsedUserContextFromGrowthBookUserContext(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')
+    }
+  }
+
+  destroy() {
+    if (this.ready) {
+      this.ready = false
+      if (this.refreshInterval) {
+        clearInterval(this.refreshInterval)
+      }
+    }
+    this.metrics.stop()
+  }
+
+  /**
+   * Evaluate multiple feature gates for a given user, returning a map of gate
+   * ID to boolean result.
+   */
+  checkGates(
+    gates: FeatureGate[],
+    rawUserContext: RawUserContext,
+  ): CheckedFeatureGatesMap {
+    const gb = this.client
+    const attributes = parseRawUserContext(rawUserContext)
+    if (!gb || !this.ready) return new Map(gates.map((g) => [g, false]))
+    return new Map(gates.map((g) => [g, gb.isOn(g, { attributes })]))
+  }
+}

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()
+  })
+})