thunderchunk 0.2.0

data/lib/thunderchunk/external_importer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class ExternalImporter
+    def initialize(chunk = nil)
+      @chunk = chunk
+      @importers = chunk.configuration['boot.external_importers'].to_h do |klass|
+        [klass.kind, klass.new(chunk)]
+      end
+    end
+
+    def load
+      @importers.each_value(&:load)
+    end
+
+    def hash
+      @importers.transform_values(&:items)
+    end
+
+    def get(kind)
+      @importers[kind.to_sym]
+    end
+
+    def get!(kind, path)
+      get(kind)&.get(path) || raise(Error, "#{kind} #{path} is not imported")
+    end
+
+    def each_constant(*, &)
+      hash.each_value do |items|
+        items.each_value(*, &)
+      end
+    end
+
+    def clear
+      @importers.each_value(&:clear)
+    end
+
+    def create_kind(importer)
+      kind = importer.class.kind
+
+      raise ArgumentError, 'This importer already has a kind' if @importers.has_value?(importer)
+      raise ArgumentError, 'This kind already has an importer' if @importers.has_key?(kind)
+
+      @importers[kind] = importer
+    end
+
+    def [](value)
+      hash[value]
+    end
+  end
+end

data/lib/thunderchunk/external_importers/base.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class ExternalImporters
+    class Base
+      def self.kind(value = nil)
+        return @kind = value if value
+
+        @kind || raise(NotImplementedError, "#{name} must declare `kind`")
+      end
+
+      def self.path(value = nil)
+        if value
+          @path = value
+          @should_load = true
+
+          return
+        end
+
+        @path || @kind.to_s.pluralize || raise(NotImplementedError, "#{name} must declare `kind` or `path`")
+      end
+
+      # Whether load reads app/external/<path> at boot. Off by default: an importer that builds each import on get
+      # has nothing to load.
+      def self.should_load(value = nil)
+        return @should_load = value unless value.nil?
+
+        @should_load || false
+      end
+
+      attr_reader :items
+
+      def initialize(chunk)
+        @chunk = chunk
+        @items = {}
+        @loader = Loader.new(@chunk.name, @chunk.root_path)
+      end
+
+      def add_constant(constant)
+        return false unless constant.is_a?(Class)
+
+        key = key_for(constant)
+        return false unless key
+
+        add(key, constant)
+        true
+      end
+
+      def key_for(_constant)
+        raise NotImplementedError
+      end
+
+      def get(_path)
+        raise NotImplementedError
+      end
+
+      def add(path, object)
+        @items[path] = object
+      end
+
+      def load
+        return unless self.class.should_load
+
+        @items = {}
+
+        @loader.load(["app/external/#{self.class.path}"])
+
+        @loader.each do |_parent, _name, constant|
+          add_constant(constant)
+        end
+
+        @loader.unload
+      end
+
+      def clear
+        @items.clear
+      end
+
+      private
+
+      def key_from_name(constant, *namespace)
+        segments = constant.name.split('::')
+        index = segments.each_index.find { |i| segments[i, namespace.size] == namespace }
+        return unless index
+
+        rest = segments.drop(index + namespace.size)
+        rest.map(&:underscore).join('.') unless rest.empty?
+      end
+    end
+  end
+end

data/lib/thunderchunk/external_importers/events.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class ExternalImporters
+    class Events < Base
+      class << self
+        # WARN: AI MADE
+        attr_accessor :resolver
+        # WARN: ---
+      end
+
+      kind :event
+      path 'messaging/events/'
+
+      def key_for(constant)
+        key_from_name(constant, 'External', 'Messaging', 'Events')&.tap do |key|
+          unless constant < ThunderChunk::Event
+            raise RegistryRequirementError, "#{constant.name} must inherit from ThunderChunk::Event"
+          end
+        end
+      end
+
+      # books.add
+      def get(key)
+        event_klass = @items[key] || raise(Error, 'this event is not registered')
+
+        event_klass.new(
+          @chunk,
+          key,
+          self.class.publisher(@chunk)
+        )
+      end
+
+      # WARN: AI MADE
+      # One publisher per chunk: each one is built with the config of its chunk.
+      def self.publisher(chunk)
+        @publishers ||= {}.compare_by_identity
+        @publishers[chunk] ||= begin
+          # WARN: ---
+          broker = chunk.config['messaging.broker.type']
+          publisher = chunk.config['messaging.publisher']
+
+          # WARN: AI MADE
+          resolver = Events.resolver || raise(Error, "no publisher for #{broker} #{publisher}: require 'thunderwire'")
+          # WARN: ---
+
+          publisher_klass = resolver.call(broker, publisher)
+
+          configuration = publisher_klass.configurations.to_h do |key, path|
+            [key, chunk.config[path]]
+          end.compact
+
+          publisher_klass.new(**configuration)
+        end
+      end
+    end
+  end
+end

data/lib/thunderchunk/external_importers/operations.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class ExternalImporters
+    class Operations < Base
+      kind :external_operation
+
+      # library/books.add
+      def get(path)
+        unless path.match?(%r{\A[a-z]+(_[a-z]+)*/[a-z]+([._][a-z]+)*\z})
+          raise Error, "invalid operation path #{path.inspect}"
+        end
+
+        @items[path] ||= begin
+          chunk_identifier, key = path.split('/')
+          dock = @chunk.sender_dock
+          # WARN: AI MADE
+          # The sender (and the remote's url in the config) is found on boot, so a missing url fails there; in specs
+          # every call is stubbed (ThunderSpec), so it is found on the first call only.
+          sender = -> { dock.sender_for(chunk_identifier, :operation) }
+          sender.call unless ENV['THUNDER_ENV'] == 'test'
+
+          ThunderChunk::Operations::Remote.new(sender:, key:)
+        end
+      end
+    end
+  end
+end

data/lib/thunderchunk/loader/load.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class Loader
+    class Load
+      # WARN: AI MADE
+      # The classes the chunk's code inherits from (ApplicationModel, InternalOperation): a file there defines one
+      # class at the top, without the chunk's modules, and any file of the chunk reaches it by its bare name.
+      COMMON = 'app/common'
+
+      def initialize(restrict_module, chunk_module, root_path)
+        @restrict_module = restrict_module
+        @root_path = root_path
+        @root = Namespace.new(chunk_module, root_path.join('app'), self)
+        @loaded = Set.new
+        @running = false
+
+        load = self
+        restrict_module.define_singleton_method(:const_missing) { |name| load.resolve_common(name) || super(name) }
+      end
+
+      def running? = @running
+
+      def run(files)
+        @running = true
+        files.each { |file| load_file(file) }
+      ensure
+        @running = false
+      end
+
+      def load_file(file)
+        return false unless @loaded.add?(file)
+
+        parent = common?(file) ? @restrict_module : @root.namespace_for(file.dirname).mod
+        @restrict_module.module_eval(file.read, file.to_s, 1)
+        validate_file_constant!(file, parent)
+        true
+      end
+
+      # WARN: AI MADE
+      # The common class with this name, loaded on its first use; nil when app/common has no file for it.
+      def resolve_common(name)
+        return unless running?
+
+        file = @root_path.glob("#{COMMON}/**/#{name.to_s.underscore}.rb").min
+        file && load_file(file) && @restrict_module.const_get(name, false)
+      end
+
+      private
+
+      def common?(file) = file.to_s.start_with?("#{@root_path.join(COMMON)}/")
+
+      def validate_file_constant!(file, parent)
+        constant = file.basename('.rb').to_s.camelize
+        return if parent.const_defined?(constant, false)
+
+        expected = parent.equal?(@restrict_module) ? constant : "#{parent.name}::#{constant}"
+        raise FileConstantMismatchError, "expected #{file.relative_path_from(@root_path)} to define #{expected}"
+      end
+    end
+  end
+end

data/lib/thunderchunk/loader/namespace.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class Loader
+    class Namespace
+      attr_reader :mod
+
+      def initialize(mod, directory, load)
+        @mod = mod
+        @directory = directory
+        @load = load
+        @children = {}
+
+        namespace = self
+        mod.define_singleton_method(:const_missing) { |name| namespace.resolve(name) || super(name) }
+      end
+
+      def namespace_for(directory)
+        directory.relative_path_from(@directory).each_filename.reduce(self) { |namespace, name| namespace.child(name) }
+      end
+
+      def child(name)
+        @children[name] ||= begin
+          constant = name.camelize
+          mod = @mod.const_defined?(constant, false) ? @mod.const_get(constant, false) : @mod.const_set(constant, Module.new)
+          Namespace.new(mod, @directory.join(name), @load)
+        end
+      end
+
+      def resolve(name)
+        return unless @load.running?
+
+        path = @directory.join(name.to_s.underscore)
+        file = path.sub_ext('.rb')
+
+        if file.file?
+          @load.load_file(file) && @mod.const_get(name, false)
+        elsif path.directory?
+          child(path.basename.to_s).mod
+        else
+          # WARN: AI MADE
+          @load.resolve_common(name)
+        end
+      end
+    end
+  end
+end

data/lib/thunderchunk/loader.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  LOADING_ORDER = %w[
+    app/internal/models
+    app/internal/operations
+  ].freeze
+
+  class Loader
+    attr_reader :chunk_module
+
+    def initialize(chunk_name, root_path)
+      @root_path = root_path
+      @chunk_name = chunk_name
+      @restrict_module = Module.new.tap { |mod| mod.set_temporary_name('<restrict>') }
+    end
+
+    def load(order = LOADING_ORDER)
+      @restrict_module.send(:remove_const, @chunk_name) if @restrict_module.const_defined?(@chunk_name, false)
+      @chunk_module = named_module(@chunk_name)
+      @restrict_module.const_set(@chunk_name, @chunk_module)
+
+      Load.new(@restrict_module, @chunk_module, @root_path).run(files(order))
+    rescue Exception
+      unload
+
+      raise
+    end
+
+    def each(&block)
+      constants_of(@restrict_module).reverse_each(&block)
+    end
+
+    def unload
+      constants_of(@restrict_module).reverse_each do |parent, name, value|
+        yield(parent, name, value) if block_given?
+
+        parent.send(:remove_const, name)
+      end
+    end
+
+    private
+
+    def files(order)
+      order.flat_map { |path| Dir.glob(@root_path.join(path, '**', '*.rb')).sort.map { Pathname(it) } }
+    end
+
+    def constants_of(parent)
+      parent.constants(false).flat_map do |name|
+        value = parent.const_get(name, false)
+        namespace = value.equal?(@chunk_module) || (value.instance_of?(Module) && value.name == "#{parent.name}::#{name}")
+
+        [[parent, name, value], *(namespace ? constants_of(value) : [])]
+      end
+    end
+
+    def named_module(name)
+      raise Error, "::#{name} already exists; it would collide with the chunk" if Object.const_defined?(name, false)
+
+      Module.new.tap do |mod|
+        Object.const_set(name, mod)
+        Object.send(:remove_const, name)
+      end
+    end
+  end
+end

data/lib/thunderchunk/model.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class Model < ActiveRecord::Base
+    self.abstract_class = true
+
+    class_attribute :chunk_key, :chunk_registry, instance_writer: false, instance_predicate: false
+
+    # WARN: AI MADE
+    # A uuid primary key gets a UUIDv7 (ordered by creation time) when the record is created without one, as in
+    # tcard_backend's ApplicationRecord. The column default (gen_random_uuid(), a v4) is left for rows inserted in SQL.
+    before_create :assign_uuid_v7_id
+
+    class << self
+      def module_parent = Object
+      def module_parents = [Object]
+
+      def chunk_name
+        raise Error, "#{name} is not registered yet" unless chunk_key
+
+        chunk_key.split('.').map(&:camelize).join('::')
+      end
+
+      def model_name
+        @model_name ||= ActiveModel::Name.new(self, nil, chunk_name)
+      end
+
+      def sti_name = chunk_name
+      def polymorphic_name = chunk_name
+
+      def sti_class_for(type_name)
+        model_for(type_name) || raise(ActiveRecord::SubclassNotFound, "unknown model #{type_name} for #{chunk_name}")
+      end
+
+      def polymorphic_class_for(name) = model_for!(name)
+
+      private
+
+      def compute_type(type_name)
+        return model_for!(type_name.delete_prefix('::')) if type_name.start_with?('::')
+
+        scope = chunk_name.split('::')[0...-1]
+        candidates = scope.size.downto(0).map { |n| [*scope.first(n), type_name].join('::') }
+        candidates.each { |candidate| (klass = model_for(candidate)) and return klass }
+
+        raise NameError.new("model #{type_name} not found from #{chunk_name} (tried #{candidates.join(', ')})", type_name)
+      end
+
+      def model_for(name) = chunk_registry.get(name.underscore.tr('/', '.'))
+      def model_for!(name) = model_for(name) || raise(NameError.new("unknown model #{name}", name))
+
+      def compute_table_name
+        base_class? ? chunk_name.underscore.tr('/', '_').pluralize : superclass.table_name
+      end
+    end
+
+    private
+
+    def assign_uuid_v7_id
+      return if id.present?
+      return unless self.class.primary_key == 'id'
+      return unless self.class.columns_hash['id']&.type == :uuid
+
+      self.id = SecureRandom.uuid_v7
+    end
+  end
+end

data/lib/thunderchunk/operations/adapters/use_dependecy.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  module Operations
+    module Adapters
+      class UseDependency < ThunderOperation::Adapter
+        adapted do
+          def self.use(kind, path, **options)
+            dependencies << Dependency.new(
+              kind: kind.to_sym,
+              path: path.to_s,
+              config: { on_instance: true },
+              options:
+            )
+          end
+
+          def self.dependencies
+            @dependencies ||= []
+          end
+
+          def self.const_missing(name)
+            raise NameError.new("#{name} is not available in this operation; #{use_hint(name)}", name)
+          end
+
+          def self.use_hint(name)
+            key = name.to_s.underscore
+            return "declare it with `use :<kind>, '#{key}'`" unless respond_to?(:chunk) && chunk
+
+            matches = chunk.registry.hash.flat_map do |kind, items|
+              items.keys.sort.select { |path| path == key || path.start_with?("#{key}.") }.map { |path| "`use :#{kind}, '#{path}'`" }
+            end
+            return "nothing named #{key} is registered in the chunk" if matches.empty?
+
+            "declare it with #{matches.join(' or ')}"
+          end
+
+          private_class_method :use_hint
+        end
+      end
+    end
+  end
+end

data/lib/thunderchunk/operations/base.rb

@@ -0,0 +1,12 @@
+
+module ThunderChunk
+  module Operations
+    class Base < ThunderOperation::Base
+      append_adapter ThunderOperation::Adapters::RichParameters
+      append_adapter ThunderOperation::Adapters::Interruptable
+      append_adapter Adapters::UseDependency
+      # WARN: AI MADE
+      append_adapter ThunderOperation::Adapters::Validations
+    end
+  end
+end

data/lib/thunderchunk/operations/external.rb

@@ -0,0 +1,7 @@
+module ThunderChunk
+  module Operations
+    class External < Base
+      append_adapter ThunderOperation::Adapters::Framer
+    end
+  end
+end

data/lib/thunderchunk/operations/internal.rb

@@ -0,0 +1,6 @@
+module ThunderChunk
+  module Operations
+    class Internal < Base
+    end
+  end
+end

data/lib/thunderchunk/operations/remote.rb

@@ -0,0 +1,50 @@
+module ThunderChunk
+  module Operations
+    class Remote
+      class RemoteFailure < ThunderChunk::Error
+        attr_reader :response
+
+        def initialize(response)
+          @response = response
+          super("Remote operation failed: #{response.inspect}")
+        end
+      end
+
+      # The error of a Response that failed in another chunk: the original exception stays there, so this one carries
+      # its message, class name, extras and trail.
+      class RemoteResponseFailure < ThunderChunk::Error
+        attr_reader :error_class, :extras, :trail
+
+        def initialize(message, error_class:, extras:, trail:)
+          @error_class = error_class
+          @extras = extras
+          @trail = trail
+          super(message)
+        end
+      end
+
+      # WARN: AI MADE
+      # sender: a sender, or a lambda that returns one when the first call needs it.
+      def initialize(sender:, key:)
+        @sender = sender
+        @key = key
+      end
+
+      def call(**params) = sender.call(@key, params)
+
+      def call!(**params)
+        response = call(**params)
+        raise RemoteFailure, response if response.failure?
+
+        response
+      end
+
+      private
+
+      def sender
+        @sender = @sender.call if @sender.is_a?(Proc)
+        @sender
+      end
+    end
+  end
+end

data/lib/thunderchunk/operations/subscriber.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  module Operations
+    class Subscriber < Base
+      # Every param of a subscriber is optional: a key the event leaves out arrives as nil.
+      def self.param(field_name, *args, **options, &)
+        super(field_name, *args, { **options, optional: true }, &)
+      end
+    end
+  end
+end

data/lib/thunderchunk/outbox.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class Outbox < Model
+    self.chunk_key = 'outbox'
+    self.table_name = 'thunder_outbox'
+
+    scope :pending, -> { where(published_at: nil).order(:id) }
+  end
+end