feat(backend): give every Bookmark an owner (Reader table) (#22)

A readers table appears, keyed by Discord user ID and carrying the SHA-256 of the owner's userscript token (the global API token today). Startup seeds exactly one Reader from OWNER_DISCORD_ID, idempotently, and a run-once migration (0004, version-table-gated) attaches existing bookmarks to it before reshaping: the surrogate key column is dropped and bookmarks are keyed (reader_id, site, series_id) with an FK to readers ON DELETE CASCADE, so a duplicate bookmark for one Reader and Series is impossible at the database level. Every store read and write is now scoped to the reader it names; handlers act as the seeded owner while the global token remains the only credential. Authentication and the wire format are untouched: the flat JSON still carries key/site/series_id, with key derived on read. OWNER_DISCORD_ID is a new required env var (compose + docs updated).
2026-08-08 07:59:40 +07:00
parent 984965ed9f
commit 3f7664ef9b
15 changed files with 553 additions and 164 deletions
@@ -159,7 +159,7 @@ var migrations embed.FS
 // compile-time constant; every request value is bound as a parameter. The
 // series-owned fields are joined in from the series table, in scanBookmark
 // order, so the flat Bookmark reads back whole despite the split (ADR-0004).
-const bookmarkColumns = `b.key, b.site, b.series_id, s.title, s.series_url, s.cover,
+const bookmarkColumns = `b.site, b.series_id, s.title, s.series_url, s.cover,
 	b.last_chapter, b.last_chapter_num, b.last_chapter_url,
 	b.favorite, s.latest_chapter, s.latest_chapter_num, b.updated_at, b.status, s.kind`

@@ -169,32 +169,91 @@ const bookmarkColumns = `b.key, b.site, b.series_id, s.title, s.series_url, s.co
 const seriesColumns = `s.site, s.series_id, s.title, s.series_url, s.cover,
 	s.kind, s.latest_chapter, s.latest_chapter_num, s.latest_checked_at`

+// Owner is the person running the service: the first Reader, and the only one
+// until registration exists. The seed makes sure exactly one readers row
+// matches their Discord ID, carrying the SHA-256 of their userscript token —
+// which today is the global API token.
+type Owner struct {
+	DiscordID string
+	// TokenHash is the SHA-256 of the userscript token; the array shape makes
+	// it a compile error to store anything that is not a hash.
+	TokenHash [32]byte
+}
+
 // Store is the Postgres-backed bookmark store.
 type Store struct {
 	db *sql.DB
+	// ownerID is the seeded owner Reader (issue #22). Authentication is still
+	// the single global token, so every request acts as this Reader; the store
+	// methods take the id explicitly so the scoping survives per-Reader auth.
+	ownerID int64
 }

+// OwnerID returns the seeded owner Reader's id — the Reader every request
+// acts as while the global token is still the only credential.
+func (s *Store) OwnerID() int64 { return s.ownerID }
+
+// readersMigration is the version that creates the readers table. The owner
+// seed runs between two migrate passes, so that the run-once migration which
+// attaches existing bookmarks (0004) finds the owner row.
+const readersMigration = 3
+
+// allMigrations is the migrate() cap that applies every pending version.
+const allMigrations = 0
+
 // Open connects to Postgres at url — a libpq connection URL such as
-// "postgres://user:pass@host:5432/bookmarks?sslmode=disable" — and brings its
-// schema up to date.
-func Open(url string) (*Store, error) {
+// "postgres://user:pass@host:5432/bookmarks?sslmode=disable" — brings its
+// schema up to date, and seeds the owner Reader.
+func Open(url string, owner Owner) (*Store, error) {
 	db, err := sql.Open("pgx", url)
 	if err != nil {
 		return nil, fmt.Errorf("open postgres: %w", err)
 	}
-	if err := migrate(db); err != nil {
+	// Schema runs in two passes with the seed between: 0003 creates the
+	// readers table, the owner row must exist before 0004 attaches the
+	// existing bookmarks to it. Anything past 0004 is applied by the second
+	// pass.
+	if err := migrate(db, readersMigration); err != nil {
+		db.Close()
+		return nil, fmt.Errorf("migrate schema: %w", err)
+	}
+	if err := seedOwner(db, owner); err != nil {
+		db.Close()
+		return nil, fmt.Errorf("seed owner: %w", err)
+	}
+	if err := migrate(db, allMigrations); err != nil {
 		db.Close()
 		return nil, fmt.Errorf("migrate: %w", err)
 	}
-	return &Store{db: db}, nil
+	var ownerID int64
+	if err := db.QueryRow(
+		`SELECT id FROM readers WHERE discord_id = $1`, owner.DiscordID).Scan(&ownerID); err != nil {
+		db.Close()
+		return nil, fmt.Errorf("resolve owner: %w", err)
+	}
+	return &Store{db: db, ownerID: ownerID}, nil
+}
+
+// seedOwner makes sure the configured owner exists as exactly one readers row,
+// and keeps its token hash current on every start: rotating the userscript
+// token must refresh the hash, or the stored credential goes stale.
+func seedOwner(db *sql.DB, o Owner) error {
+	if _, err := db.Exec(`
+		INSERT INTO readers (discord_id, token_sha256) VALUES ($1, $2)
+		ON CONFLICT (discord_id) DO UPDATE SET token_sha256 = EXCLUDED.token_sha256`,
+		o.DiscordID, o.TokenHash[:]); err != nil {
+		return fmt.Errorf("seed owner: %w", err)
+	}
+	return nil
 }

 // migrate applies every embedded migration this database has not recorded, in
-// filename order, each in its own transaction. Files are named
-// "<version>_<name>.sql" and are append-only: editing an applied file changes
-// nothing, because schema_migrations is how a database remembers what it ran.
-// Runs on every start and is a no-op once current.
-func migrate(db *sql.DB) error {
+// filename order, each in its own transaction. upto caps the highest version
+// applied; 0 means all. Files are named "<version>_<name>.sql" and are
+// append-only: editing an applied file changes nothing, because
+// schema_migrations is how a database remembers what it ran. Runs on every
+// start and is a no-op once current.
+func migrate(db *sql.DB, upto int64) error {
 	if _, err := db.Exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
 		version    bigint PRIMARY KEY,
 		applied_at timestamptz NOT NULL DEFAULT now())`); err != nil {
@@ -212,6 +271,9 @@ func migrate(db *sql.DB) error {
 		if err != nil {
 			return fmt.Errorf("migration %q: filename must start with a version number", name)
 		}
+		if upto > 0 && version > upto {
+			continue
+		}
 		body, err := migrations.ReadFile(name)
 		if err != nil {
 			return err
@@ -261,7 +323,7 @@ func scanBookmark(scan func(...any) error) (Bookmark, error) {
 		latestChapterNum sql.NullFloat64
 	)
 	if err := scan(
-		&b.Key, &b.Site, &b.SeriesID, &b.Title, &b.SeriesURL, &b.Cover,
+		&b.Site, &b.SeriesID, &b.Title, &b.SeriesURL, &b.Cover,
 		&b.LastChapter, &b.LastChapterNum, &b.LastChapterURL,
 		&b.Favorite, &b.LatestChapter, &latestChapterNum, &b.UpdatedAt, &b.Status, &b.Kind,
 	); err != nil {
@@ -270,6 +332,9 @@ func scanBookmark(scan func(...any) error) (Bookmark, error) {
 	if latestChapterNum.Valid {
 		b.LatestChapterNum = &latestChapterNum.Float64
 	}
+	// The wire identity is derived: there is no stored key column, the
+	// bookmark is keyed (reader_id, site, series_id) (issue #22).
+	b.Key = b.Site + ":" + b.SeriesID
 	// An unrecognised bucket (a hand-edited row) would leave the row in no list
 	// at all, so anything outside the three known buckets reads as the default
 	// rather than being passed through.
@@ -303,13 +368,15 @@ func scanSeries(scan func(...any) error) (Series, error) {
 // Close releases the underlying database handle.
 func (s *Store) Close() error { return s.db.Close() }

-// List returns every bookmark, newest activity first. Series-owned fields are
-// joined in, so each Bookmark reads back whole and flat (ADR-0004).
-func (s *Store) List() ([]Bookmark, error) {
-	rows, err := s.db.Query(`SELECT ` + bookmarkColumns + `
+// List returns every bookmark of one reader, newest activity first.
+// Series-owned fields are joined in, so each Bookmark reads back whole and
+// flat (ADR-0004).
+func (s *Store) List(readerID int64) ([]Bookmark, error) {
+	rows, err := s.db.Query(`SELECT `+bookmarkColumns+`
 		FROM bookmarks b
 		JOIN series s ON s.site = b.site AND s.series_id = b.series_id
-		ORDER BY b.updated_at DESC`)
+		WHERE b.reader_id = $1
+		ORDER BY b.updated_at DESC`, readerID)
 	if err != nil {
 		return nil, fmt.Errorf("query bookmarks: %w", err)
 	}
@@ -326,14 +393,19 @@ func (s *Store) List() ([]Bookmark, error) {
 	return out, rows.Err()
 }

-// Get returns one bookmark by key. A missing key is not an error: ok is false
-// and err is nil. UI mutations read-modify-write through this so they preserve
-// the fields they do not touch.
-func (s *Store) Get(key string) (Bookmark, bool, error) {
+// Get returns one bookmark of one reader by key. A missing key is not an
+// error: ok is false and err is nil. UI mutations read-modify-write through
+// this so they preserve the fields they do not touch.
+func (s *Store) Get(readerID int64, key string) (Bookmark, bool, error) {
+	site, seriesID, ok := strings.Cut(key, ":")
+	if !ok {
+		return Bookmark{}, false, nil
+	}
 	b, err := scanBookmark(s.db.QueryRow(
 		`SELECT `+bookmarkColumns+` FROM bookmarks b
 		JOIN series s ON s.site = b.site AND s.series_id = b.series_id
-		WHERE b.key = $1`, key).Scan)
+		WHERE b.reader_id = $1 AND b.site = $2 AND b.series_id = $3`,
+		readerID, site, seriesID).Scan)
 	if errors.Is(err, sql.ErrNoRows) {
 		return Bookmark{}, false, nil
 	}
@@ -343,9 +415,11 @@ func (s *Store) Get(key string) (Bookmark, bool, error) {
 	return b, true, nil
 }

-// Upsert inserts or replaces a bookmark by key (last-write-wins) and returns
-// the row as actually stored — one flat object with the series-owned fields
-// joined in, exactly as GET reports it (ADR-0004).
+// Upsert inserts or replaces one reader's bookmark by key (last-write-wins)
+// and returns the row as actually stored — one flat object with the
+// series-owned fields joined in, exactly as GET reports it (ADR-0004). A
+// bookmark is keyed (reader_id, site, series_id), so the same key upserts two
+// independent rows for two readers.
 //
 // The flat body is decomposed across two tables in one transaction. The series
 // row is written first (the bookmarks FK requires it to exist), then the
@@ -359,7 +433,7 @@ func (s *Store) Get(key string) (Bookmark, bool, error) {
 // order their list by updated_at, so favoriting a series or recording a newly
 // published chapter must not disturb that order — only real reading progress
 // does. Callers must therefore use the returned bookmark, not the argument.
-func (s *Store) Upsert(b Bookmark) (Bookmark, error) {
+func (s *Store) Upsert(readerID int64, b Bookmark) (Bookmark, error) {
 	tx, err := s.db.Begin()
 	if err != nil {
 		return Bookmark{}, fmt.Errorf("begin %q: %w", b.Key, err)
@@ -404,13 +478,12 @@ func (s *Store) Upsert(b Bookmark) (Bookmark, error) {
 	// stored row and excluded.* is the incoming one; a brand-new key never
 	// reaches this clause, so it keeps the fresh timestamp from VALUES.
 	if _, err := tx.Exec(`
-		INSERT INTO bookmarks (key, site, series_id, last_chapter, last_chapter_num,
+		INSERT INTO bookmarks (reader_id, site, series_id, last_chapter, last_chapter_num,
 		                       last_chapter_url, favorite, status, updated_at)
 		VALUES ($1, $2, $3, $4, $5, $6, $7,
-		        COALESCE(NULLIF($8::text, ''), (SELECT status FROM bookmarks WHERE key = $1), 'reading'),
+		        COALESCE(NULLIF($8::text, ''), (SELECT status FROM bookmarks WHERE reader_id = $1 AND site = $2 AND series_id = $3), 'reading'),
 		        $9)
-		ON CONFLICT (key) DO UPDATE SET
-		  site=excluded.site, series_id=excluded.series_id,
+		ON CONFLICT (reader_id, site, series_id) DO UPDATE SET
 		  last_chapter=excluded.last_chapter, last_chapter_num=excluded.last_chapter_num,
 		  last_chapter_url=excluded.last_chapter_url,
 		  favorite=excluded.favorite,
@@ -420,7 +493,7 @@ func (s *Store) Upsert(b Bookmark) (Bookmark, error) {
 		    THEN excluded.updated_at
 		    ELSE bookmarks.updated_at
 		  END`,
-		b.Key, b.Site, b.SeriesID,
+		readerID, b.Site, b.SeriesID,
 		b.LastChapter, b.LastChapterNum, b.LastChapterURL,
 		b.Favorite, b.Status, b.UpdatedAt); err != nil {
 		return Bookmark{}, fmt.Errorf("upsert %q: %w", b.Key, err)
@@ -429,7 +502,8 @@ func (s *Store) Upsert(b Bookmark) (Bookmark, error) {
 	stored, err := scanBookmark(tx.QueryRow(
 		`SELECT `+bookmarkColumns+` FROM bookmarks b
 		JOIN series s ON s.site = b.site AND s.series_id = b.series_id
-		WHERE b.key = $1`, b.Key).Scan)
+		WHERE b.reader_id = $1 AND b.site = $2 AND b.series_id = $3`,
+		readerID, b.Site, b.SeriesID).Scan)
 	if err != nil {
 		return Bookmark{}, fmt.Errorf("read back %q: %w", b.Key, err)
 	}
@@ -439,9 +513,16 @@ func (s *Store) Upsert(b Bookmark) (Bookmark, error) {
 	return stored, nil
 }

-// Delete removes a bookmark by key. Deleting a missing key is not an error.
-func (s *Store) Delete(key string) error {
-	if _, err := s.db.Exec(`DELETE FROM bookmarks WHERE key = $1`, key); err != nil {
+// Delete removes one reader's bookmark by key. Deleting a missing key is not
+// an error.
+func (s *Store) Delete(readerID int64, key string) error {
+	site, seriesID, ok := strings.Cut(key, ":")
+	if !ok {
+		return nil
+	}
+	if _, err := s.db.Exec(
+		`DELETE FROM bookmarks WHERE reader_id = $1 AND site = $2 AND series_id = $3`,
+		readerID, site, seriesID); err != nil {
 		return fmt.Errorf("delete %q: %w", key, err)
 	}
 	return nil
@@ -466,14 +547,14 @@ func (s *Store) Delete(key string) error {
 // series is up to is the whole reason for archiving instead of deleting.
 // A series with no bookmarks at all never appears: the join excludes it.
 func (s *Store) DueForLatestCheck(cutoffMs int64, limit int) ([]Series, error) {
-	rows, err := s.db.Query(`SELECT `+seriesColumns+`, COUNT(b.key) AS reader_count
+	rows, err := s.db.Query(`SELECT `+seriesColumns+`, COUNT(*) AS reader_count
 		FROM series s
 		JOIN bookmarks b ON b.site = s.site AND b.series_id = s.series_id
 		WHERE s.series_url <> ''
 		  AND s.latest_checked_at <= $1
 		GROUP BY s.site, s.series_id, s.title, s.series_url, s.cover,
 		         s.kind, s.latest_chapter, s.latest_chapter_num, s.latest_checked_at
-		HAVING COUNT(b.key) FILTER (WHERE b.status <> 'finished') > 0
+		HAVING COUNT(*) FILTER (WHERE b.status <> 'finished') > 0
 		ORDER BY reader_count DESC, s.latest_checked_at ASC
 		LIMIT $2`, cutoffMs, limit)
 	if err != nil {