yes-command-api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c850bff22a130767ba5aea77998f8a01a1ad9ac2b308537318d7e3276c8c5e9d
+  data.tar.gz: 73b487f88eb8ed2398344218c72b7042c59bdc5f8c3e7e029809db197d3813c0
+SHA512:
+  metadata.gz: 6fb467acd706625779f0c438b4400c7b086d500a2cb188ec140b5cdf472da54a3ee8a83499ed9a5e64236f8ac468e95675f13388ac5655e9db207a6ed13e75ab
+  data.tar.gz: aba5cd97549563b812be96f85bd7b3701570ef775257a3a1ee45d72d3128c57386cbac412b492739aa61a9430ae9de731b8852e853101b9530a01fc99d782f33

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2023 Nico Ritsche
+
+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,242 @@
+# Yes Command API
+
+The Yes command API is a mountable rails engine providing an endpoint for calling API commands.
+
+Commands represent the write side of CQRS in our eventsourced system.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "yes-command-api"
+```
+
+And then execute:
+```bash
+bundle install
+```
+
+## Usage
+
+See the [root README](../README.md) for the full DSL documentation, aggregate definition, and usage examples.
+
+### Configuration
+
+The preferred way of issuing commands using the commands API is asynchronously.
+
+For that, you need to configure Yes::Core to process commands asynchronously.
+
+```ruby
+Yes::Core.configure do |config|
+  config.process_commands_inline = false
+end
+```
+If `process_commands_inline` is true (the default), commands are processed synchronously in the request. When set to false, commands are enqueued via ActiveJob for asynchronous processing.
+
+
+### Mounting the Endpoint
+
+Mount the command endpoint to your rails application in `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount Yes::Command::Api::Engine => '/v1/commands'
+end
+```
+
+The mounted endpoint exposes all commands defined in your bounded context(s).
+
+
+### Writing Authorizers
+
+To make a command accessible for a caller, you need to define an authorizer for it.
+If there is no authorizer defined a command is considered unauthorized for all callers by default.
+
+Example:
+
+Given a command
+
+```ruby
+module MyContext
+  module MyAggregate
+    class Aggregate < Yes::Core::Aggregate
+      attribute :what, :string, command: true
+      attribute :user_id, :uuid
+
+      authorize do
+        command.user_id == auth_data['user_id']
+      end
+    end
+  end
+end
+```
+
+The authorizer needs to raise `CommandNotAuthorized` if the given `auth_data` (jwt payload + referer host) does not authorize the given `command`.
+In case the authorizer raises nothing, the command is considered authorized.
+
+
+### Making a Command(s) Request
+
+The commands endpoint accepts commands supplied as a json array, using a POST request.
+
+The endpoint is located where you mounted it, e.g. `https://your-app.example.com/v1/commands`.
+
+Here is an example of a valid payload:
+
+```json
+{
+  "commands": [{
+    "subject": "MyAggregate",
+    "context": "MyContext",
+    "command": "DoSomething",
+    "data": {
+      "user_id": "07393424-fa57-40fe-a3d2-c3bdd8b8e952",
+      "what": "Nonsense"
+    }
+  }],
+  "channel": "/notifications-for-user-07393424-fa57-40fe-a3d2-c3bdd8b8e952"
+}
+```
+You also need to supply a valid JWT token as a bearer token for authorization and authentication.
+
+Note that commands is an array, so you can supply any number of commands in a single request.
+
+See the next section for how to receive updates about your commands using the standard message bus notifier.
+
+### MessageBus Notifier
+
+#### Authorization
+
+In order to receive user-targeted messages - you should authorize your request first. It can be done by providing JWT token along with `Authorization` header. Example:
+
+```javascript
+let headers = { 'Authorization': 'Token eyJhbGciOiJFRDI1NTE5In0.eyJzY29wZXMiOlsiYWRtaW4iLCJjdXJyZW50X3VzZXIiLCJ1c2VyX3Byb2ZpbGUiXSwiZGF0YSI6eyJ1c2VyX3V1aWQiOiIyMjUwODIwZS00MzVhLTQ0ODQtYWUzMS1iYTFiODk1NDI2MWUifSwiZXhwIjoxNjkxNzQwNTA3fQ.D_TuOKh5LyGtusU5cZrJih-WYbB7MWChDOTS6WcWCRZUdldzZzKmXLtdgE93bkgb0TV9FNKXSvHt8DLhBZIoCA' };
+```
+
+#### Filters
+
+You can filter messages by providing filter params in the request url. Here they are:
+
+- `batch_id`. It is your command batch id. Example: `/message-bus/some-client-id/poll?batch_id=7121e60e-4d3d-4fb7-b454-f603c75f1359`
+- `type`. It is a command type. Possible values are `batch_started`, `batch_finished`, `command_success` and `command_error` so far. Example: `/message-bus/some-client-id/poll?type=command_error`
+- `command`. It is a command name. Example `/message-bus/some-client-id/poll?command=ApprenticeshipPresentation::Apprenticeship::Commands::AssignCompany::Command`
+- `since`. Unix timestamp. Providing it will filter messages which are not older than the `since` param value. Example: `/message-bus/some-client-id/poll?since=1689778808`
+
+You can provide a starting message id to start receiving messages from certain position. As stated in docs - you should pass it in the payload along with a channel name to subscribe to:
+
+```javascript
+let payload = { 'some-channel-name': 123 }
+```
+
+#### Examples
+
+Here is how long-polling HTTP request from browser using various filters and JWT authorization may look like:
+
+```javascript
+async function postData(url = "", data = {}) {
+    // Default options are marked with *
+    const response = fetch(url, {
+        method: "POST", // *GET, POST, PUT, DELETE, etc.
+        mode: "same-origin", // no-cors, *cors, same-origin
+        cache: "no-cache", // *default, no-cache, reload, force-cache, only-if-cached
+        credentials: "same-origin", // include, *same-origin, omit
+        headers: {
+            'Content-Type': 'application/json',
+            'X-SILENCE-LOGGER': 'true',
+            'Transfer-Encoding': 'chunked',
+            'Authorization': 'Token eyJhbGciOiJFRDI1NTE5In0.eyJzY29wZXMiOlsiYWRtaW4iXSwiZGF0YSI6eyJ1c2VyX3V1aWQiOiJlMmMwYzBkNC1iMWMzLTQwNzktOTlhMi0zYTlhOTg2MWVhYzgifSwiZXhwIjoxNjg5NzgzMjE4fQ.HKmthrv7HDsMof88hvCErVSlTCGg-Ikeb9-eb0DLPVXQQmpJ_4gTD52bgMFBGmGaA_TdRakAG3UGgCp9d9VYAw'
+        },
+        redirect: "error", // manual, *follow, error
+        referrerPolicy: "no-referrer", // no-referrer, *no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, unsafe-url
+        body: JSON.stringify(data), // body data type must match "Content-Type" header
+    });
+    return response;
+}
+
+function processChunkedResponse(response) {
+    var text = '';
+    var reader = response.body.getReader()
+    var decoder = new TextDecoder();
+
+    return readChunk();
+
+    function readChunk() {
+        return reader.read().then(appendChunks);
+    }
+
+    function appendChunks(result) {
+        var chunk = decoder.decode(result.value || new Uint8Array, {stream: !result.done});
+        console.log('got chunk of', chunk.length, 'bytes')
+        console.log('chunk so far is', chunk);
+        text += chunk;
+
+        if (result.done) {
+            return text;
+        } else {
+            return readChunk();
+        }
+    }
+}
+//let url = 'http://localhost:3000/message-bus/some-client-id/poll?since=1689778808&type=batch_started&batch_id=7121e60e-4d3d-4fb7-b454-f603c75f1359&command=ApprenticeshipPresentation::Apprenticeship::Commands::AssignCompany::Command'
+let url = new URL('http://localhost:3000/message-bus/some-client-id/poll');
+url.search = new URLSearchParams(
+    {
+        since: 1689778808,
+        type: 'batch_started',
+        batch_id: '7121e60e-4d3d-4fb7-b454-f603c75f1359',
+        command: 'ApprenticeshipPresentation::Apprenticeship::Commands::AssignCompany::Command'
+    }
+);
+
+postData(url, { '/notifications/testing-12345678': 0 }).then(processChunkedResponse);
+```
+
+## Development
+
+### Prerequisites
+
+- Docker and Docker Compose
+- Ruby >= 3.2.0
+- Bundler
+
+### Setup
+
+Start PostgreSQL and Redis from the **repository root**:
+
+```shell
+docker compose up -d
+```
+
+Install dependencies:
+
+```shell
+bundle install
+```
+
+Set up the EventStore database:
+
+```shell
+PG_EVENTSTORE_URI="postgresql://postgres:postgres@localhost:5532/eventstore_test" bundle exec rake pg_eventstore:create pg_eventstore:migrate
+```
+
+Set up the test database:
+
+```shell
+RAILS_ENV=test bundle exec rake db:create db:migrate
+```
+
+The `.env` file at `spec/.env` is loaded automatically and contains JWT test keys.
+
+### Running Specs
+
+```shell
+bundle exec rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yousty/yes.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+APP_RAKEFILE = File.expand_path('spec/dummy/Rakefile', __dir__)
+load 'rails/tasks/engine.rake'
+
+load 'rails/tasks/statistics.rake'
+
+require 'pg_eventstore'
+
+load 'pg_eventstore/tasks/setup.rake'
+
+require 'bundler/gem_tasks'

data/app/controllers/yes/command/api/application_controller.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      class ApplicationController < ActionController::API
+      end
+    end
+  end
+end

data/app/controllers/yes/command/api/v1/commands_controller.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      module V1
+        # Controller for executing command batches via the command bus.
+        #
+        # Auth is delegated to the configured auth adapter in Yes::Core.configuration.
+        # If no auth adapter is configured, authentication will raise an error.
+        class CommandsController < ActionController::API
+          MAX_INLINE_COMMANDS_PER_REQ = 10
+
+          include Yes::Core::OpenTelemetry::Trackable
+
+          before_action :authenticate_with_token
+          before_action :set_channel
+
+          rescue_from(StandardError, with: :handle_unexpected_error)
+          rescue_from(Yes::Core::AuthenticationError, with: :auth_error_response)
+
+          rescue_from(
+            Yes::Command::Api::Commands::ParamsValidator::CommandParamsInvalid,
+            with: :command_params_invalid_response
+          )
+
+          rescue_from(
+            Yes::Command::Api::Commands::Deserializer::DeserializationFailed,
+            with: :deserialization_failed_response
+          )
+
+          rescue_from(
+            Yes::Command::Api::Commands::BatchAuthorizer::CommandsNotAuthorized,
+            with: :commands_unauthorized_response
+          )
+
+          rescue_from(
+            Yes::Command::Api::Commands::BatchValidator::CommandsInvalid,
+            with: :commands_invalid_response
+          )
+
+          # Executes a batch of commands.
+          def execute
+            Yes::Command::Api::Commands::ParamsValidator.call(params[:commands])
+            deserialize_commands = Yes::Command::Api::Commands::Deserializer.call(params[:commands])
+            expanded_commands = expand_commands(deserialize_commands)
+            return too_many_inline_commands if perform_inline? && expanded_commands.size > MAX_INLINE_COMMANDS_PER_REQ
+
+            Yes::Command::Api::Commands::BatchAuthorizer.call(expanded_commands, auth_data)
+            Yes::Command::Api::Commands::BatchValidator.call(expanded_commands)
+            cmd_bus_response = command_bus.call(
+              add_metadata(deserialize_commands),
+              notifier_options: { channel: @channel }
+            )
+
+            render json: success_response_data(cmd_bus_response), status: :ok
+          end
+
+          private
+
+          # Authenticates the request using the configured auth adapter.
+          # Stores the returned auth data for use in subsequent actions.
+          #
+          # @raise [RuntimeError] if no auth adapter is configured
+          # @return [void]
+          def authenticate_with_token
+            adapter = Yes::Core.configuration.auth_adapter
+            raise Yes::Core::AuthenticationError, 'No auth adapter configured. Set Yes::Core.configuration.auth_adapter.' unless adapter
+
+            @auth_data = adapter.authenticate(request)
+          rescue *auth_error_classes => e
+            auth_error_response(e)
+          end
+
+          # @return [Hash] the authentication data
+          attr_reader :auth_data
+
+          # Returns the error classes defined by the auth adapter.
+          #
+          # @return [Array<Class>] auth error classes
+          def auth_error_classes
+            Yes::Core.configuration.auth_adapter&.error_classes || []
+          end
+
+          def perform_inline?
+            return false if params[:async] == 'true'
+            return true if params[:async] == 'false'
+
+            Yes::Core.configuration.process_commands_inline
+          end
+
+          def command_bus
+            return Yes::Core::Commands::Bus.new unless perform_inline?
+
+            Yes::Core::Commands::Bus.new(perform_inline: perform_inline?)
+          end
+
+          def too_many_inline_commands
+            error = "Too many commands. You can process up to #{MAX_INLINE_COMMANDS_PER_REQ} commands inline."
+            render json: { error: }, status: :unprocessable_content
+          end
+
+          def expand_commands(deserialize_commands)
+            deserialize_commands.map do |command|
+              command.is_a?(Yes::Core::Commands::Group) ? command.commands : command
+            end.flatten
+          end
+
+          def add_metadata(commands)
+            commands.map do |command|
+              command.class.new(
+                command.to_h.merge(
+                  metadata: (command.metadata || {}).merge(identity_id: auth_data[:identity_id], otl_contexts:)
+                )
+              )
+            end
+          end
+
+          def success_response_data(cmd_bus_response)
+            return { batch_id: cmd_bus_response.job_id } if cmd_bus_response.respond_to?(:job_id)
+
+            cmd_bus_response
+          end
+
+          def params
+            request.parameters.deep_symbolize_keys
+          end
+
+          def command_params_invalid_response(error)
+            error_info = {
+              title: 'Bad request',
+              detail: { message: error.message }
+            }
+            error_info[:detail][:invalid] = error.extra if error.extra
+
+            render json: error_info.to_json, status: :bad_request
+          end
+
+          def deserialization_failed_response(error)
+            error_info = {
+              title: 'Bad request',
+              detail: error.extra
+            }
+
+            render json: error_info.to_json, status: :bad_request
+          end
+
+          # Handles auth token errors from the configured auth adapter.
+          #
+          # @param error [StandardError] the auth error
+          # @return [void]
+          def auth_error_response(error)
+            render(
+              json: { title: 'Auth Token Invalid', detail: error.message }.to_json,
+              status: :unauthorized
+            )
+          end
+
+          def commands_unauthorized_response(error)
+            render(
+              json: { title: 'Unauthorized', detail: error.extra }.to_json, status: :unauthorized
+            )
+          end
+
+          def commands_invalid_response(error)
+            error_info = {
+              title: 'Unprocessable Entity',
+              errors: error.extra
+            }
+
+            render json: error_info.to_json, status: 422
+          end
+
+          def set_channel
+            @channel = params[:channel].presence || auth_data[:identity_id]
+
+            self.class.current_span&.set_attribute('channel', @channel)
+            return if @channel.present?
+
+            render json: { title: '"channel" param is required' }, status: :bad_request
+          end
+          otl_trackable :set_channel,
+                        Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(
+                          span_name: 'Set Channel',
+                          span_kind: :client
+                        )
+
+          def handle_unexpected_error(error)
+            self.class.current_span&.status = OpenTelemetry::Trace::Status.error(error.message)
+            self.class.current_span&.record_exception(error)
+
+            raise error
+          end
+          otl_trackable :handle_unexpected_error,
+                        Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Handle Unexpected Error')
+
+          def command_request_started_at_ms
+            return nil unless request.env['HTTP_X_REQUEST_START']
+
+            (request.env['HTTP_X_REQUEST_START'].to_f * 1000).to_i
+          end
+
+          def otl_contexts
+            {
+              root: self.class.propagate_context(service_name: true),
+              timestamps: { command_request_started_at_ms: }.compact
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/config/initializers/message_bus_filters.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+return unless defined?(MessageBus)
+
+# Filtering by params[:batch_id]. Applied to all channels
+MessageBus.register_client_message_filter('') do |params, message|
+  next true unless params.key?('batch_id')
+
+  message.data['batch_id'].to_s == params['batch_id']
+end
+
+# Filtering by params[:type]. Applied to all channels
+MessageBus.register_client_message_filter('') do |params, message|
+  next true unless params.key?('type')
+
+  message.data['type'] == params['type']
+end
+
+# Filtering by params[:command]. Applied to all channels
+MessageBus.register_client_message_filter('') do |params, message|
+  next true unless params.key?('command')
+
+  message.data['command'] == params['command']
+end
+
+# Filtering by params[:since]. Applied to all channels
+MessageBus.register_client_message_filter('') do |params, message|
+  next true unless params.key?('since')
+  next true unless message.data.key?('published_at')
+
+  message.data['published_at'] >= params['since'].to_i
+end
+
+MessageBus.user_id_lookup do |env|
+  request = ActionDispatch::Request.new(env)
+  token, = ActionController::HttpAuthentication::Token.token_and_options(request)
+
+  if token && Yes::Core.configuration.auth_adapter
+    verified_token = Yes::Core.configuration.auth_adapter.verify_token(token)
+    verified_token.token.first['identity_id']
+  end
+end

data/config/routes.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      class OtlTrackableRequest
+        def call(env)
+          tracer = Yes::Core.configuration.otl_tracer
+          controller = Yes::Command::Api::V1::CommandsController
+
+          return controller.action(:execute).call(env) unless tracer
+
+          tracer.in_span("Request #{controller}", kind: :client) do |request_span|
+            request_span.add_attributes(otl_auth_data(env))
+
+            Yes::Command::Api::V1::CommandsController.action(:execute).call(env).tap do |status, _headers, rack_response|
+              tracer.in_span("Response #{controller}", kind: :client) do |response_span|
+                response_span.status = OpenTelemetry::Trace::Status.error if status >= 300
+                response_span.add_attributes(
+                  {
+                    'response.status': status,
+                    'response.body': rack_response.body
+                  }.stringify_keys
+                )
+              end
+            end
+          end
+        end
+
+        private
+
+        def otl_auth_data(env)
+          request = Rack::Request.new(env)
+
+          request.body.rewind
+          params = request.body.read
+          request.body.rewind
+
+          auth_token = env['HTTP_AUTHORIZATION'] || ''
+          auth_data =  auth_token.present? ? JWT.decode(auth_token.gsub('Bearer ', ''), nil, false) : {}
+          {
+            auth_token:,
+            auth_data: auth_data.to_json,
+            params:
+          }.stringify_keys
+        end
+      end
+    end
+  end
+end
+
+Yes::Command::Api::Engine.routes.draw do
+  post '/', to: Yes::Command::Api::OtlTrackableRequest.new
+end

data/lib/yes/command/api/commands/batch_authorizer.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      module Commands
+        # Authorizes a collection of commands using their respective authorizer classes.
+        # Raises if any command is not authorized.
+        class BatchAuthorizer
+          CommandsNotAuthorized = Class.new(Yes::Core::Error)
+          CommandAuthorizerNotFound = Class.new(Yes::Core::Error)
+
+          class << self
+            include Yes::Core::OpenTelemetry::Trackable
+
+            # Authorizes the given commands with the provided auth data.
+            #
+            # @param commands [Array<Yes::Core::Command>] commands to authorize
+            # @param auth_data [Hash] authorization data
+            # @raise [CommandsNotAuthorized] if any command is not authorized
+            # @return [void]
+            def call(commands, auth_data)
+              unauthorized = []
+
+              commands.each do |command|
+                authorizer = authorizer_for(command)
+                authorizer.call(command, auth_data)
+              rescue CommandAuthorizerNotFound
+                unauthorized << unauthorized_data(command, 'Not allowed').tap do
+                  trace_error('Command authorizer not found', { command: command.to_json })
+                end
+              rescue Yes::Core::Authorization::CommandAuthorizer::CommandNotAuthorized => e
+                unauthorized << unauthorized_data(command, e.message).tap do
+                  trace_error('Command not authorized', { command: })
+                end
+              end
+
+              return unless unauthorized.any?
+
+              trace_error('Unauthorized', { unauthorized: unauthorized.to_json })
+              raise CommandsNotAuthorized.new(extra: unauthorized)
+            end
+            otl_trackable :call, Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Authorize Commands')
+
+            private
+
+            # Returns the command authorizer for the given command.
+            #
+            # @param command [Yes::Core::Command] command to authorize
+            # @return [Class] authorizer class for the command
+            # @raise [CommandAuthorizerNotFound] if no authorizer is found
+            def authorizer_for(command)
+              class_name = Yes::Core::Commands::Helper.new(command).authorizer_classname
+
+              Kernel.const_get(class_name)
+            rescue NameError
+              raise CommandAuthorizerNotFound, "#{class_name} not found"
+            end
+
+            # Builds unauthorized data hash for error reporting.
+            #
+            # @param command [Yes::Core::Command] the unauthorized command
+            # @param message [String] the error message
+            # @return [Hash] unauthorized data
+            def unauthorized_data(command, message)
+              {
+                message:,
+                command: command.class.to_s,
+                command_id: command.command_id,
+                data: command.payload,
+                metadata: command.metadata || {}
+              }
+            end
+
+            # Traces an error on the current OpenTelemetry span.
+            #
+            # @param message [String] error message
+            # @param attributes [Hash] span attributes
+            # @return [void]
+            def trace_error(message, attributes = {})
+              singleton_class.current_span&.status = ::OpenTelemetry::Trace::Status.error(message)
+              singleton_class.current_span&.add_attributes(attributes.stringify_keys)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/command/api/commands/batch_validator.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      module Commands
+        # Validates a collection of commands using their respective validator classes.
+        # Raises if any command is invalid.
+        class BatchValidator
+          CommandsInvalid = Class.new(Yes::Core::Error)
+
+          class << self
+            include Yes::Core::OpenTelemetry::Trackable
+
+            # Validates the given commands, raises CommandsInvalid if any are invalid.
+            #
+            # @param commands [Array<Yes::Core::Command>] commands to validate
+            # @raise [CommandsInvalid] if any command is invalid
+            # @return [void]
+            def call(commands)
+              invalid = []
+              commands.each do |command|
+                validator = validator_for(command)
+                next unless validator
+
+                validator.call(command)
+              rescue Yes::Core::Commands::Validator::CommandInvalid => e
+                invalid << {
+                  message: e.message,
+                  command: command.class.to_s,
+                  command_id: command.command_id,
+                  data: command.payload,
+                  metadata: command.metadata || {},
+                  details: e.extra
+                }.tap do
+                  trace_error('Command validation failed', { command: command.to_json })
+                end
+              end
+
+              return unless invalid.any?
+
+              trace_error('Commands invalid', { invalid: invalid.to_json })
+              raise CommandsInvalid.new(extra: invalid)
+            end
+            otl_trackable :call, Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Validate Commands')
+
+            private
+
+            # Returns the validator for the given command, or nil if none exists.
+            #
+            # @param command [Yes::Core::Command] command to validate
+            # @return [Class, nil] validator class for the command, or nil
+            def validator_for(command)
+              class_name = Yes::Core::Commands::Helper.new(command).validator_classname
+
+              Kernel.const_get(class_name)
+            rescue NameError
+              nil
+            end
+
+            # Traces an error on the current OpenTelemetry span.
+            #
+            # @param message [String] error message
+            # @param attributes [Hash] span attributes
+            # @return [void]
+            def trace_error(message, attributes = {})
+              singleton_class.current_span&.status = ::OpenTelemetry::Trace::Status.error(message)
+              singleton_class.current_span&.add_attributes(attributes.stringify_keys)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/command/api/commands/deserializer.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      module Commands
+        # Deserializes command data hashes into command instances.
+        # Supports V1, V2, and command group class resolution.
+        class Deserializer
+          DeserializationFailed = Class.new(Yes::Core::Error)
+
+          class << self
+            include Yes::Core::OpenTelemetry::Trackable
+
+            # Deserializes command data into command instances.
+            #
+            # @param command_data [Array<Hash>] commands to deserialize
+            # @return [Array<Yes::Core::Command>] deserialized commands
+            # @raise [DeserializationFailed] if any command cannot be deserialized
+            def call(command_data)
+              failed = { invalid: [], not_found: [] }
+              commands = []
+
+              command_data.each do |command|
+                commands << Kernel.const_get(command_class_name(command)).new(
+                  { metadata: command[:metadata] }.merge(command[:data])
+                ).tap do |cmd|
+                  singleton_class.current_span&.add_event('Deserialized',
+                                                          attributes: { 'command' => cmd.to_json })
+                end
+              rescue NameError
+                failed[:not_found] << command
+              rescue Yes::Core::Command::Invalid
+                failed[:invalid] << command
+              end
+
+              if failed.values.flatten.any?
+                singleton_class.current_span&.status = ::OpenTelemetry::Trace::Status.error('Deserialization failed')
+                singleton_class.current_span&.add_attributes({ 'failed' => failed.to_json })
+
+                raise DeserializationFailed.new(extra: failed)
+              end
+
+              commands
+            end
+            otl_trackable :call, Yes::Core::OpenTelemetry::OtlSpan::OtlData.new(span_name: 'Deserialize Commands')
+
+            private
+
+            # Resolves the command class name, trying command group, V2, then V1 conventions.
+            #
+            # @param command [Hash] command data
+            # @return [String] command class name
+            def command_class_name(command)
+              [command_group_class(command), command_v2_class(command), command_class(command)].each do |name|
+                Kernel.const_get(name)
+                return name
+              rescue NameError
+                next
+              end
+              # None found — return V2 name so const_get in caller raises NameError
+              command_v2_class(command)
+            end
+
+            # Returns the V1 command class name.
+            #
+            # @param command [Hash] command data
+            # @return [String] command class name
+            def command_class(command)
+              "#{command[:context]}::Commands::#{command[:subject]}::#{command[:command]}"
+            end
+
+            # Returns the V2 command class name.
+            #
+            # @param command [Hash] command data
+            # @return [String] command class name
+            def command_v2_class(command)
+              "#{command[:context]}::#{command[:subject]}::Commands::#{command[:command]}::Command"
+            end
+
+            # Returns the command group class name.
+            #
+            # @param command [Hash] command data
+            # @return [String] command group class name
+            def command_group_class(command)
+              "CommandGroups::#{command[:command]}::Command"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/command/api/commands/notifiers/action_cable.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      module Commands
+        module Notifiers
+          # Notifies command processing events via ActionCable broadcast.
+          # Used with an external WebSocket gateway (e.g. socket_gate).
+          class ActionCable < Yes::Core::Commands::Notifier
+            # @param batch_id [String] the id of the batch that has started processing
+            # @param transaction [TransactionDetails] the transaction details
+            # @param commands [Array<Command>] the commands being processed
+            def notify_batch_started(batch_id, transaction = nil, commands = nil)
+              ::ActionCable.server.broadcast(
+                channel,
+                {
+                  batch_id:,
+                  published_at:,
+                  type: 'batch_started',
+                  transaction: transaction.to_h
+                }.merge(commands_data(commands))
+              )
+            end
+
+            # @param batch_id [String] the id of the batch that has finished processing
+            # @param transaction [TransactionDetails] the transaction details
+            # @param responses [Array<Response>] the command responses
+            def notify_batch_finished(batch_id, transaction = nil, responses = nil)
+              ::ActionCable.server.broadcast(
+                channel,
+                {
+                  batch_id:,
+                  published_at:,
+                  type: 'batch_finished',
+                  transaction: transaction.to_h
+                }.merge(failed_commands_data(responses))
+              )
+            end
+
+            # @param cmd_response [Yes::Core::Commands::Response] the command response
+            def notify_command_response(cmd_response)
+              ::ActionCable.server.broadcast(
+                channel,
+                cmd_response.to_notification.merge(published_at:)
+              )
+            end
+
+            private
+
+            # @return [Integer]
+            def published_at
+              Time.now.to_i
+            end
+
+            def commands_data(commands)
+              return {} if commands.nil?
+
+              { commands: commands.map { { command: _1.class.to_s, command_id: _1.command_id } } }
+            end
+
+            def failed_commands_data(responses)
+              return {} if responses.nil?
+
+              failed = responses.filter_map do |resp|
+                next unless resp.error
+
+                {
+                  command: resp.cmd.class.to_s,
+                  command_id: resp.cmd.command_id,
+                  error: resp.error.to_s
+                }
+              end
+
+              failed.empty? ? {} : { failed_commands: failed }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/command/api/commands/notifiers/message_bus.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      module Commands
+        module Notifiers
+          class MessageBus < Yes::Core::Commands::Notifier
+            attr_reader :channel
+            private :channel
+
+            # @param options [Hash] the options to create a notifier with
+            # @option options [String] :channel the channel name to publish notifications to
+            def initialize(options)
+              super()
+
+              @channel = options[:channel]
+            end
+
+            # @param batch_id [String] the id of the batch that has started processing
+            # @param transaction [TransactionDetails] the transaction details of the current transaction
+            # @param commands [Array<Command>] the commands that are being processed
+            #
+            def notify_batch_started(batch_id, transaction = nil, commands = nil)
+              user_ids = [transaction&.caller_id].compact
+
+              data =
+                {
+                  batch_id:, published_at:, type: 'batch_started'
+                }.merge(
+                  transaction: transaction.to_h
+                ).merge(commands_data(commands))
+
+              ::MessageBus.publish(channel, data, user_ids: user_ids.empty? ? nil : user_ids)
+            end
+
+            # @param batch_id [String] the id of the batch that has finished processing
+            # @param transaction [TransactionDetails] the transaction details of the current transaction
+            # @param responses [Array<Response>] the responses of the commands that were processed
+            #
+            def notify_batch_finished(batch_id, transaction = nil, responses = nil)
+              user_ids = [transaction&.caller_id].compact
+
+              data = {
+                type: 'batch_finished',
+                batch_id:,
+                published_at:
+              }.merge(
+                transaction: transaction.to_h
+              ).merge(failed_commands_data(responses))
+
+              ::MessageBus.publish(channel, data, user_ids: user_ids.empty? ? nil : user_ids)
+            end
+
+            # @param cmd_response [Yes::Core::Commands::Response]
+            #   the command response to notify
+            def notify_command_response(cmd_response)
+              user_ids = [cmd_response.transaction&.caller_id].compact
+
+              ::MessageBus.publish(
+                channel,
+                cmd_response.to_notification.merge(published_at:),
+                user_ids: user_ids.empty? ? nil : user_ids
+              )
+            end
+
+            private
+
+            # @return [Integer]
+            def published_at
+              Time.now.to_i
+            end
+
+            def commands_data(commands)
+              return {} if commands.nil?
+
+              { commands: commands.map { { command: _1.class.to_s, command_id: _1.command_id } } }
+            end
+
+            def failed_commands_data(responses)
+              return {} if responses.nil?
+
+              failed = responses.filter_map do |resp|
+                next unless resp.error
+
+                {
+                  command: resp.cmd.class.to_s,
+                  command_id: resp.cmd.command_id,
+                  error: resp.error.to_s
+                }
+              end
+
+              failed.empty? ? {} : { failed_commands: failed }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/command/api/commands/params_validator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      module Commands
+        # Validates the structure of command parameter hashes before deserialization.
+        # Ensures each command hash contains the required keys.
+        class ParamsValidator
+          CommandParamsInvalid = Class.new(Yes::Core::Error)
+
+          REQUIRED_KEYS = %i[command data context subject].freeze
+
+          class << self
+            # Validates command params.
+            #
+            # @param params [Array<Hash>] Array of command params
+            # @raise [CommandParamsInvalid] if params are invalid
+            # @return [void]
+            def call(params)
+              invalid = []
+              raise CommandParamsInvalid, 'Commands must be an array' unless params.is_a? Array
+
+              params.each do |command|
+                missing_keys = missing_keys?(command)
+                next unless missing_keys.any?
+
+                invalid << {
+                  command:,
+                  error: missing_keys_message(missing_keys)
+                }
+              end
+
+              raise CommandParamsInvalid.new(required_keys_message, extra: invalid) if invalid.any?
+            end
+
+            private
+
+            # @return [String] general error message for missing keys
+            def required_keys_message
+              "A command must have the following keys: #{REQUIRED_KEYS.join(', ')}"
+            end
+
+            # Returns the missing keys of the given command params, if any.
+            #
+            # @param command [Hash] command params
+            # @return [Array<Symbol>] missing keys
+            def missing_keys?(command)
+              REQUIRED_KEYS.reject { |s| command.key? s }
+            end
+
+            # @param missing_keys [Array<Symbol>] missing keys
+            # @return [String] error message for missing keys
+            def missing_keys_message(missing_keys)
+              "Missing keys: #{missing_keys.sort.join(', ')}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yes/command/api/engine.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      class Engine < ::Rails::Engine
+        isolate_namespace Yes::Command::Api
+        config.generators.api_only = true
+
+        config.generators do |g|
+          g.test_framework :rspec
+        end
+      end
+    end
+  end
+end

data/lib/yes/command/api/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Yes
+  module Command
+    module Api
+      VERSION = '1.0.0'
+    end
+  end
+end

data/lib/yes/command/api.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'yes/command/api/version'
+require 'yes/command/api/engine'
+require 'yes/core'
+require 'yes/command/api/commands/params_validator'
+require 'yes/command/api/commands/deserializer'
+require 'yes/command/api/commands/batch_authorizer'
+require 'yes/command/api/commands/batch_validator'
+require 'yes/command/api/commands/notifiers/action_cable'
+require 'yes/command/api/commands/notifiers/message_bus'
+
+module Yes
+  module Command
+    module Api
+    end
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: yes-command-api
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Nico Ritsche
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: message_bus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  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: yes-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Command API for the Yes event sourcing framework
+email:
+- nico.ritsche@yousty.ch
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/yes/command/api/application_controller.rb
+- app/controllers/yes/command/api/v1/commands_controller.rb
+- config/initializers/message_bus_filters.rb
+- config/routes.rb
+- lib/yes/command/api.rb
+- lib/yes/command/api/commands/batch_authorizer.rb
+- lib/yes/command/api/commands/batch_validator.rb
+- lib/yes/command/api/commands/deserializer.rb
+- lib/yes/command/api/commands/notifiers/action_cable.rb
+- lib/yes/command/api/commands/notifiers/message_bus.rb
+- lib/yes/command/api/commands/params_validator.rb
+- lib/yes/command/api/engine.rb
+- lib/yes/command/api/version.rb
+homepage: https://github.com/yousty/yes
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yousty/yes
+  source_code_uri: https://github.com/yousty/yes/tree/main/yes-command-api
+  changelog_uri: https://github.com/yousty/yes/blob/main/yes-command-api/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Command API for the Yes event sourcing framework
+test_files: []