thunderchunk 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c833649b47c00913dff97d2e720c98081377b18423134fe802b974684b0845fe
+  data.tar.gz: 3f361ec71acc5ad2da5c9768e7e9f6f5a0ae60c8ae8cfd22d94a3f0372b754af
+SHA512:
+  metadata.gz: 61ffba944656899c69bb55224b4e15dec0158a6b8656a681095744420cbd6617c57350b6dae9048a75c9f0fb89a8aebbeae710bb636954bcd9d42f6105205e59
+  data.tar.gz: b0ccaacb0c416783f87c1e03fc0f1d7061463eb2cf2a172cf2c3f6f0d534fa8231640bd4c2d1f687e80744ff4f9edee75eedc6f369375fcd5940630801476167

data/README.md

@@ -0,0 +1,3 @@
+# thunderchunk
+
+Manages a chunk: operations engine, surfaces, schema and migrations. Depends on `thunderfoundation`, never on `thunderbolt`.

data/lib/rubocop/cop/thunderchunk/restricted_access.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module ThunderChunk
+      # Chunk classes live under an anonymous restrict module and everything in a chunk is reached only
+      # through `use` (ActiveRecord resolving associations and `class_name:` is the exception).
+      # Reflection reaches them anyway, so chunk code may not use it.
+      #
+      #   # bad
+      #   ThunderChunk::Model.descendants.find { |model| model.name.end_with?('Book') }
+      #   Models.const_get(:Book)
+      #   ObjectSpace.each_object(Class)
+      #
+      #   # good
+      #   use :model, 'Book'
+      class RestrictedAccess < Base
+        MSG = '`%<code>s` reaches chunk classes by reflection. ' \
+              'Everything in a chunk is only accessible inside an operation via `use`.'
+
+        RESTRICT_ON_SEND = %i[
+          const_get constantize safe_constantize descendants subclasses instance_variable_get
+        ].freeze
+
+        def on_send(node)
+          add_offense(node.loc.selector, message: format(MSG, code: node.method_name))
+        end
+        alias on_csend on_send
+
+        def on_const(node)
+          return unless node.short_name == :ObjectSpace && (node.namespace.nil? || node.namespace.cbase_type?)
+
+          add_offense(node, message: format(MSG, code: 'ObjectSpace'))
+        end
+      end
+    end
+  end
+end

data/lib/thunderchunk/chunk.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class Chunk
+    CONFIGURATION_FILE = 'config/chunk.rb'
+    DEFAULT_CONFIGURATION_FILE = Pathname(__dir__).join('default_configuration.rb')
+
+    attr_reader :chunk_name, :root_path,
+                :loader, :registry, :exporter, :external_importer, :sender_dock,
+                :dependency_injector,
+                :configuration, :database
+
+    alias config configuration
+    alias name chunk_name
+
+    def initialize(
+      chunk_name: nil,
+      root_path: nil
+    )
+      @root_path = Pathname(root_path || bundle_root)
+      @chunk_name = chunk_name || @root_path.basename.to_s.camelize
+
+      @configuration = Configuration.new
+      @dependency_injector = DependencyInjector.new(self)
+      @database = Database.new(self)
+      @booted = false
+    end
+
+    def identifier = name.underscore.to_sym
+
+    def boot(extra_config = {})
+      previous_registry = @registry
+      previous_exporter = @exporter
+      previous_external_importer = @external_importer
+      previous_sender_dock = @sender_dock
+      previous_configuration = @configuration
+
+      @configuration = Configuration.read(DEFAULT_CONFIGURATION_FILE)
+                                    .merge(load_configuration)
+                                    .merge(extra_config)
+
+      registry = Registry.new(self)
+      exporter = Exporter.new(self)
+      external_importer = ExternalImporter.new(self)
+
+      registry.load
+      exporter.load
+
+      # The imports are resolved while the dependencies are injected, so they are in place before it.
+      @sender_dock = SenderDock.new(self)
+      external_importer.load
+
+      @registry = registry
+      @exporter = exporter
+      @external_importer = external_importer
+      registry.each_constant do |klass|
+        attach(klass, registry)
+        inject_dependencies(klass)
+      end
+      exporter.each_constant do |klass|
+        attach(klass, exporter)
+        inject_dependencies(klass)
+      end
+      # WARN: AI MADE
+      [registry, exporter].each { |source| source.each_constant { |klass| TypeNames.resolve(self, klass) } }
+
+      @booted = true
+      # WARN: AI MADE
+      # The engine has one setting for the process, which runs one chunk.
+      ThunderOperation.config.validate_returns = @configuration['operations.validate_returns'] == true
+      # WARN: AI MADE
+      Time.zone_default = Time.find_zone!(@configuration['time.zone'])
+
+      @database.connect
+    rescue StandardError, ScriptError
+      @registry = previous_registry
+      @exporter = previous_exporter
+      @external_importer = previous_external_importer
+      @sender_dock = previous_sender_dock
+      @configuration = previous_configuration
+      @booted = false
+      raise
+    end
+
+    def reload = boot
+
+    def booted? = @booted
+
+    private
+
+    # Bundler is loaded only here: a process started without it (a standalone bundle) does not pay for it when the
+    # chunk is given its root.
+    def bundle_root
+      require 'bundler'
+      Bundler.root
+    end
+
+    def load_configuration
+      file = @root_path.join(CONFIGURATION_FILE)
+      return Configuration.new unless file.file?
+
+      Configuration.read(file)
+    end
+
+    def attach(klass, origin)
+      chunk = self
+      klass.define_singleton_method(:chunk) { chunk }
+    end
+
+    def inject_dependencies(klass)
+      return unless klass.respond_to?(:dependencies)
+
+      klass.dependencies.each do |dependency|
+        dependency_injector.inject(
+          klass,
+          dependency.kind,
+          dependency.path,
+          **dependency.options
+        )
+      end
+    end
+  end
+end

data/lib/thunderchunk/configuration.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# WARN: AI MADE
+module ThunderChunk
+  class Configuration < BasicObject
+    # Set while a config block runs: the method chain (database.port = 1) works only there; elsewhere config['path'].
+    BLOCK_KEY = :thunderchunk_configuration_block
+
+    def self.read(file)
+      configuration = ::Object.new.instance_eval(file.read, file.to_s, 1)
+      return configuration if Configuration === configuration
+
+      raise Error, "#{file} must return a ThunderChunk::Configuration; it returned #{configuration.inspect}"
+    end
+
+    # The block runs on first access, or on top of another configuration in merge, so `boot.registries << X` and
+    # `+=` act on the value the other configuration holds.
+    def initialize(values = {}, &block)
+      @values = {}
+      values.each { |key, value| _set(key, value) }
+      @block = block
+    end
+
+    def merge(other)
+      return Configuration.new(to_h.deep_merge(other.deep_symbolize_keys)) if ::Hash === other
+
+      merged = Configuration.new(to_h.deep_merge(other._to_h))
+      merged._run(other._block) if other._block
+      merged
+    end
+
+    def _block = @block
+
+    def _get(key)
+      _evaluate
+      @values[key.to_sym]
+    end
+
+    # A Hash becomes a group; a list is copied, so `<<` in a merge does not change the configuration merged from.
+    def _set(key, value)
+      _evaluate
+      value = Configuration.new(value) if ::Hash === value
+      value = value.dup if ::Array === value
+      @values[key.to_sym] = value
+    end
+
+    def _evaluate
+      return unless @block
+
+      block = @block
+      @block = nil
+      _run(block)
+    end
+
+    def _run(block)
+      previous = ::Fiber[BLOCK_KEY]
+      ::Fiber[BLOCK_KEY] = true
+      instance_exec(&block)
+    ensure
+      ::Fiber[BLOCK_KEY] = previous
+    end
+
+    def [](*path)
+      value = path.map(&:to_s).join('.').split('.').reduce(self) do |node, key|
+        break unless Configuration === node
+
+        node._get(key)
+      end
+
+      return value unless Configuration === value
+
+      hash = value.to_h
+      hash unless hash.empty?
+    end
+
+    # config['database.port'] = 5432: creates the groups on the way.
+    def []=(path, value)
+      *groups, key = path.to_s.split('.')
+      node = groups.reduce(self) { |group, name| group._get(name) || group._set(name, Configuration.new) }
+      ::Kernel.raise ::ArgumentError, "#{path} goes through a value, not a group" unless Configuration === node
+
+      node._set(key, value)
+    end
+
+    def to_h
+      _evaluate
+      _to_h
+    end
+
+    # The values without running the block.
+    def _to_h
+      @values.each_with_object({}) do |(key, value), hash|
+        next hash[key] = value unless Configuration === value
+
+        nested = value.to_h
+        hash[key] = nested unless nested.empty?
+      end
+    end
+
+    def inspect
+      "#<ThunderChunk::Configuration #{to_h.inspect}>"
+    end
+
+    def pretty_print(printer)
+      printer.text('#<ThunderChunk::Configuration ')
+      printer.pp(to_h)
+      printer.text('>')
+    end
+
+    def method_missing(name, *args, **kwargs, &block)
+      key = name.to_s
+
+      unless ::Fiber[BLOCK_KEY]
+        ::Kernel.raise ::NoMethodError.new(
+          "config.#{key} only works inside ThunderChunk::Configuration.new { ... }; use config['path'] instead", name
+        )
+      end
+
+      return _set(key.delete_suffix('='), args.first) if key.end_with?('=')
+      return _get(key) || _set(key, Configuration.new) if args.empty? && kwargs.empty? && !block
+
+      return ::Kernel.public_send(name, *args, **kwargs, &block) if ::Kernel.private_method_defined?(name)
+
+      ::Kernel.raise ::NoMethodError.new("undefined method '#{name}' for #{inspect}", name)
+    end
+  end
+end

data/lib/thunderchunk/database.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  # The chunk's database: ActiveRecord::Base, since a process runs one chunk.
+  class Database
+    REQUIRED_KEYS = %w[adapter].freeze
+
+    def initialize(chunk)
+      @chunk = chunk
+    end
+
+    def configuration
+      { database: "#{@chunk.chunk_name.underscore}_#{ENV.fetch('THUNDER_ENV', 'development')}" }
+        .merge(@chunk.config['database'] || {})
+    end
+
+    def connection_pool = ActiveRecord::Base.connection_pool
+
+    def connect
+      validate_configuration!
+      ActiveRecord::Base.establish_connection(configuration)
+    end
+
+    def connect!
+      connect
+      verify!
+    end
+
+    def verify!
+      connection_pool.with_connection(&:verify!)
+    end
+
+    def create!
+      validate_configuration!
+      ActiveRecord::Tasks::DatabaseTasks.create(configuration)
+      connect!
+    end
+
+    # The adapter's drop connects ActiveRecord::Base to the maintenance database; connect points it back.
+    def drop!
+      validate_configuration!
+      ActiveRecord::Base.connection_handler.clear_all_connections!
+      ActiveRecord::Tasks::DatabaseTasks.drop(configuration)
+      connect
+    end
+
+    def migrate!
+      validate_configuration!
+      ActiveRecord::MigrationContext.new(@chunk.root_path.join('database/migrate').to_s).migrate
+    end
+
+    private
+
+    def validate_configuration!
+      raise Error, 'Application not booted' unless @chunk.booted?
+
+      missing = REQUIRED_KEYS.reject { |key| @chunk.config["database.#{key}"] }
+      return if missing.empty?
+
+      file = @chunk.root_path.join(Chunk::CONFIGURATION_FILE)
+      raise Error, "#{file} does not configure #{missing.map { |key| "database.#{key}" }.join(' and ')}"
+    end
+  end
+end

data/lib/thunderchunk/default_configuration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# The framework's defaults, written like a chunk's config/chunk.rb. The chunk reads this file on boot and merges its
+# config/chunk.rb over it.
+ThunderChunk::Configuration.new do
+  boot.registries = [
+    ThunderChunk::Registries::Models,
+    ThunderChunk::Registries::Operations
+  ]
+
+  boot.exporters = []
+
+  boot.external_importers = [
+    ThunderChunk::ExternalImporters::Operations,
+    ThunderChunk::ExternalImporters::Events
+  ]
+
+  # WARN: AI MADE
+  # Payloads checked against `returns` in development and test only: a mistake in a declaration does not fail an
+  # operation in production. A chunk turns it on or off in its config/chunk.rb.
+  operations.validate_returns = %w[development test].include?(ENV.fetch('THUNDER_ENV', 'development'))
+
+  # WARN: AI MADE
+  # Time.zone of the process; Time.zone.now and the times read from the database use it.
+  time.zone = 'UTC'
+
+  messaging.broker.type = 'rabbitmq'
+  messaging.publisher = 'outbox'
+end

data/lib/thunderchunk/dependency.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class Dependency < Data.define(:kind, :path, :config, :options)
+  end
+end

data/lib/thunderchunk/dependency_injector.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class DependencyInjector
+    MODULE_NAME = :InjectedMethods
+
+    class InjectedMethods < Module; end
+
+    def initialize(chunk)
+      @chunk = chunk
+    end
+
+    def inject(target_klass, kind, path, config: {}, **options)
+      methods_module = methods_module_for(target_klass)
+
+      depended_class = @chunk.registry.get(kind, path) ||
+                       @chunk.external_importer.get(kind)&.get(path) ||
+                       raise(Error, "#{kind} #{path} is not registered")
+
+      name = options[:as]&.to_s
+
+      if name&.match?(/\A[[:lower:]_]/)
+        methods_module.define_method(name, -> { depended_class })
+      else
+        set_path_constant(methods_module, name || path, depended_class)
+      end
+
+      target_klass.extend(methods_module) if config[:on_instance] || config[:on_class].blank?
+      target_klass.include(methods_module) if config[:on_class] || config[:on_instance].blank?
+    end
+
+    def set_path_constant(methods_module, path, depended_class)
+      *namespaces, constant = path.split('.').map(&:camelize)
+
+      owner = namespaces.reduce(methods_module) do |mod, name|
+        mod.const_defined?(name, false) ? mod.const_get(name, false) : mod.const_set(name, Module.new)
+      end
+
+      owner.const_set(constant, depended_class)
+    end
+
+    def methods_module_for(owner)
+      return owner.const_get(MODULE_NAME, false) if owner.const_defined?(MODULE_NAME, false)
+
+      InjectedMethods.new.tap do |methods_module|
+        owner.const_set(MODULE_NAME, methods_module)
+        owner.include(methods_module)
+      end
+    end
+  end
+end

data/lib/thunderchunk/event.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  # The contract of an event: the fields of its payload, declared as the fields of a `Hash do ... end` param
+  # (`field`, `association`, nested `Hash`/`Array`). A payload is published only with exactly that shape.
+  class Event
+    class << self
+      # WARN: AI MADE
+      delegate :field, :association, to: :schema
+
+      def schema
+        @schema ||= ThunderOperation::Parameters::HashParameter.new
+      end
+    end
+
+    def initialize(chunk, key, publisher)
+      @chunk = chunk
+      @publisher = publisher
+      @key = key
+    end
+
+    def schema
+      self.class.schema
+    end
+
+    # WARN: AI MADE
+    # A payload with a key the event does not declare, a declared key left out or a value of another type raises
+    # Error, whatever operations.validate_returns says: the payload leaves for another chunk.
+    def publish(params)
+      Console.info(self, 'Event Published', key: @key, params:)
+      begin
+        schema.check!(params, path: @key)
+      rescue ThunderOperation::Exceptions::ParameterError => e
+        raise Error, "#{self.class.name}: #{e.message}"
+      end
+
+      @publisher.publish(@key, params)
+    end
+  end
+end

data/lib/thunderchunk/exporter.rb

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

data/lib/thunderchunk/exporters/base.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class Exporters
+    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)
+        return @path = value if value
+
+        @path || @kind.to_s.pluralize || raise(NotImplementedError, "#{name} must declare `kind` or `path`")
+      end
+
+      def initialize(chunk)
+        @chunk = chunk
+        @items = {}
+        @loader = Loader.new(@chunk.name, @chunk.root_path)
+      end
+
+      attr_reader :items
+
+      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 call(**)
+        raise NotImplementedError
+      end
+
+      def exports?(path)
+        @items.key?(path)
+      end
+
+      def get(path)
+        @items[path]
+      end
+
+      def get!(path)
+        get(path) || raise(Error, "#{self.class.kind} #{path} is not exported")
+      end
+
+      def add(path, object)
+        @items[path] = object
+      end
+
+      def clear
+        @items.clear
+      end
+
+      def load
+        @items = {}
+
+        @loader.load(["app/external/#{self.class.path}"])
+
+        @loader.each do |_parent, _name, constant|
+          add_constant(constant)
+        end
+
+        @loader.unload
+      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/exporters/events.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class Exporters
+    class Events < Base
+      kind :event
+      path 'messaging/subscribers'
+
+      def key_for(constant)
+        key_from_name(constant, 'External', 'Messaging', 'Subscribers')&.then do |key|
+          unless constant < ThunderChunk::Operations::Subscriber
+            raise RegistryRequirementError, "#{constant.name} must inherit from ThunderChunk::Operations::Subscriber"
+          end
+
+          key.sub('.', '/')
+        end
+      end
+
+      def call(key, params:)
+        get!(key).call(**params)
+      end
+    end
+  end
+end

data/lib/thunderchunk/exporters/operations.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ThunderChunk
+  class Exporters
+    class Operations < Base
+      kind :operation
+
+      def key_for(constant)
+        key_from_name(constant, 'External', 'Operations')&.tap do |key|
+          unless constant < ThunderChunk::Operations::External
+            raise RegistryRequirementError, "#{constant.name} must inherit from ThunderChunk::Operations::External"
+          end
+          # TODO: Here is the corerct location to this valiadtion?
+          # WARN: AI MADE
+          unless constant.returns_frame
+            raise RegistryRequirementError,
+                  "#{constant.name} must declare `returns Hash do ... end` (fields, or keys and values) or " \
+                  '`returns Array do items Hash do ... end end`'
+          end
+        end
+      end
+
+      def call(path, params:)
+        operation = get!(path)
+
+        operation.call(**params)
+      end
+    end
+  end
+end