gemstack-cache 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25a46e0050bdcee85e6a3885884b831e248dcd744522a1d8feb47c5f174c7904
-  data.tar.gz: f4c8bc84c9e79ee9929b013224f5680f70f8a974e62dc1a4bf42e0a7ef88be99
+  metadata.gz: 4326f904f232d74d34126acef45bb27e5629ee8d1f7027e837f909b9a2bc9cfb
+  data.tar.gz: ddc9bcc0139cf7d102ec78a4f280888f834a014fa67174104d73b5f683e06d87
 SHA512:
-  metadata.gz: 428fae85e4443fa3fb759a6aa7476ab5b4e0dbabcf32540584cde634709f1cd1726c28c946b9c20ae9a8f4fd8ed11e19fb3d2657168b8a31efcf23796e3a6c28
-  data.tar.gz: 7fd29db35be70ee1979aa2d7e1293e83f1ee8610a3b34e7cd60a45ebf9e4be72dfcb3b33edecca7897930f3afc1f75276ac2d18e1a0fc6ab2336b71b18404436
+  metadata.gz: fc4d58e8b4e7815610f3f9ae0ead1a4505bd4e34a0aa0137bc4727cb132c7dccb856d25fabebd4c19201d6d7cbf3dae72987790ecb0fc15a6670dc35cca977e7
+  data.tar.gz: 94419821fe5956f92ece4907ab2f783beca7e1767fe79b9abd3d5975897431bc7b9d575a7b28dc4aed4de3ca3236fe1f846ffbabae86a3d7d068115d2fc96665

data/CHANGELOG.md

@@ -1,29 +1,5 @@
 # Changelog
 
-## 0.2.5
+## 0.3.0
 
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.4
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.3
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.2
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.1
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.2.0
-
-See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
-
-## 0.1.0
-
-First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+Merged into the gemstack gem; this version is a transition shim. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/README.md

@@ -1,23 +1,13 @@
 # gemstack-cache
 
-GemStack cache: GemStack.cache.fetch with memory, null and Redis stores.
+**Merged into [`gemstack`](https://rubygems.org/gems/gemstack) in GemStack 0.3.0.**
 
-Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
-applications by [Adware Technologies](https://www.adwaretech.com). All GemStack gems are developed together in that repository and released with the same
-version.
+This version is a transition shim: it depends on `gemstack` and loads `gemstack/cache`, so
+Gemfiles that still list `gemstack-cache` keep working. To finish upgrading, remove `gem "gemstack-cache"`
+from your Gemfile (it's loaded by `require "gemstack"`).
 
-## Installation
-
-Installed with the `gemstack` gem; you rarely need to add it yourself.
-
-## Documentation
-
-- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/caching.md)
-- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
-  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
-
-Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
-(this gem lives in `gems/gemstack-cache`).
+GemStack is a modular Ruby API framework for Next.js applications by
+[Adware Technologies](https://www.adwaretech.com) — [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack).
 
 ## License
 

data/lib/gemstack-cache.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# gemstack-cache is part of the gemstack gem since 0.3.0. This shim keeps Gemfiles
+# that still list gemstack-cache working; remove the line from your Gemfile.
+require "gemstack/cache"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemstack-cache
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.3.0
 platform: ruby
 authors:
 - Adware Technologies
@@ -11,19 +11,28 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: gemstack-core
+  name: gemstack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: 0.3.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: '1.0'
+description: Since GemStack 0.3.0, gemstack-cache is part of the gemstack gem. This
+  version only depends on gemstack and loads gemstack/cache, so Gemfiles that still
+  list it keep working.
 email:
 - gemstack26@gmail.com
 executables: []
@@ -33,20 +42,18 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- lib/gemstack/cache.rb
-- lib/gemstack/cache/memory_store.rb
-- lib/gemstack/cache/null_store.rb
-- lib/gemstack/cache/redis_store.rb
-- lib/gemstack/cache/store.rb
+- lib/gemstack-cache.rb
 homepage: https://github.com/gemstack-rb/gemstack
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/gemstack-rb/gemstack/tree/main/gems/gemstack-cache
-  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/gems/gemstack-cache/CHANGELOG.md
+  source_code_uri: https://github.com/gemstack-rb/gemstack
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
   documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+post_install_message: gemstack-cache is now part of the gemstack gem. Remove `gem
+  "gemstack-cache"` from your Gemfile (it's loaded by `require "gemstack"`).
 rdoc_options: []
 require_paths:
 - lib
@@ -63,5 +70,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: 'GemStack cache: GemStack.cache.fetch with memory, null and Redis stores'
+summary: Merged into the gemstack gem — remove gemstack-cache from your Gemfile
 test_files: []

data/lib/gemstack/cache/memory_store.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-module GemStack
-  module Cache
-    # A thread-safe, per-process LRU cache with expiry. Values are stored
-    # marshalled, so callers never share (and can't mutate) cached objects —
-    # the same semantics as the Redis store. With several Puma workers each
-    # has its own copy; use Redis to share a cache across processes.
-    class MemoryStore < Store
-      Entry = Struct.new(:data, :expires_at)
-
-      def initialize(max_entries: 10_000, **)
-        super(**)
-        @max_entries = max_entries
-        @entries = {}
-        @mutex = Mutex.new
-      end
-
-      def size = @entries.size
-      def clear = @mutex.synchronize { @entries.clear }
-
-      def increment(key, by = 1, expires_in: default_expires_in)
-        normalized = normalize(key)
-        @mutex.synchronize do
-          entry = live_entry(normalized)
-          value = (entry ? Integer(load(entry.data)) : 0) + by
-          store(normalized, value, entry ? entry.expires_at : expires_at(expires_in))
-          value
-        end
-      end
-
-      private
-
-      def read_entry(key)
-        @mutex.synchronize do
-          entry = live_entry(key) or return MISSING
-          @entries[key] = @entries.delete(key) # mark as most recently used
-          load(entry.data)
-        end
-      end
-
-      def write_entry(key, value, expires_in)
-        data = dump(value)
-        @mutex.synchronize { store_data(key, data, expires_at(expires_in)) }
-      end
-
-      def delete_entry(key) = @mutex.synchronize { !@entries.delete(key).nil? }
-
-      # Callers hold the mutex.
-      def live_entry(key)
-        entry = @entries[key]
-        return nil unless entry
-        return entry unless entry.expires_at && entry.expires_at <= monotonic
-
-        @entries.delete(key)
-        nil
-      end
-
-      def store(key, value, expires_at) = store_data(key, dump(value), expires_at)
-
-      def store_data(key, data, expires_at)
-        @entries.delete(key)
-        @entries[key] = Entry.new(data, expires_at)
-        @entries.shift while @entries.size > @max_entries # Hash order = LRU order
-        true
-      end
-    end
-  end
-end

data/lib/gemstack/cache/null_store.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module GemStack
-  module Cache
-    # Caches nothing: fetch always runs its block. The default in tests, so
-    # tests never depend on state cached by earlier tests.
-    class NullStore < Store
-      def clear = true
-      def increment(_key, by = 1, **) = by
-
-      private
-
-      def read_entry(_key) = MISSING
-      def write_entry(_key, _value, _expires_in) = true
-      def delete_entry(_key) = false
-    end
-  end
-end

data/lib/gemstack/cache/redis_store.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-module GemStack
-  module Cache
-    # A cache shared by every process, through Redis. Uses the `redis-client`
-    # gem (add `gem "redis-client"` to the Gemfile) with a connection pool
-    # sized to the server's threads, or any client object you pass that
-    # responds to #call(*command) (a redis-client pool or connection).
-    #
-    #   config.cache.store = :redis                      # REDIS_URL
-    #   config.cache.store = GemStack::Cache::RedisStore.new(client: my_pool, namespace: "shop")
-    class RedisStore < Store
-      attr_reader :client
-
-      def initialize(url: nil, client: nil, pool_size: 5, **)
-        super(**)
-        @client = client || build_client(url, pool_size)
-      end
-
-      def increment(key, by = 1, expires_in: default_expires_in)
-        normalized = normalize(key)
-        value = client.call("INCRBY", normalized, by)
-        client.call("PEXPIRE", normalized, (Float(expires_in) * 1000).round, "NX") if expires_in
-        value
-      end
-
-      # Deletes only keys in this store's namespace (never FLUSHDB).
-      def clear
-        raise Error, "RedisStore#clear needs a namespace (config.cache.namespace)" unless namespace
-
-        cursor = "0"
-        loop do
-          cursor, keys = client.call("SCAN", cursor, "MATCH", "#{namespace}:*", "COUNT", 500)
-          client.call("UNLINK", *keys) unless keys.empty?
-          break if cursor == "0"
-        end
-        true
-      end
-
-      private
-
-      def read_entry(key)
-        data = client.call("GET", key)
-        return MISSING if data.nil?
-
-        # Counters are stored as plain integers so INCRBY works on them.
-        data.match?(/\A-?\d+\z/) ? Integer(data) : load(data.b)
-      end
-
-      def write_entry(key, value, expires_in)
-        data = value.is_a?(Integer) ? value.to_s : dump(value)
-        if expires_in
-          client.call("SET", key, data, "PX", (Float(expires_in) * 1000).round)
-        else
-          client.call("SET", key, data)
-        end
-        true
-      end
-
-      def delete_entry(key) = client.call("DEL", key).positive?
-
-      def build_client(url, pool_size)
-        require "redis-client"
-        RedisClient.config(url: url).new_pool(size: pool_size, timeout: 1.0)
-      rescue LoadError
-        raise ConfigurationError, 'the Redis cache store needs `gem "redis-client"` in the Gemfile'
-      end
-    end
-  end
-end

data/lib/gemstack/cache/store.rb

@@ -1,89 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-
-module GemStack
-  module Cache
-    # The store interface. Subclasses implement read_entry / write_entry /
-    # delete_entry / clear (and may override increment for atomicity).
-    #
-    # Keys may be strings, symbols, arrays of parts, or objects with
-    # #cache_key (GemStack models have one); they are namespaced and hashed
-    # when longer than MAX_KEY bytes. Values must be Marshal-able.
-    class Store
-      MAX_KEY = 200
-      MISSING = Object.new.freeze
-
-      attr_reader :namespace, :default_expires_in
-
-      def initialize(namespace: nil, default_expires_in: nil)
-        @namespace = namespace&.to_s
-        @default_expires_in = default_expires_in
-      end
-
-      # Returns the cached value, or computes it with the block, stores and
-      # returns it. nil results are cached too. force: true recomputes.
-      def fetch(key, expires_in: default_expires_in, force: false)
-        normalized = normalize(key)
-        unless force
-          value = read_entry(normalized)
-          return value unless value.equal?(MISSING)
-        end
-        raise ArgumentError, "fetch needs a block on a cache miss" unless block_given?
-
-        value = yield
-        write_entry(normalized, value, expires_in)
-        value
-      end
-
-      def read(key)
-        value = read_entry(normalize(key))
-        value.equal?(MISSING) ? nil : value
-      end
-
-      def write(key, value, expires_in: default_expires_in)
-        write_entry(normalize(key), value, expires_in)
-        value
-      end
-
-      def exist?(key) = !read_entry(normalize(key)).equal?(MISSING)
-      def delete(key) = delete_entry(normalize(key))
-
-      # Not atomic in the base class; stores override it where they can.
-      def increment(key, by = 1, expires_in: default_expires_in)
-        normalized = normalize(key)
-        current = read_entry(normalized)
-        value = (current.equal?(MISSING) ? 0 : Integer(current)) + by
-        write_entry(normalized, value, expires_in)
-        value
-      end
-
-      def decrement(key, by = 1, **) = increment(key, -by, **)
-
-      def normalize(key)
-        raw = key_part(key)
-        full = namespace ? "#{namespace}:#{raw}" : raw
-        full.bytesize > MAX_KEY ? "#{full[0, 100]}:sha256:#{Digest::SHA256.hexdigest(full)}" : full
-      end
-
-      private
-
-      def key_part(key)
-        case key
-        when Array then key.map { |part| key_part(part) }.join("/")
-        when String, Symbol, Numeric then key.to_s
-        else key.respond_to?(:cache_key) ? key.cache_key.to_s : key.to_s
-        end
-      end
-
-      def dump(value) = Marshal.dump(value)
-      def load(data) = Marshal.load(data) # rubocop:disable Security/MarshalLoad -- only data this process wrote
-
-      def expires_at(expires_in)
-        expires_in ? monotonic + Float(expires_in) : nil
-      end
-
-      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-    end
-  end
-end

data/lib/gemstack/cache.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require "gemstack/core"
-
-module GemStack
-  # Application caching:
-  #
-  #   GemStack.cache.fetch("product:#{id}", expires_in: 300) { Product.find(id) }
-  #   GemStack.cache.fetch([:stats, Date.today]) { expensive_report }   # array keys
-  #   GemStack.cache.increment("signups")
-  #   GemStack.cache.delete("product:#{id}")
-  #
-  # Stores are swappable (config.cache.store): :memory (default), :null
-  # (default in test), :redis, or any object implementing the Store interface.
-  # Redis is never required.
-  module Cache
-    class Config < Settings
-      setting :store, default: -> { GemStack.env.test? ? :null : :memory }
-      # Prefix for every key ("shop:product:1"). Required for Redis#clear.
-      setting :namespace, default: -> { GemStack.config.name }
-      # Seconds; nil = no expiry unless given per call.
-      setting :default_expires_in, default: nil
-      # MemoryStore: maximum entries per process before the least recently used are evicted.
-      setting :max_entries, default: 10_000
-      setting :redis_url, default: -> { ENV.fetch("REDIS_URL", "redis://localhost:6379/0") }
-      setting :redis_pool_size, default: -> { Integer(ENV.fetch("GEMSTACK_MAX_THREADS", 5)) }
-    end
-
-    class << self
-      def build(setting = GemStack.config.cache.store, config: GemStack.config.cache)
-        options = { namespace: config.namespace, default_expires_in: config.default_expires_in }
-        case setting
-        when :memory, "memory" then MemoryStore.new(max_entries: config.max_entries, **options)
-        when :null, "null" then NullStore.new(**options)
-        when :redis, "redis"
-          RedisStore.new(url: config.redis_url, pool_size: config.redis_pool_size, **options)
-        when Store then setting
-        else
-          raise ConfigurationError, "unknown cache store #{setting.inspect}" unless setting.respond_to?(:fetch)
-
-          setting
-        end
-      end
-    end
-  end
-
-  class << self
-    def cache
-      @cache ||= Cache.build
-    end
-
-    attr_writer :cache
-  end
-end
-
-require_relative "cache/store"
-require_relative "cache/memory_store"
-require_relative "cache/null_store"
-require_relative "cache/redis_store"
-
-GemStack::Config.namespace(:cache, GemStack::Cache::Config)