better_auth-redis-storage 0.1.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fec3e6f91d2678257084d87d27d230b401dde8dc9c4d852e47d5a0bc5c910de8
-  data.tar.gz: 5eee5736114ba877ba5e7308ba5da7d400a08686b9b46d01a98e57fda4bb24cc
+  metadata.gz: 93c01dd5ff213cf3095641e36d70bd2b4e0d80ce7d344688ed830e01d4ad43e6
+  data.tar.gz: 9e416e99e8c8d4df05e71c5cf1af743f43e50d99009beefb502280c49c42e726
 SHA512:
-  metadata.gz: 3890b8e529be3471125825d684da70a0280988c6c554683bfbabba6cc26612ca0d3508377ae49592c323101b2f52feb363807e996236b2c2a76640a949253226
-  data.tar.gz: bf77b96b0f29ad9c86a4ae11fc00c92a6a6a9f28aa8e02d233c4ae38a39285a63bd126b90c1b41dadc4490f993fdc88f1d0829e8b5af8fa27cff157d5f8e56fe
+  metadata.gz: dd78bfd531a72e64fb05a338261f37daaedaf5b3c32cb262b77b92bfdb6b611194e1d64b583f18c1922520affe52f6ab9f247de1613348be13b6b52a7234df41
+  data.tar.gz: 2d54b9ffe8517dd5e4729c3ef6a010b60f57015b9b05f52a3e7fab281b56037ee544e0936dca420249d4e3aeff84721524639e01cccc30fa4913184158f4496a

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.0 - 2026-04-29
+
+- Add `BetterAuth.redis_storage` and `BetterAuth::RedisStorage.redisStorage` builders for upstream-shaped Redis storage configuration.
+- Add optional `scan_count:` support to use Redis `SCAN` instead of upstream-compatible `KEYS`.
+- Split real Redis coverage into a `REDIS_INTEGRATION=1` integration suite and expand secondary-storage compatibility tests.
+
 ## 0.1.0
 
 - Initial Redis secondary storage package for Better Auth Ruby.
-

data/README.md

@@ -2,6 +2,11 @@
 
 Redis secondary storage package for Better Auth Ruby.
 
+This gem tracks the server-side behavior of upstream `@better-auth/redis-storage`
+pinned at Better Auth `v1.6.9`. The Ruby gem versions independently from the
+upstream npm package; `BetterAuth::RedisStorage::VERSION` is the Ruby gem
+version.
+
 ## Installation
 
 Add the gem and require the package before configuring auth:
@@ -19,13 +24,114 @@ redis = Redis.new(url: ENV.fetch("REDIS_URL"))
 auth = BetterAuth.auth(
   secret: ENV.fetch("BETTER_AUTH_SECRET"),
   database: :memory,
-  secondary_storage: BetterAuth::RedisStorage.new(client: redis)
+  secondary_storage: BetterAuth.redis_storage(client: redis)
+)
+```
+
+The canonical Ruby form is also supported:
+
+```ruby
+storage = BetterAuth::RedisStorage.new(client: redis)
+```
+
+For upstream-shaped call sites, use `BetterAuth.redis_storage(client: redis)` or
+the camelCase class alias:
+
+```ruby
+storage = BetterAuth::RedisStorage.redisStorage(client: redis)
+```
+
+## Configuration
+
+```ruby
+storage = BetterAuth::RedisStorage.new(
+  client: redis,
+  key_prefix: "better-auth:",
+  scan_count: nil
+)
+```
+
+`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.
+
+`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.
+
+`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:
+
+```ruby
+storage = BetterAuth::RedisStorage.new(client: redis, scan_count: 500)
+```
+
+## Behavior
+
+The storage object implements the Better Auth secondary storage contract:
+
+```ruby
+storage.get(key)
+storage.set(key, value, ttl = nil)
+storage.delete(key)
+storage.list_keys
+storage.clear
+```
+
+`listKeys` is available as a camelCase alias for upstream parity.
+
+TTL handling for `set(key, value, ttl)`:
+
+| TTL value | Redis command |
+| --- | --- |
+| `nil`, non-numeric strings, `0`, negative numbers | `set(prefixed_key, value)` |
+| Positive `Integer` | `setex(prefixed_key, ttl, value)` |
+| Positive `Float` | `setex(prefixed_key, ttl.to_i, value)` |
+| Positive numeric `String` | `setex(prefixed_key, ttl.to_i, value)` |
+
+`set`, `delete`, and `clear` return `nil`, mirroring upstream's `Promise<void>`
+contract in Ruby form. Tests and applications should assert stored values via
+`get` rather than relying on truthy return values.
+
+`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'`.
+
+## Better Auth Usage
+
+`secondary_storage` is used by Better Auth for session payload storage,
+active-session indexes, verification values, and rate limiting when
+`rate_limit: { storage: "secondary-storage" }` is configured.
+
+```ruby
+auth = BetterAuth.auth(
+  secret: ENV.fetch("BETTER_AUTH_SECRET"),
+  database: :memory,
+  secondary_storage: BetterAuth.redis_storage(client: redis),
+  rate_limit: { storage: "secondary-storage", enabled: true }
 )
 ```
 
-## Notes
+Custom secondary storage backends should implement:
 
-This package depends on the official `redis` gem. Keeping Redis storage outside `better_auth` avoids installing Redis client dependencies for applications that do not use secondary storage.
+- `get(key)`
+- `set(key, value, ttl = nil)`
+- `delete(key)`
+- Optional: `list_keys` or `listKeys`
+- Optional: `clear`
 
-`secondary_storage` is used by Better Auth for session payload storage, active-session indexes, and rate limiting when `rate_limit: { storage: "secondary-storage" }` is configured.
+## Testing
 
+The normal unit suite skips real Redis unless explicitly enabled:
+
+```bash
+bundle exec rake test
+```
+
+Run the Redis integration suite with:
+
+```bash
+REDIS_INTEGRATION=1 REDIS_URL=redis://localhost:6379/15 bundle exec rake test:integration
+```

data/lib/better_auth/redis_storage/version.rb

@@ -2,6 +2,6 @@
 
 module BetterAuth
   class RedisStorage
-    VERSION = "0.1.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/better_auth/redis_storage.rb

@@ -4,18 +4,28 @@ 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)
+  end
+
   class RedisStorage
     DEFAULT_KEY_PREFIX = "better-auth:"
+    SCAN_DEFAULT_COUNT = 100
 
-    attr_reader :client, :key_prefix
+    attr_reader :client, :key_prefix, :scan_count
+
+    def self.build(client:, key_prefix: DEFAULT_KEY_PREFIX, scan_count: nil)
+      new(client: client, key_prefix: key_prefix, scan_count: scan_count)
+    end
 
-    def self.build(client:, key_prefix: DEFAULT_KEY_PREFIX)
-      new(client: client, key_prefix: key_prefix)
+    def self.redisStorage(client:, key_prefix: DEFAULT_KEY_PREFIX, scan_count: nil)
+      new(client: client, key_prefix: key_prefix, scan_count: scan_count)
     end
 
-    def initialize(client:, key_prefix: DEFAULT_KEY_PREFIX)
+    def initialize(client:, key_prefix: DEFAULT_KEY_PREFIX, scan_count: nil)
       @client = client
-      @key_prefix = key_prefix.to_s
+      @key_prefix = key_prefix.nil? ? DEFAULT_KEY_PREFIX : key_prefix.to_s
+      @scan_count = scan_count
     end
 
     def get(key)
@@ -24,24 +34,30 @@ module BetterAuth
 
     def set(key, value, ttl = nil)
       prefixed_key = prefix_key(key)
-      if ttl&.to_i&.positive?
-        client.setex(prefixed_key, ttl.to_i, value)
+      coerced_ttl = coerce_ttl(ttl)
+      if coerced_ttl
+        client.setex(prefixed_key, coerced_ttl, value)
       else
         client.set(prefixed_key, value)
       end
+      nil
     end
 
     def delete(key)
       client.del(prefix_key(key))
+      nil
     end
 
     def list_keys
-      client.keys("#{key_prefix}*").map { |key| unprefix_key(key) }
+      storage_keys.map { |key| unprefix_key(key) }
     end
 
     def clear
-      keys = client.keys("#{key_prefix}*")
+      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?
+      nil
     end
 
     alias_method :listKeys, :list_keys
@@ -55,5 +71,37 @@ module BetterAuth
     def unprefix_key(key)
       key.sub(/\A#{Regexp.escape(key_prefix)}/, "")
     end
+
+    def storage_keys
+      return scan_keys if scan_count
+
+      client.keys("#{key_prefix}*")
+    end
+
+    def scan_keys
+      cursor = "0"
+      matches = []
+      loop do
+        cursor, keys = client.scan(cursor, match: "#{key_prefix}*", count: scan_count)
+        matches.concat(keys)
+        break if cursor.to_s == "0"
+      end
+      matches
+    end
+
+    def coerce_ttl(ttl)
+      numeric = case ttl
+      when nil
+        nil
+      when Integer
+        ttl
+      when Float
+        ttl.to_i
+      when String
+        Integer(ttl, exception: false)
+      end
+
+      numeric&.positive? ? numeric : 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.1.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Sebastian Sala