smplkit 1.0.16 → 1.0.18

data/lib/smplkit/_generated/audit/spec/models/event_response_spec.rb

@@ -0,0 +1,36 @@
+=begin
+#smplkit Audit API
+
+#Append-only change-history substrate for smpl.* resources and customer-application events. ADR-047.
+
+The version of the OpenAPI document: 0.1.0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.22.0
+
+=end
+
+require 'spec_helper'
+require 'json'
+require 'date'
+
+# Unit tests for SmplkitGeneratedClient::Audit::EventResponse
+# Automatically generated by openapi-generator (https://openapi-generator.tech)
+# Please update as you see appropriate
+describe SmplkitGeneratedClient::Audit::EventResponse do
+  #let(:instance) { SmplkitGeneratedClient::Audit::EventResponse.new }
+
+  describe 'test an instance of EventResponse' do
+    it 'should create an instance of EventResponse' do
+      # uncomment below to test the instance creation
+      #expect(instance).to be_instance_of(SmplkitGeneratedClient::Audit::EventResponse)
+    end
+  end
+
+  describe 'test attribute "data"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+end

data/lib/smplkit/_generated/audit/spec/models/event_spec.rb

@@ -0,0 +1,96 @@
+=begin
+#smplkit Audit API
+
+#Append-only change-history substrate for smpl.* resources and customer-application events. ADR-047.
+
+The version of the OpenAPI document: 0.1.0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.22.0
+
+=end
+
+require 'spec_helper'
+require 'json'
+require 'date'
+
+# Unit tests for SmplkitGeneratedClient::Audit::Event
+# Automatically generated by openapi-generator (https://openapi-generator.tech)
+# Please update as you see appropriate
+describe SmplkitGeneratedClient::Audit::Event do
+  #let(:instance) { SmplkitGeneratedClient::Audit::Event.new }
+
+  describe 'test an instance of Event' do
+    it 'should create an instance of Event' do
+      # uncomment below to test the instance creation
+      #expect(instance).to be_instance_of(SmplkitGeneratedClient::Audit::Event)
+    end
+  end
+
+  describe 'test attribute "action"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "resource_type"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "resource_id"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "occurred_at"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "snapshot"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "data"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "created_at"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "actor_type"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "actor_id"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "actor_label"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "idempotency_key"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+end

data/lib/smplkit/_generated/audit/spec/models/usage_resource_spec.rb

@@ -0,0 +1,48 @@
+=begin
+#smplkit Audit API
+
+#Append-only change-history substrate for smpl.* resources and customer-application events. ADR-047.
+
+The version of the OpenAPI document: 0.1.0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.22.0
+
+=end
+
+require 'spec_helper'
+require 'json'
+require 'date'
+
+# Unit tests for SmplkitGeneratedClient::Audit::UsageResource
+# Automatically generated by openapi-generator (https://openapi-generator.tech)
+# Please update as you see appropriate
+describe SmplkitGeneratedClient::Audit::UsageResource do
+  #let(:instance) { SmplkitGeneratedClient::Audit::UsageResource.new }
+
+  describe 'test an instance of UsageResource' do
+    it 'should create an instance of UsageResource' do
+      # uncomment below to test the instance creation
+      #expect(instance).to be_instance_of(SmplkitGeneratedClient::Audit::UsageResource)
+    end
+  end
+
+  describe 'test attribute "id"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "type"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "attributes"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+end

data/lib/smplkit/_generated/audit/spec/models/usage_response_spec.rb

@@ -0,0 +1,36 @@
+=begin
+#smplkit Audit API
+
+#Append-only change-history substrate for smpl.* resources and customer-application events. ADR-047.
+
+The version of the OpenAPI document: 0.1.0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.22.0
+
+=end
+
+require 'spec_helper'
+require 'json'
+require 'date'
+
+# Unit tests for SmplkitGeneratedClient::Audit::UsageResponse
+# Automatically generated by openapi-generator (https://openapi-generator.tech)
+# Please update as you see appropriate
+describe SmplkitGeneratedClient::Audit::UsageResponse do
+  #let(:instance) { SmplkitGeneratedClient::Audit::UsageResponse.new }
+
+  describe 'test an instance of UsageResponse' do
+    it 'should create an instance of UsageResponse' do
+      # uncomment below to test the instance creation
+      #expect(instance).to be_instance_of(SmplkitGeneratedClient::Audit::UsageResponse)
+    end
+  end
+
+  describe 'test attribute "data"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+end

data/lib/smplkit/_generated/audit/spec/spec_helper.rb

@@ -0,0 +1,111 @@
+=begin
+#smplkit Audit API
+
+#Append-only change-history substrate for smpl.* resources and customer-application events. ADR-047.
+
+The version of the OpenAPI document: 0.1.0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.22.0
+
+=end
+
+# load the gem
+require 'smplkit_audit_client'
+
+# The following  was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause
+# this file to always be loaded, without a need to explicitly require it in any
+# files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# The `.rspec` file also contains a few flags that are not defaults but that
+# users commonly want.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+=begin
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+
+  # Allows RSpec to persist some state between runs in order to support
+  # the `--only-failures` and `--next-failure` CLI options. We recommend
+  # you configure your source control system to ignore this file.
+  config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  #   - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
+  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+=end
+end

data/lib/smplkit/audit/buffer.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Audit
+    # Bounded in-memory queue + worker thread for fire-and-forget audit
+    # emits (ADR-047 §2.6).
+    #
+    # +#enqueue+ returns immediately. The worker drains on either a
+    # periodic tick or once depth crosses the high-water mark, retries
+    # transient failures with exponential backoff, drops permanent 4xx
+    # (other than 429), and evicts the oldest item under sustained
+    # back-pressure.
+    class EventBuffer
+      MAX_BUFFER_SIZE = 1000
+      WATERMARK = 50
+      FLUSH_INTERVAL = 5.0
+      MAX_ATTEMPTS = 5
+      INITIAL_BACKOFF = 0.25
+      MAX_BACKOFF = 8.0
+
+      def initialize(api)
+        @api = api
+        @queue = []
+        @mutex = Mutex.new
+        @cond = ConditionVariable.new
+        @closed = false
+        @dropped_count = 0
+        @worker = Thread.new { run }
+        @worker.report_on_exception = false
+      end
+
+      def enqueue(body, idempotency_key)
+        depth = nil
+        @mutex.synchronize do
+          return if @closed
+
+          if @queue.size >= MAX_BUFFER_SIZE
+            @queue.shift
+            @dropped_count += 1
+            warn "[smplkit.audit] buffer full (size=#{MAX_BUFFER_SIZE}); " \
+                 "dropped oldest event (total dropped=#{@dropped_count})"
+          end
+          @queue.push(PendingEvent.new(body, idempotency_key))
+          depth = @queue.size
+          @cond.signal if depth >= WATERMARK
+        end
+      end
+
+      def flush(timeout: 5.0)
+        deadline = monotonic_now + timeout
+        loop do
+          empty = @mutex.synchronize { @queue.empty? }
+          return if empty
+
+          if monotonic_now >= deadline
+            warn "[smplkit.audit] flush timed out (timeout=#{timeout}s)"
+            return
+          end
+          @mutex.synchronize { @cond.signal }
+          sleep 0.05
+        end
+      end
+
+      def close(timeout: 5.0)
+        flush(timeout: timeout)
+        @mutex.synchronize do
+          @closed = true
+          @cond.broadcast
+        end
+        @worker.join(timeout)
+      end
+
+      private
+
+      def run
+        loop do
+          drain_once
+          should_exit = false
+          sleep_for = FLUSH_INTERVAL
+          @mutex.synchronize do
+            should_exit = @closed && @queue.empty?
+            unless @queue.empty?
+              head = @queue.first
+              if head.next_retry_at
+                until_next = head.next_retry_at - monotonic_now
+                sleep_for = until_next if until_next.positive? && until_next < sleep_for
+              end
+            end
+            @cond.wait(@mutex, sleep_for) unless should_exit
+          end
+          break if should_exit
+        end
+      end
+
+      def drain_once
+        loop do
+          item = nil
+          @mutex.synchronize do
+            return if @queue.empty?
+
+            head = @queue.first
+            return if head.next_retry_at && head.next_retry_at > monotonic_now
+
+            item = @queue.shift
+          end
+
+          status = 0
+          begin
+            opts = item.idempotency_key ? { idempotency_key: item.idempotency_key } : {}
+            @api.create_event(item.body, opts)
+            status = 201
+          rescue SmplkitGeneratedClient::Audit::ApiError => e
+            status = e.code || 0
+          rescue StandardError
+            status = 0
+          end
+
+          requeue = handle_outcome(item, status)
+          if requeue
+            @mutex.synchronize { @queue.unshift(requeue) }
+            return
+          end
+        end
+      end
+
+      def handle_outcome(item, status)
+        return nil if status >= 200 && status < 300
+
+        if status >= 400 && status < 500 && status != 429
+          warn "[smplkit.audit] permanent failure status=#{status}; event dropped"
+          return nil
+        end
+
+        item.attempts += 1
+        if item.attempts >= MAX_ATTEMPTS
+          warn "[smplkit.audit] gave up after #{item.attempts} attempts (status=#{status})"
+          return nil
+        end
+        backoff = [MAX_BACKOFF, INITIAL_BACKOFF * (2**(item.attempts - 1))].min
+        jitter = rand(0.0..(backoff * 0.25))
+        item.next_retry_at = monotonic_now + backoff + jitter
+        item
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # Holds an outbound event between attempts.
+      PendingEvent = Struct.new(:body, :idempotency_key, :attempts, :next_retry_at) do
+        def initialize(body, idempotency_key, attempts = 0, next_retry_at = nil)
+          super
+        end
+      end
+      private_constant :PendingEvent
+    end
+  end
+end

data/lib/smplkit/audit/client.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Audit
+    # Audit-product entry point — accessed via +client.audit+.
+    #
+    # Today the audit namespace is exclusively +#events+; future
+    # iterations may add SIEM exports as additional sub-clients
+    # (ADR-047 §2.7 lists SIEM streaming as a Pro-tier capability).
+    class AuditClient
+      attr_reader :events
+
+      def initialize(api_key:, base_url:, timeout: 10.0)
+        cfg = SmplkitGeneratedClient::Audit::Configuration.new
+        cfg.host = URI.parse(base_url).host
+        cfg.scheme = URI.parse(base_url).scheme
+        cfg.access_token = api_key
+        cfg.timeout = timeout
+        api_client = SmplkitGeneratedClient::Audit::ApiClient.new(cfg)
+        api = SmplkitGeneratedClient::Audit::DefaultApi.new(api_client)
+        @events = Events.new(api)
+      end
+
+      def _close
+        @events._close
+      end
+    end
+  end
+end

data/lib/smplkit/audit/events.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Audit
+    # Audit events surface — accessed via +client.audit.events+.
+    #
+    # +#create+ is fire-and-forget per ADR-047 §2.6 — the call enqueues
+    # the event onto an in-memory bounded buffer and returns
+    # immediately. +#list+ and +#get+ are synchronous.
+    class Events
+      def initialize(api)
+        @api = api
+        @buffer = EventBuffer.new(api)
+      end
+
+      # Enqueue an audit event for asynchronous delivery.
+      #
+      # Customer attempts to record events with +resource_type+ starting
+      # with +smpl.+ are rejected by the server with a 403 (the buffer
+      # logs and drops permanent failures).
+      def create(action:, resource_type:, resource_id:,
+                 occurred_at: nil, snapshot: nil, data: nil, idempotency_key: nil)
+        raise ArgumentError, "action is required" if action.nil? || action.to_s.empty?
+        raise ArgumentError, "resource_type is required" if resource_type.nil? || resource_type.to_s.empty?
+        raise ArgumentError, "resource_id is required" if resource_id.nil? || resource_id.to_s.empty?
+
+        attrs = SmplkitGeneratedClient::Audit::Event.new(
+          action: action,
+          resource_type: resource_type,
+          resource_id: resource_id,
+          occurred_at: occurred_at,
+          snapshot: snapshot,
+          data: data
+        )
+        resource = SmplkitGeneratedClient::Audit::EventResource.new(
+          id: "",
+          type: "event",
+          attributes: attrs
+        )
+        body = SmplkitGeneratedClient::Audit::EventResponse.new(data: resource)
+        @buffer.enqueue(body, idempotency_key)
+      end
+
+      # Single-event retrieval.
+      #
+      # Raises +SmplkitGeneratedClient::Audit::ApiError+ on non-2xx
+      # responses (404 if the event is not in the caller's account).
+      def get(event_id)
+        resp = @api.get_event(event_id)
+        AuditEvent.from_resource(resp.data)
+      end
+
+      # List events with filters and cursor pagination. Returns a
+      # +Smplkit::Audit::ListEventsPage+ whose +#events+ is the page and
+      # +#next_cursor+ is the opaque token for the next page (or nil).
+      def list(action: nil, resource_type: nil, resource_id: nil,
+               actor_type: nil, actor_id: nil, occurred_at_range: nil,
+               page_size: nil, page_after: nil)
+        opts = {}
+        opts[:filteraction] = action if action
+        opts[:filterresource_type] = resource_type if resource_type
+        opts[:filterresource_id] = resource_id if resource_id
+        opts[:filteractor_type] = actor_type if actor_type
+        opts[:filteractor_id] = actor_id if actor_id
+        opts[:filteroccurred_at] = occurred_at_range if occurred_at_range
+        opts[:pagesize] = page_size if page_size
+        opts[:pageafter] = page_after if page_after
+
+        resp = @api.list_events(opts)
+        events = (resp.data || []).map { |r| AuditEvent.from_resource(r) }
+        next_cursor = nil
+        if resp.links&._next.is_a?(String)
+          next_link = resp.links._next
+          if (idx = next_link.index("page[after]="))
+            next_cursor = next_link[(idx + "page[after]=".length)..]
+            if (amp = next_cursor.index("&"))
+              next_cursor = next_cursor[0...amp]
+            end
+          end
+        end
+        ListEventsPage.new(events, next_cursor)
+      end
+
+      # Block until the in-memory buffer is drained or the timeout elapses.
+      def flush(timeout: 5.0)
+        @buffer.flush(timeout: timeout)
+      end
+
+      # @api private — drains best-effort and stops the worker thread.
+      def _close
+        @buffer.close
+      end
+    end
+
+    # Public-facing audit event resource. ADR-047 §2.3.1.
+    AuditEvent = Struct.new(
+      :id, :action, :resource_type, :resource_id,
+      :occurred_at, :created_at,
+      :actor_type, :actor_id, :actor_label,
+      :snapshot, :data, :idempotency_key,
+      keyword_init: true
+    ) do
+      def self.from_resource(resource)
+        attrs = resource.attributes
+        new(
+          id: resource.id,
+          action: attrs.action,
+          resource_type: attrs.resource_type,
+          resource_id: attrs.resource_id,
+          occurred_at: attrs.occurred_at,
+          created_at: attrs.created_at,
+          actor_type: attrs.actor_type,
+          actor_id: attrs.actor_id,
+          actor_label: attrs.actor_label,
+          snapshot: attrs.snapshot,
+          data: attrs.data || {},
+          idempotency_key: attrs.idempotency_key
+        )
+      end
+    end
+
+    # One page of events plus a cursor for the next page (nil on the last page).
+    ListEventsPage = Struct.new(:events, :next_cursor)
+  end
+end

data/lib/smplkit/client.rb

@@ -2,6 +2,8 @@
 
 require "concurrent"
 
+require "smplkit/audit/client"
+
 module Smplkit
   # Synchronous entry point for the smplkit SDK.
   #
@@ -28,7 +30,7 @@ module Smplkit
   class Client
     PERIODIC_FLUSH_INTERVAL = 60.0
 
-    attr_reader :manage, :config, :flags, :logging
+    attr_reader :manage, :config, :flags, :logging, :audit
 
     # Construct, yield to the block, and close on exit.
     def self.open(**kwargs)
@@ -40,7 +42,7 @@ module Smplkit
       end
     end
 
-    def initialize(api_key: nil, environment: nil, service: nil, profile: nil,
+    def initialize(api_key: nil, environment: nil, service: nil, profile: nil, # rubocop:disable Metrics/AbcSize
                    base_domain: nil, scheme: nil, debug: nil, telemetry: nil)
       cfg = ConfigResolution.resolve_config(
         profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme,
@@ -70,6 +72,7 @@ module Smplkit
       app_url = ConfigResolution.service_url(cfg.scheme, "app", cfg.base_domain)
       flags_url = ConfigResolution.service_url(cfg.scheme, "flags", cfg.base_domain)
       logging_url = ConfigResolution.service_url(cfg.scheme, "logging", cfg.base_domain)
+      audit_url = ConfigResolution.service_url(cfg.scheme, "audit", cfg.base_domain)
       @app_base_url = app_url
 
       @metrics = if cfg.telemetry
@@ -84,6 +87,7 @@ module Smplkit
                                             flags_base_url: flags_url, app_base_url: app_url)
       @logging = Logging::LoggingClient.new(self, manage: @manage, metrics: @metrics,
                                                   logging_base_url: logging_url, app_base_url: app_url)
+      @audit = Audit::AuditClient.new(api_key: cfg.api_key, base_url: audit_url)
 
       @closed = false
       schedule_periodic_flush
@@ -153,6 +157,7 @@ module Smplkit
       @logging._close
       @flags._close
       @config._close
+      @audit._close
       @ws_manager&.stop
       @ws_manager = nil
       @manage.close