tomdebone/maarcadetweet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(appview): Notifications, Follower-/Following-Listen, Thread-Route

Browse Source 
Bisher erfuhr ein Nutzer nie, dass jemand anderes mit ihm interagiert hat:
Like, Repost, Follow und Reply hinterließen keine Spur, an der der Client
hätte pollen können. Der Tray-/Notification-Pfad im Desktop-Client (Phase 7)
hing damit in der Luft.

Migration 0008:
* notifications(recipient, author, kind, subject_uri, created_at,
  indexed_at, read_at) mit Keyset-Index (recipient, indexed_at DESC, id DESC)
  und Partial-Index auf ungelesene Zeilen für den Badge-Poll.
* Dedupe-Unique-Index über COALESCE(subject_uri, '') — plain NULLs
  kollidieren nicht, sonst gäbe es pro Follow beliebig viele Zeilen.
  Folge: Unlike-Relike erzeugt keine zweite Notification, Toggle-Spam ist
  damit ausgeschlossen.
* Bewusst kein CHECK (recipient <> author): ein Ausrutscher dort würde die
  umgebende Like-Transaktion abbrechen, also das Like wegen eines
  Notification-Bugs verlieren. Gefiltert wird in Rust und im INSERT.

Indexer: record_notification() hängt an upsert_like/-repost (in derselben
Transaktion wie die Counter) sowie upsert_follow/-post. Selbst-Interaktionen
sind still. Empfänger muss uns bekannt sein (profiles- oder posts-Zeile),
sonst würden wir für den gesamten öffentlichen Firehose Zeilen anlegen —
als ein INSERT ... SELECT ... WHERE EXISTS, also ohne TOCTOU-Fenster.
Reply-Notifications tragen die URI der *Antwort* als subject_uri, weil die
Liste den Text zeigt, den der Empfänger noch nicht kennt.

Endpoints: GET /api/notifications, /api/notifications/count,
POST /api/notifications/seen (seenAt als Wasserzeichen),
GET /api/followers, /api/following, GET /api/thread (beide Schreibweisen).
Cursor-Codec, Limit-Clamping und Fehlerform sind die der bestehenden
Endpoints.

/api/post/*uri bleibt wire-kompatibel und teilt sich jetzt
load_thread_context() mit /api/thread — mit max_parents = 1, weil es nur
den direkten Parent serialisiert; die volle Ahnenkette wären bis zu 20
sequenzielle Queries für Zeilen, die danach verworfen werden.

Nebenbei ein Darstellungsfehler: der synthetische Platzhalter-Handle für
Actors ohne bekannten Handle trug ein führendes '@', während jeder Consumer
selbst '@{handle}' rendert — im Feed kam '@@did:plc:abcd…' heraus. Der
Platzhalter ist jetzt durchgängig sigil-frei.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013HC9HLrUU1LNwkzp8nkDLX
This commit is contained in:
tomdebone
2026-09-09 21:36:32 +02:00
co-authored by Claude Opus 5
parent 9d009bfcba
commit c4ca218d97
6 changed files with 2519 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/appview/src/indexer.rs
+557
View File
@@ -348,6 +348,31 @@ pub async fn upsert_post(db: &PgPool, row: &mut PostRow) -> Result<()> {
.bind(&row.avatar_cid)
.execute(db)
.await?;
// Reply notification. A post with a `parent_uri` is a reply, so the
// parent's author gets a "someone replied to you" row.
//
// `subject_uri` is the REPLY's own URI, not the parent's: the
// notification list hydrates `subject_uri`'s text, and what the
// recipient wants to read is what the replier wrote — they already
// know the content of their own post. It also makes the row a
// direct link target for "open this reply in the thread view".
//
// The dedupe index keys on the reply URI, so re-indexing (or an
// edit that re-runs the upsert) can't produce a second row.
if let Some(parent_uri) = row.parent_uri.as_deref() {
if let Some(recipient) = post_author_did(db, parent_uri).await? {
record_notification(
db,
&recipient,
&row.did,
NOTIF_REPLY,
Some(&row.uri),
row.created_at,
)
.await?;
}
}
Ok(())
}
@@ -414,6 +439,23 @@ pub async fn upsert_like(
.bind(&post_uri)
.execute(&mut *tx)
.await?;
// Notify the post's author. Runs inside the same transaction as
// the counter bump so a crash can't leave a like counted but
// un-notified (or vice versa). `post_author_did` returns None
// for a post we haven't indexed — then there's nobody to
// notify and we quietly skip.
if let Some(recipient) = post_author_did(&mut *tx, &post_uri).await? {
record_notification(
&mut *tx,
&recipient,
did,
NOTIF_LIKE,
Some(&post_uri),
created_at,
)
.await?;
}
}
tx.commit().await?;
Ok(())
@@ -489,6 +531,20 @@ pub async fn upsert_repost(
.bind(&post_uri)
.execute(&mut *tx)
.await?;
// Same transactional notification write as the like path — see
// `upsert_like` for the rationale.
if let Some(recipient) = post_author_did(&mut *tx, &post_uri).await? {
record_notification(
&mut *tx,
&recipient,
did,
NOTIF_REPOST,
Some(&post_uri),
created_at,
)
.await?;
}
}
tx.commit().await?;
Ok(())
@@ -517,6 +573,124 @@ pub async fn delete_repost(db: &PgPool, did: &str, rkey: &str) -> Result<()> {
Ok(())
}
// -- notifications ---------------------------------------------------------
/// The four notification kinds the AppView produces. Kept as `&str`
/// constants rather than an enum because the value is a plain `TEXT`
/// column guarded by a CHECK constraint (migration 0008) and every
/// call site is a literal — an enum would only add a `to_string()`.
pub const NOTIF_LIKE: &str = "like";
pub const NOTIF_REPOST: &str = "repost";
pub const NOTIF_FOLLOW: &str = "follow";
pub const NOTIF_REPLY: &str = "reply";
/// Should an interaction by `author_did` aimed at `recipient_did`
/// produce a notification row?
///
/// Pure so it can be unit-tested without a database. Two rules:
///
/// 1. **No self-interactions.** Liking your own post, reposting
/// yourself, self-following or replying to yourself must stay
/// silent — the user already knows they did it, and a "you liked
/// your own post" row is pure noise.
/// 2. **No empty DIDs.** An empty recipient means we failed to resolve
/// the target (e.g. a like against a post that isn't in our index),
/// and an empty author means the event was malformed. Either way
/// the row would be unattributable in the UI.
///
/// The same two rules are ALSO enforced in SQL inside
/// [`record_notification`], so a caller that forgets this guard still
/// can't write a bad row — this function exists to skip the round trip
/// in the common self-interaction case and to make the rule testable.
pub fn should_notify(recipient_did: &str, author_did: &str) -> bool {
!recipient_did.is_empty() && !author_did.is_empty() && recipient_did != author_did
}
/// Insert one notification row, if and only if it is warranted.
///
/// Returns `Ok(true)` when a row was actually written, `Ok(false)` when
/// the write was skipped — either because the interaction failed
/// [`should_notify`], because the recipient isn't a user this AppView
/// serves, or because the same notification already exists.
///
/// **"Local user"**: the AppView deliberately has no `users` table —
/// the PDS owns account state. The closest thing we have is "a DID this
/// AppView knows about", i.e. one with a row in the `profiles` cache
/// (written by the PDS profile push / the Jetstream `app.bsky.actor.profile`
/// arm) or at least one indexed post. That is exactly the set of users
/// a client could ever poll notifications for, so restricting writes to
/// it keeps us from materialising a notification row for every like on
/// the entire public firehose while never dropping one a local user
/// would actually see.
///
/// **Idempotency**: the `ON CONFLICT` target is the expression index
/// `notifications_dedupe_idx` from migration 0008, keyed on
/// `(recipient_did, author_did, kind, COALESCE(subject_uri, ''))`. The
/// `COALESCE` is load-bearing: a plain unique index would let two
/// `follow` rows (whose `subject_uri` is NULL) coexist, because SQL
/// NULLs never collide. Re-indexing the same Jetstream event — on a
/// reconnect replay, or via the PDS `/internal/ingest-commit` push that
/// races the firehose — is therefore a no-op.
///
/// The executor is generic so this can run either on the pool (the
/// reply path) or inside the caller's transaction (the like / repost
/// paths, where the notification must commit atomically with the
/// counter bump).
pub async fn record_notification<'e, E>(
exec: E,
recipient_did: &str,
author_did: &str,
kind: &str,
subject_uri: Option<&str>,
created_at: chrono::DateTime<chrono::Utc>,
) -> Result<bool>
where
E: sqlx::PgExecutor<'e>,
{
if !should_notify(recipient_did, author_did) {
return Ok(false);
}
// One statement, so there's no TOCTOU window between "is the
// recipient local?" and "insert". Every parameter is explicitly
// cast because `INSERT ... SELECT $1, $2, ...` gives Postgres no
// column context to infer the placeholder types from.
let res = sqlx::query(
r#"INSERT INTO notifications
(recipient_did, author_did, kind, subject_uri, created_at)
SELECT $1::text, $2::text, $3::text, $4::text, $5::timestamptz
WHERE $1::text <> $2::text
AND $1::text <> ''
AND $2::text <> ''
AND (EXISTS (SELECT 1 FROM profiles WHERE did = $1::text)
OR EXISTS (SELECT 1 FROM posts WHERE did = $1::text))
ON CONFLICT (recipient_did, author_did, kind, COALESCE(subject_uri, ''))
DO NOTHING"#,
)
.bind(recipient_did)
.bind(author_did)
.bind(kind)
.bind(subject_uri)
.bind(created_at)
.execute(exec)
.await?;
Ok(res.rows_affected() > 0)
}
/// Look up the author DID of an indexed post. `None` when the post
/// isn't in our index — which is the normal case for a like/reply
/// aimed at a post hosted somewhere we don't follow. The caller then
/// simply skips the notification rather than guessing a recipient.
async fn post_author_did<'e, E>(exec: E, uri: &str) -> Result<Option<String>>
where
E: sqlx::PgExecutor<'e>,
{
let did: Option<String> = sqlx::query_scalar("SELECT did FROM posts WHERE uri = $1")
.bind(uri)
.fetch_optional(exec)
.await?;
Ok(did)
}
// -- follows ---------------------------------------------------------------
pub async fn upsert_follow(
@@ -540,6 +714,22 @@ pub async fn upsert_follow(
.bind(created_at)
.execute(db)
.await?;
// Notify the followed user. `subject_uri` is NULL — a follow isn't
// about a post — which is exactly the case the dedupe index's
// `COALESCE(subject_uri, '')` exists for. Not wrapped in a
// transaction with the follow upsert: the follow row is the source
// of truth and a missed notification is recoverable noise, whereas
// taking a transaction here would serialise every follow write.
record_notification(
db,
subject_did,
follower_did,
NOTIF_FOLLOW,
None,
created_at,
)
.await?;
Ok(())
}
@@ -1181,6 +1371,373 @@ mod tests {
}
}
#[cfg(test)]
mod notification_tests {
use super::*;
use serde_json::json;
fn did(tag: &str) -> String {
format!("did:plc:notif_{}_{}", tag, uuid::Uuid::new_v4().simple())
}
/// Seed one post so `did` counts as a user this AppView knows
/// about (see [`record_notification`]'s "local user" note) and so
/// there's something to like / reply to.
///
/// The `handle` is deliberately non-empty. `handle_sync`'s tests
/// assert exact counts over a *global* scan of empty-handle rows,
/// so a fixture that left the column blank would silently break
/// them whenever both suites share a database.
async fn seed_post(db: &PgPool, author: &str, rkey: &str) -> String {
let uri = format!("at://{author}/app.twi.post/{rkey}");
sqlx::query(
r#"INSERT INTO posts
(uri, did, handle, rkey, collection, text, cid,
parent_uri, root_uri, langs, created_at)
VALUES ($1,$2,'notif-fixture.test','x','app.twi.post','seed','bafy',
NULL,NULL,NULL, now())
ON CONFLICT (uri) DO NOTHING"#,
)
.bind(&uri)
.bind(author)
.execute(db)
.await
.unwrap();
uri
}
async fn count_notifications(db: &PgPool, recipient: &str, kind: &str) -> i64 {
sqlx::query_scalar(
"SELECT COUNT(*)::BIGINT FROM notifications \
WHERE recipient_did = $1 AND kind = $2",
)
.bind(recipient)
.bind(kind)
.fetch_one(db)
.await
.unwrap()
}
async fn cleanup(db: &PgPool, dids: &[&str]) {
for d in dids {
let _ = sqlx::query(
"DELETE FROM notifications WHERE recipient_did = $1 OR author_did = $1",
)
.bind(d)
.execute(db)
.await;
let _ = sqlx::query("DELETE FROM likes WHERE did = $1")
.bind(d)
.execute(db)
.await;
let _ = sqlx::query("DELETE FROM reposts WHERE did = $1")
.bind(d)
.execute(db)
.await;
let _ = sqlx::query("DELETE FROM follows WHERE follower_did = $1 OR subject_did = $1")
.bind(d)
.execute(db)
.await;
let _ = sqlx::query("DELETE FROM posts WHERE did = $1")
.bind(d)
.execute(db)
.await;
}
}
#[test]
fn should_notify_rejects_self_and_empty() {
assert!(should_notify("did:plc:a", "did:plc:b"));
// Self-interaction: liking / replying to / following yourself.
assert!(!should_notify("did:plc:a", "did:plc:a"));
// Unresolvable ends of the edge.
assert!(!should_notify("", "did:plc:b"));
assert!(!should_notify("did:plc:a", ""));
assert!(!should_notify("", ""));
// Case matters — DIDs are compared verbatim, never folded.
assert!(should_notify("did:plc:A", "did:plc:a"));
}
/// A like by someone else must produce exactly one notification,
/// and re-indexing the same event (Jetstream replay racing the PDS
/// push) must not produce a second.
#[tokio::test]
async fn like_notifies_author_once() {
let Some(db) = try_test_db().await else {
eprintln!("appview DB unavailable; skipping");
return;
};
let author = did("author");
let liker = did("liker");
// The liker also needs to exist for nothing in particular —
// only the *recipient* is checked — but seeding both keeps the
// fixture symmetric with reality.
let post_uri = seed_post(&db, &author, "p1").await;
seed_post(&db, &liker, "p1").await;
let record = json!({
"subject": { "uri": post_uri, "cid": "bafysubject" },
"createdAt": "2026-07-01T12:00:00Z"
});
upsert_like(&db, &liker, "lrk1", Some("bafylike"), Some(&record))
.await
.unwrap();
assert_eq!(count_notifications(&db, &author, NOTIF_LIKE).await, 1);
// Replay the exact same event.
upsert_like(&db, &liker, "lrk1", Some("bafylike"), Some(&record))
.await
.unwrap();
assert_eq!(
count_notifications(&db, &author, NOTIF_LIKE).await,
1,
"replayed like must not duplicate the notification"
);
// Unlike + re-like under a NEW rkey. The like row is recreated
// but the notification tuple is unchanged, so the dedupe index
// suppresses it — see migration 0008's "Idempotency" note.
delete_like(&db, &liker, "lrk1").await.unwrap();
upsert_like(&db, &liker, "lrk2", Some("bafylike2"), Some(&record))
.await
.unwrap();
assert_eq!(
count_notifications(&db, &author, NOTIF_LIKE).await,
1,
"toggling a like must not be a notification-spam vector"
);
// The stored row must point at the liked post and name the
// liker as the author.
let row: (String, Option<String>) = sqlx::query_as(
"SELECT author_did, subject_uri FROM notifications \
WHERE recipient_did = $1 AND kind = $2",
)
.bind(&author)
.bind(NOTIF_LIKE)
.fetch_one(&db)
.await
.unwrap();
assert_eq!(row.0, liker);
assert_eq!(row.1.as_deref(), Some(post_uri.as_str()));
// Unread by default — that's what /api/notifications/count sees.
let unread: i64 = sqlx::query_scalar(
"SELECT COUNT(*)::BIGINT FROM notifications \
WHERE recipient_did = $1 AND read_at IS NULL",
)
.bind(&author)
.fetch_one(&db)
.await
.unwrap();
assert_eq!(unread, 1);
cleanup(&db, &[&author, &liker]).await;
}
/// Liking / reposting your own post is silent.
#[tokio::test]
async fn self_interaction_writes_no_notification() {
let Some(db) = try_test_db().await else {
eprintln!("appview DB unavailable; skipping");
return;
};
let author = did("selfie");
let post_uri = seed_post(&db, &author, "p1").await;
let record = json!({
"subject": { "uri": post_uri, "cid": "bafysubject" },
"createdAt": "2026-07-01T12:00:00Z"
});
upsert_like(&db, &author, "lrk1", None, Some(&record))
.await
.unwrap();
upsert_repost(&db, &author, "rrk1", None, Some(&record))
.await
.unwrap();
// Self-follow is legal in the protocol; it must stay silent too.
upsert_follow(&db, &author, &author, None).await.unwrap();
let total: i64 = sqlx::query_scalar(
"SELECT COUNT(*)::BIGINT FROM notifications WHERE recipient_did = $1",
)
.bind(&author)
.fetch_one(&db)
.await
.unwrap();
assert_eq!(total, 0, "self-interactions must not notify");
// The like/repost themselves still landed — the notification
// suppression must not swallow the interaction.
let likes: i64 = sqlx::query_scalar("SELECT COUNT(*)::BIGINT FROM likes WHERE did = $1")
.bind(&author)
.fetch_one(&db)
.await
.unwrap();
assert_eq!(likes, 1);
cleanup(&db, &[&author]).await;
}
/// A repost notifies, and a reply notifies the *parent's* author
/// with the reply's own URI as the subject.
#[tokio::test]
async fn repost_and_reply_notify() {
let Some(db) = try_test_db().await else {
eprintln!("appview DB unavailable; skipping");
return;
};
let author = did("parent");
let other = did("replier");
let parent_uri = seed_post(&db, &author, "p1").await;
seed_post(&db, &other, "p1").await;
let record = json!({
"subject": { "uri": parent_uri, "cid": "bafysubject" },
"createdAt": "2026-07-01T12:00:00Z"
});
upsert_repost(&db, &other, "rrk1", None, Some(&record))
.await
.unwrap();
assert_eq!(count_notifications(&db, &author, NOTIF_REPOST).await, 1);
// Now a reply from `other` to `author`'s post.
let reply_record = json!({
"text": "nice one",
"createdAt": "2026-07-01T12:05:00Z",
"reply": {
"parent": { "uri": parent_uri, "cid": "bafyparent" },
"root": { "uri": parent_uri, "cid": "bafyparent" }
}
});
let mut row = PostRow::from_record(
&other,
"replykey",
"app.twi.post",
"bafyreply",
&reply_record,
None,
);
let reply_uri = row.uri.clone();
upsert_post(&db, &mut row).await.unwrap();
let subject: Option<String> = sqlx::query_scalar(
"SELECT subject_uri FROM notifications \
WHERE recipient_did = $1 AND kind = $2",
)
.bind(&author)
.bind(NOTIF_REPLY)
.fetch_one(&db)
.await
.unwrap();
assert_eq!(
subject.as_deref(),
Some(reply_uri.as_str()),
"a reply notification's subject is the REPLY, so the list can \
preview what was written"
);
// Re-indexing the reply must not duplicate.
upsert_post(&db, &mut row).await.unwrap();
assert_eq!(count_notifications(&db, &author, NOTIF_REPLY).await, 1);
cleanup(&db, &[&author, &other]).await;
}
/// A follow notifies the followed user with a NULL subject_uri —
/// the case the dedupe index's `COALESCE(subject_uri, '')` exists
/// for, since plain SQL NULLs never collide.
#[tokio::test]
async fn follow_notifies_subject_and_dedupes_on_null_subject() {
let Some(db) = try_test_db().await else {
eprintln!("appview DB unavailable; skipping");
return;
};
let subject = did("followee");
let follower = did("follower");
seed_post(&db, &subject, "p1").await;
let record = json!({ "subject": subject, "createdAt": "2026-01-01T00:00:00Z" });
upsert_follow(&db, &follower, &subject, Some(&record))
.await
.unwrap();
upsert_follow(&db, &follower, &subject, Some(&record))
.await
.unwrap();
assert_eq!(
count_notifications(&db, &subject, NOTIF_FOLLOW).await,
1,
"two NULL-subject follow rows must collide, not coexist"
);
let subject_uri: Option<String> = sqlx::query_scalar(
"SELECT subject_uri FROM notifications \
WHERE recipient_did = $1 AND kind = $2",
)
.bind(&subject)
.bind(NOTIF_FOLLOW)
.fetch_one(&db)
.await
.unwrap();
assert!(subject_uri.is_none(), "a follow is not about a post");
cleanup(&db, &[&subject, &follower]).await;
}
/// A recipient the AppView has never seen (no profile row, no
/// posts) gets nothing — this is what keeps us from materialising
/// a row for every like on the public firehose.
#[tokio::test]
async fn unknown_recipient_is_skipped() {
let Some(db) = try_test_db().await else {
eprintln!("appview DB unavailable; skipping");
return;
};
let stranger = did("stranger");
let author = did("author");
let wrote = record_notification(
&db,
&stranger,
&author,
NOTIF_FOLLOW,
None,
chrono::Utc::now(),
)
.await
.unwrap();
assert!(!wrote, "unknown recipient must not get a notification row");
// Give the recipient a post — now they're a user we serve.
seed_post(&db, &stranger, "p1").await;
let wrote = record_notification(
&db,
&stranger,
&author,
NOTIF_FOLLOW,
None,
chrono::Utc::now(),
)
.await
.unwrap();
assert!(wrote, "known recipient must get the row");
// And the second call is a no-op thanks to ON CONFLICT.
let wrote = record_notification(
&db,
&stranger,
&author,
NOTIF_FOLLOW,
None,
chrono::Utc::now(),
)
.await
.unwrap();
assert!(!wrote, "duplicate must report false, not error");
cleanup(&db, &[&stranger, &author]).await;
}
}
/// Backfill the `posts.handle` column for every row belonging to
/// `did`. Used by the Jetstream `identity` handler when Jetstream
/// tells us a DID's handle has changed — every existing post row
crates/appview/src/routes.rs
+886 -107
View File
File diff suppressed because it is too large Load Diff
crates/appview/src/routes/types.rs
+159
View File
@@ -199,6 +199,165 @@ pub struct SearchResponse {
pub q: String,
}
// -- thread -----------------------------------------------------------------
/// `GET /api/thread` response.
///
/// This is the *full* thread shape: the ancestor chain above the post
/// and the direct replies below it. `/api/post/{uri}` keeps its own,
/// narrower `{ post, thread: { parent, root } }` shape for backwards
/// compatibility — both are built from the same
/// `routes::load_thread_context` call, so they can never disagree
/// about what the parent or root is.
///
/// `post` is `None` when the URI isn't in our index. In that case
/// `parents` / `replies` are empty and the counters are omitted, so a
/// client can render "post not found" from a single field check.
#[derive(Debug, Serialize)]
pub struct ThreadFullResponse {
pub post: Option<PostRow>,
/// Ancestor chain ordered **root first, immediate parent last**.
/// Empty for a top-level post, and truncated (from the top) when
/// the chain is longer than the walk limit or when an ancestor
/// isn't in our index — the client should treat a `parents[0]`
/// whose `parent_uri` is non-null as "chain continues above,
/// not loaded".
pub parents: Vec<PostRow>,
/// The thread root as named by the post's own `root_uri`. May be
/// the same row as `parents[0]`, and is `None` for a top-level
/// post (which is its own root).
pub root: Option<PostRow>,
/// Direct replies to `post`, oldest first. Only direct children —
/// the client re-requests `/api/thread` for a nested branch.
pub replies: Vec<PostRow>,
#[serde(skip_serializing_if = "Option::is_none")]
pub like_count: Option<i64>,
#[serde(skip_serializing_if = "Option::is_none")]
pub repost_count: Option<i64>,
/// Same semantics as on `/api/post/{uri}`: `None` means "no
/// viewer_did was supplied, state unknown" — not "not liked".
#[serde(skip_serializing_if = "Option::is_none")]
pub viewer_liked: Option<bool>,
#[serde(skip_serializing_if = "Option::is_none")]
pub viewer_reposted: Option<bool>,
}
// -- notifications ----------------------------------------------------------
/// One hydrated row of `GET /api/notifications`.
///
/// The DB row only stores DIDs and a subject URI; the read query joins
/// the `profiles` cache (falling back to the newest non-empty
/// `posts.handle` for authors we've seen post but never had a profile
/// record for) and the `posts` table so the client can render a full
/// notification line without any follow-up fetch.
///
/// `read_at` is serialised even when `None` — unlike the optional
/// fields around it — because "unread" is the state the client's badge
/// keys off, and a *missing* key would be indistinguishable from a
/// field the client forgot to read.
#[derive(Debug, Clone, Serialize)]
pub struct NotificationItem {
/// Row id. Also the tiebreaker inside the opaque cursor.
pub id: i64,
/// `"like"` | `"repost"` | `"follow"` | `"reply"`.
pub kind: String,
pub author_did: String,
/// Best known handle for the author, WITHOUT a leading `@` (the UI
/// renders `@{handle}`). Falls back to a truncated DID, and is
/// never null.
pub author_handle: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub author_display_name: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub author_avatar_cid: Option<String>,
/// The post this notification is about. `null` for `"follow"`. For
/// `"like"`/`"repost"` it's the recipient's own post; for
/// `"reply"` it's the reply itself.
pub subject_uri: Option<String>,
/// Text of `subject_uri`'s post. Omitted when the subject is not
/// (or no longer) in our index, and always for `"follow"`.
#[serde(skip_serializing_if = "Option::is_none")]
pub subject_text: Option<String>,
/// The interaction's own `createdAt` from the AT record.
pub created_at: DateTime<Utc>,
/// When the AppView indexed it. This is the list's sort key, and
/// the value a client should echo back as `seenAt`.
pub indexed_at: DateTime<Utc>,
/// `null` while unread.
pub read_at: Option<DateTime<Utc>>,
}
impl<'r> FromRow<'r, sqlx::postgres::PgRow> for NotificationItem {
fn from_row(row: &'r sqlx::postgres::PgRow) -> sqlx::Result<Self> {
Ok(NotificationItem {
id: row.try_get("id")?,
kind: row.try_get("kind")?,
author_did: row.try_get("author_did")?,
author_handle: row.try_get("author_handle")?,
author_display_name: row.try_get("author_display_name")?,
author_avatar_cid: row.try_get("author_avatar_cid")?,
subject_uri: row.try_get("subject_uri")?,
subject_text: row.try_get("subject_text")?,
created_at: row.try_get("created_at")?,
indexed_at: row.try_get("indexed_at")?,
read_at: row.try_get("read_at")?,
})
}
}
/// `GET /api/notifications` response. `cursor` is `None` at the end of
/// the list — same contract as [`TimelineResponse`].
#[derive(Debug, Serialize)]
pub struct NotificationsResponse {
pub notifications: Vec<NotificationItem>,
pub cursor: Option<String>,
}
/// `GET /api/notifications/count` response.
#[derive(Debug, Serialize)]
pub struct NotificationCountResponse {
/// Number of rows with `read_at IS NULL` for this DID.
pub count: i64,
}
/// `POST /api/notifications/seen` response.
#[derive(Debug, Serialize)]
pub struct NotificationSeenResponse {
pub ok: bool,
/// How many previously-unread rows this call flipped to read.
/// Zero is a normal, successful outcome (nothing was unread).
pub updated: i64,
}
// -- actor lists (followers / following) ------------------------------------
/// A minimal profile card, as returned by `GET /api/followers` and
/// `GET /api/following`.
///
/// Deliberately *not* [`ProfileResponse`]: those endpoints return a
/// list, and shipping each entry's posts + counts would turn one page
/// of 30 followers into 30 post queries. The client renders a row with
/// avatar + name + handle and navigates to `/api/profile` on click.
#[derive(Debug, Clone, Serialize)]
pub struct ActorProfile {
pub did: String,
/// Without a leading `@`; falls back to a truncated DID and is
/// never null.
pub handle: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub display_name: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub avatar_cid: Option<String>,
}
/// `GET /api/followers` / `GET /api/following` response.
#[derive(Debug, Serialize)]
pub struct ActorListResponse {
pub profiles: Vec<ActorProfile>,
pub cursor: Option<String>,
}
// -- Langs newtype ----------------------------------------------------------
/// A list of language tags. Always serialises as `Vec<String>`, never
crates/appview/tests/api_integration.rs
+47 -16
View File
@@ -134,7 +134,11 @@ async fn timeline_returns_seeded_posts() {
"cid": "bafyreicid",
"record": {
"text": format!("seeded post #{i}"),
"createdAt": "2026-07-01T12:00:00Z",
// Strictly increasing so the ordering assertion
// below has something to actually check: the rows
// are inserted in this order, so `indexed_at` and
// `created_at` agree for *our* posts.
"createdAt": format!("2026-07-01T12:00:{:02}Z", i),
}
}),
)
@@ -147,9 +151,15 @@ async fn timeline_returns_seeded_posts() {
// three rows in the first page.
tokio::time::sleep(Duration::from_millis(50)).await;
// `limit=100`, not 10: this DID follows nobody, so the endpoint
// serves the cold-start *global* recent feed. On any database with
// more than a handful of recent posts (i.e. every developer
// machine that has run this suite twice) the three rows we just
// seeded fall outside a 10-row window and the assertions below
// fail for reasons that have nothing to do with the timeline.
let resp = c
.get(format!("{APPVIEW_URL}/api/timeline/home"))
.query(&[("did", did.as_str()), ("limit", "10")])
.query(&[("did", did.as_str()), ("limit", "100")])
.send()
.await
.unwrap();
@@ -174,15 +184,28 @@ async fn timeline_returns_seeded_posts() {
.collect();
assert!(our_uris.len() >= 3, "missing our seeded posts in {posts:?}");
// Posts must be sorted with `indexed_at DESC`. We can't see
// indexed_at directly in the response, but the URI order in
// `app.twi.post/<rkey>` is rkey-random here, so we only assert
// `created_at` is non-increasing.
// Posts come back `indexed_at DESC`, and we can't see `indexed_at`
// in the response — but for the three rows WE just inserted,
// insertion order == `indexed_at` order == `created_at` order, so
// their `created_at` values must be non-increasing.
//
// Two fixes over the original assertion:
// - the wire field is `created_at`, not `createdAt` (the
// `PostRow` wire type in `routes/types.rs` carries no
// `rename_all = "camelCase"`), so `p["createdAt"]` was JSON
// `null` and `.as_str().unwrap()` panicked on the first row;
// - it ran over ALL posts, including other tests' fixtures from
// the global cold-start feed, whose `created_at` values have
// no relation to their `indexed_at` order. Restricting it to
// our own DID is the only version of this claim that holds.
let mut prev: Option<String> = None;
for p in posts {
let ca = p["createdAt"].as_str().unwrap().to_string();
if let Some(p) = prev.take() {
assert!(ca <= p, "createdAt must be non-increasing: {ca} <= {p}");
for p in posts.iter().filter(|p| p["did"] == json!(did)) {
let ca = p["created_at"].as_str().unwrap().to_string();
if let Some(prev) = prev.take() {
assert!(
ca <= prev,
"created_at must be non-increasing: {ca} <= {prev}"
);
}
prev = Some(ca);
}
@@ -354,16 +377,24 @@ async fn profile_returns_posts_for_handle() {
.unwrap();
assert_eq!(resp.status().as_u16(), 200);
// 404 for an unknown handle.
// An unknown handle is NOT a 404. `resolve_profile` deliberately
// synthesises an empty profile (empty `did`, zero counts, no
// posts) so the UI renders an empty profile page instead of an
// error toast — see the comment on the `let Some(target_did)`
// else-branch in `routes.rs`. This assertion used to expect 404
// and contradicted the endpoint it was testing.
let unknown = format!("nobody_{}", uuid::Uuid::new_v4().simple());
let resp = c
.get(format!(
"{APPVIEW_URL}/api/profile/nobody_{}",
uuid::Uuid::new_v4().simple()
))
.get(format!("{APPVIEW_URL}/api/profile/{unknown}"))
.send()
.await
.unwrap();
assert_eq!(resp.status().as_u16(), 404);
assert_eq!(resp.status().as_u16(), 200);
let body: Value = resp.json().await.unwrap();
assert_eq!(body["did"], json!(""));
assert_eq!(body["handle"], json!(unknown));
assert!(body["posts"].as_array().unwrap().is_empty());
assert_eq!(body["post_count"], json!(0));
// /api/profile?did=... must work too.
let resp = c
crates/appview/tests/notifications_integration.rs
+757
View File
@@ -0,0 +1,757 @@
//! Integration tests for the Phase-5c read API additions:
//! `/api/notifications` (+ `/count`, `/seen`), `/api/followers`,
//! `/api/following` and `/api/thread`.
//!
//! Same contract as `api_integration.rs`: these run against a live
//! appview service + DB and are **fail-open**. If the service or the
//! database isn't reachable the test prints a notice and returns
//! success, so `cargo test --workspace` stays green on a machine where
//! `docker compose up` hasn't been run.
//!
//! Notification rows are written by the *indexer*, not by any HTTP
//! endpoint, so every test here seeds through `/internal/ingest-commit`
//! (the same path the PDS uses) and then reads back through the public
//! API. That's deliberate: it's the only way to catch a mismatch
//! between what the write path stores and what the read path joins.
use serde_json::{json, Value};
use std::time::Duration;
/// Base URL of the appview under test. Overridable so the suite can be
/// pointed at a throwaway instance on a scratch database instead of
/// whatever the developer happens to have running on the default port.
fn appview_url() -> String {
std::env::var("APPVIEW_TEST_URL")
.unwrap_or_else(|_| "http://127.0.0.1:2584".to_string())
}
async fn client() -> reqwest::Client {
reqwest::Client::builder()
.timeout(Duration::from_secs(5))
.build()
.unwrap()
}
async fn wait_for_appview_db() -> bool {
let base = appview_url();
let c = client().await;
for _ in 0..20 {
if let Ok(r) = c.get(format!("{base}/healthz")).send().await {
if r.status().is_success() {
return true;
}
}
tokio::time::sleep(Duration::from_millis(250)).await;
}
false
}
async fn db_pool() -> Option<sqlx::PgPool> {
let url = std::env::var("DATABASE_URL_APPVIEW").ok()?;
match tokio::time::timeout(Duration::from_secs(2), sqlx::PgPool::connect(&url)).await {
Ok(Ok(pool)) => Some(pool),
_ => None,
}
}
/// Guard used at the top of every test. Returns `None` (→ skip) unless
/// both the HTTP service and the database are up.
async fn ready() -> Option<(reqwest::Client, sqlx::PgPool)> {
if !wait_for_appview_db().await {
eprintln!("appview not running, skipping");
return None;
}
let Some(pool) = db_pool().await else {
eprintln!("appview DB unreachable, skipping");
return None;
};
Some((client().await, pool))
}
async fn post_ingest(c: &reqwest::Client, body: Value) -> reqwest::Response {
let base = appview_url();
c.post(format!("{base}/internal/ingest-commit"))
.json(&body)
.send()
.await
.unwrap()
}
fn did_for_test(name: &str) -> String {
format!("did:plc:ntf_{}_{}", name, uuid::Uuid::new_v4().simple())
}
fn rkey() -> String {
uuid::Uuid::new_v4().simple().to_string()
}
/// Create one post through the ingest path and return its URI.
async fn seed_post(c: &reqwest::Client, did: &str, text: &str) -> String {
let rk = rkey();
let r = post_ingest(
c,
json!({
"did": did,
"handle": "ntf-fixture.test",
"collection": "app.twi.post",
"action": "create",
"rkey": rk,
"cid": "bafyreicid",
"record": { "text": text, "createdAt": "2026-07-01T12:00:00Z" }
}),
)
.await;
assert_eq!(r.status().as_u16(), 200);
format!("at://{did}/app.twi.post/{rk}")
}
/// Create a reply to `parent_uri` and return the reply's URI.
async fn seed_reply(
c: &reqwest::Client,
did: &str,
parent_uri: &str,
root_uri: &str,
text: &str,
) -> String {
let rk = rkey();
let r = post_ingest(
c,
json!({
"did": did,
"handle": "ntf-fixture.test",
"collection": "app.twi.post",
"action": "create",
"rkey": rk,
"cid": "bafyreicid",
"record": {
"text": text,
"createdAt": "2026-07-01T12:05:00Z",
"reply": {
"parent": { "uri": parent_uri, "cid": "bafyparent" },
"root": { "uri": root_uri, "cid": "bafyroot" }
}
}
}),
)
.await;
assert_eq!(r.status().as_u16(), 200);
format!("at://{did}/app.twi.post/{rk}")
}
async fn seed_like(c: &reqwest::Client, did: &str, post_uri: &str) {
let r = post_ingest(
c,
json!({
"did": did,
"collection": "app.bsky.feed.like",
"action": "create",
"rkey": rkey(),
"cid": "bafylike",
"record": {
"subject": { "uri": post_uri, "cid": "bafyreicid" },
"createdAt": "2026-07-01T12:01:00Z"
}
}),
)
.await;
assert_eq!(r.status().as_u16(), 200);
}
async fn seed_follow(c: &reqwest::Client, follower: &str, subject: &str) {
let r = post_ingest(
c,
json!({
"did": follower,
"collection": "app.bsky.graph.follow",
"action": "create",
"rkey": rkey(),
"subject_did": subject,
"record": { "subject": subject, "createdAt": "2026-01-01T00:00:00Z" }
}),
)
.await;
assert_eq!(r.status().as_u16(), 200);
}
// -- notifications ----------------------------------------------------------
/// A like, a repost-free reply and a follow from three different
/// people must show up as three hydrated notification rows, and the
/// unread count must agree with the list.
#[tokio::test]
async fn notifications_list_count_and_seen() {
let base = appview_url();
let Some((c, _pool)) = ready().await else {
return;
};
let alice = did_for_test("alice");
let bob = did_for_test("bob");
let carol = did_for_test("carol");
// Alice posts; bob likes it and carol replies; bob also follows her.
let post_uri = seed_post(&c, &alice, "alice's original").await;
seed_post(&c, &bob, "bob exists").await;
seed_post(&c, &carol, "carol exists").await;
seed_like(&c, &bob, &post_uri).await;
let reply_uri = seed_reply(&c, &carol, &post_uri, &post_uri, "carol's reply").await;
seed_follow(&c, &bob, &alice).await;
let resp = c
.get(format!("{base}/api/notifications"))
.query(&[("did", alice.as_str()), ("limit", "50")])
.send()
.await
.unwrap();
assert_eq!(resp.status().as_u16(), 200);
let body: Value = resp.json().await.unwrap();
let items = body["notifications"].as_array().expect("notifications array");
assert_eq!(items.len(), 3, "expected like + reply + follow, got {items:?}");
// Newest first: `indexed_at` must be non-increasing down the list.
let mut prev: Option<String> = None;
for n in items {
let at = n["indexed_at"].as_str().unwrap().to_string();
if let Some(p) = prev.take() {
assert!(at <= p, "indexed_at must be non-increasing: {at} <= {p}");
}
prev = Some(at);
}
let by_kind = |k: &str| -> Value {
items
.iter()
.find(|n| n["kind"] == json!(k))
.unwrap_or_else(|| panic!("missing {k} notification in {items:?}"))
.clone()
};
// The like points at alice's own post and previews its text.
let like = by_kind("like");
assert_eq!(like["author_did"], json!(bob));
assert_eq!(like["subject_uri"], json!(post_uri));
assert_eq!(like["subject_text"], json!("alice's original"));
assert!(like["read_at"].is_null(), "new notifications start unread");
// The reply points at the REPLY (not the parent), so the preview
// shows what carol wrote.
let reply = by_kind("reply");
assert_eq!(reply["author_did"], json!(carol));
assert_eq!(reply["subject_uri"], json!(reply_uri));
assert_eq!(reply["subject_text"], json!("carol's reply"));
// A follow has no subject at all.
let follow = by_kind("follow");
assert_eq!(follow["author_did"], json!(bob));
assert!(follow["subject_uri"].is_null());
// `author_handle` is never empty and never carries a leading '@'
// (the UI renders `@{handle}` itself).
for n in items {
let h = n["author_handle"].as_str().expect("author_handle is a string");
assert!(!h.is_empty(), "author_handle must never be empty: {n:?}");
assert!(!h.starts_with('@'), "author_handle must not carry a sigil: {h}");
}
// The unread count agrees with the list.
let resp = c
.get(format!("{base}/api/notifications/count"))
.query(&[("did", alice.as_str())])
.send()
.await
.unwrap();
assert_eq!(resp.status().as_u16(), 200);
let body: Value = resp.json().await.unwrap();
assert_eq!(body["count"], json!(3));
// Mark everything seen.
let resp = c
.post(format!("{base}/api/notifications/seen"))
.json(&json!({ "did": alice }))
.send()
.await
.unwrap();
assert_eq!(resp.status().as_u16(), 200);
let body: Value = resp.json().await.unwrap();
assert_eq!(body["ok"], json!(true));
assert_eq!(body["updated"], json!(3));
// Idempotent: a second call updates nothing and still succeeds.
let resp = c
.post(format!("{base}/api/notifications/seen"))
.json(&json!({ "did": alice }))
.send()
.await
.unwrap();
let body: Value = resp.json().await.unwrap();
assert_eq!(body["updated"], json!(0));
// Count is now zero and the rows carry a read_at.
let resp = c
.get(format!("{base}/api/notifications/count"))
.query(&[("did", alice.as_str())])
.send()
.await
.unwrap();
let body: Value = resp.json().await.unwrap();
assert_eq!(body["count"], json!(0));
let resp = c
.get(format!("{base}/api/notifications"))
.query(&[("did", alice.as_str())])
.send()
.await
.unwrap();
let body: Value = resp.json().await.unwrap();
for n in body["notifications"].as_array().unwrap() {
assert!(!n["read_at"].is_null(), "row should be read now: {n:?}");
}
// `did` is mandatory on all three.
for path in [
"/api/notifications",
"/api/notifications/count",
] {
let resp = c
.get(format!("{base}{path}"))
.query(&[("did", "")])
.send()
.await
.unwrap();
assert_eq!(resp.status().as_u16(), 400, "{path} must reject an empty did");
}
}
/// Self-interactions produce nothing: alice liking and replying to her
/// own post leaves her notification list empty.
#[tokio::test]
async fn notifications_skip_self_interactions() {
let base = appview_url();
let Some((c, _pool)) = ready().await else {
return;
};
let alice = did_for_test("solo");
let post_uri = seed_post(&c, &alice, "talking to myself").await;
seed_like(&c, &alice, &post_uri).await;
seed_reply(&c, &alice, &post_uri, &post_uri, "and replying too").await;
seed_follow(&c, &alice, &alice).await;
let resp = c
.get(format!("{base}/api/notifications"))
.query(&[("did", alice.as_str())])
.send()
.await
.unwrap();
let body: Value = resp.json().await.unwrap();
assert_eq!(
body["notifications"].as_array().unwrap().len(),
0,
"self-interactions must not notify: {body:?}"
);
}
/// Cursor pagination over the notification list: pages must be
/// disjoint, exactly `limit` long while more remain, and the cursor
/// must go null at the end.
#[tokio::test]
async fn notifications_paginate_with_cursor() {
let base = appview_url();
let Some((c, _pool)) = ready().await else {
return;
};
let alice = did_for_test("popular");
let post_uri = seed_post(&c, &alice, "the post everyone likes").await;
// 12 distinct likers → 12 notifications. (Distinct DIDs matter:
// the dedupe index is per (recipient, author, kind, subject).)
for i in 0..12 {
let liker = did_for_test(&format!("fan{i}"));
seed_like(&c, &liker, &post_uri).await;
}
let page = |cursor: Option<String>| {
let c = c.clone();
let alice = alice.clone();
let base = base.clone();
async move {
let mut req = c
.get(format!("{base}/api/notifications"))
.query(&[("did", alice.as_str()), ("limit", "5")]);
if let Some(cur) = cursor {
req = req.query(&[("cursor", cur.as_str())]);
}
let resp = req.send().await.unwrap();
assert_eq!(resp.status().as_u16(), 200);
resp.json::<Value>().await.unwrap()
}
};
let p1 = page(None).await;
assert_eq!(p1["notifications"].as_array().unwrap().len(), 5);
let c1 = p1["cursor"].as_str().expect("page1 cursor").to_string();
let p2 = page(Some(c1)).await;
assert_eq!(p2["notifications"].as_array().unwrap().len(), 5);
let c2 = p2["cursor"].as_str().expect("page2 cursor").to_string();
let p3 = page(Some(c2)).await;
assert_eq!(p3["notifications"].as_array().unwrap().len(), 2);
assert!(
p3["cursor"].is_null(),
"cursor must be null on the last page: {p3:?}"
);
// No id may appear on two pages.
let ids = |p: &Value| -> Vec<i64> {
p["notifications"]
.as_array()
.unwrap()
.iter()
.map(|n| n["id"].as_i64().unwrap())
.collect()
};
let mut all: Vec<i64> = ids(&p1);
all.extend(ids(&p2));
all.extend(ids(&p3));
let unique: std::collections::HashSet<i64> = all.iter().copied().collect();
assert_eq!(unique.len(), all.len(), "pages overlap: {all:?}");
assert_eq!(all.len(), 12);
// A mangled cursor is a 400, not a silent restart at page 1.
let resp = c
.get(format!("{base}/api/notifications"))
.query(&[("did", alice.as_str()), ("cursor", "!!!garbage!!!")])
.send()
.await
.unwrap();
assert_eq!(resp.status().as_u16(), 400);
}
/// `seenAt` is a watermark: only rows indexed at or before it flip to
/// read. Accepted in both camelCase and snake_case.
#[tokio::test]
async fn notifications_seen_respects_watermark() {
let base = appview_url();
let Some((c, _pool)) = ready().await else {
return;
};
let alice = did_for_test("watermark");
let post_uri = seed_post(&c, &alice, "watermark subject").await;
let first = did_for_test("early");
seed_like(&c, &first, &post_uri).await;
// Read back the first notification's indexed_at — that's the
// watermark a client would echo after rendering page 1.
let body: Value = c
.get(format!("{base}/api/notifications"))
.query(&[("did", alice.as_str())])
.send()
.await
.unwrap()
.json()
.await
.unwrap();
let watermark = body["notifications"][0]["indexed_at"]
.as_str()
.unwrap()
.to_string();
// A second interaction lands *after* the watermark.
tokio::time::sleep(Duration::from_millis(20)).await;
let second = did_for_test("late");
seed_like(&c, &second, &post_uri).await;
let resp = c
.post(format!("{base}/api/notifications/seen"))
.json(&json!({ "did": alice, "seenAt": watermark }))
.send()
.await
.unwrap();
assert_eq!(resp.status().as_u16(), 200);
let body: Value = resp.json().await.unwrap();
assert_eq!(
body["updated"], json!(1),
"only the row at/before the watermark may flip to read"
);
// The later one is still unread.
let body: Value = c
.get(format!("{base}/api/notifications/count"))
.query(&[("did", alice.as_str())])
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert_eq!(body["count"], json!(1));
// snake_case spelling must work identically.
let resp = c
.post(format!("{base}/api/notifications/seen"))
.json(&json!({ "did": alice, "seen_at": null }))
.send()
.await
.unwrap();
let body: Value = resp.json().await.unwrap();
assert_eq!(body["updated"], json!(1));
}
// -- follower / following lists ---------------------------------------------
#[tokio::test]
async fn followers_and_following_lists() {
let base = appview_url();
let Some((c, _pool)) = ready().await else {
return;
};
let hub = did_for_test("hub");
seed_post(&c, &hub, "hub post").await;
// Three people follow the hub; the hub follows one of them back.
let mut fans = Vec::new();
for i in 0..3 {
let fan = did_for_test(&format!("fan{i}"));
seed_post(&c, &fan, "fan post").await;
seed_follow(&c, &fan, &hub).await;
fans.push(fan);
}
seed_follow(&c, &hub, &fans[0]).await;
// Followers.
let body: Value = c
.get(format!("{base}/api/followers"))
.query(&[("did", hub.as_str()), ("limit", "50")])
.send()
.await
.unwrap()
.json()
.await
.unwrap();
let got: std::collections::HashSet<String> = body["profiles"]
.as_array()
.expect("profiles array")
.iter()
.map(|p| p["did"].as_str().unwrap().to_string())
.collect();
for fan in &fans {
assert!(got.contains(fan), "follower {fan} missing from {body:?}");
}
assert!(
!got.contains(&hub),
"the hub must not appear in its own follower list"
);
// Following — exactly one edge.
let body: Value = c
.get(format!("{base}/api/following"))
.query(&[("did", hub.as_str()), ("limit", "50")])
.send()
.await
.unwrap()
.json()
.await
.unwrap();
let following: Vec<String> = body["profiles"]
.as_array()
.unwrap()
.iter()
.map(|p| p["did"].as_str().unwrap().to_string())
.collect();
assert_eq!(following, vec![fans[0].clone()]);
// Never an empty or '@'-prefixed handle.
for p in body["profiles"].as_array().unwrap() {
let h = p["handle"].as_str().expect("handle is a string");
assert!(!h.is_empty());
assert!(!h.starts_with('@'));
}
// Pagination: limit=1 must page through all three followers
// without repeats.
let mut seen: Vec<String> = Vec::new();
let mut cursor: Option<String> = None;
for _ in 0..5 {
let mut req = c
.get(format!("{base}/api/followers"))
.query(&[("did", hub.as_str()), ("limit", "1")]);
if let Some(cur) = cursor.as_deref() {
req = req.query(&[("cursor", cur)]);
}
let body: Value = req.send().await.unwrap().json().await.unwrap();
for p in body["profiles"].as_array().unwrap() {
seen.push(p["did"].as_str().unwrap().to_string());
}
match body["cursor"].as_str() {
Some(c) => cursor = Some(c.to_string()),
None => break,
}
}
let unique: std::collections::HashSet<&String> = seen.iter().collect();
assert_eq!(unique.len(), seen.len(), "paged followers repeat: {seen:?}");
assert_eq!(seen.len(), 3, "paging lost a follower: {seen:?}");
// `did` is mandatory.
for path in ["/api/followers", "/api/following"] {
let resp = c
.get(format!("{base}{path}"))
.query(&[("did", "")])
.send()
.await
.unwrap();
assert_eq!(resp.status().as_u16(), 400);
}
}
// -- thread -----------------------------------------------------------------
/// `/api/thread` returns the ancestor chain above a post and its
/// direct replies, in both the query-param and the path spelling.
#[tokio::test]
async fn thread_returns_parents_and_replies() {
let base = appview_url();
let Some((c, _pool)) = ready().await else {
return;
};
let a = did_for_test("root");
let b = did_for_test("mid");
let d = did_for_test("leaf");
let root = seed_post(&c, &a, "root post").await;
let mid = seed_reply(&c, &b, &root, &root, "middle reply").await;
let leaf = seed_reply(&c, &d, &mid, &root, "leaf reply").await;
for url in [
format!("{base}/api/thread?uri={}", urlencoding(&mid)),
format!("{base}/api/thread/{mid}"),
] {
let resp = c.get(&url).send().await.unwrap();
assert_eq!(resp.status().as_u16(), 200, "GET {url}");
let body: Value = resp.json().await.unwrap();
assert_eq!(body["post"]["uri"], json!(mid), "GET {url}");
// One ancestor, and it's the root.
let parents = body["parents"].as_array().unwrap();
assert_eq!(parents.len(), 1, "GET {url}: {parents:?}");
assert_eq!(parents[0]["uri"], json!(root));
assert_eq!(body["root"]["uri"], json!(root));
// One direct reply: the leaf.
let replies = body["replies"].as_array().unwrap();
assert_eq!(replies.len(), 1, "GET {url}: {replies:?}");
assert_eq!(replies[0]["uri"], json!(leaf));
assert_eq!(body["like_count"], json!(0));
}
// The root's thread has no parents and one reply (the middle).
let body: Value = c
.get(format!("{base}/api/thread/{root}"))
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert_eq!(body["parents"].as_array().unwrap().len(), 0);
assert!(body["root"].is_null(), "a top-level post has no root ref");
let replies = body["replies"].as_array().unwrap();
assert_eq!(replies.len(), 1);
assert_eq!(replies[0]["uri"], json!(mid));
// An unknown URI is a 200 with a null post, not a 404 — the UI
// renders "not in index" from one field check.
let body: Value = c
.get(format!(
"{base}/api/thread/at://did:plc:nobody/app.twi.post/{}",
rkey()
))
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert!(body["post"].is_null());
assert_eq!(body["parents"].as_array().unwrap().len(), 0);
assert_eq!(body["replies"].as_array().unwrap().len(), 0);
// A missing `uri` is a 400.
let resp = c
.get(format!("{base}/api/thread"))
.send()
.await
.unwrap();
assert_eq!(resp.status().as_u16(), 400);
}
/// `/api/post/{uri}` must keep its historical shape after the thread
/// refactor — the Tauri client reads `thread.parent` / `thread.root`
/// and has no `parents` / `replies` fields.
#[tokio::test]
async fn post_by_uri_stays_backwards_compatible() {
let base = appview_url();
let Some((c, _pool)) = ready().await else {
return;
};
let a = did_for_test("compat_a");
let b = did_for_test("compat_b");
let root = seed_post(&c, &a, "compat root").await;
let mid = seed_reply(&c, &b, &root, &root, "compat reply").await;
seed_like(&c, &a, &mid).await;
let body: Value = c
.get(format!("{base}/api/post/{mid}"))
.query(&[("viewer_did", a.as_str())])
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert_eq!(body["post"]["uri"], json!(mid));
// The legacy nested shape: immediate parent + root, both hydrated.
assert_eq!(body["thread"]["parent"]["uri"], json!(root));
assert_eq!(body["thread"]["root"]["uri"], json!(root));
assert_eq!(body["like_count"], json!(1));
assert_eq!(body["repost_count"], json!(0));
assert_eq!(body["viewer_liked"], json!(true));
assert_eq!(body["viewer_reposted"], json!(false));
// The endpoint must NOT have grown the thread route's fields.
assert!(body.get("replies").is_none(), "unexpected `replies`: {body:?}");
assert!(body.get("parents").is_none(), "unexpected `parents`: {body:?}");
// And the two endpoints must agree about the parent / root.
let thread: Value = c
.get(format!("{base}/api/thread/{mid}"))
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert_eq!(
thread["parents"].as_array().unwrap().last().unwrap()["uri"],
body["thread"]["parent"]["uri"],
"/api/thread and /api/post disagree about the parent"
);
assert_eq!(thread["root"]["uri"], body["thread"]["root"]["uri"]);
}
/// Minimal percent-encoder for the `?uri=` form. Only the characters
/// an `at://did:plc:…/app.twi.post/<rkey>` URI can contain that a query
/// string would otherwise eat.
fn urlencoding(s: &str) -> String {
let mut out = String::with_capacity(s.len() * 2);
for ch in s.chars() {
match ch {
'A'..='Z' | 'a'..='z' | '0'..='9' | '-' | '_' | '.' | '~' => out.push(ch),
other => {
let mut buf = [0u8; 4];
for b in other.encode_utf8(&mut buf).as_bytes() {
out.push_str(&format!("%{b:02X}"));
}
}
}
}
out
}
migrations/appview/0008_notifications.sql
+113
View File
@@ -0,0 +1,113 @@
-- AppView database schema 0008: notifications + follow-list pagination.
--
-- Why
--
-- Phase 5 shipped the read API (timeline / profile / search / post) but
-- the client had no way to learn that *someone else* interacted with
-- the user: a like, a repost, a follow or a reply never produced a
-- durable record. The Tauri client's tray/notification path (Phase 7)
-- therefore had nothing to poll. This migration adds the table the
-- Jetstream indexer writes into and the read API serves from.
--
-- Table shape
-- id BIGSERIAL — monotonic tiebreaker for the keyset
-- cursor. The API's opaque cursor is
-- `(indexed_at, id)`, mirroring the
-- `(indexed_at, uri)` pair used by /api/timeline/home,
-- so the same `routes::cursor` encoder is reused.
-- recipient_did the user who should SEE the notification (the post
-- author for like/repost/reply, the followed user for
-- follow).
-- author_did the user who CAUSED it (the liker / reposter /
-- follower / replier).
-- kind 'like' | 'repost' | 'follow' | 'reply'. Enforced by
-- a CHECK rather than a Postgres ENUM so adding a
-- variant later is an ALTER ... DROP/ADD CONSTRAINT
-- instead of a type migration that locks every
-- dependent object.
-- subject_uri the post the notification is *about*. NULL for
-- 'follow' (there is no post). For 'like'/'repost'
-- it's the liked/reposted post (the recipient's own
-- post); for 'reply' it's the REPLY itself, because
-- the interesting text to show in the notification
-- list is what the replier wrote, not what the
-- recipient already knows they posted.
-- created_at the interaction's own `createdAt` from the AT record.
-- indexed_at when WE saw it. This is what the list is ordered by,
-- for the same reason the timeline orders by
-- `posts.indexed_at`: a client-supplied `created_at`
-- can be arbitrarily far in the past or future and
-- would break keyset pagination.
-- read_at NULL = unread. Set in bulk by
-- `POST /api/notifications/seen`.
--
-- Deliberately NO `CHECK (recipient_did <> author_did)`
-- ------------------------------------------------------
-- Self-interactions must not produce notifications, and the indexer
-- enforces that in two places (a pure `should_notify` guard in Rust
-- plus a `WHERE $1 <> $2` in the INSERT ... SELECT). A CHECK would
-- turn a future slip into a constraint violation that aborts the
-- surrounding like/repost transaction — i.e. it would lose the *like*
-- because of a notification bug. Filtering is strictly better than
-- failing here.
--
-- Idempotency
-- -----------
-- `notifications_dedupe_idx` is the unique constraint the indexer's
-- `ON CONFLICT ... DO NOTHING` infers. `subject_uri` is nullable and
-- NULLs never collide in a plain unique index, so the index is on
-- `COALESCE(subject_uri, '')` — that makes the two follow rows
-- (subject_uri IS NULL) for the same (recipient, author) pair collide
-- as intended.
--
-- Consequence worth knowing: unlike-then-relike (or unfollow-then-
-- refollow) does NOT produce a second notification, because the tuple
-- is identical. That is the desired behaviour — it makes notification
-- spam via toggling impossible — but it does mean a notification is
-- "once per (recipient, author, kind, subject)" for all time.
CREATE TABLE notifications (
id BIGSERIAL PRIMARY KEY,
recipient_did TEXT NOT NULL,
author_did TEXT NOT NULL,
kind TEXT NOT NULL
CHECK (kind IN ('like', 'repost', 'follow', 'reply')),
subject_uri TEXT,
created_at TIMESTAMPTZ NOT NULL,
indexed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
read_at TIMESTAMPTZ
);
-- Primary read path: `WHERE recipient_did = $1 ORDER BY indexed_at DESC,
-- id DESC`. The trailing `id DESC` makes the index cover the keyset
-- predicate `(indexed_at, id) < ($2, $3)` end-to-end, so a page fetch
-- never sorts.
CREATE INDEX notifications_recipient_indexed_at_idx
ON notifications (recipient_did, indexed_at DESC, id DESC);
-- Dedupe / ON CONFLICT target. See the "Idempotency" note above.
CREATE UNIQUE INDEX notifications_dedupe_idx
ON notifications (recipient_did, author_did, kind, COALESCE(subject_uri, ''));
-- `GET /api/notifications/count` is a hot poll from the client's tray
-- badge, so the unread slice gets its own partial index. It stays tiny
-- because rows leave it as soon as they're marked seen.
CREATE INDEX notifications_unread_idx
ON notifications (recipient_did)
WHERE read_at IS NULL;
-- =====================================================
-- follows: pagination indexes for the follower/following lists
-- =====================================================
--
-- `GET /api/followers` and `GET /api/following` page with the same
-- keyset scheme as the timeline: `(indexed_at, <other side's did>)`.
-- The pre-existing indexes cover only the equality half (the PK covers
-- `follower_did`, `follows_subject_idx` covers `subject_did`), which
-- leaves Postgres sorting the whole follower set on every page. These
-- two make both directions index-ordered.
CREATE INDEX IF NOT EXISTS follows_subject_indexed_at_idx
ON follows (subject_did, indexed_at DESC, follower_did DESC);
CREATE INDEX IF NOT EXISTS follows_follower_indexed_at_idx
ON follows (follower_did, indexed_at DESC, subject_did DESC);