asyncapi_cable 0.1.0

data/lib/asyncapi_cable/engine.rb

@@ -0,0 +1,18 @@
+# Required rather than assumed: a generation subprocess requires this gem
+# before the host boots Rails, and the host's routes reference
+# AsyncapiCable::Engine — so skipping the class definition when Rails happens
+# not to be loaded yet leaves it permanently undefined.
+require "rails"
+require "rails/engine"
+
+module AsyncapiCable
+  class Engine < ::Rails::Engine
+    isolate_namespace AsyncapiCable
+
+    config.after_initialize do
+      if defined?(ActionCable::Server::Broadcasting)
+        ActionCable::Server::Broadcasting.prepend(AsyncapiCable::Runtime::ChannelHook)
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/generator/asyncapi_writer.rb

@@ -0,0 +1,71 @@
+require "fileutils"
+
+module AsyncapiCable
+  module Generator
+    class AsyncapiWriter
+      class << self
+        def generate_all!(output_dir: nil, format: nil)
+          configuration = AsyncapiCable.configuration
+          output_dir ||= configuration.schema_output_dir
+          format ||= configuration.schema_output_format
+
+          raise Error, "AsyncapiCable.configuration.schemas is empty" if configuration.schemas.empty?
+
+          configuration.schemas.map do |schema_name, schema_config|
+            document = build_document(schema_name, schema_config)
+            path = write(document, schema_name, output_dir: output_dir, format: format)
+            [schema_name, path]
+          end.to_h
+        end
+
+        def build_document(schema_name, schema_config)
+          scope = (schema_config[:component_scope] || schema_config["component_scope"] || :cable).to_sym
+          components = load_cable_components(scope)
+
+          document = Core::Document.new(
+            info: schema_config[:info] || schema_config["info"] || {},
+            servers: schema_config[:servers] || schema_config["servers"] || {},
+            cable_components: components
+          )
+
+          Dsl::MetadataStore.contexts_for(schema_name).each do |context|
+            document.add_channel(context)
+          end
+
+          document
+        end
+
+        # Bypass OpenapiRuby::Components::Loader#to_openapi_hash and read raw
+        # schema definitions directly. The host's openapi-ruby is configured
+        # with `camelize_keys = true` which is correct for REST API docs but
+        # wrong for cable AsyncAPI docs whose payloads are the snake_case
+        # wire format `BroadcastingConcern` actually emits. The runtime
+        # PayloadValidator already does the same bypass for the same reason.
+        #
+        # We still need the Loader's eager-load side effect though: component
+        # classes reachable only via `$ref` strings (e.g. an enum a message
+        # schema refs) aren't autoloaded by Ruby, so a raw registry scan
+        # would miss them. `Loader#load!` is idempotent.
+        def load_cable_components(scope)
+          OpenapiRuby::Components::Loader.new.load!
+
+          schemas = OpenapiRuby::Components::Registry.instance.all_registered_classes.select do |klass|
+            klass._component_scopes.include?(scope)
+          end.each_with_object({}) do |klass, acc|
+            acc[klass.component_name] = klass._schema_definition
+          end
+          {"schemas" => schemas}
+        end
+
+        def write(document, schema_name, output_dir:, format:)
+          ext = (format.to_sym == :json) ? "json" : "yaml"
+          path = File.join(output_dir, "#{schema_name}.#{ext}")
+          FileUtils.mkdir_p(File.dirname(path))
+          contents = (ext == "json") ? document.to_json : document.to_yaml
+          File.write(path, contents)
+          path
+        end
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/generator/declaration_loader.rb

@@ -0,0 +1,97 @@
+require "asyncapi_cable"
+require "openapi_ruby/generator/autorun_suppressor"
+require "openapi_ruby/generator/test_schema_suppressor"
+
+module AsyncapiCable
+  module Generator
+    # Loads the spec/test files that carry `channel` declarations so the
+    # MetadataStore holds them. Both the generator and the channel-coverage
+    # gate need exactly that, in whichever framework the host writes its
+    # declarations.
+    #
+    # Loading must not *run* the files. Both suppressors come from
+    # openapi-ruby rather than being reimplemented here: they work around
+    # another library's `at_exit` and schema-check behaviour, and two copies
+    # of that would drift.
+    module DeclarationLoader
+      FRAMEWORKS = %w[rspec minitest hybrid].freeze
+
+      module_function
+
+      # The adapter has to be live before a declaration file loads — its class
+      # body is what calls the DSL.
+      def install_adapters!(framework)
+        validate_framework!(framework)
+
+        if framework != "minitest"
+          require "rspec/core"
+          require "asyncapi_cable/rspec"
+        end
+
+        require "asyncapi_cable/minitest" if framework != "rspec"
+      end
+
+      def suppress_side_effects!
+        OpenapiRuby::Generator::AutorunSuppressor.install!
+        OpenapiRuby::Generator::TestSchemaSuppressor.install!
+      end
+
+      # Announced through the environment so a host test helper guarding on
+      # either flag skips its test-time setup. In-process callers (the
+      # channel-coverage gate) need this as much as the generation subprocess,
+      # and it is not restored afterwards: the files loaded under the guard
+      # stay loaded, so pretending the run is over would be a lie.
+      def announce_declaration_run!
+        ENV["ASYNCAPI_CABLE_GENERATING"] ||= "true"
+        ENV["OPENAPI_RUBY_GENERATING"] ||= "true"
+      end
+
+      # Returns the files that were loaded, in load order.
+      def load!(framework:, pattern:)
+        install_adapters!(framework)
+        announce_declaration_run!
+        suppress_side_effects!
+
+        globs_for(pattern).flat_map { |dir, glob| load_glob(dir, glob) }
+      end
+
+      # Each glob is loaded with its own framework directory at the head of
+      # `$LOAD_PATH`, so the `require "rails_helper"` / `require "test_helper"`
+      # at the top of a declaration file resolves to the right helper. Spec
+      # globs load before test globs, matching openapi-ruby's hybrid script.
+      def globs_for(pattern)
+        globs = pattern.to_s.split(",").map(&:strip).reject(&:empty?)
+        spec_globs = globs.grep(%r{\bspec/})
+        test_globs = globs.grep(%r{\btest/})
+
+        spec_globs.map { |glob| ["spec", glob] } +
+          test_globs.map { |glob| ["test", glob] } +
+          (globs - spec_globs - test_globs).map { |glob| [nil, glob] }
+      end
+
+      def load_glob(dir, glob)
+        # A glob can legitimately resolve directories (`test/asyncapi/**`);
+        # `require` on one raises LoadError.
+        files = Dir.glob(glob).select { |file| File.file?(file) }.sort
+        return [] if files.empty?
+        return files.each { |file| require File.expand_path(file) } if dir.nil?
+
+        path = File.expand_path(dir)
+        added = !$LOAD_PATH.include?(path)
+        $LOAD_PATH.unshift(path) if added
+        begin
+          files.each { |file| require File.expand_path(file) }
+        ensure
+          $LOAD_PATH.delete(path) if added
+        end
+      end
+
+      def validate_framework!(framework)
+        return if FRAMEWORKS.include?(framework)
+
+        raise ArgumentError,
+          "Unknown test framework #{framework.inspect}. Expected one of #{FRAMEWORKS.join(", ")}."
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/generator/rake_task_support.rb

@@ -0,0 +1,52 @@
+require "openapi_ruby"
+require "openapi_ruby/generator/rake_task_support"
+require "asyncapi_cable/generator/declaration_loader"
+
+module AsyncapiCable
+  module Generator
+    # Helpers backing the `asyncapi_cable:generate` rake task. Framework
+    # detection and the subprocess environment are openapi-ruby's: the two
+    # generators run against the same host, and a second copy of that logic
+    # would drift from the one the OpenAPI schema is generated with.
+    module RakeTaskSupport
+      module_function
+
+      def detect_test_framework
+        OpenapiRuby::Generator::RakeTaskSupport.detect_test_framework
+      end
+
+      def default_pattern_for(framework)
+        DeclarationLoader.validate_framework!(framework)
+
+        case framework
+        when "rspec" then "spec/**/*_spec.rb"
+        when "minitest" then "test/**/*_test.rb"
+        when "hybrid" then "spec/**/*_spec.rb,test/**/*_test.rb"
+        end
+      end
+
+      # `OPENAPI_RUBY_GENERATING` comes along on purpose: host test helpers
+      # guard their test-framework requires with
+      # `unless OpenapiRuby.schema_generating?`, and a cable generation run is
+      # the same kind of run — files are loaded for their declarations, never
+      # executed — so that guard has to fire here too.
+      def subprocess_env
+        OpenapiRuby::Generator::RakeTaskSupport
+          .subprocess_env
+          .merge("ASYNCAPI_CABLE_GENERATING" => "true")
+      end
+
+      def generate_script(framework, pattern)
+        DeclarationLoader.validate_framework!(framework)
+
+        <<~RUBY
+          require "asyncapi_cable/generator/runner"
+          AsyncapiCable::Generator::Runner.call(
+            framework: #{framework.inspect},
+            pattern: #{pattern.inspect}
+          )
+        RUBY
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/generator/runner.rb

@@ -0,0 +1,27 @@
+require "asyncapi_cable"
+require "asyncapi_cable/generator/declaration_loader"
+
+module AsyncapiCable
+  module Generator
+    # The body of the generation subprocess: load the declarations, then write
+    # every configured document.
+    module Runner
+      module_function
+
+      def call(framework:, pattern:, io: $stdout)
+        loaded = DeclarationLoader.load!(framework: framework, pattern: pattern)
+
+        if loaded.empty?
+          # Writing now would replace the committed documents with channel-less
+          # ones, and a `git diff` gate over the output would still be clean if
+          # the host has no committed documents yet.
+          raise Error, "no declaration files matched PATTERN=#{pattern.inspect} (framework: #{framework})"
+        end
+
+        AsyncapiWriter.generate_all!.each do |name, path|
+          io.puts "Wrote AsyncAPI document #{name} → #{path}"
+        end
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/minitest.rb

@@ -0,0 +1,4 @@
+require "asyncapi_cable"
+require_relative "adapters/minitest"
+
+AsyncapiCable::Adapters::Minitest.install!

data/lib/asyncapi_cable/rake_tasks.rb

@@ -0,0 +1,39 @@
+require "rake"
+require "shellwords"
+require "asyncapi_cable/generator/rake_task_support"
+
+module AsyncapiCable
+  # The Rails engine picks up lib/tasks/*.rake on its own; other hosts add
+  #
+  #   require "asyncapi_cable/rake_tasks"
+  #
+  # to their Rakefile. Both routes end up here, so the task is defined once.
+  module RakeTasks
+    extend Rake::DSL
+
+    def self.install!
+      return if Rake::Task.task_defined?("asyncapi_cable:generate")
+
+      namespace :asyncapi_cable do
+        desc "Generate AsyncAPI 3 documents for ActionCable channels. " \
+             "FRAMEWORK=rspec|minitest|hybrid, PATTERN= comma-separated globs of declaration files."
+        task :generate do
+          support = AsyncapiCable::Generator::RakeTaskSupport
+          framework = ENV.fetch("FRAMEWORK") { support.detect_test_framework }.to_s
+          pattern = ENV.fetch("PATTERN") { support.default_pattern_for(framework) }
+
+          # A subprocess so the host boots in its own test environment and the
+          # suppressors are installed before anything else is required — same
+          # arrangement as `openapi_ruby:generate`.
+          script = support.generate_script(framework, pattern)
+          command = "bundle exec ruby -e #{Shellwords.escape(script)}"
+
+          puts "Generating AsyncAPI documents (#{framework})..."
+          system(support.subprocess_env, command) || abort("AsyncAPI generation failed")
+        end
+      end
+    end
+  end
+end
+
+AsyncapiCable::RakeTasks.install!

data/lib/asyncapi_cable/rspec.rb

@@ -0,0 +1,4 @@
+require "asyncapi_cable"
+require_relative "adapters/rspec"
+
+AsyncapiCable::Adapters::RSpec.install!

data/lib/asyncapi_cable/runtime/channel_hook.rb

@@ -0,0 +1,61 @@
+module AsyncapiCable
+  module Runtime
+    module ChannelHook
+      def broadcast(stream, payload, *args, **kwargs)
+        Runtime.validate_broadcast!(stream, payload)
+        super
+      end
+    end
+
+    def self.validate_broadcast!(stream, payload)
+      mode = AsyncapiCable.configuration.validation_mode
+      return if mode == :disabled
+
+      matches = ContractRegistry.broadcast_schemas_for(stream)
+      return if matches.empty?
+
+      errors = collect_errors(matches, payload)
+      return if errors.empty?
+
+      report(mode, stream, errors)
+    end
+
+    # AsyncAPI 3 treats a channel's messages as alternatives: a payload
+    # matching ANY declared message satisfies the channel. We validate
+    # against every candidate schema across all matching channels, pass if
+    # any validates clean, and otherwise surface the closest match's errors
+    # (fewest failures).
+    def self.collect_errors(matches, payload)
+      results = matches.flat_map do |match|
+        match.schema_names.map do |schema_name|
+          PayloadValidator.instance.validate(payload, schema_name, match.components)
+        end
+      end
+
+      return [] if results.empty?
+      return [] if results.any?(&:empty?)
+
+      results.min_by(&:size)
+    end
+
+    def self.report(mode, stream, errors)
+      summary = errors.map { |e| e["error"] }.compact.uniq.join("; ")
+      message = "AsyncAPI broadcast validation failed for stream #{stream.inspect}: #{summary}"
+
+      case mode
+      when :warn_only
+        logger.warn(message)
+      when :enabled
+        raise Error, message
+      end
+    end
+
+    def self.logger
+      if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+        ::Rails.logger
+      else
+        @fallback_logger ||= Logger.new($stdout)
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/runtime/contract_registry.rb

@@ -0,0 +1,129 @@
+require "yaml"
+require "pathname"
+
+module AsyncapiCable
+  module Runtime
+    # Runtime source of truth for broadcast validation: the committed
+    # `asyncapi/<schema>.yaml` artifacts, parsed and memoized. This is the
+    # read side of the contract; the write side (RSpec specs ->
+    # MetadataStore -> AsyncapiWriter) is untouched and remains the
+    # authoring path. See docs/exec-plans/asyncapi-cable-runtime-validation.md (D1).
+    class ContractRegistry
+      Match = Struct.new(:matcher, :schema_names, :components)
+
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        def reset!
+          @instance = nil
+        end
+
+        def broadcast_schemas_for(stream) = instance.broadcast_schemas_for(stream)
+      end
+
+      def broadcast_schemas_for(stream)
+        channels.select { |match| match.matcher.match?(stream) }
+      end
+
+      def channels
+        @channels ||= load_channels
+      end
+
+      private
+
+      def load_channels
+        result = AsyncapiCable.configuration.schemas.keys.flat_map do |schema_name|
+          doc = load_document(schema_name)
+          doc ? channels_from(doc) : []
+        end
+        log_load(result.size)
+        result
+      end
+
+      def channels_from(doc)
+        operations = doc["operations"] || {}
+        components = doc["components"] || {}
+
+        operations.filter_map do |_op_id, op|
+          next unless op["action"] == "receive"
+
+          channel = resolve(doc, op.dig("channel", "$ref"))
+          address = channel && channel["address"]
+          next unless address
+
+          schema_names = Array(op["messages"]).filter_map do |msg_ref|
+            schema_name_for(doc, msg_ref["$ref"])
+          end.uniq
+
+          Match.new(
+            matcher: StreamMatcher.new(address),
+            schema_names: schema_names,
+            components: components
+          )
+        end
+      end
+
+      # Walks #/channels/<Ch>/messages/<Key> -> #/components/messages/<M>
+      # -> payload.$ref -> #/components/schemas/<Schema>, returning <Schema>.
+      def schema_name_for(doc, channel_message_ref)
+        channel_message = resolve(doc, channel_message_ref)
+        message = channel_message && resolve(doc, channel_message["$ref"])
+        payload_ref = message&.dig("payload", "$ref")
+        payload_ref&.split("/")&.last
+      end
+
+      def resolve(doc, ref)
+        return nil unless ref.is_a?(String) && ref.start_with?("#/")
+        doc.dig(*ref.delete_prefix("#/").split("/"))
+      end
+
+      def load_document(schema_name)
+        path = schema_path(schema_name)
+        return nil unless path.exist?
+
+        contents = path.read
+        return nil if contents.strip.empty?
+
+        YAML.safe_load(contents)
+      rescue => e
+        logger.warn("[AsyncapiCable] failed to load contract #{path}: #{e.message}")
+        nil
+      end
+
+      def schema_path(schema_name)
+        ext = (AsyncapiCable.configuration.schema_output_format.to_sym == :json) ? "json" : "yaml"
+        schema_dir.join("#{schema_name}.#{ext}")
+      end
+
+      def schema_dir
+        dir = AsyncapiCable.configuration.schema_output_dir.to_s
+        pathname = Pathname.new(dir)
+        return pathname if pathname.absolute?
+
+        if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+          ::Rails.root.join(dir)
+        else
+          pathname
+        end
+      end
+
+      def log_load(count)
+        if count.zero?
+          logger.warn(
+            "[AsyncapiCable] contract registry loaded 0 channels; runtime broadcast " \
+            "validation is a no-op — check schema_output_dir (#{schema_dir}) and that the " \
+            "asyncapi contract files exist"
+          )
+        else
+          logger.info("[AsyncapiCable] contract registry loaded #{count} channel(s)")
+        end
+      end
+
+      def logger
+        AsyncapiCable::Runtime.logger
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/runtime/payload_validator.rb

@@ -0,0 +1,48 @@
+require "json_schemer"
+
+module AsyncapiCable
+  module Runtime
+    class PayloadValidator
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        def reset!
+          @instance = nil
+        end
+      end
+
+      # Validates `payload` against `#/components/schemas/<schema_name>` of
+      # the passed-in `components` hash (sourced from the committed YAML, not
+      # the live component registry — see exec-plan D4). The JSONSchemer
+      # document is memoized per `components` object so repeated broadcasts on
+      # the same contract reuse one compiled schema.
+      def validate(payload, schema_name, components)
+        normalized = stringify_keys(payload)
+        ref = "#/components/schemas/#{schema_name}"
+        schemer_for(components).ref(ref).validate(normalized).to_a
+      end
+
+      private
+
+      def schemer_for(components)
+        @schemers ||= {}
+        @schemers[components.object_id] ||= JSONSchemer.schema(
+          {"components" => {"schemas" => components["schemas"] || {}}}
+        )
+      end
+
+      def stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify_keys(v) }
+        when Array
+          value.map { |v| stringify_keys(v) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/runtime/stream_matcher.rb

@@ -0,0 +1,24 @@
+module AsyncapiCable
+  module Runtime
+    class StreamMatcher
+      def initialize(template)
+        @template = template.to_s
+        @regex = build_regex(@template)
+      end
+
+      def match?(stream)
+        return false if @regex.nil?
+        !@regex.match(stream.to_s).nil?
+      end
+
+      private
+
+      def build_regex(template)
+        return nil if template.empty?
+
+        escaped = Regexp.escape(template).gsub(/\\\{(\w+)\\\}/) { "(?<#{$1}>[^/]+?)" }
+        Regexp.new("\\A#{escaped}\\z")
+      end
+    end
+  end
+end