ask-guests 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4714198941d2dca3569099d2c4f4091bd06adcfa00b74ecbea2d06b1cc9c6977
-  data.tar.gz: 5bcfc52ebd6b29d135bd923b3392221c9342ba1057d131349c4f7f0b0d2025e8
+  metadata.gz: 8bec805817f573f8d9fcbc2b5e7bc7c0e6622aed391b4af6d61f02c3544f1c10
+  data.tar.gz: 381594c955f847741546177fc5bb03ead0e71ed6baa62f5adc98277e736fa223
 SHA512:
-  metadata.gz: 4c921fa2484da89d6aef5f00bdf4213bef01bab9df1c25dbc167f61e32672a3b68da54f9f58a47bf7c80b2ad6dcb583dfadb0a7b4a5b187507f209d65c6bdf1f
-  data.tar.gz: 5b8755b9083f995df2adbc6a0679336f343e20d27cb38713f6fab44c2ddc2ebe510878bb08829d8e54fd6cedddab8c88cd1b30377b17294dad23b184d0837740
+  metadata.gz: f97bf4428e04bfcb3fb018b76663b825ed46357419ec43ecd5bc2b3c5fe18463fcc8d9f42ecb6d26be59a43404f3d5fa04b1ee2c715983fa971b09c08318d1c5
+  data.tar.gz: cdc1be08b4f0ef9c13e93625c16be13fb35198fbd0ed2b9d222fc76cde0989b1fc456804aee2bf8a5cc7016ad3cf4c5304e74833638ed9f898b5a54704aa9c6b

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.3.0] — 2026-09-17
+
+### Added
+
+- **The table ships with the gem.** `db/migrate/create_ask_guest_sessions.rb` is
+  now the one definition of `ask_guest_sessions`, and the install generator copies
+  it into the host (`migration_template`, so it lands with a fresh timestamp
+  and is skipped if the host already has one). Re-running the installer after
+  an upgrade installs any migration a later version adds.
+- **The installer writes the whole app-side wiring:** the migration, the
+  `GuestSession` model, and `config/initializers/ask_guests.rb` — then prints
+  the controller, claim, and sweep steps. Nothing is left for the host to
+  transcribe from a README.
+- **`Ask::Guests::MissingTable`** — the ActiveRecord store checks for its table
+  on the first read or write (`#verify_schema!`) and raises this, naming the
+  file to copy, instead of surfacing a database error about a relation.
+- The README documents the non-Rails path (plain ActiveRecord/Sinatra) and why
+  the host owns the schema rather than the gem creating it at boot.
+
+### Changed
+
+- `Ask::Guests::ActiveRecord::SessionStore` raises on a missing table for
+  `#create`, `#find`, and `#sweep_stale`; `#verify_schema!` is public if a host
+  wants to check at boot.
+
 ## [0.2.0] — 2026-09-16
 
 ### Changed

data/README.md

@@ -31,14 +31,47 @@ require "ask-guests/rails"           # controller concern, auth hook, sweep job
 gem "ask-guests"
 ```
 
-In a Rails app, run the installer:
+### Rails
 
 ```bash
 bin/rails generate ask:guests:install
+bin/rails db:migrate
 ```
 
-It creates the `guest_sessions` migration and an initializer, and prints
-the model and controller wiring.
+The installer copies the `ask_guest_sessions` migration out of the gem, writes
+`app/models/guest_session.rb`, creates `config/initializers/ask_guests.rb`, and
+prints the controller wiring. Then register what claiming transfers (see
+[Claim](#claim)) and schedule the sweep (see [Retention](#retention)).
+
+The table ships with the gem (`db/migrate/create_ask_guest_sessions.rb`) rather
+than being created by it. Your app owns its schema: migrations run at deploy
+time, under review, against whichever database you point them at — a gem that
+creates tables at boot would need DDL rights at runtime, race other servers,
+and have to guess which database is yours. Re-running the installer after
+upgrading installs any migration a later version added, and skips the ones you
+already have.
+
+### Anywhere else (plain ActiveRecord, Sinatra, a script)
+
+The core needs nothing; the ActiveRecord adapter needs the table:
+
+```ruby
+require "ask-guests/active_record"
+
+class GuestSession < Ask::Guests::ActiveRecord::SessionBase
+  self.table_name = "ask_guest_sessions"
+end
+
+Ask::Guests.configure do |config|
+  config.secret = ENV.fetch("GUEST_TOKEN_SECRET")
+  config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
+end
+```
+
+Copy `db/migrate/create_ask_guest_sessions.rb` from the gem into your migrations
+and run them however you migrate. If the table is missing, the store raises
+`Ask::Guests::MissingTable` at the first read or write — with the file to copy
+in the message — rather than letting the database complain about a relation.
 
 ## Core usage
 
@@ -128,7 +161,7 @@ Ask::Guests.sweep.call # destroys unclaimed sessions inactive past retention
 ```ruby
 # app/models/guest_session.rb
 class GuestSession < Ask::Guests::ActiveRecord::SessionBase
-  self.table_name = "guest_sessions"
+  self.table_name = "ask_guest_sessions"
   has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
 end
 

data/db/migrate/20260917120000_create_ask_guest_sessions.rb

@@ -0,0 +1,30 @@
+# The ask_guest_sessions table.
+#
+# Shipped with the gem so the table has one definition: the install generator
+# copies this file into a Rails app, and an app without Rails copies the same
+# body into whatever migrates its database. A host that edits its copy keeps
+# its own table — but the columns the store reads and writes are these.
+#
+# Named for the gem, like every other table this ecosystem ships: a host may
+# well have its own `guest_sessions`, and the gem has no business claiming it.
+#
+# `t.json` rather than `jsonb` so the same migration runs on PostgreSQL,
+# MySQL, and SQLite; nothing here queries inside the documents, so the jsonb
+# operators buy nothing. Stamped 7.1 because that is the oldest Active Record
+# the gem supports — a newer Rails runs it unchanged.
+class CreateAskGuestSessions < ActiveRecord::Migration[7.1]
+  def change
+    create_table :ask_guest_sessions do |t|
+      t.json :counters, null: false, default: {}
+      t.json :metadata, null: false, default: {}
+      t.datetime :last_seen_at
+      t.datetime :converted_at
+      t.references :owner, polymorphic: true
+      t.timestamps
+    end
+
+    # Speculative: sessions at risk of being swept.
+    add_index :ask_guest_sessions, :converted_at
+    add_index :ask_guest_sessions, :last_seen_at
+  end
+end

data/lib/ask/guests/active_record/session_base.rb

@@ -8,7 +8,7 @@ module Ask
       # table created by the migration:
       #
       #   class GuestSession < Ask::Guests::ActiveRecord::SessionBase
-      #     self.table_name = "guest_sessions"
+      #     self.table_name = "ask_guest_sessions"
       #     has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
       #   end
       #
@@ -22,6 +22,14 @@ module Ask
       class SessionBase < ::ActiveRecord::Base
         self.abstract_class = true
 
+        # The table is named for the gem, the way the rest of the ecosystem's
+        # tables are: a host may have its own `guest_sessions`. A subclass that
+        # says nothing lands on ask_guest_sessions rather than claiming the
+        # generic name; one that sets table_name itself keeps its own.
+        def self.table_name_prefix
+          "ask_"
+        end
+
         # The gem owns these columns' semantics; use the adapter-independent
         # JSON type so PostgreSQL json/jsonb and SQLite text columns behave
         # identically (and the model loads without a database connection).

data/lib/ask/guests/active_record/session_store.rb

@@ -6,7 +6,7 @@ module Ask
       # ActiveRecord-backed session store.
       #
       #   class GuestSession < Ask::Guests::ActiveRecord::SessionBase
-      #     self.table_name = "guest_sessions"
+      #     self.table_name = "ask_guest_sessions"
       #     has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
       #   end
       #
@@ -26,6 +26,7 @@ module Ask
         end
 
         def create(attributes = {})
+          verify_schema!
           attributes = attributes.to_h.transform_keys(&:to_sym)
           now = Guests.configuration.now
           record = model.new(
@@ -42,6 +43,7 @@ module Ask
         def find(id)
           return nil if id.nil?
 
+          verify_schema!
           model.find_by(id: id)&.to_guest_session
         end
 
@@ -69,6 +71,7 @@ module Ask
         end
 
         def sweep_stale(before:)
+          verify_schema!
           destroyed = 0
           stale_scope(before).find_each do |record|
             record.destroy
@@ -77,6 +80,16 @@ module Ask
           destroyed
         end
 
+        # Raises MissingTable unless the sessions table is there. Called by the
+        # operations a host reaches first, so a forgotten migration names
+        # itself instead of surfacing as a database error about a relation.
+        # Idempotent and cheap: Active Record caches the schema.
+        def verify_schema!
+          return true if model.table_exists?
+
+          raise MissingTable, model.table_name
+        end
+
         def transaction(&block)
           model.transaction(&block)
         end

data/lib/ask/guests/errors.rb

@@ -11,5 +11,24 @@ module Ask
         super
       end
     end
+
+    # Raised on the first store operation when the sessions table is not
+    # there. The gem ships the table, so a host that has not installed it
+    # should hear that — and the command that fixes it — rather than a
+    # database complaining about a relation nobody mentioned.
+    class MissingTable < Error
+      def initialize(table_name = "ask_guest_sessions")
+        super(<<~MESSAGE.strip)
+          The #{table_name} table does not exist.
+
+          Install the table the gem ships, then migrate:
+            bin/rails generate ask:guests:install
+            bin/rails db:migrate
+
+          Without Rails, copy db/migrate/*_create_ask_guest_sessions.rb from the gem
+          into your migrations and run them.
+        MESSAGE
+      end
+    end
   end
 end

data/lib/ask/guests/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Guests
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/generators/ask/guests/install/install_generator.rb

@@ -1,65 +1,124 @@
 # frozen_string_literal: true
 
 require "rails/generators"
+require "rails/generators/migration"
 
 module Ask
   module Guests
     module Generators
+      # Installs ask-guests into a Rails app: the ask_guest_sessions migration, the
+      # model that maps it, and an initializer to configure. Run it once, then
+      # edit what it wrote.
+      #
       #   bin/rails generate ask:guests:install
+      #
+      # The migrations are copied from the gem's own db/migrate, so the table
+      # has one definition — the one the store expects. A host that already
+      # migrated ask_guest_sessions keeps its file: an identical name is skipped
+      # rather than duplicated. Re-running the installer after an upgrade is
+      # how a host picks up a migration a later version added.
       class InstallGenerator < ::Rails::Generators::Base
+        include Rails::Generators::Migration
+
         source_root File.expand_path("templates", __dir__)
+        # The DDL lives in the gem's db/migrate, not in a second copy here.
+        source_paths << File.expand_path("../../../../../db/migrate", __dir__)
+
+        desc "Creates the ask_guest_sessions migration, the model, and the ask-guests initializer"
+
+        def self.next_migration_number(_dir)
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        end
+
+        # The migrations the gem ships, by file name.
+        def self.migrations
+          Dir[File.expand_path("../../../../../db/migrate/*.rb", __dir__)]
+            .map { |path| File.basename(path) }.sort
+        end
+
+        def create_migrations
+          self.class.migrations.each do |migration|
+            next if installed?(migration) && !options[:force]
 
-        desc "Creates the guest_sessions migration and ask-guests initializer"
+            migration_template migration, "db/migrate/#{migration.sub(/\A\d+_/, "")}"
+          end
+        end
+
+        def create_model
+          template "guest_session.rb", "app/models/guest_session.rb"
+        end
 
         def create_initializer
           template "initializer.rb", "config/initializers/ask_guests.rb"
         end
 
-        def create_migration
-          timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
-          template "migration.rb", "db/migrate/#{timestamp}_create_guest_sessions.rb"
+        def check_schema
+          if schema_installed?
+            say "ask_guest_sessions is in place.", :green
+          else
+            say "Run bin/rails db:migrate to create ask_guest_sessions.", :yellow
+          end
         end
 
-        def show_readme
+        def show_next_steps
           say <<~MESSAGE
 
             ask-guests installed.
 
             Next steps:
 
-            1. Define the model (app/models/guest_session.rb):
+            1. Register what claiming transfers — one handler per record a
+               visitor owns (config/initializers/ask_guests.rb):
 
-                 class GuestSession < Ask::Guests::ActiveRecord::SessionBase
-                   self.table_name = "guest_sessions"
-
-                   # Destroying a session sweeps everything the guest owned:
-                   # has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
+                 Ask::Guests.claimable(:chats) do |session, owner|
+                   Chat.where(guest_session_id: session.id)
+                     .update_all(user_id: owner.id, guest_session_id: nil)
                  end
 
-            2. Register what claiming transfers (config/initializers/ask_guests.rb).
-
-            3. Allow guests in a controller:
+            2. Let guests in, in the controller that serves them:
 
                  include Ask::Guests::Rails::Controller
+
                  allow_guest_access
-                 before_action :require_visitor
+                 before_action :require_visitor, only: %i[chat create]
 
-            4. Claim on authentication (Devise example):
+               ...and key their records to #current_guest_session.
+
+            3. Claim on authentication (Devise example):
 
                  include Ask::Guests::Rails::ClaimOnAuthentication
                  after_action :claim_guest_session, only: :create
 
-                 def guest_claim_owner = current_user.account_users.first
+                 def guest_claim_owner = current_user
 
-            5. Schedule the sweep:
+            4. Sweep abandoned sessions on a schedule (config/recurring.yml
+               with Solid Queue):
 
-                 production:
-                   guests_sweep:
-                     class: "Ask::Guests::Rails::SweepJob"
-                     schedule: every day at 4am
+                 sweep_guest_sessions:
+                   command: "Ask::Guests::Rails::SweepJob.perform_now"
+                   schedule: every day at 4am
 
           MESSAGE
         end
+
+        private
+
+        # A migration the host already has is the host's — it may have run
+        # already, so the gem does not touch it unless asked with --force.
+        def installed?(migration)
+          name = migration.sub(/\A\d+_/, "").delete_suffix(".rb")
+          self.class.migration_exists?(File.join(destination_root, "db/migrate"), name)
+        end
+
+        # Advisory only: a database that is not there yet (db:create has not
+        # run, or the app boots without one) is not this generator's problem.
+        def schema_installed?
+          return false unless defined?(::ActiveRecord::Base)
+
+          ::ActiveRecord::Base.connection.table_exists?("ask_guest_sessions")
+        rescue ::ActiveRecord::ActiveRecordError
+          false
+        end
       end
     end
   end

data/lib/generators/ask/guests/install/templates/guest_session.rb

@@ -0,0 +1,16 @@
+require "ask-guests/active_record"
+
+# The ask_guest_sessions table, as the store reads and writes it.
+#
+# Nothing about a guest is a User row: a visitor is their own record, which is
+# what lets an abandoned visit be swept and a visitor who signs up keep the
+# threads they already had.
+class GuestSession < Ask::Guests::ActiveRecord::SessionBase
+  self.table_name = "ask_guest_sessions"
+
+  # Everything a guest owns hangs off this row, so sweeping an abandoned
+  # session takes those records with it. Add one line per model that carries a
+  # guest_session_id — and make sure claiming moves them (see the initializer):
+  #
+  #   has_many :chats, foreign_key: :guest_session_id, dependent: :destroy
+end

data/lib/generators/ask/guests/install/templates/initializer.rb

@@ -1,42 +1,46 @@
-# frozen_string_literal: true
+require "ask-guests/active_record"
+# The controller concern and the sweep job ride with Rails; the store is
+# ActiveRecord's.
+require "ask-guests/rails"
 
-# Guest access configuration (ask-guests).
+# Guest access (ask-guests).
 #
-# Anonymous visitors get a signed-cookie session, metered agent usage, and
-# a single-use claim that moves everything they own to a real account when
-# they sign up. See https://github.com/ask-rb/ask-guests for the full guide.
+# Anonymous visitors get a signed-cookie session, metered AI usage, and a
+# single-use claim that moves everything they own to a real account when they
+# sign up. See https://github.com/ask-rb/ask-guests for the full guide.
+#
+# Configured on prepare rather than at boot: the store holds the model class,
+# and a reload must not leave it holding the class that was replaced.
+Rails.application.config.to_prepare do
+  Ask::Guests.configure do |config|
+    # Required: HMAC secret for guest tokens. Rotating it invalidates all
+    # outstanding guest cookies (they simply start fresh).
+    config.secret = Rails.application.secret_key_base
 
-Ask::Guests.configure do |config|
-  # Required: HMAC secret for guest tokens. Rotating it invalidates all
-  # outstanding guest cookies (they simply start fresh).
-  config.secret = Rails.application.secret_key_base
+    # Persistence: the model the install generator wrote over the migration.
+    config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
 
-  # Persistence. Define the model first (see the install generator output):
-  #
-  #   class GuestSession < Ask::Guests::ActiveRecord::SessionBase
-  #     self.table_name = "guest_sessions"
-  #     has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
-  #   end
-  config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
+    # Usage caps for anonymous visitors, one entry per category. Signing up
+    # lifts them because a signed-in request never touches the guest budget.
+    # Periods are :day, :week, or :month; counters roll over automatically.
+    # Empty means unlimited — appropriate when the host bills the visit some
+    # other way, and a cap needs a state to show the visitor when it bites.
+    config.categories = {
+      turns: {limit: 40, per: :day}
+      # tokens:  {limit: 10_000, per: :day},
+      # uploads: {limit: 5,      per: :day},
+      # messages: {limit: 100,   per: :month}
+    }
 
-  # Usage caps for anonymous visitors, one entry per category. Signing up
-  # lifts them because a signed-in request never touches the guest budget.
-  # Periods are :day, :week, or :month; counters roll over automatically.
-  config.categories = {
-    turns:  {limit: 40, per: :day}
-    # tokens:  {limit: 10_000, per: :day},
-    # uploads: {limit: 5,      per: :day},
-    # messages: {limit: 100,   per: :month}
-  }
-
-  # Unclaimed sessions inactive for this long are swept (seconds).
-  config.retention = 14 * 24 * 60 * 60
+    # Unclaimed sessions inactive for this long are swept (seconds).
+    config.retention = 14 * 24 * 60 * 60
+  end
 
   # What claiming transfers. Register one handler per owned model; they run
   # inside the claim's transaction, exactly once.
   #
-  # Ask::Guests.claimable(:work_requests) do |session, owner|
-  #   WorkRequest.where(guest_session_id: session.id)
-  #     .update_all(account_id: owner.account_id, account_user_id: owner.id, guest_session_id: nil)
-  # end
+  #   Ask::Guests.claimable(:work_requests) do |session, owner|
+  #     WorkRequest.where(guest_session_id: session.id)
+  #       .update_all(account_id: owner.account_id, account_user_id: owner.id, guest_session_id: nil)
+  #   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-guests
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -93,6 +93,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
 description: 'Give anonymous visitors a durable identity with metered AI access: signed
   guest sessions, per-day turn/token budgets, single-use claiming of records into
   a real owner on sign-up, and stale-session retention. Framework-agnostic core with
@@ -106,6 +120,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- db/migrate/20260917120000_create_ask_guest_sessions.rb
 - lib/ask-guests.rb
 - lib/ask-guests/active_record.rb
 - lib/ask-guests/rails.rb
@@ -127,8 +142,8 @@ files:
 - lib/ask/guests/token.rb
 - lib/ask/guests/version.rb
 - lib/generators/ask/guests/install/install_generator.rb
+- lib/generators/ask/guests/install/templates/guest_session.rb
 - lib/generators/ask/guests/install/templates/initializer.rb
-- lib/generators/ask/guests/install/templates/migration.rb
 homepage: https://github.com/ask-rb/ask-guests
 licenses:
 - MIT

data/lib/generators/ask/guests/install/templates/migration.rb

@@ -1,16 +0,0 @@
-class CreateGuestSessions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
-  def change
-    create_table :guest_sessions do |t|
-      t.jsonb :counters, null: false, default: {}
-      t.jsonb :metadata, null: false, default: {}
-      t.datetime :last_seen_at
-      t.datetime :converted_at
-      t.references :owner, polymorphic: true
-      t.timestamps
-    end
-
-    # Speculative: sessions at risk of being swept.
-    add_index :guest_sessions, :converted_at
-    add_index :guest_sessions, :last_seen_at
-  end
-end