gemstack-cache 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 90c16e71a468d47bb391b18e7251767e2823459c1476557cc08a35f4d08ef88c
+  data.tar.gz: 66e2ecf9b8e4ab685ecca3d61cb829c5017c5073a5e097300170226630c455bc
+SHA512:
+  metadata.gz: 7b42b82a30074d9a61ffb52916cbe4cc5f4c0d5de5995d6f7b98adb0cbfa578a6c1ed6ee80e1cd76ba491bb542cbfd0f9c1439c54609b53ff56beffe9da9c97e
+  data.tar.gz: 47ec9b459862b8181421f300510a7f7bae112b0bead5c4275513fdabeab99877e4798d1ad3613ce963fbbcc12d3fb84075e3a35dbbd4478b904b7b397a0c503e

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,24 @@
+# gemstack-cache
+
+GemStack cache: GemStack.cache.fetch with memory, null and Redis stores.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## 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`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/cache/memory_store.rb

@@ -0,0 +1,69 @@
+# 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

@@ -0,0 +1,18 @@
+# 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

@@ -0,0 +1,70 @@
+# 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

@@ -0,0 +1,89 @@
+# 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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "gemstack/core"
+
+module GemStack
+  # Application caching (DECISIONS D-035):
+  #
+  #   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)

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: gemstack-cache
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gemstack-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+email:
+- gemstack26@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+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
+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
+  bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
+  documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'GemStack cache: GemStack.cache.fetch with memory, null and Redis stores'
+test_files: []