ecs_on_rails 0.2.2 → 0.3.0

data/lib/ecs_rails/catalogue/schema_diff.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # Compares a declaration with live PostgreSQL metadata (ECS-29). It only
+    # renders additions; a mismatch describes the explicit repair needed.
+    # Application data and existing definitions are never changed here.
+    class SchemaDiff
+      # @param schema [Schema] the expected catalogue declaration
+      # @param table_name [String, Symbol] the existing table
+      # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+      # @param slot_upgrade [Boolean] the preceding migration adds slot/index
+      def initialize(schema, table_name:, connection:, slot_upgrade: false)
+        @schema = schema
+        @table = table_name.to_s
+        @connection = connection
+        @slot_upgrade = slot_upgrade
+        @columns = connection.columns(@table).index_by(&:name)
+        @indexes = connection.indexes(@table)
+        @foreign_keys = connection.foreign_keys(@table)
+      end
+
+      # @param indent [Integer] spaces inside the generated change method
+      # @return [String] additive source, or empty for a compatible table
+      # @raise [SchemaMismatch] existing structure requires a reviewed repair
+      def to_ruby(indent: 4)
+        @additions = []
+        @problems = []
+        inspect_columns
+        inspect_indexes
+        inspect_foreign_keys
+        unless @problems.empty?
+          raise SchemaMismatch, "Catalogue schema mismatch:\n- #{@problems.join("\n- ")}\n" \
+                                "Write and review an explicit repair/backfill migration, then rerun ecs_rails:upgrade. " \
+                                "No column conversion or constraint replacement was generated."
+        end
+        @additions.map { |line| "#{' ' * indent}#{line}" }.join("\n")
+      end
+
+      private
+
+      def required_columns
+        [Schema::Column.new(:uuid, :id, null: false),
+         Schema::Column.new(:uuid, :entity_id, null: false),
+         Schema::Column.new(:string, :slot, null: false, default: ""),
+         *@schema.columns,
+         Schema::Column.new(:datetime, :created_at, null: false, precision: 6),
+         Schema::Column.new(:datetime, :updated_at, null: false, precision: 6)]
+      end
+
+      def inspect_columns
+        primary_key = @connection.primary_key(@table)
+        mismatch("primary key", primary_key, "id") unless primary_key == "id"
+        required_columns.each do |column|
+          next if column.name == :slot && @slot_upgrade
+
+          actual = @columns[column.name.to_s]
+          if actual.nil?
+            if %i[id entity_id].include?(column.name) || (!column.options.fetch(:null, true) && column.options[:default].nil?)
+              @problems << "#{@table}.#{column.name} is missing; needs #{column.type} #{column.options.inspect} and an explicit backfill"
+            else
+              @additions << "add_column :#{@table}, :#{column.name}, :#{column.type}#{options(column.options)}"
+            end
+            next
+          end
+
+          expected = column_properties(column)
+          observed = actual_properties(actual)
+          expected.each do |property, value|
+            mismatch("#{column.name} #{property}", observed[property], value) unless observed[property] == value
+          end
+        end
+      end
+
+      def column_properties(column)
+        type = column.type == :bigint ? :integer : column.type
+        properties = { type: type, null: column.options.fetch(:null, true),
+                       array: column.options.fetch(:array, false), default: column.options[:default] }
+        if column.name == :id
+          properties[:default] = "gen_random_uuid()"
+        end
+        if %i[string integer].include?(type)
+          properties[:limit] = column.options.fetch(:limit, type == :integer ? (column.type == :bigint ? 8 : 4) : nil)
+        end
+        if %i[decimal datetime].include?(type)
+          properties[:precision] = column.options.fetch(:precision, type == :datetime ? 6 : nil)
+        end
+        properties[:scale] = column.options[:scale] if type == :decimal
+        properties
+      end
+
+      def actual_properties(actual)
+        default = if actual.default_function
+                    actual.default_function.sub(/\A(?:public|pg_catalog)\./, "")
+                  else
+                    deserialize_default(actual)
+                  end
+        { type: actual.type, null: actual.null, array: actual.array, default: default,
+          limit: actual.limit, precision: actual.type == :datetime ? (actual.precision || 6) : actual.precision,
+          scale: actual.scale }
+      end
+
+      # Use registered attribute types without loading an application model or
+      # populating its table/schema cache. PostgreSQL reports arrays and JSON
+      # defaults as strings; comparing those strings to Ruby [] is incorrect.
+      def deserialize_default(column)
+        return nil if column.default.nil?
+        return column.default if column.type == :tsvector
+
+        modifiers = column.array ? { array: true } : {}
+        ActiveRecord::Type.lookup(column.type, adapter: :postgresql, **modifiers)
+                          .deserialize(column.default)
+      end
+
+      def inspect_indexes
+        singleton = Schema::Index.new(%i[entity_id slot], unique: true)
+        if @slot_upgrade
+          legacy = Schema::Index.new([:entity_id], unique: true)
+          unless @indexes.any? { |index| matching_index?(index, legacy) }
+            @problems << "#{@table} pre-slot upgrade needs an unconditional unique index on entity_id; inspect legacy duplicates before repair"
+          end
+        else
+          inspect_index(singleton)
+        end
+        @schema.indexes.each { |index| inspect_index(index) }
+      end
+
+      def inspect_index(expected)
+        return if @indexes.any? { |actual| matching_index?(actual, expected) }
+
+        name = expected.options[:name] || @connection.index_name(@table, column: expected.columns)
+        conflicts = @indexes.select { |index| index.columns == expected.columns.map(&:to_s) || index.name == name }
+        if conflicts.any?
+          actual = conflicts.map { |index| "#{index.name} #{index_properties(index).inspect}" }.join(", ")
+          mismatch("index #{expected.columns.inspect}", actual, expected_index_properties(expected))
+        else
+          @additions << "add_index :#{@table}, #{expected.columns.inspect}#{options(expected.options)}"
+        end
+      end
+
+      def matching_index?(actual, expected)
+        actual.columns == expected.columns.map(&:to_s) && index_properties(actual) == expected_index_properties(expected)
+      end
+
+      def index_properties(index)
+        { unique: index.unique, using: index.using.to_s, where: predicate(index.where),
+          order: index.orders.presence, opclass: index.opclasses.presence,
+          nulls_not_distinct: !!index.nulls_not_distinct, valid: index.valid? }
+      end
+
+      def expected_index_properties(index)
+        { unique: index.options.fetch(:unique, false), using: index.options.fetch(:using, :btree).to_s,
+          where: predicate(index.options[:where]), order: index.options[:order].presence,
+          opclass: index.options[:opclass].presence,
+          nulls_not_distinct: index.options.fetch(:nulls_not_distinct, false), valid: true }
+      end
+
+      # The catalogue has one simple Boolean predicate. Recognize its normal
+      # PostgreSQL spellings; do not guess equivalence for arbitrary SQL.
+      def predicate(value)
+        text = value.to_s.strip
+        return nil if text.empty?
+        return "exclusive" if text.match?(/\A\(*"?exclusive"?\s*(?:=\s*true|IS\s+TRUE)?\)*\z/i)
+
+        text
+      end
+
+      def inspect_foreign_keys
+        required = [Schema::ForeignKey.new(:entity_id, :cascade), *@schema.foreign_keys]
+        required.each do |expected|
+          candidates = @foreign_keys.select { |key| key.column == expected.column.to_s }
+          properties = { to_table: "entities", primary_key: "id", on_delete: expected.on_delete,
+                         on_update: nil, validate: true, deferrable: false }
+          next if candidates.any? { |key| foreign_key_properties(key) == properties }
+
+          if candidates.empty?
+            @additions << "add_foreign_key :#{@table}, :entities, column: :#{expected.column}, on_delete: :#{expected.on_delete}"
+          else
+            mismatch("foreign key #{expected.column}", candidates.map { |key| foreign_key_properties(key) }, properties)
+          end
+        end
+      end
+
+      def foreign_key_properties(key)
+        { to_table: key.to_table, primary_key: key.primary_key, on_delete: key.on_delete,
+          on_update: key.on_update, validate: key.validate?, deferrable: !!key.deferrable }
+      end
+
+      def mismatch(subject, actual, expected)
+        @problems << "#{@table}.#{subject}: found #{actual.inspect}; expected #{expected.inspect}"
+      end
+
+      def options(values)
+        values.empty? ? "" : ", " + values.map { |key, value| "#{key}: #{value.inspect}" }.join(", ")
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/search_vector.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # PostgreSQL full-text search with no dependency: a `tsvector` and a GIN
+    # index. Rebuilt from an entity's texts by an entity-blind Indexer system.
+    #
+    #   post.search_vector.reindex!(post.title_text, post.body_text)
+    #   SearchVector.matching("composable").pluck(:entity_id)
+    module SearchVector
+      extend Definition
+
+      table "search_vectors"
+      schema do |t|
+        t.tsvector :document, default: nil
+        t.index :document, using: :gin
+      end
+
+      included do
+        # Rows whose document matches `query` (plainto_tsquery, `simple` config).
+        #
+        # @param query [String]
+        # @return [ActiveRecord::Relation]
+        scope :matching, ->(query) { where("document @@ plainto_tsquery('simple', ?)", query) }
+      end
+
+      # Rebuilds the document from `texts` and saves.
+      #
+      # @param texts [Array<String, nil>]
+      # @return [void]
+      def reindex!(*texts)
+        save! unless persisted?
+        self.class.where(id: id).update_all(["document = to_tsvector('simple', ?)", texts.flatten.compact.join(" ")])
+        reload
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/state.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A state machine: a `status` and an optional `transitions` log. The
+    # vocabulary belongs to the declaring entity, not the component:
+    #
+    #   class Order < ApplicationEntity
+    #     component State, prefix: :fulfilment, states: %w[pending paid shipped], history: true
+    #   end
+    #
+    #   order.fulfilment_state.transition!("paid", event: "checkout")
+    #   order.fulfilment_state.status         # => "paid"
+    #   order.fulfilment_state.transitions    # => [{ "at" => ..., "from" => "pending", "to" => "paid", "event" => "checkout" }]
+    #
+    # `states:` — the allowed values; empty means any. `history:` — whether
+    # `transition!` appends to the log (default true); `history: false` makes a
+    # slot a plain enum (visibility, priority, severity) on the same table.
+    module State
+      extend Definition
+
+      table "states"
+      schema do |t|
+        t.string :status,      default: nil
+        t.jsonb  :transitions, default: [], null: false
+      end
+
+      included do
+        slot_option :states,  default: []
+        slot_option :history, default: true
+        validate :ecs_status_in_vocabulary
+      end
+
+      # Moves to `to`, logging the transition when `history` is on, and saves.
+      #
+      # @param to [String, Symbol] the new status
+      # @param event [String, Symbol, nil] a label for the log
+      # @return [String] the new status
+      # @raise [ArgumentError] if `to` is not in the slot's `states:`
+      def transition!(to, event: nil)
+        to = to.to_s
+        unless states.empty? || states.map(&:to_s).include?(to)
+          raise ArgumentError, "#{to.inspect} is not one of #{states.inspect} (slot #{slot.inspect})"
+        end
+
+        if history
+          entry = { "at" => Time.current.iso8601, "from" => status, "to" => to }
+          entry["event"] = event.to_s if event
+          self.transitions = transitions + [entry]
+        end
+        self.status = to
+        save!
+        status
+      end
+
+      # @param value [String, Symbol]
+      # @return [Boolean]
+      def in?(value)
+        status == value.to_s
+      end
+
+      private
+
+      def ecs_status_in_vocabulary
+        return if status.nil? || states.empty? || states.map(&:to_s).include?(status)
+
+        errors.add(:status, "must be one of #{states.join(', ')}")
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/tags.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # Free tagging: an array of strings. An unbounded set of *strings* is a
+    # value, not a collection of entities. `allow:` on the declaration
+    # restricts the vocabulary.
+    #
+    #   component Tags, prefix: :topics, allow: %w[ruby rails ecs]
+    #   post.topics_tags.add("ruby")
+    #   Post.with_component(Tags, prefix: :topics) { tagged("ruby") }
+    module Tags
+      extend Definition
+
+      table "tags"
+      schema do |t|
+        t.string :names, array: true, default: [], null: false
+        t.index :names, using: :gin
+      end
+
+      included do
+        slot_option :allow, default: nil
+        validate :ecs_names_allowed
+
+        # Rows tagged with `name`.
+        #
+        # @param name [String]
+        # @return [ActiveRecord::Relation]
+        scope :tagged, ->(name) { where("? = ANY (names)", name.to_s) }
+      end
+
+      # Adds names, de-duplicated, and returns the array.
+      #
+      # @param new_names [Array<String>]
+      # @return [Array<String>]
+      def add(*new_names)
+        self.names = (names + new_names.flatten.map(&:to_s)).uniq
+      end
+
+      # Removes names and returns the array.
+      #
+      # @param gone [Array<String>]
+      # @return [Array<String>]
+      def remove(*gone)
+        self.names = names - gone.flatten.map(&:to_s)
+      end
+
+      # @param name [String]
+      # @return [Boolean]
+      def tagged?(name)
+        names.include?(name.to_s)
+      end
+
+      private
+
+      def ecs_names_allowed
+        return if allow.nil?
+
+        disallowed = names - allow.map(&:to_s)
+        errors.add(:names, "#{disallowed.join(', ')} not allowed (allowed: #{allow.join(', ')})") if disallowed.any?
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/text.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A piece of text: title, body, bio, description — one slot each. The most
+    # generic shape in the catalogue. `value` is the primary attribute, so
+    # `component Text, prefix: :title` reads and writes as `post.title` — the
+    # slot name is the field name — while `post.title_text` is the component.
+    module Text
+      extend Definition
+
+      table "texts"
+      primary_attribute :value
+      schema do |t|
+        t.text :value, default: nil
+      end
+
+      # @return [String] the value, or ""
+      def to_s
+        value.to_s
+      end
+
+      # @return [Integer] word count
+      def words
+        value.to_s.split.size
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/timestamp.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module EcsRails
+  module Catalogue
+    # A point in time: issued_at, published_at, last_seen_at — one slot each.
+    module Timestamp
+      extend Definition
+
+      table "timestamps"
+      primary_attribute :at
+      schema do |t|
+        t.datetime :at, default: nil
+      end
+
+      # Sets `at` to now and saves.
+      #
+      # @return [Time]
+      def stamp!
+        update!(at: Time.current)
+        at
+      end
+
+      # @return [Boolean] whether `at` is set and in the past
+      def past?
+        at.present? && at <= Time.current
+      end
+
+      # @return [Boolean] whether `at` is set and in the future
+      def future?
+        at.present? && at > Time.current
+      end
+    end
+  end
+end

data/lib/ecs_rails/catalogue/token.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+require "active_support/core_ext/securerandom"
+require "active_support/security_utils"
+
+module EcsRails
+  module Catalogue
+    # A revocable secret: password reset, invitation, API key — one slot each.
+    # Stores a **digest**, never the value (the `generates_token_for` shape):
+    # generate once, show once, verify against the digest.
+    #
+    #   raw = user.reset_token.generate!(expires_in: 1.hour)   # give this to the user
+    #   user.reset_token.verify(raw)                           # => true while valid
+    #   user.reset_token.revoke!                               # the caller consumes/revokes it
+    #
+    # Verification does not consume the token. A single-use workflow must
+    # coordinate verification, its action and revocation in the application.
+    module Token
+      extend Definition
+
+      table "tokens"
+      schema do |t|
+        t.string   :digest,     default: nil
+        t.datetime :expires_at, default: nil
+        t.index :digest
+      end
+
+      # Generates a fresh value, stores its digest and saves. Returns the value
+      # — the only time it is available.
+      #
+      # @param expires_in [ActiveSupport::Duration, nil] nil for no expiry
+      # @return [String] the raw token
+      def generate!(expires_in: nil)
+        raw = SecureRandom.base58(32)
+        update!(digest: self.class.ecs_digest(raw), expires_at: expires_in && Time.current + expires_in)
+        raw
+      end
+
+      # @param raw [String]
+      # @return [Boolean] whether `raw` matches and the token has not expired
+      def verify(raw)
+        return false if digest.nil? || raw.nil? || expired?
+
+        ActiveSupport::SecurityUtils.secure_compare(digest, self.class.ecs_digest(raw))
+      end
+
+      # @return [Boolean]
+      def expired?
+        expires_at.present? && expires_at <= Time.current
+      end
+
+      # Forgets the token.
+      #
+      # @return [void]
+      def revoke!
+        update!(digest: nil, expires_at: nil)
+      end
+
+      included do
+        # @api private
+        def self.ecs_digest(raw)
+          Digest::SHA256.hexdigest(raw)
+        end
+
+        # The row for a raw token, if any (then `verify` it).
+        #
+        # @param raw [String]
+        # @return [ActiveRecord::Base, nil]
+        def self.find_by_token(raw)
+          find_by(digest: ecs_digest(raw))
+        end
+      end
+    end
+  end
+end