Changeset 30871c1 in Klonkt

Timestamp:

07/20/2026 11:35:45 PM (7 weeks ago)

Author:

Robin <roboburr@…>

Branches:

main

Children:

562e1b0

Parents:

5143ccf

git-author:

Robin <roboburr@…> (07/20/2026 11:35:44 PM)

git-committer:

Robin <roboburr@…> (07/20/2026 11:35:45 PM)

Message:

Feature: enrichment is opt-in via Prefer (FEP-9876 conformance)

Klonkt is the reference implementation of FEP-9876. The owner
followers/following collections now enrich member representations only
when the client asks with Prefer: return=representation (RFC 7240),
echo Preference-Applied and always set Vary: Prefer; the default is
bare id strings, so the collections match the AP norm and existing
consumers are unaffected. The Prefer predicate is a pure, tested
function.

Changed files:
src/services/ActivityPubService.js

• prefersEnriched(preferHeader): pure Prefer detector, exported

src/routes/activitypub.js

• owner followers/following: enrich only on the preference, set Preference-Applied + Vary: Prefer

test/c2s-contacts.test.js

• prefersEnriched cases

docs/shaer-c2s-api.md

• document the Prefer opt-in

-robo
Co-Authored-By: Claude Opus 4.8 <noreply@…>

Files:

• docs/shaer-c2s-api.md (modified) (1 diff)
• src/routes/activitypub.js (modified) (3 diffs)
• src/services/ActivityPubService.js (modified) (2 diffs)
• test/c2s-contacts.test.js (modified) (1 diff)

docs/shaer-c2s-api.md

@@ -84 +84 @@
 
 **Followers and following** are count-only for the public (privacy). With the
-owner's bearer they return the real entries as AS2 actor references with display,
-so a client shows names and avatars instead of bare ids:
+owner's bearer they return the real entries. By default these are bare id
+strings; send `Prefer: return=representation` (FEP-9876) to get them enriched as
+AS2 actor references with display, so a client shows names and avatars instead of
+bare ids. The server echoes `Preference-Applied: return=representation` and sets
+`Vary: Prefer`:
 
 ```json

src/routes/activitypub.js

@@ -169 +169 @@
 // URIs so their own client can build a friends list; everyone else gets the
 // count only (privacy).
+// FEP-9876: enrichment is opt-in via `Prefer: return=representation` (RFC 7240).
+// Returns true and sets the response headers when the owner asked for it.
+function wantsEnriched(req, res) {
+  res.set('Vary', 'Prefer');   // enriched and bare are two representations
+  if (AP.prefersEnriched(req.get('Prefer'))) {
+    res.set('Preference-Applied', 'return=representation');
+    return true;
+  }
+  return false;
+}
+
 router.get('/ap/users/:slug/followers', (req, res) => {
   const auth = OAuth.verifyBearer(req.headers.authorization);
@@ -176 +187 @@
   if (owner) {
     const uris = db.prepare('SELECT actor_uri FROM ap_followers WHERE slug = ? ORDER BY created_at').all(site.slug).map((r) => r.actor_uri);
-    const items = uris.map((u) => AP.buildActorRef(site.slug, u));   // name + avatar (shaer-aa3)
+    // Default = bare references; enrich only when the client asks (FEP-9876).
+    const items = wantsEnriched(req, res) ? uris.map((u) => AP.buildActorRef(site.slug, u)) : uris;
     return AP.sendAP(res, AP.buildFollowers(baseUrl(req), site, items.length, items));
   }
@@ -190 +202 @@
   if (!site) return res.status(404).end();
   if (owner) {
+    const enrich = wantsEnriched(req, res);   // FEP-9876 opt-in
     let items = [];
-    try { items = db.prepare("SELECT actor_uri FROM ap_following WHERE slug = ? AND status = 'accepted' ORDER BY created_at").all(site.slug).map((r) => AP.buildActorRef(site.slug, r.actor_uri)); } catch { /* table may not exist */ }
+    try {
+      const uris = db.prepare("SELECT actor_uri FROM ap_following WHERE slug = ? AND status = 'accepted' ORDER BY created_at").all(site.slug).map((r) => r.actor_uri);
+      items = enrich ? uris.map((u) => AP.buildActorRef(site.slug, u)) : uris;
+    } catch { /* table may not exist */ }
     return AP.sendAP(res, AP.buildFollowing(baseUrl(req), site, items.length, items));
   }

src/services/ActivityPubService.js

@@ -667 +667 @@
   } catch { /* ignore */ }
   return { name: null, handle: deriveHandle(uri), icon: null };
+}
+
+// FEP-9876: does this `Prefer` header ask for enriched (embedded) members?
+// Pure and testable; the route sets the response headers around it.
+export function prefersEnriched(preferHeader) {
+  return /(^|[,;\s])return=representation($|[,;\s])/i.test(String(preferHeader || ''));
 }
 
@@ -3070 +3076 @@
   linkifyBody, bakePostContent, bakePostContentWithMentions, listFollowers, removeFollower, listConnections,
   noteVisibility, isRejectedObject, rejectInteraction, interactionReportTarget,
-  getMessages, notificationsSeenAt, ingestOutboxActivity, c2sVisibility, actorDisplay, buildActorRef,
+  getMessages, notificationsSeenAt, ingestOutboxActivity, c2sVisibility, actorDisplay, buildActorRef, prefersEnriched,
 };

test/c2s-contacts.test.js

@@ -44 +44 @@
   assert.equal(ref.name, 'Dana');
 });
+
+test('prefersEnriched detects the Prefer opt-in (FEP-9876)', () => {
+  assert.equal(AP.prefersEnriched('return=representation'), true);
+  assert.equal(AP.prefersEnriched('return=representation; handling=lenient'), true);
+  assert.equal(AP.prefersEnriched('foo, return=representation'), true);
+  assert.equal(AP.prefersEnriched('return=minimal'), false);
+  assert.equal(AP.prefersEnriched('returnx=representation'), false);
+  assert.equal(AP.prefersEnriched(''), false);
+  assert.equal(AP.prefersEnriched(undefined), false);
+});