@atproto/bsky 0.3.13 → 0.5.0

package/dist/hydration/external.d.ts

@@ -1,8 +1,9 @@
 import { type AtUriString, type DidString, type NsidString, type TypedLexMap } from '@atproto/lex';
 import type { DataPlaneClient } from '../data-plane/client/index.js';
 import { type ExternalHydrationRoot, type ExternalHydrationWork, type HydrationXrpcEndpoint } from '../telemetry/events.js';
-import type { SiteStandardDocumentRecord, SiteStandardPublicationRecord } from '../views/types.js';
+import { type SiteStandardDocumentRecord, type SiteStandardPublicationRecord } from '../views/types.js';
 import type { Actors } from './actor.js';
+import type { Posts } from './feed.js';
 import type { Labels } from './label.js';
 import { HydrationMap, type ItemRef, type RecordInfo } from './util.js';
 /** Generic record bodies are decoded, but not validated against a Lexicon. */
@@ -11,6 +12,8 @@ export type ExternalRecords = HydrationMap<AtUriString, ExternalRecord>;
 /** Keyed by `genericRecordKey({ uri, cid })` to retain versions of a URI. */
 export type ExternalRecordsByRef = HydrationMap<ExactRecordKey, ExternalRecord>;
 export type ExternalRecordBacklinks = HydrationMap<AtUriString, AtUriString[]>;
+/** Viewer subscription outcomes per publication; null means unknown. */
+export type ExternalPublicationSubscriptions = HydrationMap<AtUriString, boolean>;
 export type AtmosphereActivityItem = {
     uri: AtUriString;
     sortedAt: Date;
@@ -38,33 +41,56 @@ export type ExactRecordKey = string & {
 };
 export type SiteStandardDocument = RecordInfo<SiteStandardDocumentRecord>;
 export type SiteStandardPublication = RecordInfo<SiteStandardPublicationRecord>;
+export type ExternalHydrationLevel = 'basic' | 'detailed';
 /**
- * Keyed by `${uri}@${cid}` — see `genericRecordKey`. A single hydration
- * batch can pull more than one version of the same URI (different posts
- * pinning different cids), so the composite key is needed for O(1)
- * version-exact lookups.
+ * Options for external hydration traversals. `hydration` picks one level for
+ * the whole traversal (default `'detailed'`): `'basic'` hydrates renderable
+ * content, moderation and aggregate backlink counts; `'detailed'` also samples
+ * social-preview backlinks and hydrates their records and participants.
+ * `publicationSubscriptions` opts an authenticated viewer into request-cached
+ * subscription discovery. The remaining fields are shared traversal state.
  */
-export type SiteStandardDocuments = HydrationMap<ExactRecordKey, SiteStandardDocument>;
+export type ExternalHydrationOptions = {
+    hydration?: ExternalHydrationLevel;
+    seenRecordKeys?: Set<string>;
+    hydrationPass?: number;
+    hydrationMetrics?: ExternalHydrationTracker;
+    publicationSubscriptions?: ExternalPublicationSubscriptions;
+};
 /**
- * Keyed by `${uri}@${cid}`. See `SiteStandardDocuments` for the rationale.
+ * Per-collection sample limits. Basic hydration skips social previews,
+ * but keeps gallery items. Direct publication/photo references are singular.
  */
-export type SiteStandardPublications = HydrationMap<ExactRecordKey, SiteStandardPublication>;
-export type SiteStandardRecords = {
-    documents: SiteStandardDocuments;
-    publications: SiteStandardPublications;
+export declare const EXTERNAL_HYDRATION_LIMITS: {
+    readonly "site.standard.document": {
+        readonly recommendationPreviews: 3;
+    };
+    readonly "site.standard.publication": {
+        readonly subscriberPreviews: 3;
+    };
+    readonly "social.grain.gallery": {
+        readonly items: 10;
+        readonly favoritePreviews: 3;
+    };
 };
+/** Maximum in-flight backlink sample RPCs, not a dependency-count limit. */
+export declare const MAX_CONCURRENT_BACKLINK_REQUESTS = 8;
+/** Maximum logical batches per traversal, counting the root as pass 1. */
+export declare const MAX_EXTERNAL_HYDRATION_PASSES = 8;
 export declare class ExternalHydrator {
     dataplane: DataPlaneClient;
-    static readonly MAX_BACKLINK_PREVIEWS = 3;
-    static readonly MAX_BACKLINK_GALLERY_ITEMS = 10;
-    static readonly MAX_BACKLINK_FANOUT = 8;
-    /** Hard cap on generic batches per traversal, counting the root as pass 1. */
-    static readonly MAX_EXTERNAL_HYDRATION_PASSES = 8;
     /**
      * Entries per generic record RPC. The dataplane rejects larger URI lookups;
      * exact-ref lookups use the same bound defensively.
      */
     static readonly MAX_RECORDS_PER_REQUEST = 100;
+    /**
+     * Target URIs per backlink-count RPC. The dataplane requires between 1 and
+     * 100; this is a separate limit from `MAX_RECORDS_PER_REQUEST`.
+     */
+    static readonly MAX_BACKLINK_COUNT_TARGETS_PER_REQUEST = 100;
+    /** Target URIs per actor-backlink RPC, bounded by the dataplane. */
+    static readonly MAX_BACKLINK_ACTOR_TARGETS_PER_REQUEST = 100;
     constructor(dataplane: DataPlaneClient);
     /**
      * Fetch exact record versions; unavailable records are represented by null.
@@ -83,7 +109,11 @@ export declare class ExternalHydrator {
         limit?: number;
         cursor?: string;
     }): Promise<AtmosphereTimeline>;
-    /** Fetch source-record counts, optionally restricted to one collection. */
+    /**
+     * Fetch source-record counts, optionally restricted to one collection. Large
+     * inputs are fetched in sequential bounded requests; any failed request
+     * rejects the whole call.
+     */
     getAtmosphereBacklinkCounts(targetUris: AtUriString[], collection?: NsidString): Promise<ExternalRecordBacklinkCounts>;
     /** Fetch a page of source records linking to a target. */
     getAtmosphereBacklinks(targetUri: AtUriString, collection: NsidString, opts?: {
@@ -92,11 +122,6 @@ export declare class ExternalHydrator {
     }): Promise<AtmosphereBacklinks>;
     /** Fetch an actor's links per target, retaining the batch truncation flag. */
     getAtmosphereBacklinksByActor(targetUris: AtUriString[], actorDid: DidString, collection: NsidString): Promise<AtmosphereBacklinksByActor>;
-    /**
-     * Fetch exact `site.standard.{document,publication}` versions. Does NOT
-     * resolve a document's publication; callers must pin it explicitly.
-     */
-    getSiteStandardRecordsByRef(refs: ItemRef[], includeTakedowns?: boolean): Promise<SiteStandardRecords>;
 }
 /**
  * Composes the lookup key for a ref: the bare URI for a latest-version lookup,
@@ -145,9 +170,10 @@ export type ExternalHydrationTracker = ExternalHydrationWork & {
  * there is none. Only the owner reports, once, including on failure, with the
  * context's XRPC endpoint (`'unknown'` if unset) and the traversal's wall time. A
  * returned traversal is `capped` if it hit the pass limit, else `partial` if
- * it recovered from a dependency failure. Owners that completed without
- * scheduling a batch did no work and are not reported; other outcomes always
- * are.
+ * it recovered from a dependency failure. Owners that completed report when
+ * they scheduled a batch or inspected roots (even prehydrated or unavailable
+ * ones); only genuinely empty successful calls are not reported. Other
+ * outcomes always are.
  */
 export declare function trackExternalHydration<T>(root: ExternalHydrationRoot, xrpcEndpoint: HydrationXrpcEndpoint | undefined, hydrationMetrics: ExternalHydrationTracker | undefined, fn: (hydrationMetrics: ExternalHydrationTracker) => Promise<T>): Promise<T>;
 export type AssociatedSiteStandardRecord<T> = {
@@ -158,29 +184,16 @@ export type AssociatedSiteStandardRecord<T> = {
     info: T;
 };
 /**
- * Read-path resolution: caller pinned a set of `(uri, cid)` strongRefs in
- * the post at write time, and we honor those exact versions. Any pair
- * that doesn't structurally agree is rejected, so downstream callers can
- * trust the returned shape.
- *
- * Pairing rules:
- * - Both slots referenced: `doc.site` must equal `publication.ref.uri`,
- *   else both come back `undefined`.
- * - Doc with at-uri `site` referenced but no matching publication ref:
- *   reject the whole pairing (doc claims a publication that should have
- *   been pinned, but wasn't).
- * - Loose doc (web-URL `site`) referenced: publication stays `undefined`.
- * - Only a publication referenced: document stays `undefined`.
- *
- * Each returned slot carries the matching `ref` so callers can recover
- * the owner DID for blob-cdn URL building, etc.
+ * Select one pinned embed root. Legacy publication-first pairs may put their
+ * document second; no other authored refs participate in hydration.
  */
-export declare const getSiteStandardRecordsFromHydrationMapsByRefs: (associatedRefs: readonly {
-    uri: AtUriString;
-    cid: string;
-}[] | undefined, documents: SiteStandardDocuments | undefined, publications: SiteStandardPublications | undefined) => {
+export declare function getExternalRootRef(refs: readonly Required<ItemRef>[] | undefined): Required<ItemRef> | undefined;
+/** Select a pinned Standard.site root and its derived publication, if needed. */
+export declare function getSiteStandardRecordsFromRefs(associatedRefs: readonly Required<ItemRef>[] | undefined, records: ExternalRecordsByRef | undefined, dependencies?: ExternalRecords): {
     document: AssociatedSiteStandardRecord<SiteStandardDocument> | undefined;
     publication: AssociatedSiteStandardRecord<SiteStandardPublication> | undefined;
 };
+/** Collect one root per post across all layers, deduped by exact ref. */
+export declare const externalAssociatedRefsFromPosts: (...postLayers: Posts[]) => Required<ItemRef>[];
 export {};
 //# sourceMappingURL=external.d.ts.map

package/dist/hydration/external.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../../src/hydration/external.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../../src/hydration/external.ts"],"names":[],"mappings":"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"}

package/dist/hydration/external.js

@@ -1,24 +1,39 @@
 import { performance } from 'node:perf_hooks';
 import { chunkArray } from '@atproto/common';
-import { isTypedLexMap, lexParseJsonBytes, } from '@atproto/lex';
+import { isDidString, isTypedLexMap, lexParseJsonBytes, } from '@atproto/lex';
 import { parseAtUriString } from '@atproto/syntax';
-import { site } from '../lexicons/index.js';
-import { hydrationLogger } from '../logger.js';
+import { site, social } from '../lexicons/index.js';
 import { RecordLookupStatus, } from '../proto/bsky_pb.js';
 import { events, } from '../telemetry/events.js';
-import { uriToDid } from '../util/uris.js';
+import { recordUriOf, uriToDid } from '../util/uris.js';
+import { isExternalEmbedType, isRecordWithMediaType, } from '../views/types.js';
 import { HydrationMap, parseDate, safeTakedownRef, } from './util.js';
+/**
+ * Per-collection sample limits. Basic hydration skips social previews,
+ * but keeps gallery items. Direct publication/photo references are singular.
+ */
+export const EXTERNAL_HYDRATION_LIMITS = {
+    [site.standard.document.$type]: { recommendationPreviews: 3 },
+    [site.standard.publication.$type]: { subscriberPreviews: 3 },
+    [social.grain.gallery.$type]: { items: 10, favoritePreviews: 3 },
+};
+/** Maximum in-flight backlink sample RPCs, not a dependency-count limit. */
+export const MAX_CONCURRENT_BACKLINK_REQUESTS = 8;
+/** Maximum logical batches per traversal, counting the root as pass 1. */
+export const MAX_EXTERNAL_HYDRATION_PASSES = 8;
 export class ExternalHydrator {
-    static { this.MAX_BACKLINK_PREVIEWS = 3; }
-    static { this.MAX_BACKLINK_GALLERY_ITEMS = 10; }
-    static { this.MAX_BACKLINK_FANOUT = 8; }
-    /** Hard cap on generic batches per traversal, counting the root as pass 1. */
-    static { this.MAX_EXTERNAL_HYDRATION_PASSES = 8; }
     /**
      * Entries per generic record RPC. The dataplane rejects larger URI lookups;
      * exact-ref lookups use the same bound defensively.
      */
     static { this.MAX_RECORDS_PER_REQUEST = 100; }
+    /**
+     * Target URIs per backlink-count RPC. The dataplane requires between 1 and
+     * 100; this is a separate limit from `MAX_RECORDS_PER_REQUEST`.
+     */
+    static { this.MAX_BACKLINK_COUNT_TARGETS_PER_REQUEST = 100; }
+    /** Target URIs per actor-backlink RPC, bounded by the dataplane. */
+    static { this.MAX_BACKLINK_ACTOR_TARGETS_PER_REQUEST = 100; }
     constructor(dataplane) {
         this.dataplane = dataplane;
     }
@@ -68,20 +83,24 @@ export class ExternalHydrator {
             cursor: res.cursor || undefined,
         };
     }
-    /** Fetch source-record counts, optionally restricted to one collection. */
+    /**
+     * Fetch source-record counts, optionally restricted to one collection. Large
+     * inputs are fetched in sequential bounded requests; any failed request
+     * rejects the whole call.
+     */
     async getAtmosphereBacklinkCounts(targetUris, collection) {
         const map = new HydrationMap();
-        if (!targetUris.length)
-            return map;
-        const res = await this.dataplane.getAtmosphereBacklinkCounts({
-            targetUris,
-            collection,
-        });
-        for (const result of res.results) {
-            map.set(result.targetUri, Object.fromEntries(Object.entries(result.counts).map(([nsid, count]) => [
-                nsid,
-                Number(count),
-            ])));
+        for (const chunk of chunkArray(targetUris, ExternalHydrator.MAX_BACKLINK_COUNT_TARGETS_PER_REQUEST)) {
+            const res = await this.dataplane.getAtmosphereBacklinkCounts({
+                targetUris: chunk,
+                collection,
+            });
+            for (const result of res.results) {
+                map.set(result.targetUri, Object.fromEntries(Object.entries(result.counts).map(([nsid, count]) => [
+                    nsid,
+                    Number(count),
+                ])));
+            }
         }
         return map;
     }
@@ -115,21 +134,6 @@ export class ExternalHydrator {
         }
         return { backlinks, truncated: res.truncated };
     }
-    /**
-     * Fetch exact `site.standard.{document,publication}` versions. Does NOT
-     * resolve a document's publication; callers must pin it explicitly.
-     */
-    async getSiteStandardRecordsByRef(refs, includeTakedowns = false) {
-        const ssRefs = refs.filter((ref) => !!ref.cid && siteStandardKind(ref.uri) !== undefined);
-        const out = emptySiteStandardRecords();
-        if (!ssRefs.length)
-            return out;
-        const records = await this.getRecordsByRef(ssRefs, includeTakedowns);
-        for (const [key, info] of records) {
-            setSiteStandardRecord(out, parseGenericRecordKey(key).uri, key, info);
-        }
-        return out;
-    }
 }
 export function genericRecordKey({ uri, cid }) {
     if (cid === undefined)
@@ -180,9 +184,10 @@ export function actionExternalRecordTakedowns({ externalRecords, externalRecords
  * there is none. Only the owner reports, once, including on failure, with the
  * context's XRPC endpoint (`'unknown'` if unset) and the traversal's wall time. A
  * returned traversal is `capped` if it hit the pass limit, else `partial` if
- * it recovered from a dependency failure. Owners that completed without
- * scheduling a batch did no work and are not reported; other outcomes always
- * are.
+ * it recovered from a dependency failure. Owners that completed report when
+ * they scheduled a batch or inspected roots (even prehydrated or unavailable
+ * ones); only genuinely empty successful calls are not reported. Other
+ * outcomes always are.
  */
 export async function trackExternalHydration(root, xrpcEndpoint, hydrationMetrics, fn) {
     if (hydrationMetrics)
@@ -207,7 +212,7 @@ export async function trackExternalHydration(root, xrpcEndpoint, hydrationMetric
         return state;
     }
     finally {
-        if (owned.batches || outcome !== 'completed') {
+        if (owned.batches > 0 || owned.roots > 0 || outcome !== 'completed') {
             events.externalHydrationTraversal({
                 xrpcEndpoint: xrpcEndpoint ?? 'unknown',
                 root,
@@ -251,10 +256,6 @@ function parseGenericRecord(result, includeTakedowns) {
         takedownRef: safeTakedownRef(entry),
     };
 }
-const emptySiteStandardRecords = () => ({
-    documents: new HydrationMap(),
-    publications: new HydrationMap(),
-});
 const siteStandardKind = (uri) => {
     const parsed = parseAtUriString(uri);
     if (!parsed.success)
@@ -277,82 +278,101 @@ const matchRecordInfo = (schema, info) => info && schema.$matches(info.record, {
     ? { ...info, record: info.record }
     : null;
 /**
- * Store a generic record in the map matching its collection. Records failing
- * Lexicon validation are stored as null.
+ * Select one pinned embed root. Legacy publication-first pairs may put their
+ * document second; no other authored refs participate in hydration.
  */
-const setSiteStandardRecord = (out, uri, key, info) => {
-    switch (siteStandardKind(uri)) {
-        case 'documents':
-            out.documents.set(key, matchRecordInfo(site.standard.document.main, info));
-            break;
-        case 'publications':
-            out.publications.set(key, matchRecordInfo(site.standard.publication.main, info));
-            break;
+export function getExternalRootRef(refs) {
+    let root = refs?.[0];
+    if (!root)
+        return undefined;
+    if (siteStandardKind(root.uri) === 'publications') {
+        const second = refs?.[1];
+        if (second && siteStandardKind(second.uri) === 'documents')
+            root = second;
     }
-};
-/**
- * Read-path resolution: caller pinned a set of `(uri, cid)` strongRefs in
- * the post at write time, and we honor those exact versions. Any pair
- * that doesn't structurally agree is rejected, so downstream callers can
- * trust the returned shape.
- *
- * Pairing rules:
- * - Both slots referenced: `doc.site` must equal `publication.ref.uri`,
- *   else both come back `undefined`.
- * - Doc with at-uri `site` referenced but no matching publication ref:
- *   reject the whole pairing (doc claims a publication that should have
- *   been pinned, but wasn't).
- * - Loose doc (web-URL `site`) referenced: publication stays `undefined`.
- * - Only a publication referenced: document stays `undefined`.
- *
- * Each returned slot carries the matching `ref` so callers can recover
- * the owner DID for blob-cdn URL building, etc.
- */
-export const getSiteStandardRecordsFromHydrationMapsByRefs = (associatedRefs, documents, publications) => {
-    if (!associatedRefs?.length) {
-        return { document: undefined, publication: undefined };
+    return isHydratableAssociatedRef(root) ? root : undefined;
+}
+/** Select a pinned Standard.site root and its derived publication, if needed. */
+export function getSiteStandardRecordsFromRefs(associatedRefs, records, dependencies) {
+    const empty = { document: undefined, publication: undefined };
+    const ref = getExternalRootRef(associatedRefs);
+    if (!ref)
+        return empty;
+    const info = records?.get(genericRecordKey(ref));
+    if (siteStandardKind(ref.uri) === 'publications') {
+        const publication = matchRecordInfo(site.standard.publication.main, info);
+        return publication
+            ? { document: undefined, publication: { ref, info: publication } }
+            : empty;
     }
-    // Resolve each ref against the hydration maps, taking the first hit on
-    // each side.
-    let document;
-    let publication;
-    for (const ref of associatedRefs) {
-        const key = genericRecordKey(ref);
-        if (!document) {
-            const hit = documents?.get(key);
-            if (hit)
-                document = { ref, info: hit };
-        }
-        if (!publication) {
-            const hit = publications?.get(key);
-            if (hit)
-                publication = { ref, info: hit };
-        }
-        if (document && publication)
-            break;
+    if (siteStandardKind(ref.uri) !== 'documents')
+        return empty;
+    const document = matchRecordInfo(site.standard.document.main, info);
+    if (!document)
+        return empty;
+    const documentSelection = { ref, info: document };
+    const docSite = document.record.site;
+    if (!docSite.startsWith('at://')) {
+        return { document: documentSelection, publication: undefined };
     }
-    // Both refs resolved: enforce that the doc's `site` actually points at
-    // the supplied publication. Mismatch means the post was misconstructed
-    // (or tampered with), so reject the whole pairing.
-    if (document && publication) {
-        if (document.info.record.site !== publication.ref.uri) {
-            hydrationLogger.warn({
-                documentUri: document.ref.uri,
-                documentSite: document.info.record.site,
-                publicationUri: publication.ref.uri,
-            }, 'site.standard byRefs lookup failed: doc.site does not match hydrated publication.uri');
-            return { document: undefined, publication: undefined };
-        }
+    const uri = recordUriOf(docSite, site.standard.publication.$type);
+    if (!uri)
+        return empty;
+    const publication = matchRecordInfo(site.standard.publication.main, dependencies?.get(uri));
+    if (!publication)
+        return empty;
+    return {
+        document: documentSelection,
+        publication: { ref: { uri, cid: publication.cid }, info: publication },
+    };
+}
+const externalAssociatedRefs = (post) => {
+    const embed = post?.embed;
+    if (!embed)
+        return [];
+    if (isExternalEmbedType(embed)) {
+        return embed.external.associatedRefs ?? [];
     }
-    // Doc with at-uri `site` but no publication: the post should have
-    // pinned the publication too. Treat as misconstructed.
-    if (document && !publication) {
-        const site = document.info.record.site;
-        if (site && site.startsWith('at://')) {
-            hydrationLogger.warn({ documentUri: document.ref.uri, documentSite: site }, 'site.standard byRefs lookup failed: document.site is AT URI but no matching publication was hydrated');
-            return { document: undefined, publication: undefined };
+    if (isRecordWithMediaType(embed) && isExternalEmbedType(embed.media)) {
+        return embed.media.external.associatedRefs ?? [];
+    }
+    return [];
+};
+/**
+ * An exact ref needs a nonempty CID and a complete record URI in a DID repo,
+ * so malformed refs are skipped instead of becoming latest lookups.
+ */
+const isHydratableAssociatedRef = (ref) => {
+    if (!ref.cid)
+        return false;
+    const parsed = parseAtUriString(ref.uri);
+    if (!parsed.success)
+        return false;
+    const { authority, collection, rkey, query, hash } = parsed.value;
+    return (isDidString(authority) &&
+        !!collection &&
+        !!rkey &&
+        query === undefined &&
+        hash === undefined);
+};
+/** Collect one root per post across all layers, deduped by exact ref. */
+export const externalAssociatedRefsFromPosts = (...postLayers) => {
+    const seen = new Set();
+    const out = [];
+    for (const layer of postLayers) {
+        for (const item of layer.values()) {
+            if (!item)
+                continue;
+            const ref = getExternalRootRef(externalAssociatedRefs(item.record));
+            if (!ref)
+                continue;
+            const key = genericRecordKey(ref);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ uri: ref.uri, cid: ref.cid });
         }
     }
-    return { document, publication };
+    return out;
 };
 //# sourceMappingURL=external.js.map