《互联网产品的客户端架构·内容、社交与实时互动》9.1 关注、互关与关系缓存

// file: src/relations/follow-cache.ts
// tier: L2
// verify: node --test --test-concurrency=1 test/relations/follow-cache.test.ts
export type Edge = "none" | "following" | "followedBy" | "mutual";

export type FollowAction = "follow" | "unfollow";

export type DmAccess = "granted" | "hint" | "denied";

export type Clock = () => number;

interface Entry {
  edge: Edge;
  fetchedAt: number;
}

interface PendingMutation {
  revision: number;
  previous: Entry | null;
  action: FollowAction;
}

export interface ReadResult {
  edge: Edge;
  stale: boolean;
  known: boolean;
}

export interface MutationResult {
  revision: number;
  edge: Edge;
  invalidates: string[];
}

// 关注方向只有两种：我关注对方、对方关注我。互关是两个方向的交集。
export function nextEdge(current: Edge, action: FollowAction): Edge {
  if (action === "follow") {
    return current === "followedBy" || current === "mutual" ? "mutual" : "following";
  }
  return current === "mutual" ? "followedBy" : "none";
}

export function invalidationKeys(
  userId: string,
  action: FollowAction,
  previous: Edge,
  next: Edge,
): string[] {
  const keys = ["lists:following", "feed:home", "lists:suggestions", `profile:${userId}`];
  if (previous === "mutual" || next === "mutual") {
    keys.push("lists:mutual", `dm:hint:${userId}`);
  }
  // dm:permission 故意不在这里：私信权限必须由服务端下发的能力决定，
  // 关系缓存只能影响提示，不能成为授权依据。
  return keys;
}

// 私信入口只接受三种结果：服务端明确允许、服务端明确拒绝、仅有关系缓存提示。
// 没有 grant 时，互关最多得到 hint，不能直接打开输入框。
export function dmAccess(edge: Edge, serverGrant: boolean | null): DmAccess {
  if (serverGrant === true) return "granted";
  if (serverGrant === false) return "denied";
  return edge === "mutual" ? "hint" : "denied";
}

export class FollowCache {
  #entries = new Map<string, Entry>();
  #revisions = new Map<string, number>();
  #pending = new Map<string, PendingMutation>();
  #now: Clock;
  #ttlMs: number;

  constructor(now: Clock = () => Date.now(), ttlMs = 60_000) {
    if (!Number.isFinite(ttlMs) || ttlMs < 0) throw new Error("ttlMs 必须是非负数");
    this.#now = now;
    this.#ttlMs = ttlMs;
  }

  revision(userId: string): number {
    return this.#revisions.get(userId) ?? 0;
  }

  read(userId: string): ReadResult {
    const entry = this.#entries.get(userId);
    if (!entry) return { edge: "none", stale: true, known: false };
    return {
      edge: entry.edge,
      stale: this.#now() - entry.fetchedAt > this.#ttlMs,
      known: true,
    };
  }

  // revisionAtRequest 由调用方在发请求时读取。晚到的旧快照不能覆盖
  // 已经发生的乐观更新，因此 revision 不相等时直接丢弃。
  writeSnapshot(userId: string, edge: Edge, revisionAtRequest: number): boolean {
    if (revisionAtRequest !== this.revision(userId)) return false;
    this.#entries.set(userId, { edge, fetchedAt: this.#now() });
    return true;
  }

  follow(userId: string): MutationResult {
    return this.#mutate(userId, "follow");
  }

  unfollow(userId: string): MutationResult {
    return this.#mutate(userId, "unfollow");
  }

  commit(userId: string, revision: number, edge: Edge): boolean {
    if (revision !== this.revision(userId)) return false;
    this.#pending.delete(userId);
    this.#entries.set(userId, { edge, fetchedAt: this.#now() });
    return true;
  }

  // 回滚恢复的是「变更前那条缓存」而不只是 edge，包括它原来的 fetchedAt，
  // 这样回滚后的数据不会假装成刚拉取过的新鲜数据。
  rollback(userId: string, revision: number): Edge | null {
    if (revision !== this.revision(userId)) return null;
    const pending = this.#pending.get(userId);
    if (!pending) return null;
    this.#pending.delete(userId);
    if (pending.previous) this.#entries.set(userId, pending.previous);
    else this.#entries.delete(userId);
    return pending.previous?.edge ?? "none";
  }

  isPending(userId: string): boolean {
    return this.#pending.has(userId);
  }

  #mutate(userId: string, action: FollowAction): MutationResult {
    const previous = this.#entries.get(userId) ?? null;
    const previousEdge = previous?.edge ?? "none";
    const edge = nextEdge(previousEdge, action);
    const revision = this.revision(userId) + 1;
    this.#revisions.set(userId, revision);
    this.#pending.set(userId, { revision, previous, action });
    this.#entries.set(userId, { edge, fetchedAt: this.#now() });
    return {
      revision,
      edge,
      invalidates: invalidationKeys(userId, action, previousEdge, edge),
    };
  }
}

$ node --test --test-concurrency=1 test/relations/follow-cache.test.ts
✔ 未知关系返回 none，并标记为需要拉取 (0.907625ms)
✔ 快照在 TTL 内新鲜，超时后保留 edge 但标记 stale (0.497958ms)
✔ 关注陌生人立即变为 following，并失效关注列表与主页 (0.205958ms)
✔ 对方已关注时，关注动作直接得到 mutual (0.078167ms)
✔ 取关互关对象后回落到 followedBy，并失效互关列表 (0.088583ms)
✔ 失败回滚恢复变更前缓存，未知关系回滚后重新变为未知 (0.12325ms)
✔ 晚到的旧快照被 revision 拦截，提交后的服务端结果才生效 (0.095ms)
✔ 互关缓存只能给私信提示，服务端明确拒绝优先 (0.057417ms)
ℹ tests 8
ℹ suites 0
ℹ pass 8
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 138.552333