libnovel/scraper/internal/storage/store.go

// 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

	// ── Presigned URLs ─────────────────────────────────────────────────────

	// PresignChapter returns a presigned GET URL for a chapter markdown object.
	PresignChapter(ctx context.Context, slug string, n int, expires time.Duration) (string, error)

	// PresignAudio returns a presigned GET URL for an audio object.
	PresignAudio(ctx context.Context, key string, expires time.Duration) (string, error)
}