better_auth-redis-storage 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fe62175b11c22a9391598a8252c11a2ea849420d57d8c243054e1025f44ab1c
-  data.tar.gz: ab84235280a0d49103e9f95b178f581cec1b0539b31f962abf49cdee183dc252
+  metadata.gz: f34a3a4a6ddeac7517500d5f886fd427bc7f9473ef0ee101a1d0e00d36f9a5f5
+  data.tar.gz: e00a5743378df1e4712ae318b3787762362d3a2077f8c7163978f518a2b5fc57
 SHA512:
-  metadata.gz: 3764616d585fff3071e54317958feec3613e67e5c73d9cf4e5fac5760a8510990d64bf4161810da1bf35709ff3f396b367f6c9351e81a1acbdbcf57f6bc4d68e
-  data.tar.gz: d26df3f575a4413f14083235edd7092f4a1a077c229faae8babdf3f2104a87830437a3480a91f77f1fb2a3a19e73bdd1bb6175430f3b473ff58f48d1f0a14ebe
+  metadata.gz: 2227f0cf222b1919fa63aa2fd4492b7f0ed8085677216372924492d2f42af701503adf50f4ffe50c3ffd412578e99e64074087aa232a5a4e693ac5c7b174e99c
+  data.tar.gz: a6e673a666c903a19b1ee752d5678f7da2ab2be02380e1e4e8c7710004ff7d7349acfb96e648fbf2bee318e4c95817f4e72e1c8d79b4114be4d0490c16398cb1

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.10.0 - 2026-05-21
+
+- Released in sync with the full Better Auth package set.
+
 ## 0.7.0 - 2026-05-05
 
 - Validate `scan_count` as either `nil` or a positive `Integer`.

data/README.md

@@ -34,11 +34,13 @@ The canonical Ruby form is also supported:
 storage = BetterAuth::RedisStorage.new(client: redis)
 ```
 
-For upstream-shaped call sites, use `BetterAuth.redis_storage(client: redis)` or
-the camelCase class alias:
+For upstream-shaped call sites, use `BetterAuth.redisStorage(client: redis)` or
+the camelCase class alias. The upstream `keyPrefix:` keyword is accepted
+alongside the canonical Ruby `key_prefix:` keyword:
 
 ```ruby
-storage = BetterAuth::RedisStorage.redisStorage(client: redis)
+storage = BetterAuth.redisStorage(client: redis, keyPrefix: "my-app:")
+storage = BetterAuth::RedisStorage.redisStorage(client: redis, keyPrefix: "my-app:")
 ```
 
 ## Configuration
@@ -47,20 +49,25 @@ storage = BetterAuth::RedisStorage.redisStorage(client: redis)
 storage = BetterAuth::RedisStorage.new(
   client: redis,
   key_prefix: "better-auth:",
-  scan_count: nil,
+  scan_count: BetterAuth::RedisStorage::SCAN_DEFAULT_COUNT,
   atomic_clear: false
 )
 ```
 
-`client` must respond to `get`, `set`, `setex`, `del`, and `keys`. It should
-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.
+`client` must respond to `get`, `set`, `setex`, `del`, and `scan`. It should
+also respond to `keys` only when `scan_count: nil` 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.
+`key_prefix` defaults to `"better-auth:"`. `keyPrefix:` is accepted for
+upstream-shaped call sites. 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.
+
+`list_keys` and `clear` escape Redis glob metacharacters in `key_prefix` before
+matching keys, so prefixes containing characters such as `*`, `?`, `[`, `]`, or
+`\` are treated as literal namespace bytes.
 
 > **Warning:** Passing `key_prefix: ""` puts Better Auth keys at the root of
 > the selected Redis logical namespace. `list_keys` and `clear` then match `*`,
@@ -68,14 +75,22 @@ sharing a Redis instance should use distinct prefixes.
 > 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:
+`scan_count` defaults to `BetterAuth::RedisStorage::SCAN_DEFAULT_COUNT` and uses
+Redis `SCAN` for `list_keys` and `clear`. Set `scan_count:` to a larger positive
+count such as `500` or `1000` to tune scan page size:
 
 ```ruby
 storage = BetterAuth::RedisStorage.new(client: redis, scan_count: 500)
 ```
 
+For exact legacy upstream behavior, pass `scan_count: nil` to use blocking
+`KEYS "#{key_prefix}*"`. This is intended only for small or dedicated Redis
+databases because `KEYS` can block Redis while it walks the keyspace:
+
+```ruby
+storage = BetterAuth::RedisStorage.new(client: redis, scan_count: nil)
+```
+
 `atomic_clear` is a Ruby-only opt-in for applications that need `clear` to be
 logically atomic under concurrent writers:
 
@@ -108,7 +123,8 @@ 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
+order for `KEYS` or `SCAN`. The SCAN path removes duplicate cursor results while
+preserving first-seen order. Sort the returned array in application code when a
 stable order matters.
 
 TTL handling for `set(key, value, ttl)`:
@@ -130,12 +146,13 @@ 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.
+large Redis argument lists. The SCAN path collects the matched key set before
+deleting it so cursor iteration is not affected by mutating the keyspace.
 
 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.
+best-effort and uses `SCAN` by default.
 
 Redis Cluster users should treat `list_keys` and `clear` as operationally
 constrained helpers. This adapter does not scan every cluster node, and

data/lib/better_auth/redis_storage/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   class RedisStorage
-    VERSION = "0.8.0"
+    VERSION = "0.10.0"
   end
 end

data/lib/better_auth/redis_storage.rb

@@ -4,28 +4,32 @@ require "better_auth"
 require_relative "redis_storage/version"
 
 module BetterAuth
-  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
+    UNSET = Object.new.freeze
     DEFAULT_KEY_PREFIX = "better-auth:"
     SCAN_DEFAULT_COUNT = 100
     DELETE_CHUNK_SIZE = 500
 
     attr_reader :client, :key_prefix, :scan_count, :atomic_clear
 
-    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)
+    def self.build(client:, key_prefix: UNSET, scan_count: UNSET, atomic_clear: false, **options)
+      key_prefix_camel = extract_key_prefix_camel!(options)
+      reject_unknown_keywords!(options)
+      new(client: client, key_prefix: key_prefix, key_prefix_camel: key_prefix_camel, scan_count: scan_count, atomic_clear: atomic_clear)
     end
 
-    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)
+    def self.redisStorage(client:, key_prefix: UNSET, scan_count: UNSET, atomic_clear: false, **options)
+      key_prefix_camel = extract_key_prefix_camel!(options)
+      reject_unknown_keywords!(options)
+      new(client: client, key_prefix: key_prefix, key_prefix_camel: key_prefix_camel, scan_count: scan_count, atomic_clear: atomic_clear)
     end
 
-    def initialize(client:, key_prefix: DEFAULT_KEY_PREFIX, scan_count: nil, atomic_clear: false)
+    def initialize(client:, key_prefix: UNSET, key_prefix_camel: UNSET, scan_count: UNSET, atomic_clear: false, **options)
+      key_prefix_camel = self.class.extract_key_prefix_camel!(options) if key_prefix_camel.equal?(UNSET)
+      self.class.reject_unknown_keywords!(options)
       @client = client
-      @key_prefix = key_prefix.nil? ? DEFAULT_KEY_PREFIX : key_prefix.to_s
+      @key_prefix = self.class.resolve_key_prefix(key_prefix, key_prefix_camel)
+      scan_count = SCAN_DEFAULT_COUNT if scan_count.equal?(UNSET)
       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
@@ -33,6 +37,28 @@ module BetterAuth
       @atomic_clear = !!atomic_clear
     end
 
+    def self.extract_key_prefix_camel!(options)
+      options.key?(:keyPrefix) ? options.delete(:keyPrefix) : UNSET
+    end
+
+    def self.reject_unknown_keywords!(options)
+      return if options.empty?
+
+      unknown = options.keys.map(&:inspect).join(", ")
+      label = (options.length == 1) ? "keyword" : "keywords"
+      raise ArgumentError, "unknown #{label}: #{unknown}"
+    end
+
+    def self.resolve_key_prefix(key_prefix, key_prefix_camel)
+      if !key_prefix.equal?(UNSET) && !key_prefix_camel.equal?(UNSET) && key_prefix != key_prefix_camel
+        raise ArgumentError, "key_prefix and keyPrefix cannot both be provided with different values"
+      end
+
+      selected = key_prefix.equal?(UNSET) ? key_prefix_camel : key_prefix
+      selected = DEFAULT_KEY_PREFIX if selected.equal?(UNSET) || selected.nil?
+      selected.to_s
+    end
+
     def get(key)
       client.get(prefix_key(key))
     end
@@ -113,30 +139,34 @@ module BetterAuth
     def storage_keys(prefix = storage_prefix)
       return scan_keys(prefix) if scan_count
 
-      client.keys("#{prefix}*")
+      client.keys(match_pattern(prefix))
     end
 
     def scan_keys(prefix = storage_prefix)
+      seen = {}
       matches = []
-      each_scan_batch(prefix) { |keys| matches.concat(keys) }
+      each_scan_batch(prefix) do |keys|
+        keys.each do |key|
+          next if seen[key]
+
+          seen[key] = true
+          matches << key
+        end
+      end
       matches
     end
 
     def each_scan_batch(prefix = storage_prefix)
       cursor = "0"
       loop do
-        cursor, keys = client.scan(cursor, match: "#{prefix}*", count: scan_count)
+        cursor, keys = client.scan(cursor, match: match_pattern(prefix), count: scan_count)
         yield keys
         break if cursor.to_s == "0"
       end
     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
+      delete_keys(storage_keys(prefix), single_key: single_key)
     end
 
     def delete_keys(keys, single_key: false)
@@ -149,6 +179,14 @@ module BetterAuth
       end
     end
 
+    def match_pattern(prefix)
+      "#{redis_glob_escape(prefix)}*"
+    end
+
+    def redis_glob_escape(value)
+      value.to_s.gsub(/[\\*?\[\]]/) { |character| "\\#{character}" }
+    end
+
     def coerce_ttl(ttl)
       numeric = case ttl
       when nil
@@ -171,4 +209,16 @@ module BetterAuth
       seconds.positive? ? seconds : nil
     end
   end
+
+  def self.redis_storage(client:, key_prefix: RedisStorage::UNSET, scan_count: RedisStorage::UNSET, atomic_clear: false, **options)
+    key_prefix_camel = RedisStorage.extract_key_prefix_camel!(options)
+    RedisStorage.reject_unknown_keywords!(options)
+    RedisStorage.new(client: client, key_prefix: key_prefix, key_prefix_camel: key_prefix_camel, scan_count: scan_count, atomic_clear: atomic_clear)
+  end
+
+  def self.redisStorage(client:, key_prefix: RedisStorage::UNSET, scan_count: RedisStorage::UNSET, atomic_clear: false, **options)
+    key_prefix_camel = RedisStorage.extract_key_prefix_camel!(options)
+    RedisStorage.reject_unknown_keywords!(options)
+    RedisStorage.new(client: client, key_prefix: key_prefix, key_prefix_camel: key_prefix_camel, scan_count: scan_count, atomic_clear: atomic_clear)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: better_auth-redis-storage
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Sebastian Sala
@@ -112,14 +112,14 @@ files:
 - README.md
 - lib/better_auth/redis_storage.rb
 - lib/better_auth/redis_storage/version.rb
-homepage: https://github.com/sebasxsala/better-auth
+homepage: https://github.com/sebasxsala/better-auth-rb
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/sebasxsala/better-auth
-  source_code_uri: https://github.com/sebasxsala/better-auth
-  changelog_uri: https://github.com/sebasxsala/better-auth/blob/main/packages/better_auth-redis-storage/CHANGELOG.md
-  bug_tracker_uri: https://github.com/sebasxsala/better-auth/issues
+  homepage_uri: https://github.com/sebasxsala/better-auth-rb
+  source_code_uri: https://github.com/sebasxsala/better-auth-rb
+  changelog_uri: https://github.com/sebasxsala/better-auth-rb/blob/main/packages/better_auth-redis-storage/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sebasxsala/better-auth-rb/issues
 rdoc_options: []
 require_paths:
 - lib