openui-rails 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d3b9295fd6e8fb6d3b284c0c66d80e3d02f01e7d1c09913f02acfd6ff183273
-  data.tar.gz: 9e5eb58014af64320ea178b05f63843f617f5fe3fa650e083f411a116a12dff2
+  metadata.gz: 1fd5862a42a9eaf7c669e6e94fa38d8aaac1784e4f7efe5340e9cec48756902a
+  data.tar.gz: f7ada4e9693c3de0c0d13b05a7cc7692a44b402b291721d430038a68c6047f4c
 SHA512:
-  metadata.gz: bcbbc65b5a3a3d66839d727e325238643973050b39248695e6623b4f45c7fd343ecea7cf52c8c59f70fe6caf63aace284c677d4cd50211ed4fef73e9fc984da7
-  data.tar.gz: 53147d0d353adf39e448f3ea82ac1c60dd1f7fee9168573d5802b052a3bd54fbd949fd9ac5b8d591ff134cc627c9204feeb07ffd1289304109b5eedd41ea08c0
+  metadata.gz: 0dc08e62c9508a13e11fa3d4995717d6b88be85458d505da3c363bccbfa1b57a1017bc59d72d667ed3d8043eb68f1005cd18b77bc87bae3ac9df0d2fe4683017
+  data.tar.gz: 524eb2239e400a15e6e0dee14d98b5d71e0a6f94866e4bfafda48917ea17f55a18a9eda9126cb13d7a7e4e149bd3ecfaa4f755ebac32f4ba2ca99d9b18db1d01

data/CHANGELOG.md

@@ -6,6 +6,23 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-20
+
+### Added
+
+- Optional `Actions::Idempotency::ActiveRecordStore` with atomic database claims,
+  ownership fencing, JSON result persistence, and explicit expiry cleanup.
+  SQLite is the verified database; memory remains the default.
+- `openui:idempotency` generates the opt-in table and its unique key and expiry
+  indexes. Installing the engine alone creates no shared-store table.
+- Reusable Minitest store-conformance checks, independent-process SQLite tests,
+  and a fresh-host migration and restart check against the built gem.
+
+### Changed
+
+- The support-desk reference uses the shared store while retaining its business
+  uniqueness constraint. A shared claim does not guarantee exactly-once effects.
+
 ## [0.3.0] - 2026-10-19
 
 ### Added
@@ -116,7 +133,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Gem-scoped RubyGems Trusted Publishing through GitHub OIDC, with a protected
   release environment and verified artifact handoff.
 
-[Unreleased]: https://github.com/yorzi/openui-rails/compare/v0.3.0...main
+[Unreleased]: https://github.com/yorzi/openui-rails/compare/v0.4.0...main
+[0.4.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.4.0
 [0.3.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.3.0
 [0.2.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.2.0
 [0.1.0]: https://github.com/yorzi/openui-rails/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -25,7 +25,7 @@ bundle exec bin/rails test        # unit + integration tests
 bundle exec bin/rails test:system # browser (system) tests, needs Chrome
 bundle exec rubocop               # style (rubocop-rails-omakase)
 bundle exec gem build openui-rails.gemspec
-bundle exec ruby bin/smoke-package openui-rails-0.3.0.gem
+bundle exec ruby bin/smoke-package openui-rails-0.4.0.gem
 bundle exec bundler-audit check --update
 bundle exec ruby -Itest test/compatibility/ruby_llm_smoke.rb
 ```

data/DEVELOPMENT.md

@@ -17,7 +17,7 @@ authorizes a live call. Follow this loop for each feature:
 ```sh
 bin/check-reference
 bin/check-reference --runtime tmp/real-runtime
-bin/check-reference --gem tmp/package/openui-rails-0.3.0.gem --runtime tmp/real-runtime
+bin/check-reference --gem tmp/package/openui-rails-0.4.0.gem --runtime tmp/real-runtime
 # Focus one browser scenario:
 bin/check-reference --runtime tmp/real-runtime --name test_a_lost_turbo_envelope_recovers_from_the_scoped_snapshot
 ```

data/README.md

@@ -22,8 +22,8 @@ or renderer.
 - One allowlisted action endpoint with authorization, validation, and replay protection.
 - An optional RubyLLM streaming adapter.
 
-Your app supplies scoped record lookup, stream subscriptions, snapshot recovery,
-and shared idempotency storage when running multiple processes.
+Your app supplies scoped record lookup, stream subscriptions, and snapshot
+recovery. Multi-process apps can opt into the SQLite shared idempotency store.
 
 ## Get started
 
@@ -32,7 +32,7 @@ The runtime-fetch task also needs npm. RubyLLM is optional.
 
 ```ruby
 # Gemfile
-gem "openui-rails", "~> 0.3.0"
+gem "openui-rails", "~> 0.4.0"
 ```
 
 ```sh
@@ -65,15 +65,15 @@ The documentation site contains the full guides and API reference:
 - [RubyLLM](https://openui-rails.wangyaodi.com/ruby-llm/) and [production setup](https://openui-rails.wangyaodi.com/production/)
 - [Upgrading](https://openui-rails.wangyaodi.com/upgrading/) and [API reference](https://openui-rails.wangyaodi.com/api-reference/)
 
-Version `0.3.0` adds a persisted reference workflow and stream restoration.
-See [What's New](https://openui-rails.wangyaodi.com/whats-new-in-0-3/) for the upgrade.
+Version `0.4.0` adds optional shared replay storage for Rails workers.
+See [What's New](https://openui-rails.wangyaodi.com/whats-new-in-0-4/) for the upgrade.
 The API may change during `0.x`; see the
 [changelog](CHANGELOG.md) and the proposed [path to 1.0](ROADMAP.md).
 The site's stable channel follows the latest release; [/next/](https://openui-rails.wangyaodi.com/next/)
 follows `main`.
 
 For repository work, use [Contributing](CONTRIBUTING.md),
-[Releasing](RELEASING.md), and the [0.2.0 release record](RELEASE_0_2.md).
+[Releasing](RELEASING.md), and the [0.3.0 release record](RELEASE_0_3.md).
 Report vulnerabilities through the [security policy](SECURITY.md).
 
 ## License

data/examples/support_desk/README.md

@@ -2,14 +2,16 @@
 
 This opt-in reference belongs to the host application, outside the engine's
 public API. It uses synthetic accounts, recorded generation, the real pinned
-OpenUI runtime, SQLite, importmap, and HTTP Turbo Streams.
+OpenUI runtime, SQLite, importmap, and HTTP Turbo Streams. It opts into the
+Active Record idempotency store and retains a unique business receipt for closing
+a ticket. Shared claims do not replace that database constraint.
 
 From the repository:
 
 ```sh
 mkdir -p tmp/package
-bundle exec gem build openui-rails.gemspec --output tmp/package/openui-rails-0.3.0.gem
-bin/check-reference --gem tmp/package/openui-rails-0.3.0.gem --runtime tmp/real-runtime
+bundle exec gem build openui-rails.gemspec --output tmp/package/openui-rails-0.4.0.gem
+bin/check-reference --gem tmp/package/openui-rails-0.4.0.gem --runtime tmp/real-runtime
 ```
 
 Fetch the runtime first. See the [complete guide](https://openui-rails.wangyaodi.com/reference-workflow/)

data/examples/support_desk/config/initializers/openui.rb

@@ -8,6 +8,7 @@ OpenUI::Rails.configure do |config|
   config.surface_resolver = ->(id, actor:, **) {
     SupportDesk::Conversation.find_by(id: id, user_id: actor.id, tenant_id: actor.tenant_id) if actor
   }
+  config.idempotency_store = OpenUI::Rails::Actions::Idempotency::ActiveRecordStore.new
   config.idempotency_scope = ->(invocation) { [ invocation.actor.tenant_id, invocation.actor.id ] }
   config.authorize_action = ->(invocation) {
     actor, conversation = invocation.actor, invocation.surface

data/lib/generators/openui/idempotency/idempotency_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/generators/active_record"
+
+module OpenUI
+  # Generate the opt-in shared action-claim table without changing configuration.
+  class IdempotencyGenerator < ::ActiveRecord::Generators::Base
+    namespace "openui:idempotency"
+    source_root File.expand_path("templates", __dir__)
+    desc "Create the optional OpenUI shared idempotency store migration."
+    # This generator has no model-name argument.
+    argument :name, type: :string, default: "openui_action_claims", hide: true
+
+    # Write the optional, reversible host migration.
+    def create_store_migration
+      migration_template "create_openui_action_claims.rb", "db/migrate/create_openui_action_claims.rb"
+    end
+  end
+end

data/lib/generators/openui/idempotency/templates/create_openui_action_claims.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class CreateOpenUIActionClaims < ActiveRecord::Migration[8.0]
+  def change
+    create_table :openui_action_claims do |t|
+      t.string :key, null: false
+      t.string :digest
+      t.string :claim_token, null: false
+      t.boolean :completed, null: false, default: false
+      t.text :result_json
+      t.datetime :expires_at, null: false, precision: 6
+    end
+    add_index :openui_action_claims, :key, unique: true
+    add_index :openui_action_claims, :expires_at
+  end
+end

data/lib/generators/openui/install/templates/config/initializers/openui.rb.tt

@@ -14,6 +14,10 @@ OpenUI::Rails.configure do |config|
   config.runtime_assets = :self_hosted
   # config.runtime_integrity = "sha384-..."
 
+  # Optional shared SQLite claims: first run openui:idempotency and db:migrate.
+  # See the Shared Idempotency Storage guide for JSON results and crash limits.
+  # config.idempotency_store = OpenUI::Rails::Actions::Idempotency::ActiveRecordStore.new
+
   # Authorize every action/tool call. This fails closed: with no authorizer an
   # action is denied. Return truthy to permit.
   # config.authorize_action = ->(invocation) do

data/lib/openui/rails/actions/idempotency/active_record_store.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "json"
+require "securerandom"
+
+module OpenUI
+  module Rails
+    module Actions
+      module Idempotency
+        # Optional shared action store. Verified with SQLite on Rails 8.0/8.1.
+        # Install its table with `rails generate openui:idempotency` and db:migrate.
+        # JSON values replay across workers; object keys become strings. TTL runs
+        # from claim creation, not completion. Never assumes exactly-once effects.
+        class ActiveRecordStore
+          class Entry < ::ActiveRecord::Base # :nodoc:
+            self.table_name = "openui_action_claims"
+          end
+          private_constant :Entry
+
+          # @param model [Class] dedicated Active Record model, optionally using another database
+          # @param clock [#call] shared wall clock returning UTC Time values
+          def initialize(model: Entry, clock: -> { Time.now.utc })
+            @model = model
+            @clock = clock
+          end
+
+          # Atomically insert or replace an expired claim. Returns the same
+          # [status, result, stored_digest, token] contract as MemoryStore.
+          # A changed digest is returned to the dispatcher, which rejects it.
+          def claim(key, ttl:, digest: nil)
+            raise ConfigurationError, "idempotency ttl must be positive" unless ttl.is_a?(Numeric) && ttl.finite? && ttl > 0
+
+            loop do
+              now = @clock.call
+              attributes = { key: key, digest: digest, claim_token: SecureRandom.hex(16),
+                             completed: false, result_json: nil, expires_at: now + ttl }
+              inserted = @model.insert_all([ attributes ], unique_by: :key, returning: %w[id])
+              return [ :claimed, nil, digest, attributes[:claim_token] ] if inserted.any?
+
+              replaced = @model.where(key: key).where("expires_at <= ?", now).update_all(attributes.except(:key))
+              return [ :claimed, nil, digest, attributes[:claim_token] ] if replaced == 1
+
+              # Cleanup can delete the expired row between SQL statements.
+              entry = @model.find_by(key: key)
+              next unless entry
+
+              value = entry.completed ? JSON.parse(entry.result_json) : nil
+              return [ entry.completed ? :replay : :pending, value, entry.digest, entry.claim_token ]
+            end
+          end
+
+          # Record only while this token owns a live claim. JSON encoding rejects
+          # unsupported Ruby objects before writing; it never invokes Marshal.
+          def record(key, result, claim_token:)
+            json = JSON.generate(JsonValue.copy(result))
+            @model.where(key: key, claim_token: claim_token).where("expires_at > ?", @clock.call)
+              .update_all(result_json: json, completed: true)
+            nil
+          rescue ArgumentError, JSON::GeneratorError => error
+            raise ConfigurationError, "idempotency result must be a JSON value: #{error.message}"
+          end
+
+          # Delete expired claims, returning the number removed. Call from a host
+          # maintenance task; expiry of the requested key never needs this sweep.
+          def delete_expired
+            @model.where("expires_at <= ?", @clock.call).delete_all
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/actions/idempotency/memory_store.rb

@@ -7,8 +7,8 @@ module OpenUI
     module Actions
       module Idempotency
         # Default, single-process idempotency store. Hosts that run multiple
-        # processes should inject a shared store (e.g. Redis or the database)
-        # that implements the same contract.
+        # processes can opt into ActiveRecordStore on SQLite
+        # or inject another shared adapter implementing the same contract.
         #
         # Contract:
         #   claim(key, ttl:, digest:) -> [status, result, digest, claim_token]

data/lib/openui/rails/actions.rb

@@ -13,6 +13,9 @@ module OpenUI
     # a host authorizer, stale-surface protection and idempotency, shared by
     # both component actions and browser tool calls.
     module Actions
+      module Idempotency
+        autoload :ActiveRecordStore, "openui/rails/actions/idempotency/active_record_store"
+      end
     end
   end
 end

data/lib/openui/rails/testing/idempotency_store_contract.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module OpenUI
+  module Rails
+    module Testing
+      # Reusable Minitest contract for idempotency adapters. Include this module
+      # in a test case that defines build_store and advance_store_clock(seconds).
+      # Each test needs an empty store and a controllable shared clock.
+      module IdempotencyStoreContract
+        def test_claim_distinguishes_pending_from_completed
+          store = build_store
+          status, value, digest, token = store.claim("key", ttl: 60, digest: "original")
+          assert_equal :claimed, status
+          assert_nil value
+          assert_equal "original", digest
+          refute_empty token
+          assert_equal [ :pending, nil, "original", token ], store.claim("key", ttl: 60, digest: "changed")
+          store.record("key", "saved", claim_token: token)
+          assert_equal [ :replay, "saved", "original", token ], store.claim("key", ttl: 60, digest: "changed")
+        end
+
+        def test_completed_nil_and_false_replay
+          store = build_store
+          [ nil, false ].each_with_index do |value, index|
+            key = "nullable-#{index}"
+            token = store.claim(key, ttl: 60, digest: "d").last
+            store.record(key, value, claim_token: token)
+            assert_equal [ :replay, value, "d", token ], store.claim(key, ttl: 60, digest: "d")
+          end
+        end
+
+        def test_json_results_round_trip
+          store = build_store
+          value = { "list" => [ 1, 2.5, true, false, nil, "你好" ], "nested" => { "ok" => true } }
+          token = store.claim("key", ttl: 60, digest: "d").last
+          store.record("key", value, claim_token: token)
+          assert_equal value, store.claim("key", ttl: 60, digest: "d")[1]
+        end
+
+        def test_expired_owner_cannot_record
+          store = build_store
+          token = store.claim("key", ttl: 10, digest: "old").last
+          advance_store_clock(10)
+          store.record("key", "late", claim_token: token)
+          status, value, _, replacement = store.claim("key", ttl: 60, digest: "new")
+          assert_equal :claimed, status
+          assert_nil value
+          refute_equal token, replacement
+        end
+
+        def test_replaced_owner_cannot_overwrite
+          store = build_store
+          old = store.claim("key", ttl: 10, digest: "old").last
+          advance_store_clock(11)
+          token = store.claim("key", ttl: 60, digest: "new").last
+          store.record("key", "new result", claim_token: token)
+          store.record("key", "old result", claim_token: old)
+          assert_equal [ :replay, "new result", "new", token ], store.claim("key", ttl: 60, digest: "new")
+        end
+
+        def test_wrong_token_and_unknown_key_do_not_complete_a_claim
+          store = build_store
+          token = store.claim("key", ttl: 60, digest: "d").last
+          store.record("missing", "value", claim_token: token)
+          store.record("key", "value", claim_token: "wrong")
+          assert_equal :pending, store.claim("key", ttl: 60, digest: "d").first
+          assert_equal :claimed, store.claim("missing", ttl: 60, digest: "d").first
+        end
+
+        def test_ttl_must_be_positive_and_finite
+          store = build_store
+          [ 0, -1, Float::INFINITY, Float::NAN, "60", nil ].each do |ttl|
+            assert_raises(OpenUI::Rails::ConfigurationError) { store.claim("key", ttl: ttl, digest: "d") }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openui/rails/version.rb

@@ -1,5 +1,5 @@
 module OpenUI
   module Rails
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openui-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Andy Wang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -80,12 +80,15 @@ files:
 - examples/support_desk/config/routes.rb
 - examples/support_desk/db/migrate/20261019000000_create_support_desk.rb
 - examples/support_desk/install.rb
+- lib/generators/openui/idempotency/idempotency_generator.rb
+- lib/generators/openui/idempotency/templates/create_openui_action_claims.rb
 - lib/generators/openui/install/install_generator.rb
 - lib/generators/openui/install/templates/config/initializers/openui.rb.tt
 - lib/generators/openui/install/templates/config/openui/README.md
 - lib/openui/rails.rb
 - lib/openui/rails/actions.rb
 - lib/openui/rails/actions/dispatcher.rb
+- lib/openui/rails/actions/idempotency/active_record_store.rb
 - lib/openui/rails/actions/idempotency/memory_store.rb
 - lib/openui/rails/actions/invocation.rb
 - lib/openui/rails/actions/registry.rb
@@ -116,6 +119,7 @@ files:
 - lib/openui/rails/stream/transports/memory.rb
 - lib/openui/rails/stream/transports/turbo_streams.rb
 - lib/openui/rails/surface.rb
+- lib/openui/rails/testing/idempotency_store_contract.rb
 - lib/openui/rails/version.rb
 - lib/openui/rails/view_helper.rb
 - lib/tasks/openui.rake