asyncapi_cable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1cb81ac1d3e0dbf6aec713ae2d67c5132bc969460c1f33ed112139d19282dbda
+  data.tar.gz: 8718125ac36f7bffbef7e053c9e5e8285e791efc23867618161bcf0ebd2878d2
+SHA512:
+  metadata.gz: b9a5dc6091faa5faacb0dbbf9485453e3e0feb2131f33a71ca71810e8610e2119125bb2ba85552bfc1cb09eb91dd422904c4e4d0f09391d0b3241d1e7de27fd9
+  data.tar.gz: 496a763988124507c0c75d49d3f30b884a31a84c18b4c0344ac0525d8e34e8a30c3aa18c17113e915a21d170d822eb83fa63e1e63b95b893d3c4b6b4e213d45a

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Fobizz / 101skills GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,201 @@
+# AsyncapiCable
+
+AsyncAPI 3 documentation and runtime payload validation for Rails ActionCable channels. Pairs with `openapi-ruby`: cable-only schemas share the same `OpenapiRuby::Components::Base` registry as REST schemas, so a single JSON Schema 2020-12 component can flow into both the OpenAPI document and the AsyncAPI document.
+
+## Why
+
+OpenAPI 3.1 still has no native WebSocket support. AsyncAPI 3 does, and uses JSON Schema 2020-12 by default — the same schema dialect `openapi-ruby` already produces. AsyncapiCable bridges the two: declare a channel via a familiar RSpec/Minitest DSL, point it at a component class, and you get both a publishable AsyncAPI 3 document and an in-process broadcast validator from the same source of truth.
+
+## Quick start
+
+Add the gem to the host Gemfile:
+
+```ruby
+gem "asyncapi_cable"
+```
+
+Configure one or more cable documents in an initializer. Each entry is one AsyncAPI document and one `component_scope` used to filter `OpenapiRuby::Components::Base` subclasses:
+
+```ruby
+# config/initializers/asyncapi_cable.rb
+AsyncapiCable.configure do |config|
+  config.schemas = {
+    cable_internal: {
+      info: { title: "My Internal Cable API", version: "v1" },
+      servers: {
+        dev:  { host: "localhost:3000",   pathname: "/cable", protocol: "ws"  },
+        live: { host: "app.example.com",  pathname: "/cable", protocol: "wss" }
+      },
+      component_scope: :cable_internal
+    }
+  }
+  config.schema_output_dir = "asyncapi"
+  config.validation_mode = :disabled # :disabled | :warn_only | :enabled
+end
+```
+
+Declare a message component using the standard `OpenapiRuby::Components::Base`, scoped to the cable audience:
+
+```ruby
+# packs/api_internal/app/components/internal/v1/schemas/job_status_message.rb
+class Internal::V1::Schemas::JobStatusMessage
+  include OpenapiRuby::Components::Base
+
+  component_scopes :cable_internal
+
+  schema({
+    type: :object,
+    properties: {
+      action: { type: :string },
+      user_id: { type: :integer },
+      status: { type: :string }
+    },
+    required: %w[action user_id status]
+  })
+end
+```
+
+Document a channel with the DSL adapter for your test framework. The DSL
+mirrors openapi-ruby's Minitest-style surface: a flat class-level `channel`
+declaration (no nested example groups), plus plain tests that call
+`assert_asyncapi_broadcast` — which runs your triggering code, captures every
+broadcast on the resolved stream, and validates each payload against the
+declared message schemas:
+
+```ruby
+# RSpec — spec/asyncapi/job_status_channel_spec.rb
+require "asyncapi_cable/rspec"
+
+RSpec.describe JobStatusChannel, type: :asyncapi do
+  asyncapi_schema :cable_internal
+
+  channel "{user_id}-job-status" do
+    parameter :user_id, schema: { type: :integer }
+    broadcast "Job status updates" do
+      operationId "receiveJobStatus"
+      message Internal::V1::Schemas::JobStatusMessage
+    end
+  end
+
+  it "broadcasts a schema-valid payload" do
+    payloads = assert_asyncapi_broadcast(params: { user_id: user.id }) do
+      SomeJob.perform_now(user)
+    end
+    expect(payloads.first["action"]).to eq("started")
+  end
+end
+```
+
+```ruby
+# Minitest — test/asyncapi/job_status_channel_test.rb
+require "asyncapi_cable/minitest"
+
+class JobStatusChannelTest < ActiveSupport::TestCase
+  include AsyncapiCable::Adapters::Minitest::DSL
+
+  asyncapi_schema :cable_internal
+
+  channel "{user_id}-job-status", channel_class: JobStatusChannel do
+    parameter :user_id, schema: { type: :integer }
+    broadcast "Job status updates" do
+      operationId "receiveJobStatus"
+      message Internal::V1::Schemas::JobStatusMessage
+    end
+  end
+
+  test "broadcasts a schema-valid payload" do
+    payloads = assert_asyncapi_broadcast(params: { user_id: user.id }) do
+      SomeJob.perform_now(user)
+    end
+    assert_equal "started", payloads.first["action"]
+  end
+end
+```
+
+`assert_asyncapi_broadcast` needs the ActionCable test adapter (`adapter: test`
+in `config/cable.yml`). It fails the test when no broadcast arrives on the
+expanded stream or when a captured payload violates every declared message,
+and raises `AsyncapiCable::Error` for usage mistakes — no broadcast operation
+declared, or `params` that don't resolve the stream template. It returns the
+decoded payloads for follow-up assertions.
+
+Generate the document:
+
+```sh
+bundle exec rake asyncapi_cable:generate PATTERN="spec/asyncapi/**/*_spec.rb"
+# writes asyncapi/cable_internal.yaml
+```
+
+`FRAMEWORK=` selects which DSL adapters are installed — `rspec`, `minitest`, or
+`hybrid` for a suite holding both during a migration. It defaults to what the
+host's directory layout says (`spec/rails_helper.rb` and/or
+`test/test_helper.rb` present), and `PATTERN` defaults to that framework's
+files. Both are usually worth spelling out in a wrapper script, since
+declarations live in a known subdirectory:
+
+```sh
+FRAMEWORK=hybrid bundle exec rake asyncapi_cable:generate \
+  PATTERN="spec/asyncapi/**/*_spec.rb, test/asyncapi/**/*_test.rb"
+```
+
+Generation runs in a subprocess with the host's environment set to `test`. The
+declaration files are loaded for their `channel` blocks and never executed:
+openapi-ruby's `AutorunSuppressor` keeps the `at_exit` hook that runs a suite
+from being registered, and its `TestSchemaSuppressor` keeps
+`maintain_test_schema!` from demanding a database. Nothing in a document comes
+from the database, so generation needs none.
+
+A host test helper can skip its test-time setup during such a run:
+
+```ruby
+# test/test_helper.rb
+unless AsyncapiCable.schema_generating?
+  require "rails/test_help"
+end
+```
+
+The subprocess also sets openapi-ruby's `OPENAPI_RUBY_GENERATING`, so a helper
+already guarding on `OpenapiRuby.schema_generating?` needs no second guard.
+Guarding is optional per helper: a helper whose constants are referenced at
+declaration-file *load* time must stay unguarded — narrow `PATTERN` instead.
+
+`PATTERN` matching nothing is an error rather than a no-op, so a typo in a glob
+can't quietly leave the committed documents untouched.
+
+## Runtime validation
+
+When `config.validation_mode` is not `:disabled`, the engine prepends a hook into `ActionCable::Server::Broadcasting#broadcast` that validates each payload against the **committed AsyncAPI document** (`Runtime::ContractRegistry` parses and memoizes `asyncapi/<schema>.yaml`) for any channel whose stream address matches. The specs + generator are the *write* side of the contract; the runtime only *reads* the committed artifact — so validation works in every process that broadcasts (Minitest, dev server), not just where the RSpec DSL happened to load. A channel that isn't in the generated doc is invisible to runtime validation until `rake asyncapi_cable:generate` output is committed.
+
+| Mode | Behaviour |
+|------|-----------|
+| `:disabled` (default) | hook is a no-op; broadcasts pass through untouched |
+| `:warn_only` | mismatches log a warning via `Rails.logger` (or `STDOUT` outside Rails); broadcast still delivers |
+| `:enabled` | mismatches raise `AsyncapiCable::Error`; broadcast does not deliver |
+
+An operation's `messages` are treated as alternatives per AsyncAPI 3 — a payload satisfying *any* declared message passes; mismatches surface the closest match's errors only.
+
+`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.
+
+## 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.
+
+## Developing the gem
+
+The gem lives in `ruby/` of the [asyncapi-cable](https://github.com/openapi-ruby/asyncapi-cable)
+repository, alongside the npm generator that turns the documents this gem
+writes into typed cable clients.
+
+```sh
+cd ruby
+bundle install
+bundle exec rspec
+bundle exec standardrb
+```
+
+Specs run against the dummy Rails app in `spec/dummy`. No Gemfile.lock is
+committed (gem convention), so a run resolves against the current gems.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/app/controllers/asyncapi_cable/schemas_controller.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AsyncapiCable
+  class SchemasController < ActionController::API
+    def index
+      schemas = AsyncapiCable.configuration.schemas.keys.map(&:to_s)
+      render json: {schemas: schemas}
+    end
+
+    def show
+      schema_name = params[:id]
+      return head :not_found unless AsyncapiCable.configuration.schemas.key?(schema_name.to_sym)
+
+      file_path = schema_file_path(schema_name)
+      return head :not_found unless File.exist?(file_path)
+
+      content_type = file_path.end_with?(".json") ? "application/json" : "application/x-yaml"
+      render plain: File.read(file_path), content_type: content_type
+    end
+
+    private
+
+    def schema_file_path(schema_name)
+      config = AsyncapiCable.configuration
+      ext = (config.schema_output_format == :json) ? "json" : "yaml"
+      Rails.root.join(config.schema_output_dir, "#{schema_name}.#{ext}").to_s
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,4 @@
+AsyncapiCable::Engine.routes.draw do
+  get "schemas", to: "schemas#index", as: :schemas
+  get "schemas/*id", to: "schemas#show", as: :schema
+end

data/lib/asyncapi_cable/adapters/minitest.rb

@@ -0,0 +1,53 @@
+require "asyncapi_cable"
+require "asyncapi_cable/testing/assert_helpers"
+require "active_support/core_ext/class/attribute"
+
+module AsyncapiCable
+  module Adapters
+    module Minitest
+      module DSL
+        include Testing::AssertHelpers
+
+        def self.included(base)
+          base.extend ClassMethods
+          base.class_attribute :_asyncapi_schema_name, default: nil
+          base.class_attribute :_asyncapi_contexts, default: []
+        end
+
+        module ClassMethods
+          def asyncapi_schema(name)
+            self._asyncapi_schema_name = name.to_sym
+          end
+
+          def channel(stream_template, channel_class: nil, &block)
+            context = Dsl::ChannelContext.new(
+              stream_template,
+              channel_class: channel_class,
+              schema_name: _asyncapi_schema_name
+            )
+            context.instance_eval(&block) if block
+            self._asyncapi_contexts = _asyncapi_contexts + [context]
+            Dsl::MetadataStore.register(context)
+            context
+          end
+        end
+
+        private
+
+        def asyncapi_declared_contexts
+          self.class._asyncapi_contexts
+        end
+
+        def asyncapi_flunk(message)
+          flunk(message)
+        end
+      end
+
+      def self.install!
+        # Intentional no-op — mirrors openapi-ruby's Minitest adapter.
+        # Hosts opt in by including AsyncapiCable::Adapters::Minitest::DSL
+        # into their base test class (e.g. ActiveSupport::TestCase).
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/adapters/rspec.rb

@@ -0,0 +1,58 @@
+require "asyncapi_cable"
+require "asyncapi_cable/testing/assert_helpers"
+
+module AsyncapiCable
+  module Adapters
+    module RSpec
+      # Class-level DSL extended onto :asyncapi example groups. Mirrors
+      # openapi-ruby's Minitest-style `api_path`: `channel` registers the
+      # declaration flat and opens no nested example groups; examples are
+      # plain `it` blocks calling assert_asyncapi_broadcast.
+      module ExampleGroupHelpers
+        def asyncapi_schema(name)
+          metadata[:asyncapi_schema_name] = name.to_sym
+        end
+
+        def channel(stream_template, channel_class: nil, &block)
+          context = Dsl::ChannelContext.new(
+            stream_template,
+            channel_class: channel_class || described_class,
+            schema_name: metadata[:asyncapi_schema_name]
+          )
+          context.instance_eval(&block) if block
+          metadata[:asyncapi_contexts] ||= []
+          metadata[:asyncapi_contexts] << context
+          Dsl::MetadataStore.register(context)
+          context
+        end
+      end
+
+      # Instance-level helpers mixed into :asyncapi examples.
+      module ExampleHelpers
+        include Testing::AssertHelpers
+
+        private
+
+        def asyncapi_declared_contexts
+          meta = ::RSpec.current_example.metadata
+          while meta
+            return meta[:asyncapi_contexts] if meta[:asyncapi_contexts]
+            meta = meta[:parent_example_group] || meta[:example_group]
+          end
+          []
+        end
+
+        def asyncapi_flunk(message)
+          raise message
+        end
+      end
+
+      def self.install!
+        ::RSpec.configure do |config|
+          config.extend ExampleGroupHelpers, type: :asyncapi
+          config.include ExampleHelpers, type: :asyncapi
+        end
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/configuration.rb

@@ -0,0 +1,22 @@
+module AsyncapiCable
+  class Configuration
+    attr_accessor :schemas, :schema_output_dir, :schema_output_format
+    attr_reader :validation_mode
+
+    VALIDATION_MODES = %i[disabled warn_only enabled].freeze
+
+    def initialize
+      @schemas = {}
+      @validation_mode = :disabled
+      @schema_output_dir = "asyncapi"
+      @schema_output_format = :yaml
+    end
+
+    def validation_mode=(mode)
+      unless VALIDATION_MODES.include?(mode)
+        raise ArgumentError, "validation_mode must be one of #{VALIDATION_MODES.inspect}, got #{mode.inspect}"
+      end
+      @validation_mode = mode
+    end
+  end
+end

data/lib/asyncapi_cable/core/document.rb

@@ -0,0 +1,137 @@
+require "yaml"
+
+module AsyncapiCable
+  module Core
+    class Document
+      ASYNCAPI_VERSION = "3.0.0"
+
+      attr_reader :data
+
+      def initialize(info:, servers: {}, cable_components: {})
+        @data = {
+          "asyncapi" => ASYNCAPI_VERSION,
+          "info" => deep_stringify(info),
+          "channels" => {},
+          "operations" => {},
+          "components" => {
+            "schemas" => deep_stringify(cable_components["schemas"] || {}),
+            "messages" => {}
+          }
+        }
+        @data["servers"] = deep_stringify(servers) unless servers.nil? || servers.empty?
+      end
+
+      def add_channel(channel_context)
+        channel_name = channel_name_for(channel_context)
+        channel_entry = {"address" => channel_context.stream_template}
+        # The exact Rails channel class name, so a generated client can use it
+        # as the ActionCable subscription identifier without re-deriving it.
+        if (klass = channel_context.channel_class) && klass.name
+          channel_entry["x-actioncable-channel"] = klass.name
+        end
+        channel_entry["parameters"] = parameters_for(channel_context)
+        channel_entry["messages"] = {}
+        channel_entry.delete("parameters") if channel_entry["parameters"].empty?
+
+        channel_context.operations.each do |op|
+          next unless op.kind == :broadcast || op.kind == :publish
+
+          op.messages.each do |component_class|
+            message_name = component_class.component_name
+            channel_entry["messages"][message_name] = {
+              "$ref" => "#/components/messages/#{message_name}"
+            }
+            add_message_component(component_class)
+          end
+
+          add_operation(channel_name, op)
+        end
+
+        @data["channels"][channel_name] = channel_entry
+      end
+
+      def to_h
+        result = @data.dup
+        result["channels"] = sort_hash(result["channels"])
+        result["operations"] = sort_hash(result["operations"])
+        result["components"] = result["components"].transform_values { |v| sort_hash(v) }
+        result.delete("components") if result["components"].values.all?(&:empty?)
+        result
+      end
+
+      def to_yaml = to_h.to_yaml
+
+      def to_json(*_args)
+        require "json"
+        JSON.pretty_generate(to_h)
+      end
+
+      private
+
+      def channel_name_for(channel_context)
+        klass = channel_context.channel_class
+        return channel_context.stream_template if klass.nil? || klass.name.nil?
+
+        klass.name.demodulize.sub(/Channel\z/, "")
+      end
+
+      # AsyncAPI 3.0 Parameter Objects are string-only: they carry no `schema`,
+      # only `enum`/`default`/`examples`/`description`. Map the declared schema's
+      # constraints onto those fields and drop the schema itself, otherwise the
+      # document fails 3.0 validation.
+      def parameters_for(channel_context)
+        channel_context.parameters.each_with_object({}) do |param, acc|
+          entry = {}
+          entry["description"] = param[:description] if param[:description]
+          if (schema = param[:schema])
+            entry["enum"] = deep_stringify(schema[:enum]) if schema[:enum]
+            entry["default"] = schema[:default] if schema.key?(:default)
+            entry["examples"] = deep_stringify(schema[:examples]) if schema[:examples]
+          end
+          # Server-derived params are not passed by the client at subscribe time.
+          entry["x-client-supplied"] = false if param[:client_supplied] == false
+          acc[param[:name]] = entry
+        end
+      end
+
+      def add_operation(channel_name, op)
+        op_id = op.operation_id || default_operation_id(channel_name, op)
+        action = (op.kind == :broadcast) ? "receive" : "send"
+        message_refs = op.messages.map do |klass|
+          {"$ref" => "#/channels/#{channel_name}/messages/#{klass.component_name}"}
+        end
+
+        @data["operations"][op_id] = {
+          "action" => action,
+          "channel" => {"$ref" => "#/channels/#{channel_name}"},
+          "messages" => message_refs
+        }
+        @data["operations"][op_id]["summary"] = op.summary if op.summary
+      end
+
+      def default_operation_id(channel_name, op)
+        "#{op.kind}#{channel_name}"
+      end
+
+      def add_message_component(component_class)
+        name = component_class.component_name
+        @data["components"]["messages"][name] ||= {
+          "payload" => {"$ref" => "#/components/schemas/#{name}"}
+        }
+      end
+
+      def deep_stringify(value)
+        case value
+        when Hash then value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify(v) }
+        when Array then value.map { |v| deep_stringify(v) }
+        when Symbol then value.to_s
+        else value
+        end
+      end
+
+      def sort_hash(hash)
+        hash.sort.to_h
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/dsl/channel_context.rb

@@ -0,0 +1,48 @@
+module AsyncapiCable
+  module Dsl
+    class ChannelContext
+      attr_reader :stream_template, :parameters, :operations, :channel_class, :schema_name
+
+      def initialize(stream_template, channel_class: nil, schema_name: nil)
+        @stream_template = stream_template
+        @channel_class = channel_class
+        @schema_name = schema_name
+        @parameters = []
+        @operations = []
+      end
+
+      # `client_supplied: false` marks an address parameter the server derives
+      # (e.g. from the session) rather than one the client passes at subscribe
+      # time — the generated client omits it from the channel's params.
+      def parameter(name, schema: nil, description: nil, client_supplied: true)
+        @parameters << {
+          name: name.to_s,
+          schema: schema,
+          description: description,
+          client_supplied: client_supplied
+        }.compact
+      end
+
+      def subscribe(summary = nil, &block)
+        add_operation(:subscribe, summary, &block)
+      end
+
+      def broadcast(summary = nil, &block)
+        add_operation(:broadcast, summary, &block)
+      end
+
+      def publish(summary = nil, &block)
+        add_operation(:publish, summary, &block)
+      end
+
+      private
+
+      def add_operation(kind, summary, &block)
+        op = OperationContext.new(kind, summary)
+        op.instance_eval(&block) if block
+        @operations << op
+        op
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/dsl/metadata_store.rb

@@ -0,0 +1,46 @@
+module AsyncapiCable
+  module Dsl
+    class MetadataStore
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        def register(context) = instance.register(context)
+
+        def contexts_for(schema_name) = instance.contexts_for(schema_name)
+
+        def all_contexts = instance.all_contexts
+
+        def clear!(scope: nil) = instance.clear!(scope: scope)
+      end
+
+      def initialize
+        @contexts = []
+      end
+
+      def register(context)
+        @contexts << context
+        context
+      end
+
+      def contexts_for(schema_name)
+        schema_name = schema_name&.to_sym
+        @contexts.select { |c| c.schema_name.nil? || c.schema_name.to_sym == schema_name }
+      end
+
+      def all_contexts
+        @contexts.dup
+      end
+
+      def clear!(scope: nil)
+        if scope
+          target = scope.to_sym
+          @contexts.reject! { |c| c.schema_name && c.schema_name.to_sym == target }
+        else
+          @contexts = []
+        end
+      end
+    end
+  end
+end

data/lib/asyncapi_cable/dsl/operation_context.rb

@@ -0,0 +1,32 @@
+module AsyncapiCable
+  module Dsl
+    class OperationContext
+      KINDS = %i[subscribe broadcast publish].freeze
+
+      attr_reader :kind, :summary, :messages
+      attr_accessor :operation_id
+
+      def initialize(kind, summary = nil)
+        unless KINDS.include?(kind)
+          raise ArgumentError, "operation kind must be one of #{KINDS.inspect}, got #{kind.inspect}"
+        end
+        @kind = kind
+        @summary = summary
+        @messages = []
+        @operation_id = nil
+      end
+
+      def message(component_class)
+        unless component_class.is_a?(Class) && component_class < OpenapiRuby::Components::Base
+          raise ArgumentError, "message must be an OpenapiRuby::Components::Base subclass, got #{component_class.inspect}"
+        end
+        @messages << component_class
+        component_class
+      end
+
+      def operationId(value)
+        @operation_id = value
+      end
+    end
+  end
+end