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.

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:%")



175
176
177
 
# File 'lib/ask/state.rb', line 175

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/)



182
183
184
185
 
# File 'lib/ask/state.rb', line 182

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) 


101
102
103
 
# File 'lib/ask/state.rb', line 101

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) 


68
69
70
 
# File 'lib/ask/state.rb', line 68

def clear
  raise NotImplementedError
end

#close ⇒ Object

Optional: called when the adapter is no longer needed.



166
167
168
 
# File 'lib/ask/state.rb', line 166

def close
  # no-op by default
end

#delete(key) ⇒ Object

Parameters:

  • key (String) —

    the key

Raises:

  • (NotImplementedError) 


62
63
64
 
# File 'lib/ask/state.rb', line 62

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) 


126
127
128
 
# File 'lib/ask/state.rb', line 126

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) 


119
120
121
 
# File 'lib/ask/state.rb', line 119

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



75
76
77
 
# File 'lib/ask/state.rb', line 75

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) 


50
51
52
 
# File 'lib/ask/state.rb', line 50

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) 


83
84
85
 
# File 'lib/ask/state.rb', line 83

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) 


142
143
144
 
# File 'lib/ask/state.rb', line 142

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) 


151
152
153
 
# File 'lib/ask/state.rb', line 151

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) 


159
160
161
 
# File 'lib/ask/state.rb', line 159

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) 


132
133
134
 
# File 'lib/ask/state.rb', line 132

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) 


109
110
111
 
# File 'lib/ask/state.rb', line 109

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) 


57
58
59
 
# File 'lib/ask/state.rb', line 57

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) 


91
92
93
 
# File 'lib/ask/state.rb', line 91

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