shoko 0.1.0

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'atomic_file_writer'
+require_relative '../monitoring/logger.rb'
+
+module Shoko
+  module Adapters::Storage
+    # Manages pointer files that reference serialized cache payloads on disk.
+    class CachePointerManager
+      POINTER_FORMAT = 'shoko-cache'
+      LEGACY_POINTER_FORMATS = ['reader-cache', 'reader-marshal-cache'].freeze
+      POINTER_VERSION = 2
+      POINTER_KEYS    = %w[format version sha256 source_path generated_at engine].freeze
+      SUPPORTED_FORMATS = [POINTER_FORMAT, *LEGACY_POINTER_FORMATS].freeze
+      SUPPORTED_ENGINES = %w[json marshal].freeze
+      SHA256_HEX_PATTERN = /\A[0-9a-f]{64}\z/i
+
+      def initialize(path)
+        @path = path
+      end
+
+      attr_reader :path
+
+      def read
+        return nil unless File.exist?(path)
+
+        content = File.read(path)
+        return nil if content.nil? || content.empty?
+
+        data = JSON.parse(content)
+        return nil unless valid_pointer?(data)
+
+        data
+      rescue JSON::ParserError
+        nil
+      end
+
+      def write(data)
+        AtomicFileWriter.write_using(path) do |io|
+          io.write(JSON.generate(data))
+        end
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('CachePointerManager: write failed', path:, error: e.message)
+        false
+      end
+
+      private
+
+      def valid_pointer?(data)
+        POINTER_KEYS.all? { |key| data.key?(key) } &&
+          SUPPORTED_FORMATS.include?(data['format'].to_s) &&
+          SUPPORTED_ENGINES.include?(data['engine'].to_s) &&
+          data['version'].to_i == POINTER_VERSION &&
+          data['sha256'].to_s.match?(SHA256_HEX_PATTERN)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    # Resolves XDG-aware configuration paths for Shoko.
+    module ConfigPaths
+      module_function
+
+      # Root directory for Shoko config: ${XDG_CONFIG_HOME:-~/.config}/shoko
+      def config_root
+        env_home = ENV.fetch('XDG_CONFIG_HOME', nil)
+        config_root = if env_home && !env_home.empty?
+                        env_home
+                      else
+                        File.join(Dir.home, '.config')
+                      end
+        File.join(config_root, 'shoko')
+      end
+
+      # Downloaded books directory under config root.
+      def downloads_root
+        File.join(config_root, 'downloads')
+      end
+
+      def config_path(*segments)
+        File.join(config_root, *segments)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'time'
+
+require_relative '../../core/models/chapter.rb'
+require_relative '../../core/models/toc_entry.rb'
+require_relative '../../core/models/content_block.rb'
+require_relative '../../shared/errors.rb'
+require_relative '../output/terminal/terminal_sanitizer.rb'
+require_relative 'cache_paths'
+require_relative 'json_cache_store'
+require_relative 'cache_pointer_manager'
+require_relative 'lazy_file_string'
+require_relative '../monitoring/logger.rb'
+
+module Shoko
+  module Adapters::Storage
+    # JSON-backed cache for imported EPUB data and derived pagination layouts.
+    # Pointer files keep lightweight `.cache` discovery while the bulk payload
+    # lives in JSON + binary blobs.
+    class EpubCache
+      CACHE_VERSION   = 3
+      CACHE_EXTENSION = '.cache'
+      SHA256_HEX_PATTERN = /\A[0-9a-f]{64}\z/i
+
+      # Immutable representation of the persisted cache payload.
+      CachePayload = Struct.new(
+        :version,
+        :source_sha256,
+        :source_path,
+        :source_mtime,
+        :generated_at,
+        :book,
+        :layouts,
+        keyword_init: true
+      )
+
+      # Normalized in-memory representation of a parsed EPUB.
+      BookData = Struct.new(
+        :title,
+        :language,
+        :authors,
+        :chapters,
+        :toc_entries,
+        :opf_path,
+        :spine,
+        :chapter_hrefs,
+        :resources,
+        :metadata,
+        :container_path,
+        :container_xml,
+        :chapters_generation,
+        keyword_init: true
+      )
+
+      class << self
+        def cache_extension = CACHE_EXTENSION
+
+        def cache_file?(path)
+          File.file?(path) && File.extname(path).casecmp(CACHE_EXTENSION).zero?
+        end
+
+        def cache_path_for_sha(sha, cache_root: CachePaths.cache_root)
+          normalized = sha.to_s.strip
+          return nil unless normalized.match?(SHA256_HEX_PATTERN)
+
+          File.join(cache_root, "#{normalized.downcase}#{CACHE_EXTENSION}")
+        end
+      end
+
+      attr_reader :cache_path, :source_path
+
+      def initialize(path, cache_root: CachePaths.cache_root, store: nil)
+        @cache_root = cache_root
+        @cache_store = store || JsonCacheStore.new(cache_root: @cache_root)
+        @raw_path = File.expand_path(path)
+        @payload_cache = nil
+        @layout_cache = {}
+        @pointer_metadata = nil
+        setup_source_reference
+      end
+
+      # Load pointer payload without validating source. Used by cached-library
+      # direct opens.
+      def read_cache(strict: false)
+        payload = load_payload
+        return nil unless payload
+
+        return payload unless strict
+
+        payload_valid?(payload) ? payload : invalidate_and_nil
+      rescue Shoko::CacheLoadError
+        nil
+      end
+
+      # Load payload and ensure it matches the original EPUB file.
+      def load_for_source(strict: false)
+        payload = load_payload
+        return nil unless payload
+
+        if payload_valid?(payload) && payload_matches_source?(payload, strict:)
+          payload
+        else
+          invalidate_and_nil
+        end
+      end
+
+      def write_book!(book_data)
+        ensure_sha!
+        return nil unless persist_payload(book_data, layouts_hash: {})
+
+        @layout_cache = {}
+        @payload_cache = load_payload_from_store(@source_sha)
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('EpubCache: failed to write cache', path: @cache_path, error: e.message)
+        nil
+      end
+
+      def load_layout(key)
+        key_str = key.to_s
+        return deep_dup(@layout_cache[key_str]) if @layout_cache.key?(key_str)
+
+        payload = @cache_store.load_layout(@source_sha, key_str)
+        return nil unless payload
+
+        cache_layout!(key_str, payload)
+        deep_dup(payload)
+      rescue StandardError
+        nil
+      end
+
+      def mutate_layouts!
+        ensure_sha!
+        updated_layouts = nil
+        success = @cache_store.mutate_layouts(@source_sha) do |layouts|
+          yield layouts
+          updated_layouts = layouts
+        end
+        update_layout_cache_from_layouts(updated_layouts) if success
+        success
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('EpubCache: failed to update layouts', path: @cache_path, error: e.message)
+        false
+      end
+
+      def invalidate!
+        ensure_sha!
+        @cache_store.delete_payload(@source_sha) if @source_sha
+        FileUtils.rm_f(@cache_path) if @cache_path && File.exist?(@cache_path)
+      ensure
+        @payload_cache = nil
+        @layout_cache = {}
+        @pointer_metadata = nil
+      end
+
+      def cache_file?
+        @source_type == :cache_pointer
+      end
+
+      def sha256
+        ensure_sha!
+        @source_sha
+      end
+
+      def layout_keys
+        ensure_sha!
+        keys = @cache_store.fetch_layouts(@source_sha).keys
+        keys |= @layout_cache.keys
+        keys
+      rescue StandardError
+        []
+      end
+
+      def chapters_complete?(expected_count, generation: nil)
+        ensure_sha!
+        gen = generation
+        if gen.nil? && @payload_cache&.book.respond_to?(:chapters_generation)
+          gen = @payload_cache.book.chapters_generation
+        end
+        return false if gen.to_s.strip.empty?
+
+        @cache_store.respond_to?(:chapters_complete?) &&
+          @cache_store.chapters_complete?(@source_sha, gen, expected_count: expected_count)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end
+
+require_relative 'cache/epub/serializer'
+require_relative 'cache/epub/source_reference'
+require_relative 'cache/epub/memory_cache'
+require_relative 'cache/epub/persistence'

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative '../../core/services/base_service.rb'
+
+module Shoko
+  module Adapters::Storage
+      # Provides atomic file writing for domain repositories without coupling them
+      # to infrastructure implementations.
+      class FileWriterService < BaseService
+        def initialize(dependencies)
+          super
+          @writer = resolve_optional(:atomic_file_writer)
+        end
+
+        # Write payload to path atomically when possible.
+        #
+        # Ensures the target directory exists before delegating to the underlying writer.
+        def write(path, payload)
+          dir = File.dirname(path)
+          FileUtils.mkdir_p(dir)
+
+          if @writer.respond_to?(:write)
+            @writer.write(path, payload)
+          else
+            default_write(path, payload)
+          end
+        end
+
+        private
+
+        def resolve_optional(name)
+          resolve(name)
+        rescue StandardError
+          nil
+        end
+
+      def default_write(path, payload)
+        tmp = "#{path}.tmp"
+        File.write(tmp, payload)
+        FileUtils.mv(tmp, path)
+      ensure
+        FileUtils.rm_f(tmp) if tmp && File.exist?(tmp)
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/json_cache_store/chapters.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    # Chapter persistence helpers for `JsonCacheStore`.
+    class JsonCacheStore
+      CHAPTER_ROW_EXCLUDED_KEYS = %w[raw_content lines_json blocks_json].freeze
+
+      private
+
+      def chapters_dir(sha)
+        File.join(@cache_root, CHAPTERS_DIRNAME, normalize_sha!(sha))
+      end
+
+      def chapter_generation_dir(sha, generation)
+        gen = generation.to_s.strip
+        raise ArgumentError, 'chapter generation is invalid' unless CHAPTERS_GENERATION_PATTERN.match?(gen)
+
+        File.join(chapters_dir(sha), gen.downcase)
+      end
+
+      def chapter_raw_dir(sha, generation)
+        File.join(chapter_generation_dir(sha, generation), CHAPTERS_RAW_DIRNAME)
+      end
+
+      def chapter_raw_file(sha, generation, position)
+        idx = Integer(position)
+        raise ArgumentError, 'chapter position must be >= 0' if idx.negative?
+
+        name = format("%0#{CHAPTER_FILENAME_DIGITS}d.xhtml", idx)
+        File.join(chapter_raw_dir(sha, generation), name)
+      end
+
+      def normalize_chapter_generation(generation)
+        gen = generation.to_s.strip.downcase
+        CHAPTERS_GENERATION_PATTERN.match?(gen) ? gen : nil
+      end
+
+      def normalize_expected_chapter_count(expected_count)
+        count = expected_count.to_i
+        return nil if count.negative?
+        return nil if count > MAX_CHAPTER_COUNT
+
+        count
+      end
+
+      def chapter_files_complete?(sha, generation, expected_count)
+        raw_dir = chapter_raw_dir(sha, generation)
+        return false unless Dir.exist?(raw_dir)
+
+        expected_count.times do |idx|
+          return false unless File.file?(chapter_raw_file(sha, generation, idx))
+        end
+        true
+      end
+
+      def persist_chapters(sha, chapter_rows)
+        chapter_rows = Array(chapter_rows)
+        generation = new_chapter_generation
+        return [[], generation, 0] if chapter_rows.empty?
+
+        FileUtils.mkdir_p(chapter_raw_dir(sha, generation))
+        rows, total_bytes = persist_chapter_rows(sha, generation, chapter_rows)
+        [rows, generation, total_bytes]
+      end
+
+      def new_chapter_generation
+        SecureRandom.hex(CHAPTERS_GENERATION_BYTES)
+      end
+
+      def persist_chapter_rows(sha, generation, chapter_rows)
+        rows = []
+        total_bytes = 0
+        chapter_rows.each do |row|
+          filtered, bytesize = persist_chapter_row(sha, generation, row)
+          rows << filtered
+          total_bytes += bytesize
+        end
+        [rows, total_bytes]
+      end
+
+      def persist_chapter_row(sha, generation, row)
+        idx = chapter_row_index(row)
+        text = chapter_row_raw_content(row).to_s
+        AtomicFileWriter.write(chapter_raw_file(sha, generation, idx), text)
+        [filtered_chapter_index_row(row, idx), text.bytesize]
+      end
+
+      def chapter_row_index(row)
+        raise ArgumentError, 'chapter row must be a Hash' unless row.is_a?(Hash)
+
+        position = row[:position] || row['position']
+        idx = Integer(position)
+        raise ArgumentError, 'chapter position must be >= 0' if idx.negative?
+
+        idx
+      end
+
+      def chapter_row_raw_content(row)
+        row[:raw_content] || row['raw_content']
+      end
+
+      def filtered_chapter_index_row(row, idx)
+        filtered = {}
+        row.each do |key, value|
+          key_str = key.to_s
+          next if CHAPTER_ROW_EXCLUDED_KEYS.include?(key_str)
+
+          filtered[key_str] = value
+        end
+        filtered['position'] = idx
+        filtered
+      end
+
+      def cleanup_old_chapter_generations(sha, keep:)
+        base = chapters_dir(sha)
+        return unless Dir.exist?(base)
+
+        keep_name = keep.to_s.strip.downcase
+        Dir.children(base).each do |entry|
+          next if entry == keep_name
+
+          path = File.join(base, entry)
+          next unless File.directory?(path)
+          next unless CHAPTERS_GENERATION_PATTERN.match?(entry)
+
+          FileUtils.rm_rf(path)
+        end
+      rescue StandardError
+        nil
+      end
+
+      def cleanup_failed_chapter_generation(sha, generation)
+        path = chapter_generation_dir(sha, generation)
+        FileUtils.rm_rf(path)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/json_cache_store/layouts.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    # Layout storage helpers for `JsonCacheStore`.
+    class JsonCacheStore
+      private
+
+      def layouts_dir(sha)
+        File.join(@cache_root, 'layouts', normalize_sha!(sha))
+      end
+
+      def layout_file(sha, key)
+        File.join(layouts_dir(sha), "#{normalize_layout_key!(key)}.json")
+      end
+
+      def layout_key_for_entry(entry)
+        return nil unless entry.end_with?('.json')
+
+        key = entry.delete_suffix('.json')
+        layout_key_valid?(key) ? key : nil
+      end
+
+      def read_layout_payload(dir, entry, sha:, key:)
+        JSON.parse(File.read(File.join(dir, entry)))
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('JsonCacheStore: layout parse failed', sha: sha.to_s, key: key.to_s, error: e.message)
+        nil
+      end
+
+      def write_layouts(sha, layouts_hash)
+        dir = layouts_dir(sha)
+        FileUtils.mkdir_p(dir)
+        existing = Dir.exist?(dir) ? Dir.children(dir).select { |entry| entry.end_with?('.json') } : []
+
+        written = []
+        layouts_hash.each do |key, payload|
+          normalized_key = normalize_layout_key!(key)
+          file = File.join(dir, "#{normalized_key}.json")
+          AtomicFileWriter.write(file, JSON.generate(payload))
+          written << "#{normalized_key}.json"
+        end
+
+        stale = existing - written
+        stale.each { |entry| FileUtils.rm_f(File.join(dir, entry)) }
+      end
+
+      def layout_key_valid?(key)
+        normalize_layout_key!(key)
+        true
+      rescue ArgumentError
+        false
+      end
+
+      def normalize_layout_key!(key)
+        value = key.to_s
+        raise ArgumentError, 'layout key is blank' if value.empty?
+        raise ArgumentError, 'layout key too long' if value.bytesize > MAX_LAYOUT_KEY_BYTES
+        raise ArgumentError, 'layout key contains null byte' if value.include?("\0")
+        raise ArgumentError, 'layout key contains path separator' if value.include?('/') || value.include?('\\')
+        raise ArgumentError, 'layout key has invalid characters' unless LAYOUT_KEY_PATTERN.match?(value)
+
+        value
+      end
+    end
+  end
+end

data/lib/shoko/adapters/storage/json_cache_store/manifest.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    # Manifest helpers for `JsonCacheStore` (cache listing).
+    class JsonCacheStore
+      private
+
+      def manifest_path
+        File.join(@cache_root, MANIFEST_FILENAME)
+      end
+
+      def update_manifest(metadata_row, cache_size_bytes:)
+        row = metadata_row.merge('cache_size_bytes' => cache_size_bytes.to_i)
+        manifest = self.class.manifest_rows(@cache_root)
+        manifest.reject! { |entry| entry['source_sha'] == row['source_sha'] }
+        manifest << row
+        AtomicFileWriter.write(manifest_path, JSON.generate(manifest))
+      rescue StandardError => e
+        Shoko::Adapters::Monitoring::Logger.debug('JsonCacheStore: manifest write failed', error: e.message)
+      end
+
+      def remove_from_manifest(sha)
+        manifest = self.class.manifest_rows(@cache_root)
+        manifest.reject! { |entry| entry['source_sha'] == sha }
+        AtomicFileWriter.write(manifest_path, JSON.generate(manifest))
+      rescue StandardError
+        nil
+      end
+
+      def self.read_manifest_file(path)
+        return [] unless File.file?(path)
+
+        data = JSON.parse(File.read(path))
+        data.is_a?(Array) ? data : []
+      rescue StandardError
+        []
+      end
+      private_class_method :read_manifest_file
+    end
+  end
+end

data/lib/shoko/adapters/storage/json_cache_store/payload_helpers.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Shoko
+  module Adapters::Storage
+    # Payload IO + normalization helpers for `JsonCacheStore`.
+    class JsonCacheStore
+      private
+
+      def payload_path(sha)
+        File.join(@cache_root, "#{normalize_sha!(sha)}.json")
+      end
+
+      def load_payload_data(sha)
+        path = payload_path(sha)
+        return nil unless File.file?(path)
+
+        data = JSON.parse(File.read(path))
+        valid_payload_file?(data) ? data : nil
+      end
+
+      def valid_payload_file?(data)
+        return false unless data.is_a?(Hash)
+        return false unless payload_header_valid?(data)
+
+        metadata_row = data['metadata_row']
+        return false unless metadata_row.is_a?(Hash)
+        return false unless payload_metadata_valid?(metadata_row)
+        return false unless payload_collections_valid?(data)
+
+        true
+      rescue StandardError
+        false
+      end
+
+      def payload_header_valid?(data)
+        data['format'] == FORMAT &&
+          data['format_version'].to_i == FORMAT_VERSION &&
+          data['engine'].to_s == ENGINE
+      end
+
+      def payload_metadata_valid?(metadata_row)
+        CHAPTERS_GENERATION_PATTERN.match?(metadata_row['chapters_generation'].to_s)
+      end
+
+      def payload_collections_valid?(data)
+        data['chapters'].is_a?(Array) && data['resources'].is_a?(Array)
+      end
+
+      def build_metadata_row(serialized_book, normalized_sha, source_path:, source_mtime:, generated_at:)
+        now = Time.now.utc.to_f
+        stringify_keys(serialized_book).merge(
+          'source_sha' => normalized_sha,
+          'source_path' => source_path,
+          'source_mtime' => source_mtime&.to_f,
+          'source_size_bytes' => safe_file_size(source_path),
+          'source_fingerprint' => Shoko::Adapters::BookSources::SourceFingerprint.compute(source_path),
+          'generated_at' => generated_at&.to_f,
+          'created_at' => now,
+          'updated_at' => now,
+          'engine' => ENGINE
+        )
+      end
+
+      def payload_hash(metadata_row, chapter_generation, indexes)
+        chapters_index = indexes.fetch(:chapters)
+        resources_index = indexes.fetch(:resources)
+        metadata_row['chapters_generation'] = chapter_generation
+        metadata_row['chapters_format_version'] = 1
+
+        {
+          'format' => FORMAT,
+          'format_version' => FORMAT_VERSION,
+          'engine' => ENGINE,
+          'metadata_row' => metadata_row,
+          'chapters' => chapters_index,
+          'resources' => resources_index,
+        }
+      end
+
+      def write_payload_file(sha, payload)
+        AtomicFileWriter.write(payload_path(sha), JSON.generate(payload))
+      end
+
+      def post_write_housekeeping(sha, metadata_row, chapter_generation, cache_size_bytes, serialized_layouts:)
+        write_layouts(sha, serialized_layouts)
+        update_manifest(metadata_row, cache_size_bytes: cache_size_bytes)
+        cleanup_old_chapter_generations(sha, keep: chapter_generation)
+      end
+
+      def stringify_keys(hash)
+        (hash || {}).transform_keys(&:to_s)
+      rescue StandardError
+        hash || {}
+      end
+
+      def normalize_sha!(sha)
+        value = sha.to_s.strip
+        raise ArgumentError, 'sha is blank' if value.empty?
+        raise ArgumentError, 'sha must be a 64-char hex digest' unless SHA256_HEX_PATTERN.match?(value)
+
+        value.downcase
+      end
+
+      def safe_file_size(path)
+        return nil if path.nil? || path.to_s.empty?
+
+        File.size(path)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end