Module: CMDx::Stores

Extended by:
Stores
Included in:
Stores
Defined in:
lib/cmdx/stores.rb,
lib/cmdx/stores/redis.rb,
lib/cmdx/stores/memory.rb

Overview

Key/value scratch space for idempotency keys, locks, rate limits, circuit breakers, checkpoints, and cached results. Stores delegates to Configuration#store; swap the configured backend (for example Memory or Redis) at boot.

Defined Under Namespace

Classes: Memory, Redis

Instance Method Summary collapse

Instance Method Details

#decr(key, ttl: nil) ⇒ Integer

Returns value after decrement.

Parameters:

  • key (String, Symbol)
  • ttl (Integer, nil) (defaults to: nil) —

    unused; accepted for API symmetry with #incr

Returns:

  • (Integer) —

    value after decrement

Raises:

  • (ArgumentError) —

    when key is blank



43
44
45
 
# File 'lib/cmdx/stores.rb', line 43

def decr(key, ttl: nil)
  CMDx.configuration.store.decr(key, ttl:)
end

#del(key) ⇒ Integer

Returns 1 when a key was removed, 0 otherwise.

Parameters:

  • key (String, Symbol)

Returns:

  • (Integer) —

    1 when a key was removed, 0 otherwise

Raises:

  • (ArgumentError) —

    when key is blank



50
51
52
 
# File 'lib/cmdx/stores.rb', line 50

def del(key)
  CMDx.configuration.store.del(key)
end

#del_if(key, expected) ⇒ Boolean

Returns whether the key was removed.

Parameters:

  • key (String, Symbol)
  • expected (#to_s) —

    value that must match the stored string for deletion

Returns:

  • (Boolean) —

    whether the key was removed

Raises:

  • (ArgumentError) —

    when key is blank

  • (NotImplementedError) —

    when the configured store does not implement #del_if



59
60
61
62
63
64
 
# File 'lib/cmdx/stores.rb', line 59

def del_if(key, expected)
  store = CMDx.configuration.store
  raise NotImplementedError, "store must implement del_if(key, expected) for lock release" unless store.respond_to?(:del_if)

  store.del_if(key, expected)
end

#get(key) ⇒ String?

Returns stored value, or nil when missing or expired.

Parameters:

  • key (String, Symbol)

Returns:

  • (String, nil) —

    stored value, or nil when missing or expired

Raises:

  • (ArgumentError) —

    when key is blank

See Also:



16
17
18
 
# File 'lib/cmdx/stores.rb', line 16

def get(key)
  CMDx.configuration.store.get(key)
end

#incr(key, ttl: nil) ⇒ Integer

Returns value after increment.

Parameters:

  • key (String, Symbol)
  • ttl (Integer, nil) (defaults to: nil) —

    when set, refreshes expiry on every increment

Returns:

  • (Integer) —

    value after increment

Raises:

  • (ArgumentError) —

    when key is blank or ttl is invalid



35
36
37
 
# File 'lib/cmdx/stores.rb', line 35

def incr(key, ttl: nil)
  CMDx.configuration.store.incr(key, ttl:)
end

#key!(key) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters:

  • key (String, Symbol)

Returns:

  • (String)

Raises:

  • (ArgumentError) —

    when key is blank



82
83
84
85
86
87
 
# File 'lib/cmdx/stores.rb', line 82

def key!(key)
  str = key.to_s
  raise ArgumentError, "store key must be non-empty" if str.empty?

  str
end

#nx_xx!(nx, xx) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Parameters:

  • nx (Boolean)
  • xx (Boolean)

Raises:

  • (ArgumentError) —

    when both flags are true



104
105
106
107
108
 
# File 'lib/cmdx/stores.rb', line 104

def nx_xx!(nx, xx)
  return unless nx && xx

  raise ArgumentError, "store set cannot use nx and xx together"
end

#remaining_ttl(key) ⇒ Integer?

Returns seconds until expiry when the backend supports #ttl; nil when the key is missing, expired, or TTL is unavailable.

Parameters:

  • key (String, Symbol)

Returns:

  • (Integer, nil) —

    seconds until expiry when the backend supports #ttl; nil when the key is missing, expired, or TTL is unavailable

Raises:

  • (ArgumentError) —

    when key is blank



70
71
72
73
74
75
76
 
# File 'lib/cmdx/stores.rb', line 70

def remaining_ttl(key)
  store = CMDx.configuration.store
  return unless store.respond_to?(:ttl)

  seconds = store.ttl(key)
  seconds if seconds.is_a?(Integer) && seconds.positive?
end

#set(key, value, ttl: nil, nx: false, xx: false) ⇒ Boolean

Returns whether the value was written.

Parameters:

  • key (String, Symbol)
  • value (#to_s)
  • ttl (Integer, nil) (defaults to: nil)
  • nx (Boolean) (defaults to: false)
  • xx (Boolean) (defaults to: false)

Returns:

  • (Boolean) —

    whether the value was written

Raises:

  • (ArgumentError) —

    when key is blank, ttl is invalid, or nx and xx are both true



27
28
29
 
# File 'lib/cmdx/stores.rb', line 27

def set(key, value, ttl: nil, nx: false, xx: false)
  CMDx.configuration.store.set(key, value, ttl:, nx:, xx:)
end

#ttl!(ttl) ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters:

  • ttl (Integer)

Returns:

  • (Integer)

Raises:

  • (ArgumentError) —

    when ttl is not a positive Integer



93
94
95
96
97
 
# File 'lib/cmdx/stores.rb', line 93

def ttl!(ttl)
  return ttl if ttl.is_a?(Integer) && ttl.positive?

  raise ArgumentError, "store ttl must be a positive Integer (got #{ttl.inspect})"
end