Class: Ask::State::Adapter

Inherits:
Object
  • Object
show all
Defined in:
lib/ask/state.rb

Overview

Abstract base class for state backends. Subclasses must implement all methods.

Direct Known Subclasses

Memory

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.glob_to_like(pattern) ⇒ String

Convert a glob pattern (*, ?) to a SQL LIKE pattern.

Parameters:

  • pattern (String) —

    glob pattern (e.g., "session:*")

Returns:

  • (String) —

    LIKE pattern (e.g., "session:%")



177
178
179
 
# File 'lib/ask/state.rb', line 177

def self.glob_to_like(pattern)
  pattern.gsub("*", "%").gsub("?", "_")
end

.glob_to_regex(pattern) ⇒ Regexp

Convert a glob pattern (*, ?) to a Regexp.

Parameters:

  • pattern (String) —

    glob pattern (e.g., "session:*")

Returns:

  • (Regexp) —

    matching regex (e.g., /Asession:.*\z/)



184
185
186
187
 
# File 'lib/ask/state.rb', line 184

def self.glob_to_regex(pattern)
  escaped = Regexp.escape(pattern)
  Regexp.new("\\A#{escaped.gsub("\\*", ".*").gsub("\\?", ".")}\\z")
end

Instance Method Details

#acquire_lock(key, ttl: 10) ⇒ Lock?

Acquire a lock for a key. Returns nil if the lock is held by another owner.

Parameters:

  • key (String) —

    the resource to lock

  • ttl (Integer) (defaults to: 10) —

    lock time-to-live in seconds (default 10)

Returns:

  • (Lock, nil) —

    the lock if acquired, nil if already held

Raises:

  • (NotImplementedError) 


103
104
105
 
# File 'lib/ask/state.rb', line 103

def acquire_lock(key, ttl: 10)
  raise NotImplementedError
end

#clear ⇒ Object

Remove all keys from the store (key-value only by default). Subclasses should override to also clear locks, queues, and lists.

Raises:

  • (NotImplementedError) 


70
71
72
 
# File 'lib/ask/state.rb', line 70

def clear
  raise NotImplementedError
end

#close ⇒ Object

Optional: called when the adapter is no longer needed.



168
169
170
 
# File 'lib/ask/state.rb', line 168

def close
  # no-op by default
end

#delete(key) ⇒ Object

Parameters:

  • key (String) —

    the key

Raises:

  • (NotImplementedError) 


64
65
66
 
# File 'lib/ask/state.rb', line 64

def delete(key)
  raise NotImplementedError
end

#dequeue(queue) ⇒ QueueEntry?

Pop the next item from a named queue.

Parameters:

  • queue (String) —

    the queue name

Returns:

  • (QueueEntry, nil) —

    the next entry, or nil if the queue is empty

Raises:

  • (NotImplementedError) 


128
129
130
 
# File 'lib/ask/state.rb', line 128

def dequeue(queue)
  raise NotImplementedError
end

#enqueue(queue, value) ⇒ QueueEntry

Push an item onto a named queue.

Parameters:

  • queue (String) —

    the queue name

  • value (Object) —

    the value to enqueue

Returns:

Raises:

  • (NotImplementedError) 


121
122
123
 
# File 'lib/ask/state.rb', line 121

def enqueue(queue, value)
  raise NotImplementedError
end

#exists?(key) ⇒ Boolean

Check if a key exists and has not expired.

Parameters:

  • key (String) —

    the key

Returns:

  • (Boolean) —

    true if the key exists and is not expired



77
78
79
 
# File 'lib/ask/state.rb', line 77

def exists?(key)
  !get(key).nil?
end

#get(key) ⇒ Object?

Returns the stored value, or nil if not found.

Parameters:

  • key (String) —

    the key

Returns:

  • (Object, nil) —

    the stored value, or nil if not found

Raises:

  • (NotImplementedError) 


52
53
54
 
# File 'lib/ask/state.rb', line 52

def get(key)
  raise NotImplementedError
end

#keys(pattern: nil) ⇒ Array<String>

Return all non-expired keys, optionally filtered by a glob pattern. Glob syntax: * matches any sequence, ? matches any single character.

Parameters:

  • pattern (String, nil) (defaults to: nil) —

    optional glob pattern (e.g., "session:*")

Returns:

  • (Array<String>) —

    matching keys

Raises:

  • (NotImplementedError) 


85
86
87
 
# File 'lib/ask/state.rb', line 85

def keys(pattern: nil)
  raise NotImplementedError
end

#list_append(key, value, max_length: nil) ⇒ Object

Append a value to an ordered list. Trims to max_length (keeps newest).

Parameters:

  • key (String) —

    the list key

  • value (Object) —

    the value to append

  • max_length (Integer, nil) (defaults to: nil) —

    maximum list length (nil = no limit)

Raises:

  • (NotImplementedError) 


144
145
146
 
# File 'lib/ask/state.rb', line 144

def list_append(key, value, max_length: nil)
  raise NotImplementedError
end

#list_range(key, start = 0, stop = -1)) ⇒ Array<Object>

Return a slice of the list.

Parameters:

  • key (String) —

    the list key

  • start (Integer) (defaults to: 0) —

    starting index (0-based)

  • stop (Integer) (defaults to: -1)) —

    ending index (inclusive, -1 for all)

Returns:

  • (Array<Object>) —

    the list slice

Raises:

  • (NotImplementedError) 


153
154
155
 
# File 'lib/ask/state.rb', line 153

def list_range(key, start = 0, stop = -1)
  raise NotImplementedError
end

#list_remove(key, value) ⇒ Integer

Remove all occurrences of a value from a list.

Parameters:

  • key (String) —

    the list key

  • value (Object) —

    the value to remove

Returns:

  • (Integer) —

    number of removed elements

Raises:

  • (NotImplementedError) 


161
162
163
 
# File 'lib/ask/state.rb', line 161

def list_remove(key, value)
  raise NotImplementedError
end

#queue_depth(queue) ⇒ Integer

Returns the number of items in the queue.

Parameters:

  • queue (String) —

    the queue name

Returns:

  • (Integer) —

    the number of items in the queue

Raises:

  • (NotImplementedError) 


134
135
136
 
# File 'lib/ask/state.rb', line 134

def queue_depth(queue)
  raise NotImplementedError
end

#release_lock(key, lock) ⇒ Boolean

Release a lock. Only the lock owner can release it.

Parameters:

  • key (String) —

    the resource to unlock

  • lock (Lock) —

    the lock returned by #acquire_lock

Returns:

  • (Boolean) —

    true if released, false if lock was already expired or not held

Raises:

  • (NotImplementedError) 


111
112
113
 
# File 'lib/ask/state.rb', line 111

def release_lock(key, lock)
  raise NotImplementedError
end

#set(key, value, ttl: nil) ⇒ Object

Parameters:

  • key (String) —

    the key

  • value (Object) —

    the value (must be JSON-serializable)

  • ttl (Integer, nil) (defaults to: nil) —

    time-to-live in seconds (nil = no expiry)

Raises:

  • (NotImplementedError) 


59
60
61
 
# File 'lib/ask/state.rb', line 59

def set(key, value, ttl: nil)
  raise NotImplementedError
end

#set_if_not_exists(key, value, ttl: nil) ⇒ Boolean

Atomically set a value only if the key does not already exist.

Parameters:

  • key (String) —

    the key

  • value (Object) —

    the value

Returns:

  • (Boolean) —

    true if the value was set, false if the key already exists

Raises:

  • (NotImplementedError) 


93
94
95
 
# File 'lib/ask/state.rb', line 93

def set_if_not_exists(key, value, ttl: nil)
  raise NotImplementedError
end