Suggestions skeleton impl

lexicons/app/bsky/actor/defs.json

@@ -114,6 +114,13 @@
         "followedBy": { "type": "string", "format": "at-uri" }
       }
     },
+    "skeletonActor": {
+      "type": "object",
+      "required": ["did"],
+      "properties": {
+        "did": { "type": "string", "format": "did" }
+      }
+    },
     "preferences": {
       "type": "array",
       "items": {

lexicons/app/bsky/actor/getSuggestionsSkeleton.json

@@ -0,0 +1,44 @@
+{
+  "lexicon": 1,
+  "id": "app.bsky.actor.getSuggestionsSkeleton",
+  "defs": {
+    "main": {
+      "type": "query",
+      "description": "Get a skeleton of suggested actors. Intended to be called and then hydrated through app.bsky.actor.getSuggestions",
+      "parameters": {
+        "type": "params",
+        "properties": {
+          "viewer": {
+            "type": "string",
+            "format": "did",
+            "description": "DID of the account making the request (not included for public/unauthenticated queries). Used to boost followed accounts in ranking."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "default": 50
+          },
+          "cursor": { "type": "string" }
+        }
+      },
+      "output": {
+        "encoding": "application/json",
+        "schema": {
+          "type": "object",
+          "required": ["actors"],
+          "properties": {
+            "cursor": { "type": "string" },
+            "actors": {
+              "type": "array",
+              "items": {
+                "type": "ref",
+                "ref": "app.bsky.actor.defs#skeletonActor"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

packages/api/src/client/index.ts

@@ -89,6 +89,7 @@ import * as AppBskyActorGetPreferences from './types/app/bsky/actor/getPreferenc
 import * as AppBskyActorGetProfile from './types/app/bsky/actor/getProfile'
 import * as AppBskyActorGetProfiles from './types/app/bsky/actor/getProfiles'
 import * as AppBskyActorGetSuggestions from './types/app/bsky/actor/getSuggestions'
+import * as AppBskyActorGetSuggestionsSkeleton from './types/app/bsky/actor/getSuggestionsSkeleton'
 import * as AppBskyActorProfile from './types/app/bsky/actor/profile'
 import * as AppBskyActorPutPreferences from './types/app/bsky/actor/putPreferences'
 import * as AppBskyActorSearchActors from './types/app/bsky/actor/searchActors'
@@ -249,6 +250,7 @@ export * as AppBskyActorGetPreferences from './types/app/bsky/actor/getPreferenc
 export * as AppBskyActorGetProfile from './types/app/bsky/actor/getProfile'
 export * as AppBskyActorGetProfiles from './types/app/bsky/actor/getProfiles'
 export * as AppBskyActorGetSuggestions from './types/app/bsky/actor/getSuggestions'
+export * as AppBskyActorGetSuggestionsSkeleton from './types/app/bsky/actor/getSuggestionsSkeleton'
 export * as AppBskyActorProfile from './types/app/bsky/actor/profile'
 export * as AppBskyActorPutPreferences from './types/app/bsky/actor/putPreferences'
 export * as AppBskyActorSearchActors from './types/app/bsky/actor/searchActors'
@@ -1358,6 +1360,17 @@ export class AppBskyActorNS {
       })
   }
 
+  getSuggestionsSkeleton(
+    params?: AppBskyActorGetSuggestionsSkeleton.QueryParams,
+    opts?: AppBskyActorGetSuggestionsSkeleton.CallOptions,
+  ): Promise<AppBskyActorGetSuggestionsSkeleton.Response> {
+    return this._service.xrpc
+      .call('app.bsky.actor.getSuggestionsSkeleton', params, undefined, opts)
+      .catch((e) => {
+        throw AppBskyActorGetSuggestionsSkeleton.toKnownErr(e)
+      })
+  }
+
   putPreferences(
     data?: AppBskyActorPutPreferences.InputSchema,
     opts?: AppBskyActorPutPreferences.CallOptions,

packages/api/src/client/lexicons.ts

@@ -3799,6 +3799,16 @@ export const schemaDict = {
           },
         },
       },
+      skeletonActor: {
+        type: 'object',
+        required: ['did'],
+        properties: {
+          did: {
+            type: 'string',
+            format: 'did',
+          },
+        },
+      },
       preferences: {
         type: 'array',
         items: {
@@ -4165,6 +4175,56 @@ export const schemaDict = {
       },
     },
   },
+  AppBskyActorGetSuggestionsSkeleton: {
+    lexicon: 1,
+    id: 'app.bsky.actor.getSuggestionsSkeleton',
+    defs: {
+      main: {
+        type: 'query',
+        description:
+          'Get a skeleton of suggested actors. Intended to be called and then hydrated through app.bsky.actor.getSuggestions',
+        parameters: {
+          type: 'params',
+          properties: {
+            viewer: {
+              type: 'string',
+              format: 'did',
+              description:
+                'DID of the account making the request (not included for public/unauthenticated queries). Used to boost followed accounts in ranking.',
+            },
+            limit: {
+              type: 'integer',
+              minimum: 1,
+              maximum: 100,
+              default: 50,
+            },
+            cursor: {
+              type: 'string',
+            },
+          },
+        },
+        output: {
+          encoding: 'application/json',
+          schema: {
+            type: 'object',
+            required: ['actors'],
+            properties: {
+              cursor: {
+                type: 'string',
+              },
+              actors: {
+                type: 'array',
+                items: {
+                  type: 'ref',
+                  ref: 'lex:app.bsky.actor.defs#skeletonActor',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
   AppBskyActorProfile: {
     lexicon: 1,
     id: 'app.bsky.actor.profile',
@@ -9563,6 +9623,7 @@ export const ids = {
   AppBskyActorGetProfile: 'app.bsky.actor.getProfile',
   AppBskyActorGetProfiles: 'app.bsky.actor.getProfiles',
   AppBskyActorGetSuggestions: 'app.bsky.actor.getSuggestions',
+  AppBskyActorGetSuggestionsSkeleton: 'app.bsky.actor.getSuggestionsSkeleton',
   AppBskyActorProfile: 'app.bsky.actor.profile',
   AppBskyActorPutPreferences: 'app.bsky.actor.putPreferences',
   AppBskyActorSearchActors: 'app.bsky.actor.searchActors',

packages/api/src/client/types/app/bsky/actor/defs.ts

@@ -128,6 +128,23 @@ export function validateViewerState(v: unknown): ValidationResult {
   return lexicons.validate('app.bsky.actor.defs#viewerState', v)
 }
 
+export interface SkeletonActor {
+  did: string
+  [k: string]: unknown
+}
+
+export function isSkeletonActor(v: unknown): v is SkeletonActor {
+  return (
+    isObj(v) &&
+    hasProp(v, '$type') &&
+    v.$type === 'app.bsky.actor.defs#skeletonActor'
+  )
+}
+
+export function validateSkeletonActor(v: unknown): ValidationResult {
+  return lexicons.validate('app.bsky.actor.defs#skeletonActor', v)
+}
+
 export type Preferences = (
   | AdultContentPref
   | ContentLabelPref

packages/api/src/client/types/app/bsky/actor/getSuggestionsSkeleton.ts

@@ -0,0 +1,40 @@
+/**
+ * GENERATED CODE - DO NOT MODIFY
+ */
+import { Headers, XRPCError } from '@atproto/xrpc'
+import { ValidationResult, BlobRef } from '@atproto/lexicon'
+import { isObj, hasProp } from '../../../../util'
+import { lexicons } from '../../../../lexicons'
+import { CID } from 'multiformats/cid'
+import * as AppBskyActorDefs from './defs'
+
+export interface QueryParams {
+  /** DID of the account making the request (not included for public/unauthenticated queries). Used to boost followed accounts in ranking. */
+  viewer?: string
+  limit?: number
+  cursor?: string
+}
+
+export type InputSchema = undefined
+
+export interface OutputSchema {
+  cursor?: string
+  actors: AppBskyActorDefs.SkeletonActor[]
+  [k: string]: unknown
+}
+
+export interface CallOptions {
+  headers?: Headers
+}
+
+export interface Response {
+  success: boolean
+  headers: Headers
+  data: OutputSchema
+}
+
+export function toKnownErr(e: any) {
+  if (e instanceof XRPCError) {
+  }
+  return e
+}

packages/bsky/src/api/app/bsky/actor/getSuggestions.ts

@@ -12,6 +12,7 @@ import { Views } from '../../../../views'
 import { DataPlaneClient } from '../../../../data-plane'
 import { parseString } from '../../../../hydration/util'
 import { resHeaders } from '../../../util'
+import AtpAgent from '@atproto/api'
 
 export default function (server: Server, ctx: AppContext) {
   const getSuggestions = createPipeline(
@@ -43,21 +44,34 @@ const skeleton = async (input: {
 }): Promise<Skeleton> => {
   const { ctx, params } = input
   const viewer = params.hydrateCtx.viewer
-  // @NOTE for appview swap moving to rkey-based cursors which are somewhat permissive, should not hard-break pagination
-  const suggestions = await ctx.dataplane.getFollowSuggestions({
-    actorDid: viewer ?? undefined,
-    cursor: params.cursor,
-    limit: params.limit,
-  })
-  let dids = suggestions.dids
-  if (viewer !== null) {
-    const follows = await ctx.dataplane.getActorFollowsActors({
-      actorDid: viewer,
-      targetDids: dids,
+  if (ctx.suggestionsAgent) {
+    const res =
+      await ctx.suggestionsAgent.api.app.bsky.actor.getSuggestionsSkeleton({
+        viewer: viewer ?? undefined,
+        limit: params.limit,
+        cursor: params.cursor,
+      })
+    return {
+      dids: res.data.actors.map((a) => a.did),
+      cursor: res.data.cursor,
+    }
+  } else {
+    // @NOTE for appview swap moving to rkey-based cursors which are somewhat permissive, should not hard-break pagination
+    const suggestions = await ctx.dataplane.getFollowSuggestions({
+      actorDid: viewer ?? undefined,
+      cursor: params.cursor,
+      limit: params.limit,
     })
-    dids = dids.filter((did, i) => !follows.uris[i] && did !== viewer)
+    let dids = suggestions.dids
+    if (viewer !== null) {
+      const follows = await ctx.dataplane.getActorFollowsActors({
+        actorDid: viewer,
+        targetDids: dids,
+      })
+      dids = dids.filter((did, i) => !follows.uris[i] && did !== viewer)
+    }
+    return { dids, cursor: parseString(suggestions.cursor) }
   }
-  return { dids, cursor: parseString(suggestions.cursor) }
 }
 
 const hydration = async (input: {
@@ -101,6 +115,7 @@ const presentation = (input: {
 }
 
 type Context = {
+  suggestionsAgent: AtpAgent | undefined
   dataplane: DataPlaneClient
   hydrator: Hydrator
   views: Views

packages/bsky/src/config.ts

@@ -20,6 +20,8 @@ export interface ServerConfigValues {
   courierHttpVersion?: '1.1' | '2'
   courierIgnoreBadTls?: boolean
   searchUrl?: string
+  suggestionsUrl?: string
+  suggestionsApiKey?: string
   cdnUrl?: string
   blobRateLimitBypassKey?: string
   blobRateLimitBypassHostname?: string
@@ -55,6 +57,8 @@ export class ServerConfig {
       process.env.BSKY_SEARCH_URL ||
       process.env.BSKY_SEARCH_ENDPOINT ||
       undefined
+    const suggestionsUrl = process.env.BSKY_SUGGESTIONS_URL || undefined
+    const suggestionsApiKey = process.env.BSKY_SUGGESTIONS_API_KEY || undefined
     let dataplaneUrls = overrides?.dataplaneUrls
     dataplaneUrls ??= process.env.BSKY_DATAPLANE_URLS
       ? process.env.BSKY_DATAPLANE_URLS.split(',')
@@ -104,6 +108,8 @@ export class ServerConfig {
       dataplaneHttpVersion,
       dataplaneIgnoreBadTls,
       searchUrl,
+      suggestionsUrl,
+      suggestionsApiKey,
       didPlcUrl,
       labelsFromIssuerDids,
       handleResolveNameservers,
@@ -206,6 +212,14 @@ export class ServerConfig {
     return this.cfg.searchUrl
   }
 
+  get suggestionsUrl() {
+    return this.cfg.suggestionsUrl
+  }
+
+  get suggestionsApiKey() {
+    return this.cfg.suggestionsApiKey
+  }
+
   get cdnUrl() {
     return this.cfg.cdnUrl
   }

packages/bsky/src/context.ts

@@ -24,6 +24,7 @@ export class AppContext {
       cfg: ServerConfig
       dataplane: DataPlaneClient
       searchAgent: AtpAgent | undefined
+      suggestionsAgent: AtpAgent | undefined
       hydrator: Hydrator
       views: Views
       signingKey: Keypair
@@ -46,6 +47,10 @@ export class AppContext {
     return this.opts.searchAgent
   }
 
+  get suggestionsAgent(): AtpAgent | undefined {
+    return this.opts.suggestionsAgent
+  }
+
   get hydrator(): Hydrator {
     return this.opts.hydrator
   }

packages/bsky/src/index.ts

@@ -74,6 +74,17 @@ export class BskyAppView {
     const searchAgent = config.searchUrl
       ? new AtpAgent({ service: config.searchUrl })
       : undefined
+
+    const suggestionsAgent = config.suggestionsUrl
+      ? new AtpAgent({ service: config.suggestionsUrl })
+      : undefined
+    if (suggestionsAgent && config.suggestionsApiKey) {
+      suggestionsAgent.api.setHeader(
+        'authorization',
+        `Bearer ${config.suggestionsApiKey}`,
+      )
+    }
+
     const dataplane = createDataPlaneClient(config.dataplaneUrls, {
       httpVersion: config.dataplaneHttpVersion,
       rejectUnauthorized: !config.dataplaneIgnoreBadTls,
@@ -107,6 +118,7 @@ export class BskyAppView {
       cfg: config,
       dataplane,
       searchAgent,
+      suggestionsAgent,
       hydrator,
       views,
       signingKey,