shoko 0.1.0

data/lib/shoko/adapters/storage/cache/epub/memory_cache.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    # In-memory caching helpers for loaded payloads + layouts.
+    class EpubCache
+      private
+
+      def load_payload
+        return @payload_cache if @payload_cache
+
+        ensure_sha!
+        cache_payload(load_payload_from_store(@source_sha))
+      end
+
+      def cache_payload(payload)
+        return nil unless payload
+
+        @payload_cache = payload
+        @layout_cache = normalize_layout_cache(payload.layouts)
+        refresh_payload_layouts!
+        payload
+      end
+
+      def load_payload_from_store(sha)
+        raw = fetch_raw_payload(sha)
+        return nil unless raw
+
+        ensure_pointer_from_metadata(raw.metadata_row)
+        Serializer.build_payload_from_store(raw, cache_root: @cache_root, book_sha: sha)
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('EpubCache: failed to load cache', sha: sha.to_s, error: e.message)
+        nil
+      end
+
+      def fetch_raw_payload(sha)
+        return nil unless sha
+
+        @cache_store.fetch_payload(sha)
+      end
+
+      def cache_layout!(key, payload)
+        @layout_cache ||= {}
+        @layout_cache[key] = deep_dup(payload)
+        return unless @payload_cache
+
+        @payload_cache.layouts ||= {}
+        @payload_cache.layouts[key] = deep_dup(payload)
+      end
+
+      def update_layout_cache_from_layouts(layouts)
+        @layout_cache = normalize_layout_cache(layouts)
+        refresh_payload_layouts!
+      end
+
+      def refresh_payload_layouts!
+        return unless @payload_cache
+
+        @payload_cache.layouts = @layout_cache.transform_values do |value|
+          deep_dup(value)
+        end
+      end
+
+      def normalize_layout_cache(layouts)
+        (layouts || {}).each_with_object({}) do |(key, payload), acc|
+          acc[key.to_s] = deep_dup(payload)
+        end
+      end
+
+      def deep_dup(obj)
+        deep_dup_value(obj)
+      end
+
+      def deep_dup_value(value)
+        case value
+        when String
+          value.dup
+        when Array
+          value.map { |item| deep_dup_value(item) }
+        when Hash
+          value.transform_values { |item| deep_dup_value(item) }
+        else
+          value
+        end
+      end
+
+      def invalidate_and_nil
+        invalidate!
+        nil
+      end
+
+      def payload_valid?(payload)
+        payload.is_a?(CachePayload) &&
+          payload.version.to_i == CACHE_VERSION &&
+          payload.book.is_a?(BookData)
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/cache/epub/persistence.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Shoko
+  module Adapters::Storage
+    # Persistence helpers for writing cache payloads + pointer metadata.
+    class EpubCache
+      private
+
+      def persist_payload(book_data, layouts_hash:)
+        ensure_sha!
+        generated_at = Time.now.utc
+
+        success = @cache_store.write_payload(
+          **payload_write_params(book_data, layouts_hash, generated_at)
+        )
+        return nil unless success
+
+        metadata = pointer_metadata_for_write(generated_at, engine: cache_engine)
+        write_pointer_metadata(metadata)
+        metadata
+      end
+
+      def payload_write_params(book_data, layouts_hash, generated_at)
+        serialized = Serializer.serialize(book_data, json: false)
+        layouts_serialized = Serializer.serialize_layouts(layouts_hash)
+
+        {
+          sha: @source_sha,
+          source_path: @source_path,
+          source_mtime: safe_mtime(@source_path),
+          generated_at: generated_at,
+          serialized_book: serialized[:book],
+          serialized_chapters: serialized[:chapters],
+          serialized_resources: serialized[:resources],
+          serialized_layouts: layouts_serialized,
+        }
+      end
+
+      def write_pointer_metadata(metadata)
+        @pointer_manager ||= CachePointerManager.new(@cache_path)
+        @pointer_manager.write(metadata)
+        @pointer_metadata = metadata
+        @source_type = :cache_pointer
+      end
+
+      def pointer_metadata_for_write(generated_at, engine:)
+        pointer_metadata(
+          sha: @source_sha,
+          source_path: @source_path,
+          generated_at: generated_at.iso8601,
+          engine: engine
+        )
+      end
+
+      def pointer_metadata(sha:, source_path:, generated_at:, engine:)
+        {
+          'format' => CachePointerManager::POINTER_FORMAT,
+          'version' => CachePointerManager::POINTER_VERSION,
+          'sha256' => sha,
+          'source_path' => source_path,
+          'generated_at' => generated_at,
+          'engine' => engine,
+        }
+      end
+
+      def ensure_pointer_from_metadata(record)
+        return unless record
+
+        ensure_sha!
+        pointer_metadata = pointer_metadata_for_record(record)
+        return if pointer_current?(pointer_metadata['sha256'])
+
+        write_pointer_metadata(pointer_metadata)
+      end
+
+      def pointer_metadata_for_record(record)
+        record_engine = Serializer.value_for(record, :engine) || cache_engine
+        pointer_metadata(
+          sha: Serializer.value_for(record, :source_sha),
+          source_path: Serializer.value_for(record, :source_path),
+          generated_at: pointer_generated_at(record),
+          engine: record_engine
+        )
+      end
+
+      def pointer_generated_at(record)
+        raw = Serializer.value_for(record, :generated_at)
+        time = Serializer.coerce_time(raw)
+        (time || Time.now.utc).iso8601
+      end
+
+      def pointer_current?(sha)
+        current = @pointer_manager&.read
+        current && current['sha256'] == sha
+      end
+
+      def cache_engine
+        engine = @cache_store.respond_to?(:engine) ? @cache_store.engine : nil
+        engine || JsonCacheStore::ENGINE
+      rescue StandardError
+        JsonCacheStore::ENGINE
+      end
+
+      def payload_matches_source?(payload, strict:)
+        return true if cache_file? && !payload.source_path
+
+        ensure_sha!
+        return false unless payload.source_sha256 == @source_sha
+
+        mtime_matches?(payload, strict: strict)
+      end
+
+      def mtime_matches?(payload, strict:)
+        source_mtime = safe_mtime(@source_path)
+        payload_mtime = payload.source_mtime
+        return true unless source_mtime && payload_mtime
+
+        tolerance = strict ? 1e-3 : 1.0
+        (source_mtime.to_f - payload_mtime.to_f).abs <= tolerance
+      end
+
+      def safe_mtime(path)
+        File.mtime(path)&.utc
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/cache/epub/serializer/deserialize.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    class EpubCache
+      # Deserialization helpers for reading cache payloads from JsonCacheStore.
+      module Serializer
+        module_function
+
+        def build_payload_from_store(raw_payload, cache_root:, book_sha:)
+          metadata = raw_payload.metadata_row || {}
+          book = deserialize_book(
+            metadata,
+            raw_payload.chapters,
+            raw_payload.resources,
+            cache_root: cache_root,
+            book_sha: book_sha
+          )
+          CachePayload.new(
+            **cache_payload_attributes(metadata, raw_payload, book_sha: book_sha, book: book)
+          )
+        end
+
+        def deserialize_book(book_row, chapter_rows, resource_rows, cache_root:, book_sha:)
+          expected_sha = book_sha.to_s
+          validate_payload_sha!(book_row, cache_root, expected_sha)
+          generation = chapters_generation!(book_row, cache_root)
+          json_fields = parse_book_json_fields(book_row)
+
+          chapters = deserialize_chapters(
+            chapter_rows,
+            cache_root: cache_root,
+            book_sha: expected_sha,
+            generation: generation
+          )
+          resources = deserialize_resources(resource_rows)
+          fields = book_display_fields(book_row, json_fields)
+          fields.merge!(book_navigation_fields(book_row, json_fields))
+          fields.merge!(book_storage_fields(json_fields, chapters, resources, generation))
+          BookData.new(**fields)
+        end
+
+        def cache_payload_attributes(metadata, raw_payload, book_sha:, book:)
+          {
+            version: value_for(metadata, :cache_version) || CACHE_VERSION,
+            source_sha256: book_sha.to_s,
+            source_path: value_for(metadata, :source_path),
+            source_mtime: coerce_time(value_for(metadata, :source_mtime)),
+            generated_at: coerce_time(value_for(metadata, :generated_at)),
+            book: book,
+            layouts: normalize_layouts(raw_payload.layouts),
+          }
+        end
+        private_class_method :cache_payload_attributes
+
+        def deserialize_chapters(rows, cache_root:, book_sha:, generation:)
+          Array(rows).map do |row|
+            idx = chapter_index(row)
+            Shoko::Core::Models::Chapter.new(
+              number: value_for(row, :number),
+              title: sanitize_display(value_for(row, :title)),
+              lines: [],
+              metadata: chapter_metadata(row),
+              blocks: nil,
+              raw_content: chapter_raw_content(cache_root, book_sha, generation, idx)
+            )
+          end
+        end
+
+        def deserialize_toc(json)
+          data = json.is_a?(String) ? JSON.parse(json || '[]') : json
+          Array(data).map do |entry|
+            Shoko::Core::Models::TOCEntry.new(
+              title: sanitize_display(value_for(entry, :title)),
+              href: sanitize_display(value_for(entry, :href)),
+              level: value_for(entry, :level),
+              chapter_index: value_for(entry, :chapter_index),
+              navigable: toc_navigable?(entry)
+            )
+          end
+        end
+
+        def deserialize_resources(rows)
+          Array(rows).each_with_object({}) do |row, acc|
+            data = value_for(row, :data).to_s.dup
+            data.force_encoding(Encoding::BINARY)
+            path = value_for(row, :path)
+            acc[path] = data if path
+          end
+        end
+
+        def normalize_layouts(raw_layouts)
+          return {} unless raw_layouts
+
+          raw_layouts.is_a?(Hash) ? normalize_layouts_hash(raw_layouts) : normalize_layouts_rows(raw_layouts)
+        end
+
+        def normalize_layout_payload(payload)
+          return nil unless payload
+
+          payload.is_a?(String) ? JSON.parse(payload) : payload
+        rescue JSON::ParserError
+          nil
+        end
+
+        def validate_payload_sha!(book_row, cache_root, expected_sha)
+          declared_sha = value_for(book_row, :source_sha).to_s
+          return if declared_sha == expected_sha
+
+          raise Shoko::CacheLoadError.new(cache_root, 'sha mismatch in payload')
+        end
+        private_class_method :validate_payload_sha!
+
+        def chapters_generation!(book_row, cache_root)
+          generation = value_for(book_row, :chapters_generation).to_s
+          return generation if generation.match?(JsonCacheStore::CHAPTERS_GENERATION_PATTERN)
+
+          raise Shoko::CacheLoadError.new(cache_root, 'invalid chapters generation')
+        end
+        private_class_method :chapters_generation!
+
+        def parse_book_json_fields(book_row)
+          {
+            authors: parse_json_array(value_for(book_row, :authors_json)),
+            metadata: parse_json_hash(value_for(book_row, :metadata_json)),
+            spine: parse_json_array(value_for(book_row, :spine_json)),
+            hrefs: parse_json_array(value_for(book_row, :chapter_hrefs_json)),
+            toc: parse_json_array(value_for(book_row, :toc_json)),
+          }
+        end
+        private_class_method :parse_book_json_fields
+
+        def book_display_fields(book_row, json_fields)
+          authors = Array(json_fields[:authors]).map { |name| sanitize_display(name) }
+          {
+            title: sanitize_display(value_for(book_row, :title)),
+            language: sanitize_display(value_for(book_row, :language)),
+            authors: authors,
+            container_path: value_for(book_row, :container_path),
+            container_xml: sanitize_content(value_for(book_row, :container_xml)),
+          }
+        end
+        private_class_method :book_display_fields
+
+        def book_navigation_fields(book_row, json_fields)
+          {
+            toc_entries: deserialize_toc(json_fields[:toc]),
+            opf_path: value_for(book_row, :opf_path),
+            spine: Array(json_fields[:spine]),
+            chapter_hrefs: Array(json_fields[:hrefs]),
+          }
+        end
+        private_class_method :book_navigation_fields
+
+        def book_storage_fields(json_fields, chapters, resources, generation)
+          {
+            metadata: json_fields[:metadata] || {},
+            chapters: chapters,
+            resources: resources,
+            chapters_generation: generation,
+          }
+        end
+        private_class_method :book_storage_fields
+
+        def chapter_index(row)
+          pos = value_for(row, :position)
+          Integer(pos)
+        end
+        private_class_method :chapter_index
+
+        def chapter_metadata(row)
+          metadata = value_for(row, :metadata_json)
+          parse_json_hash(metadata)
+        end
+        private_class_method :chapter_metadata
+
+        def chapter_raw_content(cache_root, book_sha, generation, idx)
+          Shoko::Adapters::Storage::LazyFileString.new(
+            chapter_raw_path(cache_root, book_sha, generation, idx),
+            sanitizer: method(:sanitize_content)
+          )
+        end
+        private_class_method :chapter_raw_content
+
+        def chapter_raw_path(cache_root, book_sha, generation, idx)
+          file = format("%0#{JsonCacheStore::CHAPTER_FILENAME_DIGITS}d.xhtml", idx)
+          File.join(cache_root.to_s, JsonCacheStore::CHAPTERS_DIRNAME, book_sha,
+                    generation, JsonCacheStore::CHAPTERS_RAW_DIRNAME, file)
+        end
+        private_class_method :chapter_raw_path
+
+        def normalize_layouts_hash(layouts_hash)
+          layouts_hash.each_with_object({}) do |(key, payload), acc|
+            normalized = normalize_layout_payload(payload)
+            acc[key.to_s] = normalized if normalized
+          end
+        end
+        private_class_method :normalize_layouts_hash
+
+        def normalize_layouts_rows(raw_layouts)
+          Array(raw_layouts).each_with_object({}) do |row, acc|
+            normalized = normalize_row_layout(row)
+            acc[normalized[:key]] = normalized[:payload] if normalized
+          end
+        end
+        private_class_method :normalize_layouts_rows
+
+        def normalize_row_layout(row)
+          key = value_for(row, :key)
+          payload = value_for(row, :payload_json) || value_for(row, :payload)
+          normalized = normalize_layout_payload(payload)
+          return nil unless key && normalized
+
+          { key: key.to_s, payload: normalized }
+        end
+        private_class_method :normalize_row_layout
+
+        def toc_navigable?(entry)
+          value_for(entry, :navigable) != false
+        end
+        private_class_method :toc_navigable?
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/cache/epub/serializer/helpers.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    class EpubCache
+      # Shared helpers used by the cache payload serializer/deserializer.
+      module Serializer
+        module_function
+
+        def coerce_time(raw)
+          return raw if raw.is_a?(Time)
+          return nil unless raw
+
+          Time.at(raw.to_f).utc
+        rescue StandardError
+          nil
+        end
+
+        def value_for(obj, key)
+          if obj.respond_to?(key)
+            obj.public_send(key)
+          elsif obj.respond_to?(:[])
+            obj[key] || obj[key.to_s]
+          end
+        end
+
+        def sanitize_display(text)
+          string = text.to_s
+          Shoko::Adapters::Output::Terminal::TerminalSanitizer.sanitize(string, preserve_newlines: false, preserve_tabs: false)
+        rescue StandardError
+          string.to_s
+        end
+        private_class_method :sanitize_display
+
+        def sanitize_content(text)
+          string = text.to_s
+          Shoko::Adapters::Output::Terminal::TerminalSanitizer.sanitize(string, preserve_newlines: true, preserve_tabs: true)
+        rescue StandardError
+          string.to_s
+        end
+        private_class_method :sanitize_content
+
+        def parse_json(raw, fallback_json:)
+          return raw unless raw.is_a?(String)
+
+          JSON.parse(raw.empty? ? fallback_json : raw)
+        end
+        private_class_method :parse_json
+
+        def parse_json_array(raw)
+          Array(parse_json(raw, fallback_json: '[]'))
+        end
+        private_class_method :parse_json_array
+
+        def parse_json_hash(raw)
+          parsed = parse_json(raw, fallback_json: '{}')
+          parsed.is_a?(Hash) ? parsed : {}
+        end
+        private_class_method :parse_json_hash
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/cache/epub/serializer/serialize.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    class EpubCache
+      # Serialization helpers for persisting cache payloads.
+      module Serializer
+        module_function
+
+        def serialize(book_data, json: false)
+          {
+            book: serialize_book(book_data, json: json),
+            chapters: serialize_chapters(book_data.chapters, json: json),
+            resources: serialize_resources(book_data.resources),
+          }
+        end
+
+        def serialize_layouts(layouts_hash)
+          return {} unless layouts_hash.is_a?(Hash)
+
+          layouts_hash.transform_keys(&:to_s)
+        end
+
+        def serialize_book(book, json: true)
+          {
+            payload_version: CACHE_VERSION, cache_version: CACHE_VERSION,
+            title: book.title, language: book.language,
+            authors_json: json_field(Array(book.authors), json),
+            metadata_json: json_field(book.metadata || {}, json),
+            opf_path: book.opf_path,
+            spine_json: json_field(Array(book.spine), json),
+            chapter_hrefs_json: json_field(Array(book.chapter_hrefs), json),
+            toc_json: json_field(serialized_toc(book), json),
+            container_path: book.container_path, container_xml: book.container_xml.to_s
+          }
+        end
+
+        def serialize_chapters(chapters, json: true)
+          Array(chapters).each_with_index.map do |chapter, idx|
+            metadata = chapter.metadata || {}
+            {
+              position: idx,
+              number: chapter.number,
+              title: chapter.title,
+              metadata_json: json_field(metadata, json),
+              raw_content: chapter.raw_content,
+            }
+          end
+        end
+
+        def serialize_resources(resources)
+          return [] unless resources
+
+          resources.map do |path, data|
+            bytes = String(data).dup
+            bytes.force_encoding(Encoding::BINARY)
+            { path: path.to_s, data: bytes }
+          end
+        end
+
+        def serialize_toc_entry(entry)
+          {
+            title: value_for(entry, :title),
+            href: value_for(entry, :href),
+            level: value_for(entry, :level),
+            chapter_index: value_for(entry, :chapter_index),
+            navigable: value_for(entry, :navigable),
+          }
+        end
+
+        def json_field(value, json)
+          json ? JSON.generate(value) : value
+        end
+        private_class_method :json_field
+
+        def serialized_toc(book)
+          Array(book.toc_entries).map { |entry| serialize_toc_entry(entry) }
+        end
+        private_class_method :serialized_toc
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/cache/epub/serializer.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'serializer/serialize'
+require_relative 'serializer/deserialize'
+require_relative 'serializer/helpers'

data/lib/shoko/adapters/storage/cache/epub/source_reference.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    # Source resolution helpers for `EpubCache` (EPUB source vs `.cache` pointer file).
+    class EpubCache
+      private
+
+      def setup_source_reference
+        if self.class.cache_file?(@raw_path)
+          setup_source_reference_from_pointer
+        else
+          setup_source_reference_from_epub
+        end
+      end
+
+      def setup_source_reference_from_pointer
+        @cache_path = @raw_path
+        @pointer_manager = CachePointerManager.new(@cache_path)
+        pointer = @pointer_manager.read
+        raise Shoko::CacheLoadError.new(@raw_path, 'invalid pointer file') unless pointer
+
+        @source_type = :cache_pointer
+        @pointer_metadata = pointer
+        @source_sha = pointer['sha256']
+        @source_path = pointer['source_path']
+      end
+
+      def setup_source_reference_from_epub
+        raise Shoko::FileNotFoundError, @raw_path unless File.file?(@raw_path)
+
+        @source_type = :epub
+        @source_path = @raw_path
+        @source_sha = Digest::SHA256.file(@source_path).hexdigest
+        @cache_path = cache_path_for_source_sha
+        @pointer_manager = CachePointerManager.new(@cache_path)
+        @pointer_metadata = @pointer_manager.read
+      end
+
+      def cache_path_for_source_sha
+        cache_path = self.class.cache_path_for_sha(@source_sha, cache_root: @cache_root)
+        raise Shoko::CacheLoadError.new(@raw_path, 'invalid sha256 digest') unless cache_path
+
+        cache_path
+      end
+
+      def ensure_sha!
+        return if @source_sha
+
+        if @source_type == :epub
+          @source_sha = Digest::SHA256.file(@source_path).hexdigest
+        elsif @pointer_metadata
+          @source_sha = @pointer_metadata['sha256']
+        end
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/cache_paths.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    # Cache path helpers (XDG-compatible) for on-disk Shoko artifacts.
+    module CachePaths
+      module_function
+
+      # Root directory for Shoko cache: ${XDG_CACHE_HOME:-~/.cache}/shoko
+      def cache_root
+        env_home = ENV.fetch('XDG_CACHE_HOME', nil)
+        cache_root = if env_home && !env_home.empty?
+                       env_home
+                     else
+                       File.join(Dir.home, '.cache')
+                     end
+        File.join(cache_root, 'shoko')
+      end
+    end
+  end
+end