asyncapi_cable 0.1.0

data/lib/asyncapi_cable/testing/assert_helpers.rb

@@ -0,0 +1,137 @@
+require "json"
+
+module AsyncapiCable
+  module Testing
+    # Shared core of assert_asyncapi_broadcast. Adapters mix this in and
+    # supply two hooks: #asyncapi_declared_contexts (the channel contexts
+    # declared on the test class / example group) and #asyncapi_flunk
+    # (framework-native test failure).
+    #
+    # Usage errors (undeclared broadcast operation, unresolved template
+    # params, non-test cable adapter) raise AsyncapiCable::Error; only
+    # genuine test failures go through asyncapi_flunk.
+    module AssertHelpers
+      def assert_asyncapi_broadcast(params: {}, &trigger)
+        raise Error, "assert_asyncapi_broadcast requires a block that triggers the broadcast" unless trigger
+
+        context = asyncapi_find_broadcast_context!(asyncapi_declared_contexts, params)
+        stream = asyncapi_expand_stream!(context.stream_template, params)
+        payloads = asyncapi_capture_broadcasts(stream, &trigger)
+
+        if payloads.empty?
+          asyncapi_flunk("Expected at least one broadcast on #{stream.inspect}, but none was captured")
+        end
+
+        payloads.each do |payload|
+          errors = asyncapi_broadcast_errors(context, payload)
+          next if errors.empty?
+
+          asyncapi_flunk(
+            "AsyncAPI broadcast validation failed for #{stream.inspect}:\n  #{asyncapi_error_summary(errors)}"
+          )
+        end
+
+        payloads
+      end
+
+      # Declared message schemas may `$ref` sibling components (enums etc.),
+      # so the validation document carries every registry class sharing the
+      # messages' scopes — the same set AsyncapiWriter publishes for those
+      # scopes. Loader#load! eager-loads classes reachable only via `$ref`
+      # strings and is idempotent. Memoized per scope set: PayloadValidator
+      # caches one compiled schema per components object.
+      def self.components_for(message_classes)
+        scopes = message_classes.flat_map(&:_component_scopes).uniq.sort
+        @components ||= {}
+        @components[scopes] ||= begin
+          OpenapiRuby::Components::Loader.new.load!
+          schemas = OpenapiRuby::Components::Registry.instance.all_registered_classes.select { |klass|
+            (klass._component_scopes & scopes).any?
+          }.to_h { |klass| [klass.component_name, klass._schema_definition] }
+          {"schemas" => schemas}
+        end
+      end
+
+      private
+
+      def asyncapi_find_broadcast_context!(contexts, params)
+        candidates = contexts.select { |ctx| ctx.operations.any? { |op| op.kind == :broadcast } }
+
+        if candidates.empty?
+          raise Error, "No channel with a broadcast operation is declared in this test class"
+        end
+        return candidates.first if candidates.size == 1
+
+        keys = params.keys.map(&:to_s).sort
+        scoped = candidates.select { |ctx| asyncapi_template_params(ctx.stream_template).sort == keys }
+        return scoped.first if scoped.size == 1
+
+        raise Error, "Ambiguous channel for params #{params.keys.inspect}: " \
+          "#{candidates.size} declared channels have broadcast operations " \
+          "(#{candidates.map { |c| c.stream_template.inspect }.join(", ")})"
+      end
+
+      def asyncapi_expand_stream!(template, params)
+        missing = []
+        stream = template.gsub(/\{(\w+)\}/) do
+          name = ::Regexp.last_match(1)
+          value = params[name.to_sym] || params[name]
+          missing << name if value.nil?
+          value.to_s
+        end
+
+        unless missing.empty?
+          raise Error, "Missing params #{missing.inspect} to expand stream template #{template.inspect}"
+        end
+
+        stream
+      end
+
+      def asyncapi_capture_broadcasts(stream)
+        pubsub = ::ActionCable.server.pubsub
+        unless pubsub.respond_to?(:broadcasts)
+          raise Error, "assert_asyncapi_broadcast requires the ActionCable test adapter " \
+            "(set `adapter: test` for the test environment in config/cable.yml)"
+        end
+
+        seen = pubsub.broadcasts(stream).size
+        yield
+        pubsub.broadcasts(stream).drop(seen).map { |message| asyncapi_decode(message) }
+      end
+
+      # Validates against the *declared* message classes (the authoring
+      # side), not the committed YAML the runtime ContractRegistry reads —
+      # when a spec documents a new channel, the YAML doesn't exist yet.
+      # Messages are alternatives per AsyncAPI 3: pass if any validates
+      # clean, otherwise surface the closest match's errors.
+      def asyncapi_broadcast_errors(context, payload)
+        message_classes = context.operations
+          .select { |op| op.kind == :broadcast }
+          .flat_map(&:messages)
+        return [] if message_classes.empty?
+
+        components = AssertHelpers.components_for(message_classes)
+        results = message_classes.map do |klass|
+          Runtime::PayloadValidator.instance.validate(payload, klass.component_name, components)
+        end
+        return [] if results.any?(&:empty?)
+
+        results.min_by(&:size) || []
+      end
+
+      def asyncapi_error_summary(errors)
+        errors.map { |e| e["error"] }.compact.uniq.join("\n  ")
+      end
+
+      def asyncapi_template_params(template)
+        template.scan(/\{(\w+)\}/).flatten
+      end
+
+      def asyncapi_decode(message)
+        message.is_a?(String) ? JSON.parse(message) : message
+      rescue JSON::ParserError
+        message
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/version.rb

@@ -0,0 +1,3 @@
+module AsyncapiCable
+  VERSION = "0.1.0"
+end

data/lib/asyncapi_cable.rb

@@ -0,0 +1,47 @@
+require "asyncapi_cable/version"
+require "asyncapi_cable/configuration"
+require "asyncapi_cable/dsl/metadata_store"
+require "asyncapi_cable/dsl/operation_context"
+require "asyncapi_cable/dsl/channel_context"
+require "asyncapi_cable/core/document"
+require "asyncapi_cable/generator/asyncapi_writer"
+require "asyncapi_cable/runtime/stream_matcher"
+require "asyncapi_cable/runtime/payload_validator"
+require "asyncapi_cable/runtime/contract_registry"
+require "asyncapi_cable/runtime/channel_hook"
+require "asyncapi_cable/engine"
+
+module AsyncapiCable
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # True when the current process was started by `asyncapi_cable:generate`
+    # (the rake task sets ASYNCAPI_CABLE_GENERATING=true in the subprocess).
+    #
+    # Such a run loads declaration files for their `channel` blocks and never
+    # executes them, so a host test helper can skip its test-time setup:
+    #
+    #   unless AsyncapiCable.schema_generating?
+    #     require "rails/test_help"
+    #   end
+    #
+    # Cable generation also sets openapi-ruby's OPENAPI_RUBY_GENERATING, so a
+    # helper already guarding on `OpenapiRuby.schema_generating?` needs no
+    # second guard.
+    def schema_generating?
+      ENV["ASYNCAPI_CABLE_GENERATING"] == "true"
+    end
+  end
+end

data/lib/tasks/asyncapi_cable_tasks.rake

@@ -0,0 +1 @@
+require "asyncapi_cable/rake_tasks"

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: asyncapi_cable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Fobizz
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actioncable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: openapi-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.3
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: |
+  AsyncAPI Cable adds an AsyncAPI 3 DSL on top of Rails ActionCable.
+  It generates an AsyncAPI document for your channels, sharing JSON
+  Schema components with OpenAPI tooling, and validates broadcast and
+  transmit payloads against declared message schemas at runtime.
+email:
+- dev@fobizz.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/asyncapi_cable/schemas_controller.rb
+- config/routes.rb
+- lib/asyncapi_cable.rb
+- lib/asyncapi_cable/adapters/minitest.rb
+- lib/asyncapi_cable/adapters/rspec.rb
+- lib/asyncapi_cable/configuration.rb
+- lib/asyncapi_cable/core/document.rb
+- lib/asyncapi_cable/dsl/channel_context.rb
+- lib/asyncapi_cable/dsl/metadata_store.rb
+- lib/asyncapi_cable/dsl/operation_context.rb
+- lib/asyncapi_cable/engine.rb
+- lib/asyncapi_cable/generator/asyncapi_writer.rb
+- lib/asyncapi_cable/generator/declaration_loader.rb
+- lib/asyncapi_cable/generator/rake_task_support.rb
+- lib/asyncapi_cable/generator/runner.rb
+- lib/asyncapi_cable/minitest.rb
+- lib/asyncapi_cable/rake_tasks.rb
+- lib/asyncapi_cable/rspec.rb
+- lib/asyncapi_cable/runtime/channel_hook.rb
+- lib/asyncapi_cable/runtime/contract_registry.rb
+- lib/asyncapi_cable/runtime/payload_validator.rb
+- lib/asyncapi_cable/runtime/stream_matcher.rb
+- lib/asyncapi_cable/testing/assert_helpers.rb
+- lib/asyncapi_cable/version.rb
+- lib/tasks/asyncapi_cable_tasks.rake
+homepage: https://github.com/openapi-ruby/asyncapi-cable
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/openapi-ruby/asyncapi-cable
+  source_code_uri: https://github.com/openapi-ruby/asyncapi-cable/tree/main/ruby
+  changelog_uri: https://github.com/openapi-ruby/asyncapi-cable/blob/main/ruby/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: AsyncAPI 3 documentation and runtime validation for Rails ActionCable channels.
+test_files: []