ask-state-providers 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4af42039dcfbb213799ab09a162acb60c1e78f1b09cb94e52d9dd2bece7b18c
-  data.tar.gz: b0deb44a8f91e0c6cc36dcabf279d822b08386ef49854225b78dc4955cc723b0
+  metadata.gz: 128f88b945a38f01707b8bac7bb1d78e85ffff581c392894346cdace4aad4f64
+  data.tar.gz: 0fae335db04415df0ebb3482afc5f132f83fe6822a988787f4cc10828d979197
 SHA512:
-  metadata.gz: 53bf5a675035408f401a354f0ee3c778ac1c23dcd9115d54b192e65ddcd3df7b64a6ff0bf69aa9cc9b879cf7b485ed59ce2a79da15d8cee9b07688b03a66d5b1
-  data.tar.gz: '09c163faa51ecfb38db57c93fcd33752213e8cfe4367706167cabf3e54130b88b7b6dfebd9e9ee14571b30ac839418fac3fafa06daccf9ae5729739d4716f7e1'
+  metadata.gz: d266562afb53d4e22cb30b340e5e973cc88962386baa295f430a0dcd53873562b8e0f0029215dfbbe241e3a62d11187e09b9eadc546e89517cffb70e9b28cf61
+  data.tar.gz: 37a5a82527b15ab1837f8ebf5c918af68de9e504b70f773b615bfa7d2adbe1700007b0df482428aa8fe709cb95ebd6215aa8b014133c54e842e28e5e8df7d797

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.1] — 2026-08-12
+
+### Fixed
+
+- **`delete(key)` now removes everything under the key** — including
+  ordered lists (and queues in the Memory backend). Consumers store event
+  feeds as lists (ask-workflow's project store, the app-server session
+  store); previously the feed survived deletion. New shared contract test
+  `test_delete_removes_list_entries` runs against every provider.
+
 ## [0.3.0] — 2026-07-28
 
 ### Added

data/README.md

@@ -1,44 +1,22 @@
 # ask-state-providers
 
-Pluggable state backends for the [ask-rb](https://github.com/ask-rb) ecosystem. Provides `Ask::State::Adapter` implementations for **SQLite**, **Redis**, **PostgreSQL**, and **MySQL** — one interface, four databases, zero coupling to your infrastructure.
+[![Gem Version](https://badge.fury.io/rb/ask-state-providers.svg)](https://badge.fury.io/rb/ask-state-providers)
 
-```ruby
-# Local dev — zero config
-store = Ask::State::Providers::SQLite.new
-
-# In production with Rails
-store = Ask::State::Providers::Redis.new(url: ENV["REDIS_URL"])
-
-# With your existing database
-store = Ask::State::Providers::Postgres.new(url: ENV["DATABASE_URL"])
-```
-
-## Why?
-
-ask-rb agents and sessions need to persist state — conversations, tool results, locks, task queues. Each deployment has different infrastructure: a CLI tool needs SQLite, a Rails app already has Postgres, a distributed system needs Redis. Instead of baking one backend into ask-core, this gem provides them all as drop-in adapters behind the same `Ask::State::Adapter` contract.
+Pluggable state backends for the ask-rb ecosystem. One `Ask::State::Adapter` contract, five backends: in-memory Memory, SQLite, Redis, Postgres, and MySQL. `Ask::State::Memory`, the in-process default, lives in this gem since 0.3.0.
 
 ## Installation
 
-Add this line to your `Gemfile`:
-
 ```ruby
 gem "ask-state-providers"
 ```
 
-Then add the database driver for the backend you want to use:
+Add the driver gem for the backend you use:
 
 ```ruby
-# For SQLite (ships with Ruby's standard library — no extra gem needed on most systems)
-gem "sqlite3"
-
-# For Redis
-gem "redis"
-
-# For PostgreSQL
-gem "pg"
-
-# For MySQL
-gem "mysql2"
+gem "sqlite3"   # SQLite
+gem "redis"     # Redis
+gem "pg"        # PostgreSQL
+gem "mysql2"    # MySQL
 ```
 
 ## Quick Start
@@ -46,175 +24,53 @@ gem "mysql2"
 ```ruby
 require "ask-state-providers"
 
-# Pick your backend:
-store = Ask::State::Providers::SQLite.new(path: "my_app.db")
+store = Ask::State::Memory.new        # in-process, no persistence
+# store = Ask::State::Providers::SQLite.new(path: "sessions.db")
 # store = Ask::State::Providers::Redis.new(url: ENV["REDIS_URL"])
 # store = Ask::State::Providers::Postgres.new(url: ENV["DATABASE_URL"])
 # store = Ask::State::Providers::MySQL.new(url: ENV["MYSQL_URL"])
 
-# Key-value storage
-store.set("user:1", { name: "Alice", role: "admin" })
-store.get("user:1")         # => {"name" => "Alice", "role" => "admin"}
-store.set("temp", "expires", ttl: 3600)  # auto-expires in 1 hour
-store.delete("user:1")
-
-# Conditional create
+store.set("user:1", { name: "Alice", role: "admin" }, ttl: 3600)
+store.get("user:1")                   # => { "name" => "Alice", "role" => "admin" }
 store.set_if_not_exists("lock:deploy", "in_progress")
-
-# Distributed locking
-lock = store.acquire_lock("deploy-prod", ttl: 60)
-store.release_lock("deploy-prod", lock) if lock
-
-# Message queues
+store.acquire_lock("deploy-prod", ttl: 60)
 store.enqueue("tasks", { action: "send_email" })
-task = store.dequeue("tasks")
-
-# Ordered lists
-store.list_append("recent_events", event, max_length: 100)
-store.list_range("recent_events", 0, 9)  # first 10
+store.dequeue("tasks")
+store.list_append("recent_events", "event-1", max_length: 100)
+store.list_range("recent_events", 0, 9)
+store.delete("user:1")
 ```
 
 ## Backends
 
-### SQLite (`Ask::State::Providers::SQLite`)
-
-Best for single-process, single-user applications — CLI tools, local development, personal agents.
-
-| Feature | Detail |
-|---------|--------|
-| **Driver** | [`sqlite3`](https://github.com/sparklemotion/sqlite3-ruby) |
-| **Configuration** | `SQLite.new(path:)` |
-| **Storage** | Single file on disk |
-| **Concurrency** | WAL mode with 5-second busy timeout |
-| **Tables** | `state_store`, `locks`, `queues`, `lists` (auto-created) |
-
-Uses `INSERT OR REPLACE` for key-value, `INSERT ... WHERE NOT EXISTS` for conditional writes, and `DELETE ... RETURNING` for safe queue dequeue.
-
-### Redis (`Ask::State::Providers::Redis`)
-
-Best for distributed, multi-process, or multi-host deployments.
-
-| Feature | Detail |
-|---------|--------|
-| **Driver** | [`redis`](https://github.com/redis-rb/redis-rb) |
-| **Configuration** | `Redis.new(url:)` |
-| **Storage** | In-memory with optional persistence |
-| **Key prefix** | `ask:state:` (all keys are namespaced) |
-
-Leverages Redis-native primitives: `SET NX EX` for atomic locking with auto-expire, `RPUSH`/`LPOP` for FIFO queues, `LTRIM` for bounded lists, Lua `EVAL` for safe lock release.
-
-### PostgreSQL (`Ask::State::Providers::Postgres`)
-
-Best for Rails apps and deployments already running Postgres.
-
-| Feature | Detail |
-|---------|--------|
-| **Driver** | [`pg`](https://github.com/ged/ruby-pg) |
-| **Configuration** | `Postgres.new(url:)` |
-| **Connection pool** | Built-in via `connection_pool` (default pool size: 5) |
-
-Uses `ON CONFLICT`, `RETURNING`, and `INSERT ... WHERE NOT EXISTS` for safe concurrent access.
+| Backend | Constructor | Notes |
+|---|---|---|
+| `Ask::State::Memory` | `Memory.new` | In-memory, thread-safe, lost on process exit |
+| `Ask::State::Providers::SQLite` | `SQLite.new(path: "sessions.db")` | Single file, WAL mode, tables auto-created |
+| `Ask::State::Providers::Redis` | `Redis.new(url:)` | Keys namespaced under `ask:state:` |
+| `Ask::State::Providers::Postgres` | `Postgres.new(url:, pool_size: 5)` | Built-in connection pool |
+| `Ask::State::Providers::MySQL` | `MySQL.new(url:)` | `utf8mb4` character set |
 
-### MySQL (`Ask::State::Providers::MySQL`)
+## Adapter contract
 
-Best for teams already running MySQL or MariaDB.
+Every backend implements `Ask::State::Adapter`:
 
-| Feature | Detail |
-|---------|--------|
-| **Driver** | [`mysql2`](https://github.com/brianmario/mysql2) |
-| **Configuration** | `MySQL.new(url:)` |
-| **Character set** | `utf8mb4` (full Unicode including emoji) |
+- Key-value: `get`, `set(key, value, ttl:)`, `delete`, `set_if_not_exists`, `keys(pattern:)`, `clear`
+- Distributed locking: `acquire_lock(key, ttl:)`, `release_lock(key, lock)`
+- Message queues: `enqueue(queue, value)`, `dequeue(queue)`
+- Ordered lists: `list_append(key, value, max_length:)`, `list_range(key, start, stop)`, `list_remove(key, value)`
 
-Uses prepared statements, `ON DUPLICATE KEY UPDATE`, and `SELECT ... LIMIT 1` for safe dequeue.
+## Full documentation
 
-## API Reference
-
-All backends implement `Ask::State::Adapter`:
-
-### Key-Value
-
-| Method | Description |
-|--------|-------------|
-| `get(key)` | Retrieve a value, or `nil` if missing or expired |
-| `set(key, value, ttl:)` | Store a value (JSON-serializable). `ttl` in seconds |
-| `delete(key)` | Remove a key |
-| `set_if_not_exists(key, value, ttl:)` | Create only if key doesn't exist (or is expired). Returns `true`/`false` |
-| `clear` | Remove all keys |
-
-### Distributed Locking
-
-| Method | Description |
-|--------|-------------|
-| `acquire_lock(key, ttl:)` | Acquire a lock. Returns `Lock` or `nil` |
-| `release_lock(key, lock)` | Release a lock (only the owner can). Returns `true`/`false` |
-
-### Message Queues
-
-| Method | Description |
-|--------|-------------|
-| `enqueue(queue, value)` | Push to the back of a queue. Returns `QueueEntry` |
-| `dequeue(queue)` | Pop from the front of a queue. Returns `QueueEntry` or `nil` |
-| `queue_depth(queue)` | Number of items in the queue |
-
-### Ordered Lists
-
-| Method | Description |
-|--------|-------------|
-| `list_append(key, value, max_length:)` | Append to list. Trims to `max_length` (keeps newest) |
-| `list_range(key, start, stop)` | Slice of the list. `stop = -1` means all |
-| `list_remove(key, value)` | Remove all occurrences. Returns count removed |
-
-### Lifecycle
-
-| Method | Description |
-|--------|-------------|
-| `close` | Close the connection(s) |
-
-## Using with ask-agent Sessions
-
-```ruby
-require "ask-state-providers"
-require "ask-agent"
-
-store = Ask::State::Providers::SQLite.new
-
-session = Ask::Agent::Session.new(
-  "triage",
-  model: "gpt-4o",
-  state: store
-)
-
-session.run("What happened last time we saw this error?")
-# Every turn is persisted — survive restarts, searchable, auditable
-```
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. [ask-state-providers in depth](https://ask-rb.github.io/ask-docs/reference/api#ask-state-providers) covers the adapter contract and backends. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
-# Install dependencies
+```
 bundle install
-
-# Run tests (SQLite tests run everywhere, Redis needs fakeredis,
-# Postgres/MySQL need DATABASE_URL/MYSQL_URL env vars)
 bundle exec rake test
-
-# Run tests with verbose output
-bundle exec ruby -Itest test/ask/state/providers/sqlite_test.rb
-bundle exec ruby -Itest test/ask/state/providers/redis_test.rb
-
-# Test Postgres locally
-DATABASE_URL="postgres://localhost:5432/ask_state_test" bundle exec rake test
-
-# Test MySQL locally
-MYSQL_URL="mysql2://root@localhost:3306/ask_state_test" bundle exec rake test
 ```
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
-
-## Links
-
-- **Source:** https://github.com/ask-rb/ask-state-providers
-- **Issues:** https://github.com/ask-rb/ask-state-providers/issues
-- **Docs:** https://github.com/ask-rb/ask-docs
+MIT

data/lib/ask/state/memory.rb

@@ -41,7 +41,13 @@ module Ask
       end
 
       def delete(key)
-        @mutex.synchronize { @data.delete(key) }
+        @mutex.synchronize do
+          @data.delete(key)
+          # delete removes everything under the key, including ordered
+          # lists (consumers store event feeds and queues as lists).
+          @lists.delete(key)
+          @queues.delete(key)
+        end
       end
 
       def set_if_not_exists(key, value, ttl: nil)

data/lib/ask/state/providers/mysql.rb

@@ -92,6 +92,9 @@ module Ask
 
         def delete(key)
           @client.prepare("DELETE FROM state_store WHERE `key` = ?").execute(key)
+          # delete removes everything under the key, including ordered
+          # lists (consumers store event feeds as lists).
+          @client.prepare("DELETE FROM lists WHERE list_key = ?").execute(key)
         end
 
         def set_if_not_exists(key, value, ttl: nil)

data/lib/ask/state/providers/postgres.rb

@@ -94,6 +94,9 @@ module Ask
         def delete(key)
           @pool.with do |conn|
             conn.exec_params("DELETE FROM state_store WHERE key = $1", [key])
+            # delete removes everything under the key, including ordered
+            # lists (consumers store event feeds as lists).
+            conn.exec_params("DELETE FROM lists WHERE list_key = $1", [key])
           end
         end
 

data/lib/ask/state/providers/redis.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "securerandom"
+require "time"
 
 module Ask
   module State
@@ -44,7 +45,9 @@ module Ask
         end
 
         def delete(key)
-          @redis.call("DEL", prefixed(key))
+          # delete removes everything under the key, including ordered
+          # lists (consumers store event feeds as lists).
+          @redis.call("DEL", prefixed(key), prefixed("list:#{key}"))
         end
 
         def set_if_not_exists(key, value, ttl: nil)

data/lib/ask/state/providers/sqlite.rb

@@ -68,6 +68,9 @@ module Ask
         def delete(key)
           @mutex.synchronize do
             @db.execute("DELETE FROM state_store WHERE key = ?", [key])
+            # delete removes everything under the key, including ordered
+            # lists (consumers store event feeds as lists).
+            @db.execute("DELETE FROM lists WHERE list_key = ?", [key])
           end
         end
 

data/lib/ask/state/providers/version.rb

@@ -3,7 +3,7 @@
 module Ask
   module State
     module Providers
-      VERSION = "0.4.0"
+      VERSION = "0.4.1"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-state-providers
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Kaka Ruto