feat(history): write pinned_at to messages_by_room on pin/unpin

[chenjr0719]

Summary

Pin state was only stored on messages_by_id and pinned_messages_by_room, so channel history served from messages_by_room never populated pinnedAt — timeline pin indicators disappeared after a reload. This mirrors pinned_at onto messages_by_room end-to-end:

• Schema (3 locations): pinned_at TIMESTAMP added to the canonical schema in docs/cassandra_message_model.md, the local bootstrap docker-local/cassandra/init/10-table-messages_by_room.cql (ALTER, following the enc_payload precedent), and a new prod migration docker-local/cassandra/migrations/2026-06-pinnedat-messages-by-room.cql. The integration-test bootstrap schema in history-service/internal/cassrepo/integration_test.go was updated to match.
• Write: PinMessage / UnpinMessage gain a third statement in the existing UnloggedBatch:

  UPDATE messages_by_room SET pinned_at = ? WHERE room_id = ? AND bucket = ? AND created_at = ? AND message_id = ?

  (unpin sets pinned_at = null). The bucket is derived from msg.CreatedAt via the Repository's existing msgbucket.Sizer — the same sizer already used by the room-history read walk and the reactions mirror, so no new wiring.
• Read: pinned_at added to the room-history base column list; the struct already had the cql:"pinned_at" tag, so scanning works unchanged.

Upsert guard (tshow=false thread replies)

A thread-only reply (thread_parent_id set, tshow=false) has no messages_by_room row, and a Cassandra UPDATE is an upsert — an unguarded pin would create a ghost timeline row containing nothing but the primary key and pin column. The new hasRoomTimelineRow helper (msg.ThreadParentID == "" || msg.TShow) gates the third batch statement on both pin and unpin; this mirrors the routing convention already used by the reactions mirror in cassrepo/reactions.go. Covered by TestRepository_PinThreadOnlyReply_NoGhostRoomRow.

The rejected alternative was accept-and-document (let the ghost row exist; history reads would still never surface it as a real message only if filtered) — rejected because ghost rows would surface in room-history scans as empty messages and pollute the timeline.

Scope

pinned_by is deliberately excluded — it is an explicit open question on #298, not approved. Only pinned_at is mirrored; richer pin metadata remains a point lookup on messages_by_id. Adding pinned_by later is a cheap independent ALTER + batch-statement change.

Rows pinned before the migration keep a null pinned_at on messages_by_room until re-pinned; a backfill recipe is noted in the migration file header.

Test evidence

• go build ./... and go vet -tags=integration ./history-service/... clean.
• go test ./history-service/... green (includes new unit tests for the guard helper).
• Full Cassandra-backed integration suite green: go test -tags=integration ./history-service/internal/cassrepo/ → ok ... 360.7s, including:
  • extended TestRepository_PinAndUnpinMessage: room row's pinned_at mirrors the pin time, room-history GetMessagesBefore surfaces PinnedAt, unpin clears it while the timeline row survives;
  • new TestRepository_PinThreadOnlyReply_NoGhostRoomRow: no ghost row on pin or unpin, while messages_by_id + pinned_messages_by_room still record the pin.

Refs #298 (kept open intentionally — the pinned_by open question on the issue is undecided; closing is the maintainer's call once that's resolved).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Pinned messages now appear in channel message history and timeline loads alongside existing pin-list functionality.

• Documentation

  • Updated API documentation to clarify pinned message field behavior in timeline retrieval.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b6f7a5ab-d55e-4c41-9880-2734218d2dad

📥 Commits

Reviewing files that changed from the base of the PR and between 723d33e and 426d227.

📒 Files selected for processing (9)

• docker-local/cassandra/init/10-table-messages_by_room.cql
• docker-local/cassandra/migrations/2026-06-pinnedat-messages-by-room.cql
• docs/cassandra_message_model.md
• docs/client-api.md
• history-service/internal/cassrepo/integration_test.go
• history-service/internal/cassrepo/messages_by_room.go
• history-service/internal/cassrepo/pin.go
• history-service/internal/cassrepo/pin_integration_test.go
• history-service/internal/cassrepo/pin_test.go

---

📝 Walkthrough

Walkthrough

Adds a pinned_at TIMESTAMP column to chat.messages_by_room via init script and a versioned migration. The baseColumns SELECT projection is updated to include the new column. PinMessage and UnpinMessage conditionally mirror pin state into messages_by_room using a new hasRoomTimelineRow helper to avoid ghost rows for thread-only replies. Unit and integration tests cover the new logic, and documentation is updated.

Changes

pinned_at mirror into messages_by_room

Layer / File(s)	Summary
Schema: pinned_at column docker-local/cassandra/init/10-table-messages_by_room.cql, docker-local/cassandra/migrations/2026-06-pinnedat-messages-by-room.cql, history-service/internal/cassrepo/integration_test.go	Adds pinned_at TIMESTAMP to chat.messages_by_room in the local init CQL, the versioned migration file, and the integration test setupCassandra statement.
Read path: baseColumns projection history-service/internal/cassrepo/messages_by_room.go	Extends baseColumns SELECT list to include pinned_at after updated_at, propagating the column to all existing room-timeline queries.
Write path: conditional pin/unpin mirror history-service/internal/cassrepo/pin.go	Introduces pinMsgByRoom/unpinMsgByRoom CQL statements, hasRoomTimelineRow gate, and pinBatchTables for error reporting; PinMessage and UnpinMessage conditionally include the messages_by_room update in their unlogged batch.
Unit tests: helpers history-service/internal/cassrepo/pin_test.go	Table-driven tests for hasRoomTimelineRow (channel, TShow reply, thread-only reply) and pinBatchTables (both boolean branches).
Integration tests: mirror correctness and ghost-row prevention history-service/internal/cassrepo/pin_integration_test.go	Adds roomRowPinnedAt helper; extends TestRepository_PinAndUnpinMessage to assert the messages_by_room.pinned_at mirror; adds TestRepository_PinThreadOnlyReply_NoGhostRoomRow to confirm no ghost row is created for thread-only replies.
Documentation docs/cassandra_message_model.md, docs/client-api.md	Documents pinned_at in the messages_by_room schema reference and clarifies that history/timeline loads return pinnedAt via the mirror column.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant PinMessage
  participant hasRoomTimelineRow
  participant CassandraBatch

  Client->>PinMessage: PinMessage(msg)
  PinMessage->>hasRoomTimelineRow: check msg.ThreadParent & msg.TShow
  hasRoomTimelineRow-->>PinMessage: withRoomRow (bool)
  PinMessage->>CassandraBatch: UPDATE messages_by_id SET pinned_at
  PinMessage->>CassandraBatch: INSERT pinned_messages_by_room
  alt withRoomRow == true
    PinMessage->>CassandraBatch: UPDATE messages_by_room SET pinned_at
  end
  CassandraBatch-->>Client: nil or error(pinBatchTables(withRoomRow))

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Should also set pinnedAt on messages_by_room table #298: This PR directly implements the requirement from that issue — adding pinned_at to messages_by_room with conditional writes gated by hasRoomTimelineRow, including the thread-only reply edge case.

Possibly related PRs

• hmchangw/chat#143: Modifies the same baseColumns variable in messages_by_room.go; this PR adds pinned_at to that projection.
• hmchangw/chat#205: Implements the original pin/unpin handlers and Cassandra persistence that this PR extends with the messages_by_room mirror.
• hmchangw/chat#22: Establishes the Cassandra message schema docs that this PR extends with the pinned_at column entry.

Suggested labels

ready

Suggested reviewers

• ngangwar962
• mliu33

Poem

🐇 Hop hop, a column appears,
pinned_at now lives in messages_by_room!
No ghost rows for thread replies, my dears,
hasRoomTimelineRow sweeps out the gloom.
The timeline shines with every pin —
A tidy schema tucked neatly in! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly matches the main change: adding pinned_at field writes to messages_by_room during pin/unpin operations, which is the core feature of this PR.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mliu33]

Great work, thanks!