asyncapi_cable 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cb81ac1d3e0dbf6aec713ae2d67c5132bc969460c1f33ed112139d19282dbda
-  data.tar.gz: 8718125ac36f7bffbef7e053c9e5e8285e791efc23867618161bcf0ebd2878d2
+  metadata.gz: 368fd67f79835ca09ab0f0317cf6b36691ee6f291b86c3cf96c74fc711ad26ef
+  data.tar.gz: d29525107905822ec4472586e8ca1d78109692901b8f0349ad73a3b58f949e56
 SHA512:
-  metadata.gz: b9a5dc6091faa5faacb0dbbf9485453e3e0feb2131f33a71ca71810e8610e2119125bb2ba85552bfc1cb09eb91dd422904c4e4d0f09391d0b3241d1e7de27fd9
-  data.tar.gz: 496a763988124507c0c75d49d3f30b884a31a84c18b4c0344ac0525d8e34e8a30c3aa18c17113e915a21d170d822eb83fa63e1e63b95b893d3c4b6b4e213d45a
+  metadata.gz: 0573f54362c01f9f880d501aab32101225c586a547d4e443a319b6bd6b078adb6a45f367d03e67a59cb2c2ba6ab9ca8392f2a0555cbd0bbd4aa5f8b0fb03a01c
+  data.tar.gz: '08731a2683b02e3831d14149681b732d47ae38d78b8dc4ada624bb565f1cf428a379407e7d171a0575a65ba049073b207cf2729540c25982f2bb9d0eba6c6d24'

data/README.md

@@ -176,6 +176,107 @@ An operation's `messages` are treated as alternatives per AsyncAPI 3 — a paylo
 
 `assert_asyncapi_broadcast` (see Quick start) validates against the *declared* message classes instead — the write side — so a spec documenting a brand-new channel can prove its payloads before the YAML artifact exists.
 
+## Broadcast objects, not serialized strings
+
+`ActionCable.server.broadcast` encodes what you hand it. Hand it a String that
+is already JSON and the wire carries a JSON string *literal* — the client parses
+twice, `contentSchema` becomes the only honest way to describe the shape, and
+validation can say no more than "it is a string".
+
+The pattern is easy to arrive at without choosing it, because the usual way to
+render a payload returns a String:
+
+```ruby
+# Encodes twice: `to_json` renders, ActionCable escapes the result
+WidgetChannel.broadcast_to(user, widget.to_json)
+```
+
+Two costs worth knowing. Escaping every `"` as `\"` inflated a 1.2 KB payload by
+**12.4%**, paid on every message — worst on the high-frequency channels. And the
+double encoding is what makes `assert_asyncapi_broadcast` report `value at root
+is not an object`, which reads like a schema problem and is not one; both that
+failure and the `:warn_only` log now name the cause.
+
+If a renderer only returns Strings, parse once on the way out — a jbuilder host
+might pair `to_jbuilder_json` with:
+
+```ruby
+def to_jbuilder_hash(*_args)
+  JSON.parse(to_jbuilder_json)
+end
+```
+
+That parse is cheap next to the render it follows (0.3% of it, measured on the
+same payload), and it buys a message schema that describes the object itself:
+`message ::V1::Schemas::Widgets::Widget` rather than a string wrapping one.
+
+A String payload is still the right answer when the transport genuinely carries
+an opaque representation — one rendered elsewhere, cached as text, or signed.
+That is what `contentMediaType` and `contentSchema` are for, and such a message
+validates without complaint.
+
+## Which components land in a document
+
+A document's **entry points** are what `component_scope` selects *plus every
+message a channel declares*, and each entry point brings the transitive closure
+of everything it `$ref`s. Scope is not a fence around the document.
+
+The declared messages matter on their own: the most natural way to describe a
+channel that broadcasts a rendered REST resource is to point straight at the
+component that already describes it, and that component carries no cable scope.
+
+```ruby
+channel "widgets:{user_gid}", channel_class: WidgetChannel do
+  broadcast "A widget the user owns changed" do
+    message ::V1::Schemas::Widgets::Widget   # scope :v1
+  end
+end
+```
+
+That matters as soon as a message describes an embedded payload by pointing at
+an existing component — say a presence broadcast whose `payload` string carries
+a rendered REST representation:
+
+```ruby
+payload: {
+  type: :string,
+  contentMediaType: "application/json",
+  contentSchema: {"$ref": "#/components/schemas/WordCloud"}
+}
+```
+
+`WordCloud` is a REST component and carries no cable scope. Including the
+message without it would write a pointer that resolves to nothing, and
+`@asyncapi/parser` rejects the whole document (`'#/components/schemas/X' does
+not exist`). So the writer follows the reference and brings it along, together
+with anything it references in turn. A name that matches no registered
+component is left as written — the document then fails to parse, which is the
+right outcome for a typo.
+
+Runtime validation resolves components the same way, so a payload that passes
+`assert_asyncapi_broadcast` passes against the committed document too.
+
+### Shadowed component names
+
+A `component_name` is only unique within a scope. openapi-ruby hosts routinely
+document a richer admin variant of a public resource under the same name, and
+`to_openapi_hash` never meets the collision because it filters by scope before
+indexing by name. A closure walk has no such filter, so it has to say which
+variant a pointer meant — picking by registration order would write a document
+that parses cleanly and describes the wrong contract.
+
+A `$ref` means what it means in the referring component's own document, so the
+candidate sharing a scope with the referrer wins. Failing that the document's
+own scope decides, then openapi-ruby's specificity rule (a scope-specific
+component beats a multi-scope one). A name still undecided after all three is a
+real ambiguity and raises, naming the candidates:
+
+```
+Ambiguous $ref #/components/schemas/Widget from Cable::V1::Schemas::WidgetMessage:
+V1::Schemas::Widgets::Widget [:v1], Admin::V1::Schemas::Widgets::Widget [:admin].
+Give the intended component a scope the referrer shares, or name the variants distinctly.
+```
+
 ## Snake_case wire format
 
 The AsyncAPI doc is written from the raw schema definitions, not the camelized `OpenapiRuby::Components::Loader` projection. This is deliberate: ActionCable broadcasts are snake_case in the wild, so the cable document describes the actual wire shape rather than the REST-style camelCase view of the same component. Both the writer and the runtime validator follow the same convention.

data/lib/asyncapi_cable/components/reference_closure.rb

@@ -0,0 +1,123 @@
+require "openapi_ruby"
+
+module AsyncapiCable
+  module Components
+    # Expands a set of component classes to everything they `$ref`.
+    #
+    # Scope alone is not a sufficient filter for a document. A cable message
+    # can legitimately reference a component that is not cable-scoped — the
+    # presence channels embed a rendered REST representation, so the honest
+    # contract says "this is an Item" and points at the REST component. Include
+    # the referrer without the referee and the document carries a pointer that
+    # resolves to nothing: `@asyncapi/parser` rejects the whole document with
+    # `'#/components/schemas/X' does not exist`.
+    #
+    # So a document includes what its own scope selects, plus the transitive
+    # closure of what those components reference. Scope stays the *entry point*
+    # into the graph rather than a fence around it.
+    module ReferenceClosure
+      SCHEMA_REF = %r{\A#/components/schemas/(?<name>\w+)\z}
+
+      module_function
+
+      # `scope` is the document's own scope (a symbol, or several in priority
+      # order), consulted when the referring component cannot settle a name on
+      # its own. The entry points' own scopes follow it: a document assembled
+      # from `:v1` components resolves its pointers the way the `:v1` document
+      # would, which is what makes the walk order-independent.
+      def expand(classes, scope: nil, registry: OpenapiRuby::Components::Registry.instance.all_registered_classes)
+        entry_points = classes.to_a
+        candidates = registry.group_by(&:component_name)
+        preferred = (Array(scope) + entry_points.flat_map(&:_component_scopes)).compact.uniq
+        included = {}
+        queue = entry_points.dup
+
+        until queue.empty?
+          klass = queue.shift
+          name = klass.component_name
+          next if included.key?(name)
+
+          included[name] = klass
+          referenced_names(klass._schema_definition).each do |referenced|
+            next if included.key?(referenced)
+
+            referee = resolve(referenced, candidates, referrer: klass, prefer: preferred)
+            queue << referee if referee
+          end
+        end
+
+        included.values
+      end
+
+      # A component_name is only unique within a scope: openapi-ruby documents
+      # routinely carry a richer admin variant of a public resource under the
+      # same name, and its own `to_openapi_hash` never meets the collision
+      # because it filters by scope before indexing by name. A closure walk has
+      # no such filter, so it has to say which variant a pointer meant.
+      #
+      # A `$ref` means what it means in the referring component's own document,
+      # so a candidate sharing a scope with the referrer wins. A shared
+      # component settles nothing on its own though — one carrying
+      # `[:v1, :admin]` shares a scope with both variants of the name it
+      # references — so the document's scopes are applied next, in priority
+      # order, then openapi-ruby's specificity rule (scope-specific beats
+      # multi-scope). Anything still undecided is a real ambiguity and says so
+      # rather than picking by registration order.
+      def resolve(name, candidates, referrer:, prefer: [])
+        found = candidates[name]
+        return nil if found.nil? || found.empty?
+        return found.first if found.size == 1
+
+        narrowed = narrow(found, referrer._component_scopes)
+        prefer.each do |scope|
+          break if narrowed.size == 1
+
+          narrowed = narrow(narrowed, [scope])
+        end
+        narrowed = least_scoped(narrowed) if narrowed.size > 1
+        return narrowed.first if narrowed.size == 1
+
+        raise Error, ambiguity_message(name, referrer, narrowed)
+      end
+
+      def referenced_names(node, found = [])
+        case node
+        when Hash
+          node.each do |key, value|
+            match = (key.to_s == "$ref") && value.is_a?(String) && SCHEMA_REF.match(value)
+            if match
+              found << match[:name]
+            else
+              referenced_names(value, found)
+            end
+          end
+        when Array
+          node.each { |element| referenced_names(element, found) }
+        end
+
+        found.uniq
+      end
+
+      # Narrowing never empties the set: a scope no candidate carries tells us
+      # nothing, so it leaves the decision to the next rule.
+      def narrow(candidates, scopes)
+        wanted = scopes.compact
+        return candidates if wanted.empty?
+
+        matching = candidates.select { |klass| (klass._component_scopes & wanted).any? }
+        matching.empty? ? candidates : matching
+      end
+
+      def least_scoped(candidates)
+        fewest = candidates.map { |klass| klass._component_scopes.size }.min
+        candidates.select { |klass| klass._component_scopes.size == fewest }
+      end
+
+      def ambiguity_message(name, referrer, candidates)
+        listed = candidates.map { |klass| "#{klass.name} #{klass._component_scopes.inspect}" }.join(", ")
+        "Ambiguous $ref #/components/schemas/#{name} from #{referrer.name}: #{listed}. " \
+          "Give the intended component a scope the referrer shares, or name the variants distinctly."
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/diagnostics.rb

@@ -0,0 +1,45 @@
+require "json"
+
+module AsyncapiCable
+  # Explanations for validation failures whose cause is not what the failure
+  # says. Only the wording changes — a payload that fails still fails.
+  module Diagnostics
+    DOUBLE_ENCODED = <<~TEXT.chomp
+      The payload is a JSON string rather than an object. A broadcast site
+      passing already-serialized JSON (`to_json`, or a renderer that returns a
+      String) leaves ActionCable to encode it a second time, so the wire
+      carries a JSON string literal and the client has to parse twice.
+      Broadcast a Hash, or describe the string with `contentMediaType` and
+      `contentSchema`.
+    TEXT
+
+    module_function
+
+    # A String payload alone proves nothing: `contentSchema` describes an
+    # embedded representation on purpose, and such a message validates. This
+    # fires only when a schema wanted an object or array at the root and got a
+    # string that happens to parse as one — the signature of a payload
+    # serialized a layer too early.
+    def hint_for(payload, errors)
+      return nil unless serialized_container?(payload)
+      return nil unless root_container_expected?(errors)
+
+      DOUBLE_ENCODED
+    end
+
+    def serialized_container?(payload)
+      return false unless payload.is_a?(String)
+
+      parsed = JSON.parse(payload)
+      parsed.is_a?(Hash) || parsed.is_a?(Array)
+    rescue JSON::ParserError
+      false
+    end
+
+    def root_container_expected?(errors)
+      errors.any? do |error|
+        error["data_pointer"].to_s.empty? && %w[object array].include?(error["type"])
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/generator/asyncapi_writer.rb

@@ -20,7 +20,8 @@ module AsyncapiCable
 
         def build_document(schema_name, schema_config)
           scope = (schema_config[:component_scope] || schema_config["component_scope"] || :cable).to_sym
-          components = load_cable_components(scope)
+          contexts = Dsl::MetadataStore.contexts_for(schema_name)
+          components = load_cable_components(scope, declared: declared_messages(contexts))
 
           document = Core::Document.new(
             info: schema_config[:info] || schema_config["info"] || {},
@@ -28,13 +29,22 @@ module AsyncapiCable
             cable_components: components
           )
 
-          Dsl::MetadataStore.contexts_for(schema_name).each do |context|
+          contexts.each do |context|
             document.add_channel(context)
           end
 
           document
         end
 
+        # Every declared message becomes a `components/messages` entry pointing
+        # at a schema of the same name, so these are referenced by construction
+        # — whatever scope they carry. A contract that reuses an existing REST
+        # component as its payload declares one that the document's own scope
+        # does not select.
+        def declared_messages(contexts)
+          contexts.flat_map { |context| context.operations.flat_map(&:messages) }.uniq
+        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
@@ -46,14 +56,21 @@ module AsyncapiCable
         # 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)
+        #
+        # Scope and the declared messages select the entry points;
+        # ReferenceClosure adds what those components reference, whatever scope
+        # the referee carries.
+        def load_cable_components(scope, declared: [])
           OpenapiRuby::Components::Loader.new.load!
 
-          schemas = OpenapiRuby::Components::Registry.instance.all_registered_classes.select do |klass|
+          scoped = 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
+          entry_points = (scoped + declared).uniq
+          schemas = Components::ReferenceClosure.expand(entry_points, scope: scope)
+            .each_with_object({}) do |klass, acc|
+              acc[klass.component_name] = klass._schema_definition
+            end
           {"schemas" => schemas}
         end
 

data/lib/asyncapi_cable/runtime/channel_hook.rb

@@ -17,7 +17,7 @@ module AsyncapiCable
       errors = collect_errors(matches, payload)
       return if errors.empty?
 
-      report(mode, stream, errors)
+      report(mode, stream, errors, payload)
     end
 
     # AsyncAPI 3 treats a channel's messages as alternatives: a payload
@@ -38,9 +38,12 @@ module AsyncapiCable
       results.min_by(&:size)
     end
 
-    def self.report(mode, stream, errors)
+    def self.report(mode, stream, errors, payload = nil)
       summary = errors.map { |e| e["error"] }.compact.uniq.join("; ")
       message = "AsyncAPI broadcast validation failed for stream #{stream.inspect}: #{summary}"
+      if (hint = Diagnostics.hint_for(payload, errors))
+        message = "#{message}\n#{hint}"
+      end
 
       case mode
       when :warn_only

data/lib/asyncapi_cable/testing/assert_helpers.rb

@@ -27,27 +27,42 @@ module AsyncapiCable
           next if errors.empty?
 
           asyncapi_flunk(
-            "AsyncAPI broadcast validation failed for #{stream.inspect}:\n  #{asyncapi_error_summary(errors)}"
+            [
+              "AsyncAPI broadcast validation failed for #{stream.inspect}:",
+              "  #{asyncapi_error_summary(errors)}",
+              Diagnostics.hint_for(payload, errors)
+            ].compact.join("\n")
           )
         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.
+      # Declared message schemas may `$ref` sibling components — an enum, or a
+      # REST component an embedded payload points at — so the validation
+      # document carries every registry class sharing the messages' scopes
+      # plus the transitive closure of what those reference. The message
+      # classes are entry points in their own right, as they are for the
+      # writer: one may well carry a scope no other component shares. That is
+      # the same set AsyncapiWriter publishes, so a payload that validates here
+      # validates against the committed document too. Memoized per scope set:
+      # PayloadValidator caches one compiled schema per components object.
+      #
+      # `Loader#load!` runs first because it is what assigns inferred scopes:
+      # reading `_component_scopes` before it has run yields an empty scope set
+      # for every class, and with it an empty components object. It eager-loads
+      # classes reachable only via `$ref` strings and is idempotent.
       def self.components_for(message_classes)
+        OpenapiRuby::Components::Loader.new.load!
+
         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|
+          scoped = OpenapiRuby::Components::Registry.instance.all_registered_classes.select { |klass|
             (klass._component_scopes & scopes).any?
-          }.to_h { |klass| [klass.component_name, klass._schema_definition] }
+          }
+          schemas = Components::ReferenceClosure.expand((scoped + message_classes).uniq, scope: scopes)
+            .to_h { |klass| [klass.component_name, klass._schema_definition] }
           {"schemas" => schemas}
         end
       end

data/lib/asyncapi_cable/version.rb

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

data/lib/asyncapi_cable.rb

@@ -1,5 +1,7 @@
 require "asyncapi_cable/version"
 require "asyncapi_cable/configuration"
+require "asyncapi_cable/diagnostics"
+require "asyncapi_cable/components/reference_closure"
 require "asyncapi_cable/dsl/metadata_store"
 require "asyncapi_cable/dsl/operation_context"
 require "asyncapi_cable/dsl/channel_context"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asyncapi_cable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Fobizz
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -99,8 +99,10 @@ files:
 - lib/asyncapi_cable.rb
 - lib/asyncapi_cable/adapters/minitest.rb
 - lib/asyncapi_cable/adapters/rspec.rb
+- lib/asyncapi_cable/components/reference_closure.rb
 - lib/asyncapi_cable/configuration.rb
 - lib/asyncapi_cable/core/document.rb
+- lib/asyncapi_cable/diagnostics.rb
 - lib/asyncapi_cable/dsl/channel_context.rb
 - lib/asyncapi_cable/dsl/metadata_store.rb
 - lib/asyncapi_cable/dsl/operation_context.rb