4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2a94921e88
ReadViewSDK/.planning/phases/08-pagination-quality-cache-performance/08-01-PLAN.md

11 KiB
Raw Blame History

phase plan type wave depends_on files_modified autonomous requirements must_haves
08-pagination-quality-cache-performance 01 execute 1
Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookCache.swift
true
QUAL-01
truths artifacts key_links
Same bookID + fontSize + lineHeightMultiple + contentInsets produces same cache key
Cache hit returns stored RDEPUBTextBook without calling build()
Cache miss falls through to build and stores result
Schema version bump invalidates all cached entries
Changing any layout parameter produces a different cache key
path provides contains min_lines
Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookCache.swift Disk-persistent RDEPUBTextBook cache with SHA256 key generation class RDEPUBTextBookCache 100
from to via pattern
RDEPUBTextBookCache.swift Library/Caches/RDEPUBTextBookCache/ FileManager.default.urls(for: .cachesDirectory) cachesDirectory
Create a disk-persistent cache for RDEPUBTextBook objects keyed by layout parameters (bookID + fontSize + lineHeightMultiple + contentInsets + pageSize), using NSKeyedArchiver for serialization and SHA256 for cache key hashing. This eliminates redundant full pagination of the same book under identical layout configuration.

Purpose: QUAL-01 requires that the same viewport and typography configuration does not trigger redundant full pagination. The cache stores complete RDEPUBTextBook objects to disk so repeated opens with the same parameters skip the entire build pipeline.

Output: A new RDEPUBTextBookCache.swift file providing load/save/invalidate operations.

<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/08-pagination-quality-cache-performance/08-CONTEXT.md @.planning/phases/08-pagination-quality-cache-performance/08-RESEARCH.md @.planning/phases/08-pagination-quality-cache-performance/08-PATTERNS.md @Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift @Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift @Sources/RDReaderView/EPUBCore/RDEPUBParser+Archive.swift

From RDEPUBTextBookBuilder.swift:

public struct RDEPUBTextBook: Equatable {
    public var chapters: [RDEPUBTextChapter]
    public var pages: [RDEPUBTextPage]
    public init(chapters: [RDEPUBTextChapter], pages: [RDEPUBTextPage])
}

public struct RDEPUBTextChapter: Equatable {
    public var chapterIndex: Int
    public var spineIndex: Int
    public var href: String
    public var title: String
    public var attributedContent: NSAttributedString
    public var fragmentOffsets: [String: Int]
    public var pageBreakReasons: [RDEPUBTextPageBreakReason]
    public var pages: [RDEPUBTextPage]
}

public struct RDEPUBTextPage: Equatable {
    public var absolutePageIndex: Int
    public var chapterIndex: Int
    public var spineIndex: Int
    public var href: String
    public var chapterTitle: String
    public var pageIndexInChapter: Int
    public var totalPagesInChapter: Int
    public var content: NSAttributedString
    public var contentRange: NSRange
    public var pageStartOffset: Int
    public var pageEndOffset: Int
    public var metadata: RDEPUBTextPageMetadata
}

From RDEPUBReadingModels.swift lines 183-215:

public struct RDEPUBTextPageMetadata: Codable, Equatable {
    public var breakReason: RDEPUBTextPageBreakReason
    public var blockRange: NSRange?
    public var attachmentRanges: [NSRange]
    public var attachmentKinds: [RDEPUBTextAttachmentKind]
    public var blockKinds: [RDEPUBTextBlockKind]
    public var semanticHints: [RDEPUBTextSemanticHint]
    public var attachmentPlacements: [RDEPUBTextAttachmentPlacement]
    public var trailingFragmentID: String?
    public var diagnostics: [String]
}

// Cache directory pattern:
let baseURL = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first?
    .appendingPathComponent("RDEPUBTextBookCache", isDirectory: true)
    ?? FileManager.default.temporaryDirectory.appendingPathComponent("RDEPUBTextBookCache", isDirectory: true)
try FileManager.default.createDirectory(at: cacheDirectory, withIntermediateDirectories: true)

// NSAttributedString supports NSCoding — serialize via NSKeyedArchiver
let data = try NSKeyedArchiver.archivedData(withRootObject: object, requiringSecureCoding: false)
let object = try NSKeyedUnarchiver.unarchivedObject(ofClass: SomeClass.self, from: data)
Task 1: Create RDEPUBTextBookCache class with cache key generation and disk I/O Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookCache.swift Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookBuilder.swift Sources/RDReaderView/EPUBCore/RDEPUBReadingModels.swift Sources/RDReaderView/EPUBCore/RDEPUBParser+Archive.swift Create a new file `Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookCache.swift` implementing the complete cache system.

RDEPUBTextBookCache class (per D-01):

  1. Cache key generation using CryptoKit SHA256:

    • Key inputs: bookID: String, fontSize: CGFloat, lineHeightMultiple: CGFloat, contentInsets: UIEdgeInsets, pageSize: CGSize, schemaVersion: Int
    • Format: SHA256("\(bookID)_\(fontSize)_\(lineHeightMultiple)_\(contentInsets.top)_\(contentInsets.left)_\(contentInsets.bottom)_\(contentInsets.right)_\(pageSize.width)_\(pageSize.height)_v\(schemaVersion)")
    • Output: hex-encoded string + ".cache" extension for use as filename
    • Reference WXRead pattern: WRChapterPageCount.currentCacheKeyWithBookId: encodes bookId + fontSize + lineSpacing + pageWidth + pageHeight

  2. Thread safety using a serial DispatchQueue:

    • private let queue = DispatchQueue(label: "com.rdreader.textbookcache", qos: .utility)
    • All read/write operations wrapped in queue.sync { }

  3. Storage directory: Library/Caches/RDEPUBTextBookCache/ using FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask), with fallback to temporaryDirectory. Create directory with createDirectory(at:withIntermediateDirectories:) on init.

  4. Serialization strategy using NSKeyedArchiver:

    • Since RDEPUBTextBook is NOT NSCoding-conformant, create NSCoding wrapper classes for serialization:
      • RDEPUBTextBookArchive: NSObject, NSCoding — stores array of chapter archives
      • RDEPUBTextChapterArchive: NSObject, NSCoding — stores attributedContent (via NSKeyedArchiver), page data arrays
      • RDEPUBTextPageArchive: NSObject, NSCoding — stores all RDEPUBTextPage fields
      • RDEPUBTextPageMetadataArchive: NSObject, NSCoding — stores RDEPUBTextPageMetadata fields
    • For NSRange fields: encode as {location: Int, length: Int} pairs
    • For enums: encode as rawValue strings
    • Wrap all NSCoding classes as private or internal (not public API)

  5. Public API:

    • public init(subdirectory: String = "RDEPUBTextBookCache") — sets up cache directory
    • public func cacheKey(bookID: String, fontSize: CGFloat, lineHeightMultiple: CGFloat, contentInsets: UIEdgeInsets, pageSize: CGSize) -> String — returns SHA256 hash filename
    • public func load(key: String) -> RDEPUBTextBook? — deserializes from disk, returns nil on miss or error
    • public func save(_ book: RDEPUBTextBook, key: String) — serializes to disk
    • public func invalidateAll() — deletes all files in cache directory
    • public var schemaVersion: Int — default 1, bump when pagination logic changes to force invalidation

  6. Error handling: All file I/O wrapped in do/catch. Failures logged via print("[Cache] ...") pattern and return nil/false (no throws in public API to avoid breaking callers).

  7. Console logging pattern (follows existing [EPUB] style):

    • [Cache] save key=... chapters=N pages=N on save
    • [Cache] load HIT key=... on hit
    • [Cache] load MISS key=... on miss
    • [Cache] invalidateAll on clear xcodebuild build -scheme ReadViewDemo -destination 'platform=iOS Simulator,name=iPhone 17' 2>&1 | tail -5 <acceptance_criteria>
    • File Sources/RDReaderView/EPUBTextRendering/RDEPUBTextBookCache.swift exists and contains public final class RDEPUBTextBookCache
    • Cache key method produces deterministic SHA256 hex string from layout parameters
    • Same inputs always produce identical key (deterministic)
    • Different fontSize values produce different keys
    • schemaVersion is a public property defaulting to 1
    • load(key:) returns RDEPUBTextBook? (not throwing)
    • save(_:key:) accepts RDEPUBTextBook (not throwing)
    • invalidateAll() method exists
    • Serial dispatch queue used for thread safety (queue.sync)
    • Cache directory is under Library/Caches/RDEPUBTextBookCache/
    • NSCoding wrapper classes exist for RDEPUBTextBook/Chapter/Page/Metadata serialization
    • NSRange fields encoded as location+length integer pairs
    • Build succeeds without compiler errors </acceptance_criteria> RDEPUBTextBookCache.swift is a complete, compilable file implementing SHA256 cache key generation, NSKeyedArchiver serialization with NSCoding wrappers, serial-queue thread safety, and load/save/invalidateAll API. Build succeeds.

<threat_model>

Trust Boundaries

Boundary Description
disk-cache → memory Cached RDEPUBTextBook loaded from disk into memory; tampered cache files could inject malicious attributed strings

STRIDE Threat Register

Threat ID Category Component Disposition Mitigation
T-08-01 Tampering RDEPUBTextBookCache disk files accept Cache stored in app sandbox Library/Caches; no external access; low-value target
T-08-02 Information Disclosure RDEPUBTextBookCache disk files accept No PII in cache; book content already accessible via app bundle
T-08-SC Tampering npm/pip/cargo installs mitigate No external packages installed in this phase
</threat_model>
- `xcodebuild build -scheme ReadViewDemo` succeeds - `RDEPUBTextBookCache.swift` contains public class with cacheKey/load/save/invalidateAll - SHA256 key generation uses CryptoKit - NSCoding wrapper classes handle NSAttributedString and NSRange serialization - Cache directory created under Library/Caches

<success_criteria>

  • New file RDEPUBTextBookCache.swift exists with complete implementation
  • Cache key is deterministic: same inputs -> same key
  • NSKeyedArchiver serialization produces valid .cache files
  • Build succeeds with no warnings related to new code </success_criteria>
Create `.planning/phases/08-pagination-quality-cache-performance/08-01-SUMMARY.md` when done