fbe 0.19.3 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df9755e6d4d7bf5ae3a716031216786929ddfcdf328a3f026b308e9bbfc93f92
-  data.tar.gz: ed1cfe9f9877a3e3e1b77f30f4b9c8ca525885306d100058d5397019ca1005e6
+  metadata.gz: ae9a9de76ff2dba753f10923fb0f984acc0c0e2e4f2a626a15c0ae6622d64392
+  data.tar.gz: ceeef4187f94f32b39569cf7f1e98c1a25559b1730c742f8c01073520456afce
 SHA512:
-  metadata.gz: 3bfc015d2f0c47035fae903627404da6fafcd823c14abdcdc8a37694fea73bbb4edd1f1467497379fff51e62388b741a205b28bcd0ee8a4b5c28aceaf0f6c22c
-  data.tar.gz: dc92c946e0d1bd14deb3d29a73b36f9317d7e06597ac2ec4fc05030ed9afea415830a71f101eb54ddd2793a02a3c6b480d2a2b95482f3deb0d62903230b1432e
+  metadata.gz: c2cec9308283d6d2ced937184b6e62b09bee329a10b7d65d69d369002dfb797b7e2b513611d64911d09cbaa50b7c00aec6480040f5955510297a20128528b443
+  data.tar.gz: 4d901bf3b1a062683dd481398e4961447676af8ae97ef8d938b321c6b0774fdadde71ba69e4875859e138e1853be2f1a734db1bf0fbe72f5ea62695c67fb67e3

data/Gemfile

@@ -8,6 +8,7 @@ gemspec
 
 gem 'minitest', '~>5.25', require: false
 gem 'minitest-reporters', '~>1.7', require: false
+gem 'minitest-stub-const', '~>0.6', require: false
 gem 'os', '~>1.1', require: false
 gem 'qbash', '~>0.4', require: false
 gem 'rake', '~>13.3', require: false

data/Gemfile.lock

@@ -143,6 +143,7 @@ GEM
       builder
       minitest (>= 5.0)
       ruby-progressbar
+    minitest-stub-const (0.6)
     moments (0.3.0)
     multipart-post (2.4.1)
     net-http (0.6.0)
@@ -179,7 +180,7 @@ GEM
     regexp_parser (2.10.0)
     retries (0.0.5)
     rexml (3.4.1)
-    rubocop (1.76.0)
+    rubocop (1.76.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -190,7 +191,7 @@ GEM
       rubocop-ast (>= 1.45.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.45.0)
+    rubocop-ast (1.45.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-minitest (0.38.1)
@@ -258,6 +259,7 @@ DEPENDENCIES
   fbe!
   minitest (~> 5.25)
   minitest-reporters (~> 1.7)
+  minitest-stub-const (~> 0.6)
   os (~> 1.1)
   qbash (~> 0.4)
   rake (~> 13.3)

data/lib/fbe/middleware/sqlite_store.rb

@@ -3,55 +3,119 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024-2025 Zerocracy
 # SPDX-License-Identifier: MIT
 
+require 'time'
 require 'json'
 require 'sqlite3'
+require 'loog'
 require_relative '../../fbe'
 require_relative '../../fbe/middleware'
 
 # Persisted SQLite store for Faraday::HttpCache
 #
+# This class provides a persistent cache store backed by SQLite for use with
+# Faraday::HttpCache middleware. It's designed to cache HTTP responses from
+# GitHub API calls to reduce API rate limit consumption and improve performance.
+#
+# Key features:
+# - Automatic version management to invalidate cache on version changes
+# - Size-based cache eviction (configurable, defaults to 10MB)
+# - Thread-safe SQLite transactions
+# - JSON serialization for cached values
+# - Filtering of non-cacheable requests (non-GET, URLs with query parameters)
+#
+# Usage example:
+#   store = Fbe::Middleware::SqliteStore.new(
+#     '/path/to/cache.db',
+#     '1.0.0',
+#     loog: logger,
+#     maxsize: 50 * 1024 * 1024  # 50MB max size
+#   )
+#
+#   # Use with Faraday
+#   Faraday.new do |builder|
+#     builder.use Faraday::HttpCache, store: store
+#   end
+#
+# The store automatically manages the SQLite database schema and handles
+# cleanup operations when the database grows too large. Old entries are
+# deleted based on their last access time to maintain the configured size limit.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Zerocracy
 # License:: MIT
 class Fbe::Middleware::SqliteStore
   attr_reader :path
 
-  def initialize(path)
+  # Initialize the SQLite store.
+  # @param path [String] Path to the SQLite database file
+  # @param version [String] Version identifier for cache compatibility
+  # @param loog [Loog] Logger instance (optional, defaults to Loog::NULL)
+  # @param maxsize [Integer] Maximum database size in bytes (optional, defaults to 10MB)
+  # @raise [ArgumentError] If path is nil/empty, directory doesn't exist, or version is nil/empty
+  def initialize(path, version, loog: Loog::NULL, maxsize: 10 * 1024 * 1024)
     raise ArgumentError, 'Database path cannot be nil or empty' if path.nil? || path.empty?
     dir = File.dirname(path)
     raise ArgumentError, "Directory #{dir} does not exist" unless File.directory?(dir)
+    raise ArgumentError, 'Version cannot be nil or empty' if version.nil? || version.empty?
     @path = File.absolute_path(path)
+    @version = version
+    @loog = loog
+    @maxsize = maxsize
   end
 
+  # Read a value from the cache.
+  # @param key [String] The cache key to read
+  # @return [Object, nil] The cached value parsed from JSON, or nil if not found
   def read(key)
-    value = perform { _1.execute('SELECT value FROM cache WHERE key = ? LIMIT 1', [key]) }.dig(0, 0)
+    value = perform do |t|
+      t.execute('UPDATE cache SET touched_at = ?2 WHERE key = ?1;', [key, Time.now.utc.iso8601])
+      t.execute('SELECT value FROM cache WHERE key = ? LIMIT 1;', [key])
+    end.dig(0, 0)
     JSON.parse(value) if value
   end
 
+  # Delete a key from the cache.
+  # @param key [String] The cache key to delete
+  # @return [nil]
   def delete(key)
     perform { _1.execute('DELETE FROM cache WHERE key = ?', [key]) }
     nil
   end
 
+  # Write a value to the cache.
+  # @param key [String] The cache key to write
+  # @param value [Object] The value to cache (will be JSON encoded)
+  # @return [nil]
+  # @note Values larger than 10KB are not cached
+  # @note Non-GET requests and URLs with query parameters are not cached
   def write(key, value)
     return if value.is_a?(Array) && value.any? do |vv|
       req = JSON.parse(vv[0])
       req['url'].include?('?') || req['method'] != 'get'
     end
     value = JSON.dump(value)
+    return if value.bytesize > 10_000
     perform do |t|
-      t.execute(<<~SQL, [key, value])
-        INSERT INTO cache(key, value) VALUES(?1, ?2)
-        ON CONFLICT(key) DO UPDATE SET value = ?2
+      t.execute(<<~SQL, [key, value, Time.now.utc.iso8601])
+        INSERT INTO cache(key, value, touched_at) VALUES(?1, ?2, ?3)
+        ON CONFLICT(key) DO UPDATE SET value = ?2, touched_at = ?3
       SQL
     end
     nil
   end
 
+  # Clear all entries from the cache.
+  # @return [void]
   def clear
-    perform { _1.execute 'DELETE FROM cache;' }
+    perform do |t|
+      t.execute 'DELETE FROM cache;'
+      t.execute "UPDATE meta SET value = ? WHERE key = 'version';", [@version]
+    end
+    @db.execute 'VACUUM;'
   end
 
+  # Get all entries from the cache.
+  # @return [Array<Array>] Array of [key, value] pairs
   def all
     perform { _1.execute('SELECT key, value FROM cache') }
   end
@@ -62,8 +126,46 @@ class Fbe::Middleware::SqliteStore
     @db ||=
       SQLite3::Database.new(@path).tap do |d|
         d.transaction do |t|
-          t.execute 'CREATE TABLE IF NOT EXISTS cache(key TEXT UNIQUE NOT NULL, value TEXT);'
-          t.execute 'CREATE INDEX IF NOT EXISTS key_idx ON cache(key);'
+          t.execute <<~SQL
+            CREATE TABLE IF NOT EXISTS cache(
+              key TEXT UNIQUE NOT NULL, value TEXT, touched_at TEXT NOT NULL
+            );
+          SQL
+          t.execute 'CREATE INDEX IF NOT EXISTS cache_key_idx ON cache(key);'
+          t.execute 'CREATE INDEX IF NOT EXISTS cache_touched_at_idx ON cache(touched_at);'
+          t.execute 'CREATE TABLE IF NOT EXISTS meta(key TEXT UNIQUE NOT NULL, value TEXT);'
+          t.execute 'CREATE INDEX IF NOT EXISTS meta_key_idx ON meta(key);'
+          t.execute "INSERT INTO meta(key, value) VALUES('version', ?) ON CONFLICT(key) DO NOTHING;", [@version]
+        end
+        found = d.execute("SELECT value FROM meta WHERE key = 'version' LIMIT 1;").dig(0, 0)
+        if found != @version
+          @loog.info("Version mismatch in SQLite cache: stored '#{found}' != current '#{@version}', cleaning up")
+          d.transaction do |t|
+            t.execute 'DELETE FROM cache;'
+            t.execute "UPDATE meta SET value = ? WHERE key = 'version';", [@version]
+          end
+          d.execute 'VACUUM;'
+        end
+        if File.size(@path) > @maxsize
+          @loog.info(
+            "SQLite cache file size (#{File.size(@path)} bytes) exceeds " \
+            "#{@maxsize / 1024 / 1024}MB, cleaning up old entries"
+          )
+          deleted = 0
+          while d.execute(<<~SQL).dig(0, 0) > @maxsize
+            SELECT (page_count - freelist_count) * page_size AS size
+            FROM pragma_page_count(), pragma_freelist_count(), pragma_page_size();
+          SQL
+            d.transaction do |t|
+              t.execute <<~SQL
+                DELETE FROM cache
+                WHERE key IN (SELECT key FROM cache ORDER BY touched_at LIMIT 50)
+              SQL
+              deleted += t.changes
+            end
+          end
+          d.execute 'VACUUM;'
+          @loog.info("Deleted #{deleted} old cache entries, new file size: #{File.size(@path)} bytes")
         end
         at_exit { @db&.close }
       end

data/lib/fbe/octo.rb

@@ -25,6 +25,10 @@ require_relative 'middleware/sqlite_store'
 # logging, and caching.
 #
 # @param [Judges::Options] options The options available globally
+# @option options [String] :github_token GitHub API token for authentication
+# @option options [Boolean] :testing When true, uses FakeOctokit for testing
+# @option options [String] :sqlite_cache Path to SQLite cache file for HTTP responses
+# @option options [Integer] :sqlite_cache_maxsize Maximum size of SQLite cache in bytes (default: 10MB)
 # @param [Hash] global Hash of global options
 # @param [Loog] loog Logging facility
 # @return [Hash] Usually returns a JSON, as it comes from the GitHub API
@@ -77,11 +81,12 @@ def Fbe.octo(options: $options, global: $global, loog: $loog)
               backoff_factor: 2
             )
             if options.sqlite_cache
-              store = Fbe::Middleware::SqliteStore.new(options.sqlite_cache)
+              maxsize = options.sqlite_cache_maxsize || (10 * 1024 * 1024)
+              store = Fbe::Middleware::SqliteStore.new(options.sqlite_cache, Fbe::VERSION, loog:, maxsize:)
               loog.info(
                 "Using HTTP cache in SQLite file: #{store.path} (" \
-                "#{File.exist?(store.path) ? "#{File.size(store.path)} bytes" : 'file is absent'}" \
-                ')'
+                "#{File.exist?(store.path) ? "#{File.size(store.path)} bytes" : 'file is absent'}, " \
+                "max size: #{maxsize / 1024 / 1024}MB)"
               )
               builder.use(
                 Faraday::HttpCache,

data/lib/fbe.rb

@@ -10,5 +10,5 @@
 # License:: MIT
 module Fbe
   # Current version of the gem (changed by +.rultor.yml+ on every release)
-  VERSION = '0.19.3' unless const_defined?(:VERSION)
+  VERSION = '0.21.0' unless const_defined?(:VERSION)
 end

data/test/fbe/middleware/test_sqlite_store.rb

@@ -15,7 +15,7 @@ require_relative '../../../lib/fbe/middleware/sqlite_store'
 class SqliteStoreTest < Fbe::Test
   def test_simple_caching_algorithm
     with_tmpfile('x.db') do |f|
-      store = Fbe::Middleware::SqliteStore.new(f)
+      store = Fbe::Middleware::SqliteStore.new(f, '0.0.0')
       k = 'some-key'
       assert_nil(store.read(k))
       assert_nil(store.delete(k))
@@ -33,14 +33,14 @@ class SqliteStoreTest < Fbe::Test
 
   def test_returns_empty_list
     with_tmpfile('b.db') do |f|
-      store = Fbe::Middleware::SqliteStore.new(f)
+      store = Fbe::Middleware::SqliteStore.new(f, '0.0.0')
       assert_empty(store.all)
     end
   end
 
   def test_clear_all_keys
     with_tmpfile('a.db') do |f|
-      store = Fbe::Middleware::SqliteStore.new(f)
+      store = Fbe::Middleware::SqliteStore.new(f, '0.0.0')
       k = 'a key'
       store.write(k, 'some value')
       store.clear
@@ -50,20 +50,20 @@ class SqliteStoreTest < Fbe::Test
 
   def test_empty_all_if_not_written
     with_tmpfile do |f|
-      store = Fbe::Middleware::SqliteStore.new(f)
+      store = Fbe::Middleware::SqliteStore.new(f, '0.0.0')
       assert_empty(store.all)
     end
   end
 
   def test_wrong_db_path
     assert_raises(ArgumentError) do
-      Fbe::Middleware::SqliteStore.new(nil).read('my_key')
+      Fbe::Middleware::SqliteStore.new(nil, '0.0.0').read('my_key')
     end
     assert_raises(ArgumentError) do
-      Fbe::Middleware::SqliteStore.new('').read('my_key')
+      Fbe::Middleware::SqliteStore.new('', '0.0.0').read('my_key')
     end
     assert_raises(ArgumentError) do
-      Fbe::Middleware::SqliteStore.new('/fakepath/fakefolder/test.db').read('my_key')
+      Fbe::Middleware::SqliteStore.new('/fakepath/fakefolder/test.db', '0.0.0').read('my_key')
     end
   end
 
@@ -72,7 +72,7 @@ class SqliteStoreTest < Fbe::Test
       File.binwrite(f, Array.new(20) { rand(0..255) }.pack('C*'))
       ex =
         assert_raises(SQLite3::NotADatabaseException) do
-          Fbe::Middleware::SqliteStore.new(f).read('my_key')
+          Fbe::Middleware::SqliteStore.new(f, '0.0.0').read('my_key')
         end
       assert_match('file is not a database', ex.message)
     end
@@ -94,7 +94,7 @@ class SqliteStoreTest < Fbe::Test
       end
 
       Tempfile.open('test.db') do |f|
-        Fbe::Middleware::SqliteStore.new(f.path).then do |s|
+        Fbe::Middleware::SqliteStore.new(f.path, '0.0.0').then do |s|
           s.write('my_key', 'my_value')
           s.read('my_key')
         end
@@ -109,6 +109,79 @@ class SqliteStoreTest < Fbe::Test
     assert_match('closed sqlite after process exit', out)
   end
 
+  def test_different_versions
+    with_tmpfile('d.db') do |f|
+      Fbe::Middleware::SqliteStore.new(f, '0.0.1').then do |store|
+        store.write('kkk1', 'some value')
+        store.write('kkk2', 'another value')
+      end
+      Fbe::Middleware::SqliteStore.new(f, '0.0.1').then do |store|
+        assert_equal('some value', store.read('kkk1'))
+        assert_equal('another value', store.read('kkk2'))
+      end
+      Fbe::Middleware::SqliteStore.new(f, '0.0.2').then do |store|
+        assert_nil(store.read('kkk1'))
+        assert_nil(store.read('kkk2'))
+      end
+    end
+  end
+
+  def test_initialize_wrong_version
+    with_tmpfile('e.db') do |f|
+      msg = 'Version cannot be nil or empty'
+      assert_raises(ArgumentError) { Fbe::Middleware::SqliteStore.new(f, nil) }.then do |ex|
+        assert_match(msg, ex.message)
+      end
+      assert_raises(ArgumentError) { Fbe::Middleware::SqliteStore.new(f, '') }.then do |ex|
+        assert_match(msg, ex.message)
+      end
+    end
+  end
+
+  def test_skip_write_if_value_more_then_10k_bytes
+    with_tmpfile('a.db') do |f|
+      Fbe::Middleware::SqliteStore.new(f, '0.0.1').then do |store|
+        store.write('a', 'a' * 9_997)
+        store.write('b', 'b' * 9_998)
+        store.write('c', 'c' * 9_999)
+        store.write('d', 'd' * 10_000)
+        assert_equal('a' * 9_997, store.read('a'))
+        assert_equal('b' * 9_998, store.read('b'))
+        assert_nil(store.read('c'))
+        assert_nil(store.read('d'))
+      end
+    end
+  end
+
+  def test_shrink_cache_if_more_then_10_mb
+    with_tmpfile('large.db') do |f|
+      Fbe::Middleware::SqliteStore.new(f, '0.0.1').then do |store|
+        key = 'aaa'
+        alpha = ('a'..'z').to_a
+        store.write('a', 'aa')
+        Time.stub(:now, (Time.now - (5 * 60 * 60)).round) do
+          store.write('b', 'bb')
+          store.write('c', 'cc')
+        end
+        assert_equal('cc', store.read('c'))
+        Time.stub(:now, rand((Time.now - (5 * 60 * 60))..Time.now).round) do
+          10_240.times do
+            value = alpha.sample * rand(1024..2048)
+            store.write(key, value)
+            key = key.next
+          end
+        end
+      end
+      assert_operator(File.size(f), :>, 10 * 1024 * 1024)
+      Fbe::Middleware::SqliteStore.new(f, '0.0.1').then do |store|
+        assert_equal('aa', store.read('a'))
+        assert_nil(store.read('b'))
+        assert_equal('cc', store.read('c'))
+        assert_operator(File.size(f), :<=, 10 * 1024 * 1024)
+      end
+    end
+  end
+
   private
 
   def with_tmpfile(name = 'test.db', &)

data/test/fbe/test_octo.rb

@@ -405,4 +405,45 @@ class TestOcto < Fbe::Test
       assert_path_exists(file)
     end
   end
+
+  def test_sqlite_store_for_use_in_different_versions
+    WebMock.disable_net_connect!
+    Dir.mktmpdir do |dir|
+      global = {}
+      stub =
+        stub_request(:get, 'https://api.github.com/user/42')
+          .to_return(
+            status: 200,
+            body: { login: 'user1' }.to_json,
+            headers: {
+              'Content-Type' => 'application/json',
+              'Cache-Control' => 'public, max-age=60, s-maxage=60',
+              'Etag' => 'W/"2ff9dd4c3153f006830b2b8b721f6a4bb400a1eb81a2e1fa0a3b846ad349b9ec"',
+              'Last-Modified' => 'Wed, 01 May 2025 20:00:00 GMT'
+            }
+          )
+      sqlite_cache = File.expand_path('test.db', dir)
+      Fbe.stub_const(:VERSION, '0.0.1') do
+        o = Fbe.octo(loog: Loog::NULL, global:, options: Judges::Options.new({ 'sqlite_cache' => sqlite_cache }))
+        assert_equal('user1', o.user_name_by_id(42))
+      end
+      WebMock.remove_request_stub(stub)
+      stub_request(:get, 'https://api.github.com/user/42')
+        .to_return(
+          status: 200,
+          body: { login: 'user2' }.to_json,
+          headers: {
+            'Content-Type' => 'application/json',
+            'Cache-Control' => 'public, max-age=60, s-maxage=60',
+            'Etag' => 'W/"2ff9dd4c3153f006830b2b8b721f6a4bb400a1eb81a2e1fa0a3b846ad349b9ec"',
+            'Last-Modified' => 'Wed, 01 May 2025 20:00:00 GMT'
+          }
+        )
+      global = {}
+      Fbe.stub_const(:VERSION, '0.0.2') do
+        o = Fbe.octo(loog: Loog::NULL, global:, options: Judges::Options.new({ 'sqlite_cache' => sqlite_cache }))
+        assert_equal('user2', o.user_name_by_id(42))
+      end
+    end
+  end
 end

data/test/test__helper.rb

@@ -31,6 +31,7 @@ end
 require 'minitest/reporters'
 Minitest::Reporters.use! [Minitest::Reporters::SpecReporter.new]
 
+require 'minitest/stub_const'
 require 'minitest/autorun'
 require 'webmock/minitest'
 require_relative '../lib/fbe'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fbe
 version: !ruby/object:Gem::Version
-  version: 0.19.3
+  version: 0.21.0
 platform: ruby
 authors:
 - Yegor Bugayenko