meta_states 0.1.0

data/lib/meta_states/configuration.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module MetaStates
+  class Configuration
+    include Singleton
+
+    attr_reader :callbacks, :model_configurations
+
+    def initialize
+      @callbacks = {}
+      @next_callback_id = 0
+      @model_configurations = {}
+    end
+
+    # Configure a model to use MetaStates
+    # @param model_class [Class] The model class to configure
+    # @return [Configuration::ModelConfiguration] The model configuration
+    # @raise [ArgumentError] If the model class is not an ActiveRecord model
+    def configure_model(model_class)
+      unless model_class.is_a?(Class) && model_class < ActiveRecord::Base
+        raise ArgumentError, "#{model_class} must be an ActiveRecord model"
+      end
+
+      model_config = Configuration::ModelConfiguration.new(model_class)
+
+      yield(model_config)
+
+      @model_configurations[model_class] = model_config
+      model_class.include(Stateable) unless model_class.included_modules.include?(Stateable)
+    end
+
+    # Check if a status is valid for a given state type
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @param status [String] The status
+    # @return [Boolean] True if the status is valid, false otherwise
+    def valid_status?(model_class, state_type, status)
+      return false unless @model_configurations[model_class]&.state_types&.dig(state_type.to_s)
+
+      @model_configurations[model_class].state_types[state_type.to_s].statuses.include?(status)
+    end
+
+    # Check if a state type is valid for a given model
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @return [Boolean] True if the state type is valid, false otherwise
+    def valid_state_type?(model_class, state_type)
+      @model_configurations[model_class]&.state_types&.key?(state_type.to_s)
+    end
+
+    # Get the configuration for a given state type
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @return [Configuration::StateTypeConfiguration] The state type configuration
+    def config_for(model_class, state_type)
+      @model_configurations[model_class]&.state_types&.dig(state_type.to_s)
+    end
+
+    # Get the state types for a given model
+    # @param model_class [Class] The model class
+    # @return [Hash] The state types for the model
+    def state_types_for(model_class)
+      @model_configurations[model_class]&.state_types
+    end
+
+    # Get the statuses for a given state type
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @return [Array] The statuses for the state type
+    def statuses_for(model_class, state_type)
+      return nil unless (config = config_for(model_class, state_type))
+
+      config.statuses
+    end
+
+    # Get the limit for a given state type
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @return [Integer] The limit for the state type
+    def limit_for(model_class, state_type)
+      return nil unless (config = config_for(model_class, state_type))
+
+      config.limit
+    end
+
+    # Get the metadata schema for a given state type
+    # @param model_class [Class] The model class
+    # @param state_type [String] The state type
+    # @return [Hash] The metadata schema for the state type
+    def metadata_schema_for(model_class, state_type)
+      return nil unless (config = config_for(model_class, state_type))
+
+      config.metadata_schema
+    end
+
+    # Register a callback for a given state type
+    # @param state_type [String] The state type
+    # @param id [Symbol] The callback id
+    # @param conditions [Hash] The conditions for the callback
+    # @param block [Proc] The callback block
+    # @return [Callback] The callback
+    def on(state_type, id: nil, **conditions, &block)
+      callback = Callback.new(state_type, conditions, block)
+      callback_id = id&.to_sym || generate_callback_id
+      @callbacks[callback_id] = callback
+      callback
+    end
+
+    # Remove a callback by id or callback object
+    # @param callback_or_id [Symbol, Callback] The callback id or callback object
+    # @return [Callback] The removed callback
+    def off(callback_or_id)
+      if callback_or_id.is_a?(Callback)
+        @callbacks.delete_if { |_, cb| cb == callback_or_id }
+      else
+        @callbacks.delete(callback_or_id)
+      end
+    end
+
+    # Get the callbacks that match a given state
+    # @param state [State] The state
+    # @return [Array] The matching callbacks
+    def matching_callbacks(state)
+      @callbacks.values.select { |callback| callback.matches?(state) }
+    end
+
+    # Clear all callbacks
+    # @return [void]
+    def clear_callbacks!
+      @callbacks = {}
+    end
+
+    private
+
+    # Generate a unique callback id
+    # @return [Symbol] The generated callback id
+    def generate_callback_id
+      @next_callback_id += 1
+      :"callback_#{@next_callback_id}"
+    end
+  end
+end

data/lib/meta_states/railtie.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module MetaStates
+  class Railtie < Rails::Railtie
+  end
+end
+
+require 'generators/meta_states/install/install_generator'

data/lib/meta_states/state.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MetaStates
+  class State < Base; end
+end

data/lib/meta_states/stateable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MetaStates
+  module Stateable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :states, class_name: 'MetaStates::Base',
+                        as: :stateable,
+                        dependent: :destroy
+    end
+
+    # Instance methods for managing states
+    def add_state(type, status: 'pending', metadata: {}, state_class: MetaStates::State)
+      states.create!(type: state_class.name, state_type: type, status: status, metadata: metadata)
+    end
+
+    def current_state(type)
+      states.where(state_type: type).order(created_at: :desc).first
+    end
+
+    def current_states(type)
+      states.where(state_type: type).order(created_at: :desc)
+    end
+  end
+end

data/lib/meta_states/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MetaStates
+  VERSION = '0.1.0'
+end

data/lib/meta_states.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'meta_states/version'
+require 'meta_states/configuration'
+require 'meta_states/configuration/model_configuration'
+require 'meta_states/configuration/state_type_configuration'
+
+module MetaStates
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      Configuration.instance
+    end
+  end
+end
+
+require 'meta_states/base'
+require 'meta_states/state'
+require 'meta_states/callback'
+require 'meta_states/stateable'
+require 'meta_states/railtie' if defined?(Rails)

data/spec/dummy/Gemfile

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"
+gem 'rails', '~> 8.0.1'
+# Use sqlite3 as the database for Active Record
+gem 'sqlite3', '>= 2.1'
+# Use the Puma web server [https://github.com/puma/puma]
+gem 'puma', '>= 5.0'
+
+# Use Active Model has_secure_password [https://guides.rubyonrails.org/active_model_basics.html#securepassword]
+# gem "bcrypt", "~> 3.1.7"
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem 'tzinfo-data', platforms: %i[windows jruby]
+
+# Use the database-backed adapters for Rails.cache and Active Job
+gem 'solid_cache'
+gem 'solid_queue'
+
+# Deploy this application anywhere as a Docker container [https://kamal-deploy.org]
+gem 'kamal', require: false
+
+# Add HTTP asset caching/compression and X-Sendfile acceleration to Puma [https://github.com/basecamp/thruster/]
+gem 'thruster', require: false
+
+# Use Rack CORS for handling Cross-Origin Resource Sharing (CORS), making cross-origin Ajax possible
+# gem "rack-cors"
+
+group :development, :test do
+  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
+  gem 'debug', platforms: %i[mri windows], require: 'debug/prelude'
+
+  # Static analysis for security vulnerabilities [https://brakemanscanner.org/]
+  gem 'brakeman', require: false
+end
+
+# MetaStates gem for state management and event system capabilities
+gem 'meta_states', path: '../..' # This points to the root of your gem

data/spec/dummy/Gemfile.lock

@@ -0,0 +1,308 @@
+PATH
+  remote: ../..
+  specs:
+    meta_states (0.1.0)
+      json-schema
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (8.0.2)
+      actionpack (= 8.0.2)
+      activesupport (= 8.0.2)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+      zeitwerk (~> 2.6)
+    actionmailbox (8.0.2)
+      actionpack (= 8.0.2)
+      activejob (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      mail (>= 2.8.0)
+    actionmailer (8.0.2)
+      actionpack (= 8.0.2)
+      actionview (= 8.0.2)
+      activejob (= 8.0.2)
+      activesupport (= 8.0.2)
+      mail (>= 2.8.0)
+      rails-dom-testing (~> 2.2)
+    actionpack (8.0.2)
+      actionview (= 8.0.2)
+      activesupport (= 8.0.2)
+      nokogiri (>= 1.8.5)
+      rack (>= 2.2.4)
+      rack-session (>= 1.0.1)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+      useragent (~> 0.16)
+    actiontext (8.0.2)
+      actionpack (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      globalid (>= 0.6.0)
+      nokogiri (>= 1.8.5)
+    actionview (8.0.2)
+      activesupport (= 8.0.2)
+      builder (~> 3.1)
+      erubi (~> 1.11)
+      rails-dom-testing (~> 2.2)
+      rails-html-sanitizer (~> 1.6)
+    activejob (8.0.2)
+      activesupport (= 8.0.2)
+      globalid (>= 0.3.6)
+    activemodel (8.0.2)
+      activesupport (= 8.0.2)
+    activerecord (8.0.2)
+      activemodel (= 8.0.2)
+      activesupport (= 8.0.2)
+      timeout (>= 0.4.0)
+    activestorage (8.0.2)
+      actionpack (= 8.0.2)
+      activejob (= 8.0.2)
+      activerecord (= 8.0.2)
+      activesupport (= 8.0.2)
+      marcel (~> 1.0)
+    activesupport (8.0.2)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    base64 (0.2.0)
+    bcrypt_pbkdf (1.1.1)
+    bcrypt_pbkdf (1.1.1-arm64-darwin)
+    bcrypt_pbkdf (1.1.1-x86_64-darwin)
+    benchmark (0.4.0)
+    bigdecimal (3.1.9)
+    brakeman (7.0.0)
+      racc
+    builder (3.3.0)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.0)
+    crass (1.0.6)
+    date (3.4.1)
+    debug (1.10.0)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    dotenv (3.1.7)
+    drb (2.2.1)
+    ed25519 (1.3.0)
+    erubi (1.13.1)
+    et-orbi (1.2.11)
+      tzinfo
+    fugit (1.11.1)
+      et-orbi (~> 1, >= 1.2.11)
+      raabro (~> 1.4)
+    globalid (1.2.1)
+      activesupport (>= 6.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.0)
+    irb (1.15.1)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json-schema (5.1.1)
+      addressable (~> 2.8)
+      bigdecimal (~> 3.1)
+    kamal (2.5.3)
+      activesupport (>= 7.0)
+      base64 (~> 0.2)
+      bcrypt_pbkdf (~> 1.0)
+      concurrent-ruby (~> 1.2)
+      dotenv (~> 3.1)
+      ed25519 (~> 1.2)
+      net-ssh (~> 7.3)
+      sshkit (>= 1.23.0, < 2.0)
+      thor (~> 1.3)
+      zeitwerk (>= 2.6.18, < 3.0)
+    logger (1.6.6)
+    loofah (2.24.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.12.0)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    marcel (1.0.4)
+    mini_mime (1.1.5)
+    mini_portile2 (2.8.8)
+    minitest (5.25.5)
+    net-imap (0.5.6)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-scp (4.1.0)
+      net-ssh (>= 2.6.5, < 8.0.0)
+    net-sftp (4.0.0)
+      net-ssh (>= 5.0.0, < 8.0.0)
+    net-smtp (0.5.1)
+      net-protocol
+    net-ssh (7.3.0)
+    nio4r (2.7.4)
+    nokogiri (1.18.5)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.18.5-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.5-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.5-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.5-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.5-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.5-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.5-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.5-x86_64-linux-musl)
+      racc (~> 1.4)
+    ostruct (0.6.1)
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    psych (5.2.3)
+      date
+      stringio
+    public_suffix (6.0.2)
+    puma (6.6.0)
+      nio4r (~> 2.0)
+    raabro (1.4.0)
+    racc (1.8.1)
+    rack (3.1.12)
+    rack-session (2.1.0)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
+    rack-test (2.2.0)
+      rack (>= 1.3)
+    rackup (2.2.1)
+      rack (>= 3)
+    rails (8.0.2)
+      actioncable (= 8.0.2)
+      actionmailbox (= 8.0.2)
+      actionmailer (= 8.0.2)
+      actionpack (= 8.0.2)
+      actiontext (= 8.0.2)
+      actionview (= 8.0.2)
+      activejob (= 8.0.2)
+      activemodel (= 8.0.2)
+      activerecord (= 8.0.2)
+      activestorage (= 8.0.2)
+      activesupport (= 8.0.2)
+      bundler (>= 1.15.0)
+      railties (= 8.0.2)
+    rails-dom-testing (2.2.0)
+      activesupport (>= 5.0.0)
+      minitest
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.6.2)
+      loofah (~> 2.21)
+      nokogiri (>= 1.15.7, != 1.16.7, != 1.16.6, != 1.16.5, != 1.16.4, != 1.16.3, != 1.16.2, != 1.16.1, != 1.16.0.rc1, != 1.16.0)
+    railties (8.0.2)
+      actionpack (= 8.0.2)
+      activesupport (= 8.0.2)
+      irb (~> 1.13)
+      rackup (>= 1.0.0)
+      rake (>= 12.2)
+      thor (~> 1.0, >= 1.2.2)
+      zeitwerk (~> 2.6)
+    rake (13.2.1)
+    rdoc (6.12.0)
+      psych (>= 4.0.0)
+    reline (0.6.0)
+      io-console (~> 0.5)
+    securerandom (0.4.1)
+    solid_cache (1.0.7)
+      activejob (>= 7.2)
+      activerecord (>= 7.2)
+      railties (>= 7.2)
+    solid_queue (1.1.4)
+      activejob (>= 7.1)
+      activerecord (>= 7.1)
+      concurrent-ruby (>= 1.3.1)
+      fugit (~> 1.11.0)
+      railties (>= 7.1)
+      thor (~> 1.3.1)
+    sqlite3 (2.6.0-aarch64-linux-gnu)
+    sqlite3 (2.6.0-aarch64-linux-musl)
+    sqlite3 (2.6.0-arm-linux-gnu)
+    sqlite3 (2.6.0-arm-linux-musl)
+    sqlite3 (2.6.0-arm64-darwin)
+    sqlite3 (2.6.0-x86-linux-gnu)
+    sqlite3 (2.6.0-x86-linux-musl)
+    sqlite3 (2.6.0-x86_64-darwin)
+    sqlite3 (2.6.0-x86_64-linux-gnu)
+    sqlite3 (2.6.0-x86_64-linux-musl)
+    sshkit (1.24.0)
+      base64
+      logger
+      net-scp (>= 1.1.2)
+      net-sftp (>= 2.1.2)
+      net-ssh (>= 2.8.0)
+      ostruct
+    stringio (3.1.5)
+    thor (1.3.2)
+    thruster (0.1.12)
+    thruster (0.1.12-aarch64-linux)
+    thruster (0.1.12-arm64-darwin)
+    thruster (0.1.12-x86_64-darwin)
+    thruster (0.1.12-x86_64-linux)
+    timeout (0.4.3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.0.3)
+    useragent (0.16.11)
+    websocket-driver (0.7.7)
+      base64
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    zeitwerk (2.7.2)
+
+PLATFORMS
+  aarch64-linux
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x86-linux
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  brakeman
+  debug
+  kamal
+  meta_states!
+  puma (>= 5.0)
+  rails (~> 8.0.1)
+  solid_cache
+  solid_queue
+  sqlite3 (>= 2.1)
+  thruster
+  tzinfo-data
+
+BUNDLED WITH
+   2.6.1

data/spec/dummy/README.md

@@ -0,0 +1,24 @@
+# README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...

data/spec/dummy/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative 'config/application'
+
+Rails.application.load_tasks

data/spec/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ApplicationController < ActionController::API
+end

data/spec/dummy/app/jobs/application_job.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class ApplicationJob < ActiveJob::Base
+  # Automatically retry jobs that encountered a deadlock
+  # retry_on ActiveRecord::Deadlocked
+
+  # Most jobs are safe to ignore if the underlying records are no longer available
+  # discard_on ActiveJob::DeserializationError
+end

data/spec/dummy/app/models/application_record.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+end

data/spec/dummy/app/models/company.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+class Company < ApplicationRecord; end

data/spec/dummy/app/models/user.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+class User < ApplicationRecord; end

data/spec/dummy/bin/brakeman

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'bundler/setup'
+
+ARGV.unshift('--ensure-latest')
+
+load Gem.bin_path('brakeman', 'brakeman')

data/spec/dummy/bin/dev

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+exec './bin/rails', 'server', *ARGV

data/spec/dummy/bin/docker-entrypoint

@@ -0,0 +1,14 @@
+#!/bin/bash -e
+
+# Enable jemalloc for reduced memory usage and latency.
+if [ -z "${LD_PRELOAD+x}" ]; then
+    LD_PRELOAD=$(find /usr/lib -name libjemalloc.so.2 -print -quit)
+    export LD_PRELOAD
+fi
+
+# If running the rails server then create or migrate existing database
+if [ "${@: -2:1}" == "./bin/rails" ] && [ "${@: -1:1}" == "server" ]; then
+  ./bin/rails db:prepare
+fi
+
+exec "${@}"

data/spec/dummy/bin/rails

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+APP_PATH = File.expand_path('../config/application', __dir__)
+require_relative '../config/boot'
+require 'rails/commands'

data/spec/dummy/bin/rake

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../config/boot'
+require 'rake'
+Rake.application.run

data/spec/dummy/bin/rubocop

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'rubygems'
+require 'bundler/setup'
+
+# explicit rubocop config increases performance slightly while avoiding config confusion.
+ARGV.unshift('--config', File.expand_path('../.rubocop.yml', __dir__))
+
+load Gem.bin_path('rubocop', 'rubocop')