smplkit 1.0.17 → 1.0.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22da5481c89c52426de98fac54b278a253202a6a3f28aa1e7a03eac0372ec790
-  data.tar.gz: '0190db86b79b56f478cab2c0c3814e48e5d7e48917afc6925ca42948277f7afe'
+  metadata.gz: 30387f75831a98eef6f343ab2c4d8971826f8d01d3e90331403f99cb53d7797e
+  data.tar.gz: a03b4de90c32c53e84b9c902af5b45c89317b8b064629b16bf366d4a8e40c0c7
 SHA512:
-  metadata.gz: 538c86b5c363d0e38f21e1c4b009a1cdec528ebc3b6bc9dba353bc5e6ea22f91613dfe15980b044bf4aec91e3c8bfa3d3282875b0889141842bbcb9264743371
-  data.tar.gz: 6ca828d6c3f0b111ca911328a4a7116dfbe4e5b8807b4a7aa56e9bc2f0a4088ae69f655c16b9d64d2307ed8aa6f4030b3baf34f63eff627ddbd6a21fc0672313
+  metadata.gz: d4632f78bcfb874dbf478a8dfd3030c732e782ba0099810931bedac53e36aadcf62628e7ff7dc4e1f264f06e797c8fde837116731b237466a1bcf6f70604cd68
+  data.tar.gz: 5ab26d7a65e5849975ac3bf3c64166e3cb455dd0e59f7c593124d4e44b2127cea55488b9499f97cf2e1822296442509916ab3193701adf69db7d567fba8c6c58

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,145 @@
+# 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?
+
+        # Pydantic validation on the server expects an ISO-8601 string
+        # for ``occurred_at`` — Ruby's ``Time#to_s`` (which is what the
+        # generated client falls back to during JSON serialization)
+        # emits ``"2026-05-07 04:43:23 UTC"`` and trips the gate. Coerce
+        # Time/DateTime to ``.iso8601`` here so end users can pass the
+        # native Ruby type.
+        normalized_occurred_at = if occurred_at.respond_to?(:iso8601)
+                                   occurred_at.iso8601
+                                 else
+                                   occurred_at
+                                 end
+
+        # Server-side validation also rejects ``data: null`` (the field
+        # is required-non-null in the OpenAPI schema). Always default to
+        # an empty hash so users who omit ``data:`` don't trip the gate.
+        attrs = SmplkitGeneratedClient::Audit::Event.new(
+          action: action,
+          resource_type: resource_type,
+          resource_id: resource_id,
+          occurred_at: normalized_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)
+        # Generated client opts use snake_case keys that internally map
+        # to the JSON:API ``filter[*]`` / ``page[*]`` query-string format
+        # (see default_api.rb#list_events_with_http_info). Without the
+        # underscores these silently fall through and the filters never
+        # reach the server.
+        opts = {}
+        opts[:filter_action] = action if action
+        opts[:filter_resource_type] = resource_type if resource_type
+        opts[:filter_resource_id] = resource_id if resource_id
+        opts[:filter_actor_type] = actor_type if actor_type
+        opts[:filter_actor_id] = actor_id if actor_id
+        opts[:filter_occurred_at] = occurred_at_range if occurred_at_range
+        opts[:page_size] = page_size if page_size
+        opts[:page_after] = 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

data/lib/smplkit.rb

@@ -16,7 +16,7 @@ require_relative "smplkit/version"
 # +lib/smplkit/_generated/<svc>/lib+ uses internal +require+ paths like
 # +smplkit_<svc>_client/api_client+, so the directory has to be on
 # +$LOAD_PATH+ before its top-level entry is required.
-%w[app config flags logging].each do |svc|
+%w[app audit config flags logging].each do |svc|
   generated_lib = File.expand_path("smplkit/_generated/#{svc}/lib", __dir__)
   $LOAD_PATH.unshift(generated_lib) if File.directory?(generated_lib)
 end
@@ -27,7 +27,8 @@ end
 module SmplkitGeneratedClient # rubocop:disable Style/OneClassPerFile
 end
 
-%w[smplkit_app_client smplkit_config_client smplkit_flags_client smplkit_logging_client].each do |gem_lib|
+%w[smplkit_app_client smplkit_audit_client smplkit_config_client smplkit_flags_client
+   smplkit_logging_client].each do |gem_lib|
   require gem_lib
 rescue LoadError
   # Generated tree may be intentionally absent in development snapshots —
@@ -61,6 +62,9 @@ require_relative "smplkit/management/types"
 require_relative "smplkit/management/models"
 require_relative "smplkit/management/buffer"
 require_relative "smplkit/management/client"
+require_relative "smplkit/audit/buffer"
+require_relative "smplkit/audit/events"
+require_relative "smplkit/audit/client"
 require_relative "smplkit/client"
 
 require_relative "smplkit/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smplkit
 version: !ruby/object:Gem::Version
-  version: 1.0.17
+  version: 1.0.19
 platform: ruby
 authors:
 - Smpl Solutions LLC
@@ -560,6 +560,9 @@ files:
 - lib/smplkit/_generated/logging/spec/models/usage_list_response_spec.rb
 - lib/smplkit/_generated/logging/spec/models/usage_resource_spec.rb
 - lib/smplkit/_generated/logging/spec/spec_helper.rb
+- lib/smplkit/audit/buffer.rb
+- lib/smplkit/audit/client.rb
+- lib/smplkit/audit/events.rb
 - lib/smplkit/client.rb
 - lib/smplkit/config/client.rb
 - lib/smplkit/config/helpers.rb