ask-guests 0.1.0

data/lib/ask/guests.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative "guests/version"
+require_relative "guests/errors"
+require_relative "guests/token"
+require_relative "guests/session"
+require_relative "guests/stores/base"
+require_relative "guests/stores/memory"
+require_relative "guests/budget"
+require_relative "guests/budget/policy"
+require_relative "guests/budget/unlimited"
+require_relative "guests/budget/turn_limit"
+require_relative "guests/budget/token_quota"
+require_relative "guests/claim"
+require_relative "guests/sweep"
+
+module Ask
+  # Anonymous, cookie-backed guest access with metered AI usage.
+  #
+  # A guest session is a durable identity for a visitor who has not signed
+  # up: a random id behind an HMAC-signed token, plus counters used to meter
+  # agent usage and a single-use claim that transfers everything the guest
+  # owns to a real owner when they authenticate.
+  #
+  # The core is framework-agnostic — plain Ruby with stdlib only. Optional
+  # adapters plug in persistence and web frameworks:
+  #
+  #   require "ask-guests/active_record"  # ActiveRecord store + model base
+  #   require "ask-guests/rails"          # controller concern, Devise hook, job
+  #
+  # @example Configuration
+  #   Ask::Guests.configure do |config|
+  #     config.secret = ENV.fetch("GUEST_TOKEN_SECRET")
+  #     config.store = Ask::Guests::Stores::Memory.new
+  #     config.policies = [Ask::Guests::Budget::TurnLimit.new(per_day: 40)]
+  #     config.retention = 14 * 24 * 60 * 60 # seconds
+  #   end
+  #
+  # @example Metering an agent turn
+  #   guest = Ask::Guests.store.find(id)   # or current_guest_session in Rails
+  #   budget = Ask::Guests.budget
+  #
+  #   unless budget.allowed?(guest)
+  #     # show "sign up to keep going"
+  #   end
+  #   response = agent.run(...)
+  #   budget.record!(guest, turns: 1, tokens: response.total_tokens)
+  #
+  # @example Claiming on sign-up
+  #   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::Claim.new(session: guest, owner: account_user).call # => true/false
+  module Guests
+    class << self
+      def configure
+        yield configuration
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def reset_configuration!
+        @configuration = nil
+      end
+
+      def secret
+        configuration.secret
+      end
+
+      def store
+        configuration.store
+      end
+
+      # A budget built from the current configuration. Rebuilt on each call
+      # so configuration changes (and test resets) always take effect.
+      def budget
+        Budget.new(
+          policies: configuration.policies,
+          store: configuration.store,
+          clock: configuration.clock
+        )
+      end
+
+      # Registered record-transfer handlers, run by {Guests::Claim}.
+      # @return [Hash{String => Proc}]
+      def claimables
+        @claimables ||= {}
+      end
+
+      # Register a handler that transfers records the guest session owns to
+      # a real owner. Called inside the claim's transaction.
+      #
+      #   Ask::Guests.claimable(:work_requests) { |session, owner| ... }
+      def claimable(name, &block)
+        raise ArgumentError, "claimable requires a block" unless block
+
+        claimables[name.to_s] = block
+      end
+
+      def clear_claimables!
+        @claimables = {}
+      end
+
+      def sweep
+        Sweep.new(
+          store: configuration.store,
+          retention: configuration.retention,
+          clock: configuration.clock
+        )
+      end
+    end
+
+    # Configuration for the guest system. All values have working defaults
+    # except +secret+, which is required to sign and verify tokens.
+    class Configuration
+      # HMAC secret for signing guest tokens (required).
+      attr_accessor :secret
+      # Persistence adapter (see Stores::Base). Defaults to in-memory.
+      attr_accessor :store
+      # Usage policies (see Budget::TurnLimit, Budget::TokenQuota).
+      attr_accessor :policies
+      # Unclaimed sessions older than this many seconds are swept.
+      attr_accessor :retention
+      # Injectable clock returning a Time (used for daily counter rollover
+      # and sweep cutoffs).
+      attr_accessor :clock
+      # Name of the cookie holding the signed guest token (Rails adapter).
+      attr_accessor :cookie_name
+      # Flash message shown after a successful claim (Rails adapter).
+      attr_accessor :claim_notice
+      # Minimum seconds between last-seen writes while a guest browses
+      # (Rails adapter). Keeps ordinary page views from writing per request.
+      attr_accessor :touch_interval
+      # Queue for the Rails sweep job.
+      attr_accessor :sweep_queue
+
+      def initialize
+        @secret = nil
+        @store = Stores::Memory.new
+        @policies = [Budget::Unlimited.new]
+        @retention = 14 * 24 * 60 * 60
+        @clock = -> { Time.now.utc }
+        @cookie_name = "guest_session_token"
+        @claim_notice = "Welcome! We've moved your work to your account."
+        @touch_interval = 300
+        @sweep_queue = :default
+      end
+
+      def now
+        clock.call
+      end
+    end
+  end
+end

data/lib/ask-guests/active_record.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "ask-guests"
+require "active_record"
+
+require_relative "../ask/guests/active_record/json_value"
+require_relative "../ask/guests/active_record/session_base"
+require_relative "../ask/guests/active_record/session_store"

data/lib/ask-guests/rails.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "ask-guests"
+require "active_support/concern"
+require "active_job"
+
+require_relative "../ask/guests/rails/controller"
+require_relative "../ask/guests/rails/claim_on_authentication"
+require_relative "../ask/guests/rails/sweep_job"

data/lib/ask-guests.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ask/guests"

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Ask
+  module Guests
+    module Generators
+      #   bin/rails generate ask:guests:install
+      class InstallGenerator < ::Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Creates the guest_sessions migration and ask-guests initializer"
+
+        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"
+        end
+
+        def show_readme
+          say <<~MESSAGE
+
+            ask-guests installed.
+
+            Next steps:
+
+            1. Define the model (app/models/guest_session.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
+                 end
+
+            2. Register what claiming transfers (config/initializers/ask_guests.rb).
+
+            3. Allow guests in a controller:
+
+                 include Ask::Guests::Rails::Controller
+                 allow_guest_access
+                 before_action :require_visitor
+
+            4. 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
+
+            5. Schedule the sweep:
+
+                 production:
+                   guests_sweep:
+                     class: "Ask::Guests::Rails::SweepJob"
+                     schedule: every day at 4am
+
+          MESSAGE
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Guest access configuration (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.
+
+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. 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. Signing up lifts them because a
+  # signed-in request never touches the guest budget.
+  config.policies = [
+    Ask::Guests::Budget::TurnLimit.new(per_day: 40)
+    # Ask::Guests::Budget::TokenQuota.new(per_day: 10_000)
+  ]
+
+  # Unclaimed sessions inactive for this long are swept (seconds).
+  config.retention = 14 * 24 * 60 * 60
+
+  # 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
+end

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

@@ -0,0 +1,16 @@
+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

metadata

@@ -0,0 +1,159 @@
+--- !ruby/object:Gem::Specification
+name: ask-guests
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  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'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  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
+  optional ActiveRecord and Rails adapters.'
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-guests.rb
+- lib/ask-guests/active_record.rb
+- lib/ask-guests/rails.rb
+- lib/ask/guests.rb
+- lib/ask/guests/active_record/json_value.rb
+- lib/ask/guests/active_record/session_base.rb
+- lib/ask/guests/active_record/session_store.rb
+- lib/ask/guests/budget.rb
+- lib/ask/guests/budget/policy.rb
+- lib/ask/guests/budget/token_quota.rb
+- lib/ask/guests/budget/turn_limit.rb
+- lib/ask/guests/budget/unlimited.rb
+- lib/ask/guests/claim.rb
+- lib/ask/guests/errors.rb
+- lib/ask/guests/rails/claim_on_authentication.rb
+- lib/ask/guests/rails/controller.rb
+- lib/ask/guests/rails/sweep_job.rb
+- lib/ask/guests/session.rb
+- lib/ask/guests/stores/base.rb
+- lib/ask/guests/stores/memory.rb
+- lib/ask/guests/sweep.rb
+- lib/ask/guests/token.rb
+- lib/ask/guests/version.rb
+- lib/generators/ask/guests/install/install_generator.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
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-guests
+  source_code_uri: https://github.com/ask-rb/ask-guests
+  changelog_uri: https://github.com/ask-rb/ask-guests/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: Anonymous, cookie-backed guest access for ask-rb apps
+test_files: []