overseer-testing-control-rails 0.1.0

data/lib/overseer/testing_control/rails/configuration.rb

@@ -0,0 +1,370 @@
+# frozen_string_literal: true
+
+require 'monitor'
+
+module Overseer
+  module TestingControl
+    module Rails
+      class ConfigurationError < StandardError; end
+
+      class Configuration
+        State = Data.define(:id, :version, :title, :description, :idempotency, :input_schema, :output_schema, :handler)
+        Probe = Data.define(:id, :version, :title, :description, :input_schema, :output_schema, :handler)
+        Sink = Data.define(
+          :id, :version, :title, :description, :effect_kinds, :outcomes, :query_input_schema,
+          :record_schema, :query_matcher
+        )
+        HandlerContext = Data.define(:run_id, :correlation_id, :step_id, :idempotency_key)
+        FEATURES = %w[
+          correlation-propagation
+          deterministic-replay
+          reset
+          schema-validation
+          sink-clearing
+        ].freeze
+        RESET_STRATEGIES = %w[in-process runtime-restart].freeze
+        IDEMPOTENCY = %w[required supported none].freeze
+        EFFECT_KINDS = %w[email sms webhook document-delivery integration-command custom].freeze
+        DEFAULT_SOURCE_PROVIDER = -> { ENV.fetch('OVERSEER_TESTING_CONTROL_APPLICATION_VERSION', '') }
+        DEFAULT_ENVIRONMENT_PROVIDER = -> { ENV.fetch('OVERSEER_TESTING_CONTROL_ENVIRONMENT_ID', '') }
+        DEFAULT_LIMITS = {
+          'maxRequestBytes' => 65_536,
+          'maxResponseBytes' => 262_144,
+          'maxSchemaBytes' => 65_536,
+          'maxSinkRecordsPerQuery' => 25,
+          'maxSinkRecordBytes' => 16_384
+        }.freeze
+        LIMIT_RANGES = {
+          'maxRequestBytes' => (1_024..16_777_216),
+          'maxResponseBytes' => (1_024..16_777_216),
+          'maxSchemaBytes' => (1_024..1_048_576),
+          'maxSinkRecordsPerQuery' => (1..1_000),
+          'maxSinkRecordBytes' => (256..1_048_576)
+        }.freeze
+
+        attr_reader :states, :probes, :sinks, :idempotency_store, :sink_store, :reset_strategy,
+                    :reset_handler, :max_sink_records, :limits, :request_lock
+
+        def initialize
+          @request_lock = Monitor.new
+          @identity = {
+            application: nil,
+            source: DEFAULT_SOURCE_PROVIDER,
+            environment: DEFAULT_ENVIRONMENT_PROVIDER,
+            kind: 'test',
+            isolated: true
+          }
+          @reset_strategy = 'runtime-restart'
+          @reset_handler = nil
+          @states = []
+          @probes = []
+          @sinks = []
+          @limits = DEFAULT_LIMITS
+          @idempotency_limit = 128
+          @max_sink_records = 250
+          rebuild_stores!
+          @finalized = false
+        end
+
+        def identity(
+          application:,
+          source: DEFAULT_SOURCE_PROVIDER,
+          environment: DEFAULT_ENVIRONMENT_PROVIDER,
+          kind: 'test',
+          isolated: true
+        )
+          mutable!
+          @identity = { application:, source:, environment:, kind:, isolated: }
+        end
+
+        def reset(strategy:, handler: nil)
+          mutable!
+          @reset_strategy = strategy
+          @reset_handler = handler
+        end
+
+        def bounds(
+          max_request_bytes: limits.fetch('maxRequestBytes'),
+          max_response_bytes: limits.fetch('maxResponseBytes'),
+          max_schema_bytes: limits.fetch('maxSchemaBytes'),
+          max_sink_records_per_query: limits.fetch('maxSinkRecordsPerQuery'),
+          max_sink_record_bytes: limits.fetch('maxSinkRecordBytes'),
+          idempotency_entries: @idempotency_limit,
+          sink_records: max_sink_records
+        )
+          mutable!
+          candidate = {
+            'maxRequestBytes' => max_request_bytes,
+            'maxResponseBytes' => max_response_bytes,
+            'maxSchemaBytes' => max_schema_bytes,
+            'maxSinkRecordsPerQuery' => max_sink_records_per_query,
+            'maxSinkRecordBytes' => max_sink_record_bytes
+          }
+          validate_limits!(candidate, idempotency_entries:, sink_records:)
+          @limits = candidate.freeze
+          @idempotency_limit = idempotency_entries
+          @max_sink_records = sink_records
+          rebuild_stores!
+        end
+
+        def register_state(id:, version:, title:, idempotency:, input_schema:, output_schema:, handler:,
+                           description: nil)
+          mutable!
+          @states << State.new(
+            id:, version:, title:, description:, idempotency:, input_schema:, output_schema:, handler:
+          )
+        end
+
+        def register_probe(id:, version:, title:, input_schema:, output_schema:, handler:, description: nil)
+          mutable!
+          @probes << Probe.new(id:, version:, title:, description:, input_schema:, output_schema:, handler:)
+        end
+
+        def register_sink(
+          id:, version:, title:, effect_kinds:, outcomes:, query_input_schema:, record_schema:,
+          description: nil, query_matcher: nil
+        )
+          mutable!
+          @sinks << Sink.new(
+            id:, version:, title:, description:, effect_kinds:, outcomes:, query_input_schema:,
+            record_schema:, query_matcher:
+          )
+        end
+
+        def finalize!
+          return self if @finalized
+
+          validate!
+          @states.freeze
+          @probes.freeze
+          @sinks.freeze
+          @finalized = true
+          self
+        rescue ProtocolV3::ValidationError => e
+          raise ConfigurationError, e.message
+        end
+
+        def runtime_identity_valid?
+          validate_identity!
+          true
+        rescue ConfigurationError, ProtocolV3::ValidationError, KeyError, TypeError
+          false
+        end
+
+        def application_id
+          resolve_identity(:application)
+        end
+
+        def environment_id
+          resolve_identity(:environment)
+        end
+
+        def application_version
+          resolve_identity(:source)
+        end
+
+        def environment_kind
+          resolve_identity(:kind)
+        end
+
+        def environment_isolated
+          resolve_identity(:isolated)
+        end
+
+        def capabilities_data
+          finalize!
+          {
+            'application' => { 'id' => application_id, 'version' => application_version },
+            'environment' => {
+              'id' => environment_id,
+              'kind' => environment_kind,
+              'isolated' => environment_isolated
+            },
+            'reset' => { 'strategy' => reset_strategy, 'clearsSinks' => true },
+            'features' => FEATURES,
+            'limits' => limits,
+            'safety' => {
+              'syntheticDataRequired' => true,
+              'realCredentialsAllowed' => false,
+              'secretPersistenceAllowed' => false,
+              'externalNetwork' => 'blocked'
+            },
+            'states' => states.map { |state| state_document(state) },
+            'probes' => probes.map { |probe| probe_document(probe) },
+            'sinks' => sinks.map { |sink| sink_document(sink) }
+          }
+        end
+
+        def state!(id, version)
+          states.find { |item| item.id == id && item.version == version } ||
+            raise(ProtocolV3::ValidationError, "state capability #{id}@#{version} is unavailable")
+        end
+
+        def probe!(id, version)
+          probes.find { |item| item.id == id && item.version == version } ||
+            raise(ProtocolV3::ValidationError, "probe capability #{id}@#{version} is unavailable")
+        end
+
+        def sink!(id, version)
+          sinks.find { |item| item.id == id && item.version == version } ||
+            raise(ProtocolV3::ValidationError, "sink capability #{id}@#{version} is unavailable")
+        end
+
+        def clear_stores!
+          idempotency_store.clear
+          sink_store.clear
+        end
+
+        private
+
+        def mutable!
+          return unless @finalized
+
+          raise ConfigurationError,
+                'Overseer Rails testing-control adapter configuration is already active'
+        end
+
+        def validate!
+          validate_identity!
+          raise ConfigurationError, 'reset strategy is invalid' unless RESET_STRATEGIES.include?(reset_strategy)
+          raise ConfigurationError, 'in-process reset requires a reset handler' if
+            reset_strategy == 'in-process' && !reset_handler.respond_to?(:call)
+
+          validate_limits!(limits, idempotency_entries: @idempotency_limit, sink_records: max_sink_records)
+
+          validate_family!(states, 'state') { |item| validate_state!(item) }
+          validate_family!(probes, 'probe') { |item| validate_probe!(item) }
+          validate_family!(sinks, 'sink') { |item| validate_sink!(item) }
+        end
+
+        def validate_family!(items, kind)
+          seen = {}
+          items.each do |item|
+            key = "#{item.id}@#{item.version}"
+            raise ConfigurationError, "duplicate #{kind} capability #{key}" if seen[key]
+
+            seen[key] = true
+            validate_common!(item, kind)
+            yield(item)
+          end
+        end
+
+        def validate_common!(item, kind)
+          ProtocolV3.capability_id!(item.id, label: "#{kind} ID")
+          ProtocolV3.capability_version!(item.version, label: "#{kind} version")
+          raise ConfigurationError, "#{kind} title is invalid" unless
+            item.title.is_a?(String) && item.title.bytesize.between?(1, 160)
+          raise ConfigurationError, "#{kind} description is invalid" if
+            item.description && (!item.description.is_a?(String) || item.description.bytesize > 1000)
+        end
+
+        def validate_state!(state)
+          unless IDEMPOTENCY.include?(state.idempotency)
+            raise ConfigurationError,
+                  'state idempotency declaration is invalid'
+          end
+          raise ConfigurationError, 'state handler must be callable' unless state.handler.respond_to?(:call)
+
+          validate_schema_pair!(state, :input_schema, :output_schema, label: "state #{state.id}@#{state.version}")
+        end
+
+        def validate_probe!(probe)
+          raise ConfigurationError, 'probe handler must be callable' unless probe.handler.respond_to?(:call)
+
+          validate_schema_pair!(probe, :input_schema, :output_schema, label: "probe #{probe.id}@#{probe.version}")
+        end
+
+        def validate_sink!(sink)
+          valid_kinds = sink.effect_kinds.is_a?(Array) && !sink.effect_kinds.empty? &&
+                        sink.effect_kinds.uniq == sink.effect_kinds &&
+                        sink.effect_kinds.all? { |kind| EFFECT_KINDS.include?(kind) }
+          raise ConfigurationError, 'sink effect kinds are invalid' unless valid_kinds
+
+          valid_outcomes = sink.outcomes.is_a?(Array) && !sink.outcomes.empty? &&
+                           sink.outcomes.uniq == sink.outcomes
+          raise ConfigurationError, 'sink outcomes are invalid' unless valid_outcomes
+
+          sink.outcomes.each { |outcome| ProtocolV3.capability_id!(outcome, label: 'sink outcome') }
+          validate_schema_pair!(sink, :query_input_schema, :record_schema, label: "sink #{sink.id}@#{sink.version}")
+        end
+
+        def validate_schema_pair!(item, *names, label:)
+          names.each do |name|
+            ProtocolV3.validate_schema!(
+              item.public_send(name),
+              label: "#{label} #{name}",
+              max_bytes: limits.fetch('maxSchemaBytes')
+            )
+          end
+        end
+
+        def validate_identity!
+          ProtocolV3.capability_id!(application_id, label: 'application ID')
+          ProtocolV3.application_version!(application_version)
+          ProtocolV3.identifier!(environment_id, label: 'environment ID')
+          raise ConfigurationError, 'environment kind must be test' unless environment_kind == 'test'
+          raise ConfigurationError, 'environment isolation witness must be true' unless environment_isolated == true
+        end
+
+        def validate_limits!(candidate, idempotency_entries:, sink_records:)
+          LIMIT_RANGES.each do |name, range|
+            value = candidate.fetch(name)
+            raise ConfigurationError, "#{name} is outside the protocol v3 range" unless
+              value.is_a?(Integer) && range.cover?(value)
+          end
+          raise ConfigurationError, 'idempotency entry limit must be between 1 and 1000' unless
+            idempotency_entries.is_a?(Integer) && idempotency_entries.between?(1, 1_000)
+          raise ConfigurationError, 'fake-sink record limit must be between 1 and 1000' unless
+            sink_records.is_a?(Integer) && sink_records.between?(1, 1_000)
+        end
+
+        def resolve_identity(name)
+          value = @identity.fetch(name)
+          value.respond_to?(:call) ? value.call : value
+        end
+
+        def rebuild_stores!
+          @idempotency_store = IdempotencyStore.new(limit: @idempotency_limit)
+          @sink_store = SinkStore.new(self)
+        end
+
+        def state_document(state)
+          {
+            'id' => state.id,
+            'version' => state.version,
+            'title' => state.title,
+            **(state.description ? { 'description' => state.description } : {}),
+            'idempotency' => state.idempotency,
+            'inputSchema' => state.input_schema,
+            'outputSchema' => state.output_schema
+          }
+        end
+
+        def probe_document(probe)
+          {
+            'id' => probe.id,
+            'version' => probe.version,
+            'title' => probe.title,
+            **(probe.description ? { 'description' => probe.description } : {}),
+            'readOnly' => true,
+            'inputSchema' => probe.input_schema,
+            'outputSchema' => probe.output_schema
+          }
+        end
+
+        def sink_document(sink)
+          {
+            'id' => sink.id,
+            'version' => sink.version,
+            'title' => sink.title,
+            **(sink.description ? { 'description' => sink.description } : {}),
+            'effectKinds' => sink.effect_kinds,
+            'outcomes' => sink.outcomes,
+            'queryInputSchema' => sink.query_input_schema,
+            'recordSchema' => sink.record_schema
+          }
+        end
+      end
+    end
+  end
+end

data/lib/overseer/testing_control/rails/correlation_middleware.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Overseer
+  module TestingControl
+    module Rails
+      class CorrelationMiddleware
+        def initialize(app)
+          @app = app
+        end
+
+        def call(environment)
+          return @app.call(environment) unless Overseer::TestingControl::Rails.active?
+
+          # Memory stores belong to one process. Serialize its public and control
+          # requests so reset cannot race a mutation or capture in that process.
+          Overseer::TestingControl::Rails.configuration.request_lock.synchronize do
+            correlated_call(environment)
+          end
+        end
+
+        private
+
+        def correlated_call(environment)
+          context = context_from(environment)
+          RequestContext.with(context) do
+            status, headers, body = @app.call(environment)
+            headers[ProtocolV3::HEADERS.fetch(:correlation_id)] = context.correlation_id if context&.correlation_id
+            [status, headers, body]
+          end
+        end
+
+        def context_from(environment)
+          correlation_id = header(environment, :correlation_id)
+          return unless valid_identifier?(correlation_id)
+
+          run_id = header(environment, :run_id)
+          step_id = header(environment, :step_id)
+          RequestContext::Context.new(
+            run_id: valid_identifier?(run_id) ? run_id : nil,
+            correlation_id:,
+            step_id: valid_identifier?(step_id) ? step_id : nil
+          )
+        end
+
+        def header(environment, name)
+          rack_name = "HTTP_#{ProtocolV3::HEADERS.fetch(name).upcase.tr('-', '_')}"
+          environment[rack_name]
+        end
+
+        def valid_identifier?(value)
+          value.is_a?(String) && value.match?(ProtocolV3::IDENTIFIER_PATTERN)
+        end
+      end
+    end
+  end
+end

data/lib/overseer/testing_control/rails/engine.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'action_controller/railtie'
+
+module Overseer
+  module TestingControl
+    module Rails
+      class Engine < ::Rails::Engine
+        isolate_namespace Overseer::TestingControl::Rails
+
+        initializer 'overseer-testing-control-rails.correlation-middleware' do |application|
+          application.middleware.insert_before(0, CorrelationMiddleware)
+        end
+      end
+    end
+  end
+end

data/lib/overseer/testing_control/rails/protocol_v3.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'overseer/testing_control/protocol_v3'
+
+module Overseer
+  module TestingControl
+    module Rails
+      ProtocolV3 = ::Overseer::TestingControl::ProtocolV3
+    end
+  end
+end

data/lib/overseer/testing_control/rails/request_context.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Overseer
+  module TestingControl
+    module Rails
+      module RequestContext
+        Context = Data.define(:run_id, :correlation_id, :step_id)
+        THREAD_KEY = :overseer_testing_control_rails_request_context
+
+        module_function
+
+        def current
+          Thread.current[THREAD_KEY]
+        end
+
+        def with(context)
+          previous = current
+          Thread.current[THREAD_KEY] = context
+          yield
+        ensure
+          Thread.current[THREAD_KEY] = previous
+        end
+      end
+    end
+  end
+end

data/lib/overseer/testing_control/rails/stores.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'securerandom'
+
+module Overseer
+  module TestingControl
+    module Rails
+      class CaptureError < StandardError; end
+      class IdempotencyConflict < StandardError; end
+      class StoreLimitExceeded < StandardError; end
+
+      class IdempotencyStore
+        Entry = Data.define(:digest, :value)
+
+        def initialize(limit:)
+          @limit = limit
+          @entries = {}
+          @mutex = Mutex.new
+        end
+
+        def fetch_or_store(key:, digest:)
+          @mutex.synchronize do
+            existing = @entries[key]
+            if existing
+              raise IdempotencyConflict, 'Idempotency key was reused with different input' unless
+                existing.digest == digest
+
+              return deep_copy(existing.value)
+            end
+            raise StoreLimitExceeded, 'Idempotency storage reached its bounded limit' if @entries.length >= @limit
+
+            value = yield
+            @entries[key] = Entry.new(digest:, value: deep_copy(value))
+            deep_copy(value)
+          end
+        end
+
+        def clear
+          @mutex.synchronize { @entries.clear }
+        end
+
+        private
+
+        def deep_copy(value)
+          JSON.parse(JSON.generate(value))
+        end
+      end
+
+      class SinkStore
+        def initialize(configuration)
+          @configuration = configuration
+          @records = []
+          @mutex = Mutex.new
+        end
+
+        def capture(capability:, version:, effect_kind:, summary:, payload:, context:, outcome: nil, metadata: nil)
+          definition = @configuration.sink!(capability, version)
+          ProtocolV3.identifier!(context.run_id, label: 'capture run ID')
+          ProtocolV3.identifier!(context.correlation_id, label: 'capture correlation ID')
+          ProtocolV3.identifier!(context.step_id, label: 'capture step ID') if context.step_id
+          validate_capture!(definition, effect_kind:, outcome:, summary:, payload:, metadata:)
+          record = {
+            'id' => "effect-#{SecureRandom.hex(12)}",
+            'capability' => { 'id' => capability, 'version' => version },
+            'effectKind' => effect_kind,
+            **(outcome ? { 'outcome' => outcome } : {}),
+            'correlationId' => context.correlation_id,
+            **(context.step_id ? { 'stepId' => context.step_id } : {}),
+            'capturedAt' => ProtocolV3.timestamp,
+            'summary' => summary,
+            **(metadata ? { 'metadata' => ProtocolV3.stringify(metadata) } : {}),
+            'payload' => ProtocolV3.stringify(payload)
+          }
+          validate_record_size!(record)
+          @mutex.synchronize do
+            raise StoreLimitExceeded, 'Fake-sink storage reached its bounded limit' if
+              @records.length >= @configuration.max_sink_records
+
+            @records << { run_id: context.run_id, record: deep_copy(record) }
+          end
+          deep_copy(record)
+        rescue ProtocolV3::ValidationError => e
+          raise CaptureError, e.message
+        end
+
+        def query(capability:, version:, run_id:, input:, filter:, cursor:, limit:)
+          definition = @configuration.sink!(capability, version)
+          ProtocolV3.identifier!(run_id, label: 'sink query run ID')
+          ProtocolV3.validate_value!(definition.query_input_schema, input, label: 'sink query input')
+          if !input.empty? && !definition.query_matcher
+            raise ProtocolV3::ValidationError, 'non-empty sink input requires a product query matcher'
+          end
+
+          offset = cursor ? Integer(cursor, 10) : 0
+          raise ProtocolV3::ValidationError, 'sink cursor is outside the bounded result' if offset.negative?
+
+          matched = @mutex.synchronize do
+            selected = @records.filter_map do |entry|
+              next unless entry.fetch(:run_id) == run_id
+
+              record = entry.fetch(:record)
+              next unless matches_filter?(record, capability, version, filter)
+              next unless matches_input?(definition, record, input)
+
+              record
+            end
+            selected.map { |record| deep_copy(record) }
+          end
+          records = matched.slice(offset, limit) || []
+          next_offset = offset + records.length
+          [records, next_offset < matched.length ? next_offset.to_s : nil]
+        rescue ArgumentError
+          raise ProtocolV3::ValidationError, 'sink cursor is invalid'
+        end
+
+        def clear
+          @mutex.synchronize { @records.clear }
+        end
+
+        private
+
+        def matches_filter?(record, capability, version, filter)
+          record.dig('capability', 'id') == capability &&
+            record.dig('capability', 'version') == version &&
+            record['correlationId'] == filter.fetch('correlationId') &&
+            (!filter['stepId'] || record['stepId'] == filter['stepId']) &&
+            (!filter['effectKinds'] || filter['effectKinds'].include?(record['effectKind'])) &&
+            (!filter['capturedAfter'] || Time.iso8601(record['capturedAt']) > Time.iso8601(filter['capturedAfter']))
+        end
+
+        def matches_input?(definition, record, input)
+          !definition.query_matcher || definition.query_matcher.call(deep_copy(record.fetch('payload')),
+                                                                     deep_copy(input))
+        end
+
+        def validate_capture!(definition, effect_kind:, outcome:, summary:, payload:, metadata:)
+          raise ProtocolV3::ValidationError, 'fake effect kind is not registered for the sink' unless
+            definition.effect_kinds.include?(effect_kind)
+          raise ProtocolV3::ValidationError, 'fake effect outcome is not registered for the sink' if
+            outcome && !definition.outcomes.include?(outcome)
+          raise ProtocolV3::ValidationError, 'fake effect summary is invalid' unless
+            summary.is_a?(String) && summary.bytesize.between?(1, 500)
+          if metadata && !metadata.is_a?(Hash)
+            raise ProtocolV3::ValidationError,
+                  'fake effect metadata must be an object'
+          end
+
+          ProtocolV3.validate_value!(definition.record_schema, ProtocolV3.stringify(payload),
+                                     label: 'fake effect payload')
+        end
+
+        def validate_record_size!(record)
+          return if JSON.generate(record).bytesize <= @configuration.limits.fetch('maxSinkRecordBytes')
+
+          raise CaptureError, 'Fake effect record exceeds the bounded record size'
+        end
+
+        def deep_copy(value)
+          JSON.parse(JSON.generate(value))
+        end
+      end
+    end
+  end
+end

data/lib/overseer/testing_control/rails/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Overseer
+  module TestingControl
+    module Rails
+      VERSION = '0.1.0'
+    end
+  end
+end