overseer-testing-control-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a8a82dda4e7a0fd6d97c395b6639d49da084140ef72f072ed1c713189bc02207
+  data.tar.gz: 5e3e0951f138eee9ab614e1656abae3e6314594ffd01790264dd581c1662e948
+SHA512:
+  metadata.gz: 3a39c6a9bb3e5044c286ce1266e671bbf84d6c303bc812162a38fe1dcad45182e015e5b56ee033a9a9555ab854e3ec3251b4d8ed677a4b96612d53b487da7425
+  data.tar.gz: 482c65e907157763aafba1763a741b5d3d7f374af3f06186b890376c8f2f1c121ebec9a10cdaaa93d14f965d75eab4e111d843fde0c1da2d80aadfc7d20d4003

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright 2026 Olistik
+
+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,81 @@
+# Overseer testing-control Rails helper
+
+An optional Rails adapter for [Overseer testing protocol](https://source.olisti.co/overseer/testing-protocol)
+v3. The protocol owns schemas, wire conventions and HTTP conformance. This gem
+owns Rails routing, safe JSON responses, correlation and bounded memory stores.
+It works with frontend tests, curl and CI without Overseer Studio.
+
+For a checkout before a published release, the repository includes an exact
+protocol package snapshot under `vendor/`. Applications should pin reviewed
+package snapshots or released versions in their test-only bundle:
+
+```ruby
+group :test do
+  gem 'overseer-testing-protocol', path: 'vendor/gems/overseer-testing-protocol', require: false
+  gem 'overseer-testing-control-rails', path: 'vendor/gems/overseer-testing-control-rails',
+      require: 'overseer/testing_control/rails'
+end
+```
+
+Mount `Overseer::TestingControl::Rails::Engine` at `/v1/testing` only in test.
+Configure it in a test-only initializer:
+
+```ruby
+Overseer::TestingControl::Rails.configure do |config|
+  config.identity(application: 'my-api', source: -> { ENV.fetch('TEST_SOURCE') },
+                  environment: -> { ENV.fetch('TEST_RUNTIME_ID') })
+  config.reset(strategy: 'runtime-restart')
+  config.register_state(id: 'open-item', version: '1', title: 'Open synthetic item',
+                        idempotency: 'required', input_schema: OPEN_ITEM_INPUT,
+                        output_schema: OPEN_ITEM_OUTPUT, handler: Testing::OpenItem.method(:call))
+end
+```
+
+The adapter fails closed unless Rails is in `test`,
+`OVERSEER_TESTING_CONTROL_ENABLED=true`, and configured identity providers are
+valid. The host must additionally verify its isolation, database identity,
+synthetic data and credential policy. The helper cannot establish network
+containment or safely identify a database on its own.
+
+Register probes with input/output schemas and a read-only `handler` callable
+receiving `(input, context)`. Register sinks with effect kinds, outcomes,
+`query_input_schema`, `record_schema` and a `query_matcher` receiving
+`(payload, input)`. A matcher must return true for each record to retain.
+Non-empty query input without a matcher is rejected rather than ignored.
+Matchers and probe handlers must have no side effects.
+
+At a product-owned fake boundary, call
+`Overseer::TestingControl::Rails.capture_effect(capability:, version:,
+effect_kind:, summary:, payload:, outcome:)`. Supply only sanitized fields
+allowed by the registered schema. The helper records the current public
+request's run and correlation; step IDs are optional. Records are partitioned
+by run and queries do not consume them. Storage is bounded and fails on
+exhaustion. It does not silently discard records.
+
+Internal spies are product-owned bounded event stores exposed through probes.
+There is no arbitrary method interception, model inspection or `/spies` route.
+Product semantics and safe fields remain in the application.
+
+This implementation supports **one process**, with synchronous request effects.
+Its middleware serializes active public and control requests so reset cannot
+race them. Independent test suites need independent runtimes. Worker processes,
+streaming effects and automatic Active Job/Sidekiq correlation propagation are
+not implemented. Do not advertise worker completion using a pre-enqueue record.
+
+For an in-process reset, `config.reset(strategy: 'in-process', handler: ...)`
+requires a handler returning exactly `true` after all product state is reset.
+False, nil, a failure object or an exception cannot report success; helper stores
+are retained on failure. A successful reset clears observations and idempotency.
+The product must own file, job, cache, database and external fake cleanup.
+
+```sh
+bundle install
+bundle exec rake test
+gem build overseer-testing-control-rails.gemspec
+```
+
+Run the protocol package's HTTP conformance command against a disposable host
+application to check the complete adapter. The package has no Studio,
+container orchestration or product persistence dependency.
+
+Made with ❤️ by [olistik](https://olisti.co)

data/app/controllers/overseer/testing_control/rails/application_controller.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+module Overseer
+  module TestingControl
+    module Rails
+      class ProtocolFailure < StandardError
+        attr_reader :status, :code, :title, :detail, :pointer, :retryable
+
+        def initialize(status:, code:, title:, detail:, pointer: nil, retryable: false)
+          @status = status
+          @code = code
+          @title = title
+          @detail = detail
+          @pointer = pointer
+          @retryable = retryable
+          super(detail)
+        end
+      end
+
+      class ApplicationController < ::ActionController::API
+        before_action :require_activation!
+        before_action :prepare_identity!
+
+        rescue_from StandardError, with: :render_internal_error
+        rescue_from ConfigurationError, with: :render_configuration_error
+        rescue_from StoreLimitExceeded, with: :render_store_limit
+        rescue_from IdempotencyConflict, with: :render_idempotency_conflict
+        rescue_from JSON::ParserError, with: :render_invalid_json
+        rescue_from ProtocolFailure, with: :render_protocol_failure
+
+        private
+
+        def configuration
+          Overseer::TestingControl::Rails.configuration.finalize!
+        end
+
+        def require_activation!
+          head :not_found unless Overseer::TestingControl::Rails.active?
+        end
+
+        def prepare_identity!
+          version = request.headers[ProtocolV3::HEADERS.fetch(:version)]
+          if version.nil?
+            raise ProtocolFailure.new(
+              status: :bad_request,
+              code: 'invalid-request',
+              title: 'Protocol version required',
+              detail: 'The testing-control protocol version header is required.'
+            )
+          end
+          unless version == ProtocolV3::VERSION
+            raise ProtocolFailure.new(
+              status: :conflict,
+              code: 'protocol-version-unsupported',
+              title: 'Unsupported protocol version',
+              detail: 'The request must use testing-control protocol version 3.'
+            )
+          end
+
+          run_id = validate_header!(:run_id, required: true)
+          correlation_id = validate_header!(:correlation_id, required: true)
+          step_id = validate_header!(:step_id, required: false)
+          validate_header!(:idempotency_key, required: false)
+          @identity = { run_id:, correlation_id:, step_id: }
+          response.set_header(ProtocolV3::HEADERS.fetch(:version), ProtocolV3::VERSION)
+          response.set_header(ProtocolV3::HEADERS.fetch(:correlation_id), correlation_id)
+        end
+
+        def validate_header!(name, required:)
+          value = request.headers[ProtocolV3::HEADERS.fetch(name)]
+          return if !required && value.nil?
+
+          ProtocolV3.identifier!(value, label: ProtocolV3::HEADERS.fetch(name))
+        rescue ProtocolV3::ValidationError
+          raise ProtocolFailure.new(
+            status: :bad_request,
+            code: 'invalid-request',
+            title: 'Invalid request identity',
+            detail: 'A required testing-control identity header is missing or invalid.'
+          )
+        end
+
+        def request_document(kind)
+          unless request.media_type == 'application/json'
+            raise ProtocolFailure.new(
+              status: :bad_request,
+              code: 'invalid-request',
+              title: 'JSON request required',
+              detail: 'The testing-control request must use application/json.'
+            )
+          end
+          raw = bounded_body
+          if raw.bytesize > configuration.limits.fetch('maxRequestBytes')
+            raise ProtocolFailure.new(
+              status: :content_too_large,
+              code: 'payload-too-large',
+              title: 'Payload too large',
+              detail: 'The testing-control request exceeds the advertised byte limit.'
+            )
+          end
+
+          document = JSON.parse(raw)
+          validate_request_envelope!(kind, document)
+          validate_request_meta!(document.fetch('meta'))
+          document
+        end
+
+        def bounded_body
+          # Rack may already have buffered the body; otherwise read only limit + 1.
+          request.get_header('RAW_POST_DATA') ||
+            request.body&.read(configuration.limits.fetch('maxRequestBytes') + 1).to_s
+        end
+
+        def require_empty_body!
+          return if bounded_body.empty?
+
+          raise ProtocolFailure.new(
+            status: :bad_request,
+            code: 'invalid-request',
+            title: 'Request body is not allowed',
+            detail: 'This testing-control operation does not accept a request body.'
+          )
+        end
+
+        def validate_request_meta!(meta)
+          expected = ProtocolV3.meta(**@identity)
+          return if meta == expected
+
+          raise ProtocolFailure.new(
+            status: :bad_request,
+            code: 'invalid-request',
+            title: 'Request identity mismatch',
+            detail: 'The protocol envelope metadata must match the request headers.',
+            pointer: '/meta'
+          )
+        end
+
+        def handler_context
+          Configuration::HandlerContext.new(
+            **@identity,
+            idempotency_key: request.headers[ProtocolV3::HEADERS.fetch(:idempotency_key)]
+          )
+        end
+
+        def validate_capability_input!(schema, value, label:)
+          ProtocolV3.validate_value!(schema, value, label:)
+        rescue ProtocolV3::ValidationError => e
+          raise ProtocolFailure.new(
+            status: :unprocessable_entity,
+            code: 'schema-validation-failed',
+            title: 'Schema validation failed',
+            detail: e.message.byteslice(0, 1000)
+          )
+        end
+
+        def validate_capability_output!(schema, value, label:)
+          ProtocolV3.validate_value!(schema, value, label:)
+        rescue ProtocolV3::ValidationError
+          raise ProtocolFailure.new(
+            status: :internal_server_error,
+            code: 'internal-error',
+            title: 'Testing-control handler failed',
+            detail: 'A product handler returned an invalid bounded result.'
+          )
+        end
+
+        def render_data(kind, data, status: :ok)
+          document = ProtocolV3.envelope(data:, **@identity)
+          ProtocolV3.validate_document!(kind, document)
+          render_json(document, status:)
+        end
+
+        def render_json(document, status:)
+          encoded = JSON.generate(document)
+          if encoded.bytesize > configuration.limits.fetch('maxResponseBytes')
+            raise ProtocolFailure.new(
+              status: :unprocessable_entity,
+              code: 'limit-exceeded',
+              title: 'Response limit exceeded',
+              detail: 'The bounded testing-control response could not be produced.'
+            )
+          end
+          render body: encoded, content_type: 'application/json', status:
+        end
+
+        def capability_reference(data)
+          reference = data.fetch('capability')
+          [reference.fetch('id'), reference.fetch('version')]
+        end
+
+        def render_protocol_failure(error)
+          identity = safe_identity
+          document = ProtocolV3.error_envelope(
+            errors: [
+              {
+                'code' => error.code,
+                'title' => error.title,
+                'detail' => error.detail,
+                **(error.pointer ? { 'pointer' => error.pointer } : {}),
+                'retryable' => error.retryable
+              }
+            ],
+            **identity
+          )
+          response.set_header(ProtocolV3::HEADERS.fetch(:version), ProtocolV3::VERSION)
+          response.set_header(ProtocolV3::HEADERS.fetch(:correlation_id), identity.fetch(:correlation_id))
+          ProtocolV3.validate_document!(:error, document)
+          render body: JSON.generate(document), content_type: 'application/json', status: error.status
+        end
+
+        def safe_identity
+          return @identity if @identity
+
+          run_id = request.headers[ProtocolV3::HEADERS.fetch(:run_id)]
+          correlation_id = request.headers[ProtocolV3::HEADERS.fetch(:correlation_id)]
+          step_id = request.headers[ProtocolV3::HEADERS.fetch(:step_id)]
+          {
+            run_id: valid_identifier?(run_id) ? run_id : 'invalid-run',
+            correlation_id: valid_identifier?(correlation_id) ? correlation_id : 'invalid-correlation',
+            step_id: valid_identifier?(step_id) ? step_id : nil
+          }
+        end
+
+        def valid_identifier?(value)
+          value.is_a?(String) && value.match?(ProtocolV3::IDENTIFIER_PATTERN)
+        end
+
+        def render_invalid_json(_error)
+          render_protocol_failure(
+            ProtocolFailure.new(
+              status: :bad_request,
+              code: 'invalid-request',
+              title: 'Invalid JSON request',
+              detail: 'The testing-control request body is not valid JSON.'
+            )
+          )
+        end
+
+        def render_idempotency_conflict(_error)
+          render_protocol_failure(
+            ProtocolFailure.new(
+              status: :bad_request,
+              code: 'invalid-request',
+              title: 'Idempotency conflict',
+              detail: 'The idempotency key was reused with different input.'
+            )
+          )
+        end
+
+        def render_store_limit(_error)
+          render_protocol_failure(
+            ProtocolFailure.new(
+              status: :unprocessable_entity,
+              code: 'limit-exceeded',
+              title: 'Bounded storage limit reached',
+              detail: 'The adapter storage limit was reached; reset or restart the isolated runtime.',
+              retryable: true
+            )
+          )
+        end
+
+        def render_configuration_error(_error)
+          render_protocol_failure(
+            ProtocolFailure.new(
+              status: :service_unavailable,
+              code: 'runtime-unavailable',
+              title: 'Testing runtime unavailable',
+              detail: 'The testing-control adapter configuration is unavailable.'
+            )
+          )
+        end
+
+        def render_internal_error(error)
+          ::Rails.logger.error("Overseer Rails testing-control adapter request failed (#{error.class.name})")
+          render_protocol_failure(
+            ProtocolFailure.new(
+              status: :internal_server_error,
+              code: 'internal-error',
+              title: 'Testing-control request failed',
+              detail: 'The isolated testing-control request could not be completed.'
+            )
+          )
+        end
+
+        def validate_request_envelope!(kind, document)
+          ProtocolV3.validate_document!(kind, document)
+        rescue ProtocolV3::ValidationError
+          raise ProtocolFailure.new(
+            status: :bad_request,
+            code: 'invalid-request',
+            title: 'Invalid request envelope',
+            detail: 'The testing-control request does not match the closed protocol v3 envelope.'
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/overseer/testing_control/rails/capabilities_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Overseer
+  module TestingControl
+    module Rails
+      class CapabilitiesController < ApplicationController
+        def show
+          require_empty_body!
+          render_data(:capabilities, configuration.capabilities_data)
+        end
+      end
+    end
+  end
+end

data/app/controllers/overseer/testing_control/rails/probes_controller.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Overseer
+  module TestingControl
+    module Rails
+      class ProbesController < ApplicationController
+        def create
+          document = request_document(:probe_request)
+          data = document.fetch('data')
+          id, version = capability_reference(data)
+          probe = find_probe(id, version)
+          input = data.fetch('input')
+          validate_capability_input!(probe.input_schema, input, label: "probe #{id}@#{version} input")
+          projection = ProtocolV3.stringify(probe.handler.call(input, handler_context))
+          validate_capability_output!(probe.output_schema, projection, label: "probe #{id}@#{version} output")
+          render_data(
+            :probe_response,
+            {
+              'capability' => { 'id' => id, 'version' => version },
+              'observedAt' => ProtocolV3.timestamp,
+              'projection' => projection
+            }
+          )
+        end
+
+        private
+
+        def find_probe(id, version)
+          configuration.probe!(id, version)
+        rescue ProtocolV3::ValidationError
+          raise ProtocolFailure.new(
+            status: :not_found,
+            code: 'capability-not-found',
+            title: 'Probe capability not found',
+            detail: 'The requested probe capability is not registered.'
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/overseer/testing_control/rails/resets_controller.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Overseer
+  module TestingControl
+    module Rails
+      class ResetsController < ApplicationController
+        def update
+          require_empty_body!
+          if configuration.reset_strategy == 'runtime-restart'
+            raise ProtocolFailure.new(
+              status: :conflict,
+              code: 'reset-requires-restart',
+              title: 'Runtime restart required',
+              detail: 'The test runner must recreate this isolated runtime to reset it.',
+              retryable: true
+            )
+          end
+
+          unless configuration.reset_handler.call == true
+            raise ConfigurationError, 'The product reset handler did not confirm a successful reset'
+          end
+
+          configuration.clear_stores!
+          render_data(
+            :reset,
+            {
+              'resetAt' => ProtocolV3.timestamp,
+              'strategy' => 'in-process',
+              'sinksCleared' => true
+            }
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/overseer/testing_control/rails/sinks_controller.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Overseer
+  module TestingControl
+    module Rails
+      class SinksController < ApplicationController
+        def query
+          document = request_document(:sink_query_request)
+          data = document.fetch('data')
+          id, version = capability_reference(data)
+          sink = find_sink(id, version)
+          validate_capability_input!(
+            sink.query_input_schema,
+            data.fetch('input'),
+            label: "sink #{id}@#{version} query input"
+          )
+          limit = data.fetch('limit', configuration.limits.fetch('maxSinkRecordsPerQuery'))
+          if limit > configuration.limits.fetch('maxSinkRecordsPerQuery')
+            raise ProtocolFailure.new(
+              status: :unprocessable_entity,
+              code: 'limit-exceeded',
+              title: 'Sink query limit exceeded',
+              detail: 'The sink query limit exceeds the advertised maximum.'
+            )
+          end
+          records, cursor = query_store(
+            capability: id,
+            version:,
+            run_id: @identity.fetch(:run_id),
+            input: data.fetch('input'),
+            filter: data.fetch('filter'),
+            cursor: data['cursor'],
+            limit:
+          )
+          render_data(
+            :sink_query_response,
+            {
+              'capability' => { 'id' => id, 'version' => version },
+              'records' => records,
+              **(cursor ? { 'nextCursor' => cursor } : {})
+            }
+          )
+        end
+
+        private
+
+        def find_sink(id, version)
+          configuration.sink!(id, version)
+        rescue ProtocolV3::ValidationError
+          raise ProtocolFailure.new(
+            status: :not_found,
+            code: 'capability-not-found',
+            title: 'Sink capability not found',
+            detail: 'The requested sink capability is not registered.'
+          )
+        end
+
+        def query_store(**)
+          configuration.sink_store.query(**)
+        rescue ProtocolV3::ValidationError
+          raise ProtocolFailure.new(
+            status: :bad_request,
+            code: 'invalid-request',
+            title: 'Invalid sink query',
+            detail: 'The fake-sink cursor or filter is invalid.'
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/overseer/testing_control/rails/states_controller.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Overseer
+  module TestingControl
+    module Rails
+      class StatesController < ApplicationController
+        def create
+          document = request_document(:state_request)
+          data = document.fetch('data')
+          id, version = capability_reference(data)
+          state = find_state(id, version)
+          input = data.fetch('input')
+          validate_capability_input!(state.input_schema, input, label: "state #{id}@#{version} input")
+          idempotency_key = validated_idempotency_key(state)
+          result = execute_state(state, input, idempotency_key)
+          render_data(
+            :state_response,
+            {
+              'capability' => { 'id' => id, 'version' => version },
+              'identifiers' => result.fetch('identifiers'),
+              'output' => result.fetch('output')
+            }
+          )
+        end
+
+        private
+
+        def find_state(id, version)
+          configuration.state!(id, version)
+        rescue ProtocolV3::ValidationError
+          raise ProtocolFailure.new(
+            status: :not_found,
+            code: 'capability-not-found',
+            title: 'State capability not found',
+            detail: 'The requested state capability is not registered.'
+          )
+        end
+
+        def validated_idempotency_key(state)
+          key = request.headers[ProtocolV3::HEADERS.fetch(:idempotency_key)]
+          if state.idempotency == 'required' && key.nil?
+            raise ProtocolFailure.new(
+              status: :bad_request,
+              code: 'invalid-request',
+              title: 'Idempotency key required',
+              detail: 'The requested state requires an Overseer idempotency key.'
+            )
+          end
+          return if key.nil?
+
+          ProtocolV3.identifier!(key, label: 'idempotency key')
+        rescue ProtocolV3::ValidationError
+          raise ProtocolFailure.new(
+            status: :bad_request,
+            code: 'invalid-request',
+            title: 'Invalid idempotency key',
+            detail: 'The Overseer idempotency key must be a valid opaque identifier.'
+          )
+        end
+
+        def execute_state(state, input, idempotency_key)
+          operation = lambda do
+            raw = state.handler.call(input, handler_context)
+            result = ProtocolV3.stringify(raw)
+            validate_state_result!(state, result)
+            result
+          end
+          return operation.call if state.idempotency == 'none' || idempotency_key.nil?
+
+          configuration.idempotency_store.fetch_or_store(
+            key: [@identity.fetch(:run_id), state.id, state.version, idempotency_key].freeze,
+            digest: Digest::SHA256.hexdigest(::Overseer::TestingControl::Discovery.canonical_json(input)),
+            &operation
+          )
+        end
+
+        def validate_state_result!(state, result)
+          unless result.is_a?(Hash) && result['identifiers'].is_a?(Hash) && !result['identifiers'].empty? &&
+                 result['output'].is_a?(Hash)
+            raise ProtocolV3::ValidationError, 'state handler must return identifiers and output objects'
+          end
+
+          validate_capability_output!(state.output_schema, result.fetch('output'), label: 'state output')
+        end
+      end
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+Overseer::TestingControl::Rails::Engine.routes.draw do
+  get '/capabilities', to: 'capabilities#show'
+  put '/reset', to: 'resets#update'
+  post '/states', to: 'states#create'
+  post '/probes', to: 'probes#create'
+  post '/sinks/query', to: 'sinks#query'
+end