better_auth-redis-storage 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17fa8afb46d292631de0909478ece0012c2b77dd1e08c6381c522992ca29584c
-  data.tar.gz: cbfec6b35cb9b1b65c6ecfa2b40873cc38545d2694a2fc731081e6457945bd87
+  metadata.gz: bf3169d1223b56ee0f482b4eb81c7d748f1014bbd52c43a98e83bea301155820
+  data.tar.gz: 6e00528c060b9cd991dfbb8e204bd736c81b931140d168b1a40b1ed9e4a33ba8
 SHA512:
-  metadata.gz: 254e99d01478165d5b559f6e6fe552ef75c5d5a0513691768d630ebc4aedddd981f6ba15b45de927944a491af8c517b77b0dda0ca8b9fde5d271e2f6d0f8af0b
-  data.tar.gz: fb2a10201de2b4c05ba58770205d0bdb4f702a1468818c49d00c118f770b2cd1a75fe21e7859b0cfe5744dac3e7b93f48f1154aa8c9c24d543196d58af3434a0
+  metadata.gz: fe7311656877d8aa018c6644d795bf1dbc0111640458f7de9fe8ab17991d72c26bb81624271e0267f4be8a540482e729e98f77413714c9f5507aca51eef3b403
+  data.tar.gz: ccbacf369690383a7798049b09fcc4c6e1b04e3fdb9fed42f97908ad677cd7de6243cdc3875dd7b2573bfb5440ce302489431e57c030cbf3bbd8b191632a366d

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 0.7.0 - 2026-05-05
+
+- Validate `scan_count` as either `nil` or a positive `Integer`.
+- Reject `nil` logical keys before prefixing Redis keys.
+- Coerce positive finite non-Integer `Numeric` TTL values for `SETEX`.
+- Fall back to plain `SET` for positive sub-second numeric TTLs that would truncate to `0`.
+- Delete `clear` matches in chunks to avoid oversized Redis `DEL` commands.
+- Stream `clear` deletion by `SCAN` page when `scan_count:` is configured.
+- Add `atomic_clear:` opt-in generation-scoped keys so `clear` is logically atomic under concurrent writers.
+- Run the real Redis integration suite explicitly in CI and release verification.
+- Document Redis operational caveats for empty prefixes, key ordering, TTLs, and clusters.
+
 ## 0.2.0 - 2026-04-29
 
 - Add `BetterAuth.redis_storage` and `BetterAuth::RedisStorage.redisStorage` builders for upstream-shaped Redis storage configuration.

data/README.md

@@ -47,19 +47,27 @@ storage = BetterAuth::RedisStorage.redisStorage(client: redis)
 storage = BetterAuth::RedisStorage.new(
   client: redis,
   key_prefix: "better-auth:",
-  scan_count: nil
+  scan_count: nil,
+  atomic_clear: false
 )
 ```
 
 `client` must respond to `get`, `set`, `setex`, `del`, and `keys`. It should
-also respond to `scan` when `scan_count:` is configured. This matches the
-interfaces exposed by the `redis` and `redis-namespace` gems.
+also respond to `scan` when `scan_count:` is configured, and to `incr` when
+`atomic_clear:` is enabled. This matches the interfaces exposed by the `redis`
+and `redis-namespace` gems.
 
 `key_prefix` defaults to `"better-auth:"`. Passing `nil` falls back to the
 default. Any other value, including the empty string, is honored verbatim.
 Redis databases are not isolation boundaries for shared clients; applications
 sharing a Redis instance should use distinct prefixes.
 
+> **Warning:** Passing `key_prefix: ""` puts Better Auth keys at the root of
+> the selected Redis logical namespace. `list_keys` and `clear` then match `*`,
+> so collisions across apps or tenants are possible and `clear` deletes every
+> key in that Redis database. Use an application-specific prefix unless the
+> Redis database is fully dedicated to Better Auth.
+
 `scan_count` is a Ruby-only opt-in for large Redis databases. By default the gem
 uses `KEYS "#{key_prefix}*"` to match upstream exactly. Set `scan_count:` to a
 positive count such as `100`, `500`, or `1000` to use `SCAN` instead:
@@ -68,6 +76,23 @@ positive count such as `100`, `500`, or `1000` to use `SCAN` instead:
 storage = BetterAuth::RedisStorage.new(client: redis, scan_count: 500)
 ```
 
+`atomic_clear` is a Ruby-only opt-in for applications that need `clear` to be
+logically atomic under concurrent writers:
+
+```ruby
+storage = BetterAuth::RedisStorage.new(
+  client: redis,
+  scan_count: 500,
+  atomic_clear: true
+)
+```
+
+When enabled, data keys are stored under a generation prefix such as
+`better-auth:v1:<key>`. Calling `clear` atomically increments the generation key
+so new reads and writes immediately move to the next generation. The previous
+generation is then deleted best-effort, but correctness does not depend on that
+physical cleanup finishing immediately.
+
 ## Behavior
 
 The storage object implements the Better Auth secondary storage contract:
@@ -82,13 +107,18 @@ storage.clear
 
 `listKeys` is available as a camelCase alias for upstream parity.
 
+`list_keys` returns every matching logical key but Redis does not guarantee key
+order for `KEYS` or `SCAN`. Sort the returned array in application code when a
+stable order matters.
+
 TTL handling for `set(key, value, ttl)`:
 
 | TTL value | Redis command |
 | --- | --- |
-| `nil`, non-numeric strings, `0`, negative numbers | `set(prefixed_key, value)` |
+| `nil`, non-numeric strings, `0`, negative numbers, non-finite numbers | `set(prefixed_key, value)` |
 | Positive `Integer` | `setex(prefixed_key, ttl, value)` |
-| Positive `Float` | `setex(prefixed_key, ttl.to_i, value)` |
+| Positive finite `Float` or other `Numeric` values `>= 1` | `setex(prefixed_key, ttl.to_i, value)` |
+| Positive finite `Float` or other `Numeric` values `< 1` | `set(prefixed_key, value)` |
 | Positive numeric `String` | `setex(prefixed_key, ttl.to_i, value)` |
 
 `set`, `delete`, and `clear` return `nil`, mirroring upstream's `Promise<void>`
@@ -98,6 +128,23 @@ contract in Ruby form. Tests and applications should assert stored values via
 `clear` intentionally differs from upstream when there are no matching keys:
 upstream calls `del(...keys)` even when `keys` is empty, while this Ruby gem
 skips `del` to avoid Redis `ERR wrong number of arguments for 'del'`.
+When keys do exist, `clear` deletes them in batches of
+`BetterAuth::RedisStorage::DELETE_CHUNK_SIZE` keys per `del` call to avoid very
+large Redis argument lists.
+
+With `atomic_clear: true`, `clear` increments a generation key with Redis
+`INCR`, making old generation keys immediately invisible to `get`, `set`,
+`delete`, `list_keys`, and Better Auth itself. Cleanup of the old generation is
+best-effort and uses `SCAN` when `scan_count:` is configured.
+
+Redis Cluster users should treat `list_keys` and `clear` as operationally
+constrained helpers. This adapter does not scan every cluster node, and
+multi-key `del` calls require keys to live in a compatible hash slot. Prefer a
+single-slot prefix strategy such as Redis hash tags when using these helpers in
+clustered deployments. `atomic_clear: true` improves the logical `clear`
+contract because correctness uses a single `INCR` generation key, but physical
+cleanup of old generations remains subject to the connected client's scan
+coverage.
 
 ## Better Auth Usage
 

data/lib/better_auth/redis_storage/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   class RedisStorage
-    VERSION = "0.6.2"
+    VERSION = "0.7.0"
   end
 end

data/lib/better_auth/redis_storage.rb

@@ -4,28 +4,33 @@ require "better_auth"
 require_relative "redis_storage/version"
 
 module BetterAuth
-  def self.redis_storage(client:, key_prefix: RedisStorage::DEFAULT_KEY_PREFIX, scan_count: nil)
-    RedisStorage.new(client: client, key_prefix: key_prefix, scan_count: scan_count)
+  def self.redis_storage(client:, key_prefix: RedisStorage::DEFAULT_KEY_PREFIX, scan_count: nil, atomic_clear: false)
+    RedisStorage.new(client: client, key_prefix: key_prefix, scan_count: scan_count, atomic_clear: atomic_clear)
   end
 
   class RedisStorage
     DEFAULT_KEY_PREFIX = "better-auth:"
     SCAN_DEFAULT_COUNT = 100
+    DELETE_CHUNK_SIZE = 500
 
-    attr_reader :client, :key_prefix, :scan_count
+    attr_reader :client, :key_prefix, :scan_count, :atomic_clear
 
-    def self.build(client:, key_prefix: DEFAULT_KEY_PREFIX, scan_count: nil)
-      new(client: client, key_prefix: key_prefix, scan_count: scan_count)
+    def self.build(client:, key_prefix: DEFAULT_KEY_PREFIX, scan_count: nil, atomic_clear: false)
+      new(client: client, key_prefix: key_prefix, scan_count: scan_count, atomic_clear: atomic_clear)
     end
 
-    def self.redisStorage(client:, key_prefix: DEFAULT_KEY_PREFIX, scan_count: nil)
-      new(client: client, key_prefix: key_prefix, scan_count: scan_count)
+    def self.redisStorage(client:, key_prefix: DEFAULT_KEY_PREFIX, scan_count: nil, atomic_clear: false)
+      new(client: client, key_prefix: key_prefix, scan_count: scan_count, atomic_clear: atomic_clear)
     end
 
-    def initialize(client:, key_prefix: DEFAULT_KEY_PREFIX, scan_count: nil)
+    def initialize(client:, key_prefix: DEFAULT_KEY_PREFIX, scan_count: nil, atomic_clear: false)
       @client = client
       @key_prefix = key_prefix.nil? ? DEFAULT_KEY_PREFIX : key_prefix.to_s
+      if !scan_count.nil? && !(scan_count.is_a?(Integer) && scan_count.positive?)
+        raise ArgumentError, "scan_count must be nil or a positive Integer; got #{scan_count.inspect}"
+      end
       @scan_count = scan_count
+      @atomic_clear = !!atomic_clear
     end
 
     def get(key)
@@ -49,14 +54,16 @@ module BetterAuth
     end
 
     def list_keys
-      storage_keys.map { |key| unprefix_key(key) }
+      prefix = storage_prefix
+      storage_keys(prefix).map { |key| unprefix_key(key, prefix) }
     end
 
     def clear
-      keys = storage_keys
-      # Upstream calls del(...keys) unconditionally; Ruby keeps this guard to
-      # avoid Redis ERR wrong number of arguments when no prefixed keys exist.
-      client.del(*keys) unless keys.empty?
+      if atomic_clear
+        clear_current_generation
+      else
+        delete_matching_keys(storage_prefix)
+      end
       nil
     end
 
@@ -65,28 +72,81 @@ module BetterAuth
     private
 
     def prefix_key(key)
-      "#{key_prefix}#{key}"
+      raise ArgumentError, "secondary storage key must not be nil" if key.nil?
+
+      "#{storage_prefix}#{key}"
     end
 
-    def unprefix_key(key)
-      key.sub(/\A#{Regexp.escape(key_prefix)}/, "")
+    def unprefix_key(key, prefix = storage_prefix)
+      key.sub(/\A#{Regexp.escape(prefix)}/, "")
     end
 
-    def storage_keys
-      return scan_keys if scan_count
+    def storage_prefix(generation = current_generation)
+      return key_prefix unless atomic_clear
 
-      client.keys("#{key_prefix}*")
+      "#{key_prefix}v#{generation}:"
     end
 
-    def scan_keys
-      cursor = "0"
+    def generation_key
+      "#{key_prefix}__generation__"
+    end
+
+    def current_generation
+      return nil unless atomic_clear
+
+      generation = client.get(generation_key).to_i
+      generation.positive? ? generation : 1
+    end
+
+    def clear_current_generation
+      generation = current_generation
+      bump_generation(generation)
+      delete_matching_keys(storage_prefix(generation), single_key: true)
+    end
+
+    def bump_generation(previous_generation)
+      generation = client.incr(generation_key).to_i
+      generation = client.incr(generation_key).to_i if generation <= previous_generation.to_i
+      generation
+    end
+
+    def storage_keys(prefix = storage_prefix)
+      return scan_keys(prefix) if scan_count
+
+      client.keys("#{prefix}*")
+    end
+
+    def scan_keys(prefix = storage_prefix)
       matches = []
+      each_scan_batch(prefix) { |keys| matches.concat(keys) }
+      matches
+    end
+
+    def each_scan_batch(prefix = storage_prefix)
+      cursor = "0"
       loop do
-        cursor, keys = client.scan(cursor, match: "#{key_prefix}*", count: scan_count)
-        matches.concat(keys)
+        cursor, keys = client.scan(cursor, match: "#{prefix}*", count: scan_count)
+        yield keys
         break if cursor.to_s == "0"
       end
-      matches
+    end
+
+    def delete_matching_keys(prefix, single_key: false)
+      if scan_count
+        each_scan_batch(prefix) { |keys| delete_keys(keys, single_key: single_key) }
+      else
+        delete_keys(storage_keys(prefix), single_key: single_key)
+      end
+    end
+
+    def delete_keys(keys, single_key: false)
+      # Upstream calls del(...keys) unconditionally; Ruby keeps this guard to
+      # avoid Redis ERR wrong number of arguments when no prefixed keys exist.
+      if single_key
+        keys.each { |key| client.del(key) }
+      else
+        keys.each_slice(DELETE_CHUNK_SIZE) { |chunk| client.del(*chunk) }
+      end
     end
 
     def coerce_ttl(ttl)
@@ -96,12 +156,19 @@ module BetterAuth
       when Integer
         ttl
       when Float
-        ttl.to_i
+        ttl.finite? ? ttl : nil
       when String
         Integer(ttl, exception: false)
+      when Numeric
+        ttl.to_f
       end
 
-      numeric&.positive? ? numeric : nil
+      return nil unless numeric.is_a?(Numeric)
+      return nil unless numeric.respond_to?(:positive?) && numeric.positive?
+      return nil if numeric.respond_to?(:finite?) && !numeric.finite?
+
+      seconds = numeric.is_a?(Integer) ? numeric : numeric.to_i
+      seconds.positive? ? seconds : nil
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_auth-redis-storage
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Sebastian Sala