feat(v2): add internal/storage package with MinIO + PocketBase clients and Store interface

scraper/internal/storage/store.go

@@ -0,0 +1,124 @@
+// Package storage defines the unified Store interface and helper types used by
+// the server and orchestrator.  Concrete implementations back the interface
+// with PocketBase (structured data) and MinIO (binary objects).
+package storage
+
+import (
+	"context"
+	"os"
+	"time"
+
+	"github.com/libnovel/scraper/internal/scraper"
+)
+
+// ─── Shared types ─────────────────────────────────────────────────────────────
+
+// ChapterInfo is a lightweight chapter descriptor (mirrors writer.ChapterInfo).
+type ChapterInfo struct {
+	Number int
+	Title  string
+	Date   string
+}
+
+// RankingItem represents a single entry in the novel ranking list.
+type RankingItem struct {
+	Rank      int      `json:"rank"`
+	Slug      string   `json:"slug"`
+	Title     string   `json:"title"`
+	Author    string   `json:"author,omitempty"`
+	Cover     string   `json:"cover,omitempty"`
+	Status    string   `json:"status,omitempty"`
+	Genres    []string `json:"genres,omitempty"`
+	SourceURL string   `json:"source_url,omitempty"`
+}
+
+// ReadingProgress holds a single user's reading position for one book.
+type ReadingProgress struct {
+	Slug      string    `json:"slug"`
+	Chapter   int       `json:"chapter"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+// AudioCacheEntry maps a (slug, chapter, voice, speed) tuple to a Kokoro
+// download filename so audio is not re-generated after a server restart.
+type AudioCacheEntry struct {
+	CacheKey string `json:"cache_key"`
+	Filename string `json:"filename"`
+}
+
+// ─── Store interface ──────────────────────────────────────────────────────────
+
+// Store is the single persistence abstraction consumed by the server and the
+// orchestrator.  Implementations may route calls to different backends
+// (PocketBase for structured records, MinIO for binary blobs).
+type Store interface {
+	// ── Book metadata ──────────────────────────────────────────────────────
+
+	// WriteMetadata upserts book metadata.
+	WriteMetadata(ctx context.Context, meta scraper.BookMeta) error
+	// ReadMetadata returns the metadata for slug. Returns (zero, false, nil)
+	// when the book is not found.
+	ReadMetadata(ctx context.Context, slug string) (scraper.BookMeta, bool, error)
+	// ListBooks returns all books, sorted alphabetically by title.
+	ListBooks(ctx context.Context) ([]scraper.BookMeta, error)
+	// LocalSlugs returns the set of slugs that have metadata stored.
+	LocalSlugs(ctx context.Context) (map[string]bool, error)
+	// MetadataMtime returns the Unix-second mtime of the metadata record, or 0.
+	MetadataMtime(ctx context.Context, slug string) int64
+
+	// ── Chapters (binary blobs in MinIO) ───────────────────────────────────
+
+	// ChapterExists returns true if the markdown file for the given ref exists.
+	ChapterExists(ctx context.Context, slug string, ref scraper.ChapterRef) bool
+	// WriteChapter stores the chapter markdown.
+	WriteChapter(ctx context.Context, slug string, chapter scraper.Chapter) error
+	// ReadChapter returns the raw markdown for chapter number n.
+	ReadChapter(ctx context.Context, slug string, n int) (string, error)
+	// ListChapters returns all stored chapters for slug, sorted by number.
+	ListChapters(ctx context.Context, slug string) ([]ChapterInfo, error)
+	// CountChapters returns the number of stored chapters for slug.
+	CountChapters(ctx context.Context, slug string) int
+
+	// ── Ranking ────────────────────────────────────────────────────────────
+
+	// WriteRanking persists the ranking list.
+	WriteRanking(ctx context.Context, items []RankingItem) error
+	// ReadRankingItems returns the stored ranking items.
+	ReadRankingItems(ctx context.Context) ([]RankingItem, error)
+	// RankingFileInfo returns os.FileInfo-like data for the ranking record.
+	// Returns (nil, nil) when no ranking has been stored yet.
+	RankingFileInfo(ctx context.Context) (os.FileInfo, error)
+
+	// ── Ranking page HTML cache ────────────────────────────────────────────
+
+	// WriteRankingPageCache stores raw HTML for a ranking page.
+	WriteRankingPageCache(ctx context.Context, page int, html string) error
+	// ReadRankingPageCache returns cached HTML for a ranking page, or "" on miss.
+	ReadRankingPageCache(ctx context.Context, page int) (string, error)
+	// RankingPageCacheInfo returns file-like info for a cached ranking page.
+	RankingPageCacheInfo(ctx context.Context, page int) (os.FileInfo, error)
+
+	// ── Audio cache ────────────────────────────────────────────────────────
+
+	// GetAudioCache returns the Kokoro filename for cacheKey, or ("", false).
+	GetAudioCache(ctx context.Context, cacheKey string) (string, bool)
+	// SetAudioCache persists a Kokoro filename for cacheKey.
+	SetAudioCache(ctx context.Context, cacheKey, filename string) error
+
+	// ── Reading progress ───────────────────────────────────────────────────
+
+	// GetProgress returns the reading progress for the given session ID and slug.
+	// Returns (zero, false) if no progress is recorded.
+	GetProgress(ctx context.Context, sessionID, slug string) (ReadingProgress, bool)
+	// SetProgress saves or updates reading progress.
+	SetProgress(ctx context.Context, sessionID string, p ReadingProgress) error
+	// AllProgress returns all progress entries for a session.
+	AllProgress(ctx context.Context, sessionID string) ([]ReadingProgress, error)
+	// DeleteProgress removes progress for a specific slug.
+	DeleteProgress(ctx context.Context, sessionID, slug string) error
+
+	// ── Audio object paths (MinIO) ─────────────────────────────────────────
+
+	// AudioObjectKey returns the MinIO object key for a cached audio file.
+	AudioObjectKey(slug string, n int, voice string, speed float64) string
+}