logbrew-sdk 0.1.0 → 0.1.2

data/lib/logbrew/persistent_event_store.rb

@@ -0,0 +1,403 @@
+# frozen_string_literal: true
+
+module LogBrew
+  class PersistentEventStore
+    EVENT_FILE = /\A(\d{20})\.event\z/.freeze
+    TEMP_FILE = /\A\.tmp-[0-9a-f]{32}\z/.freeze
+    LOCK_FILE = ".lock"
+    ACK_FILE = ".ack"
+
+    StoredRecord = Struct.new(:sequence, :json, :bytes, :durable) do
+      def initialize(sequence, json, bytes, durable = true)
+        super(sequence, json.dup.freeze, bytes, durable)
+        freeze
+      end
+    end
+
+    def self.open(path:)
+      validate_path(path)
+      new(path)
+    rescue SdkError
+      raise
+    rescue StandardError
+      raise SdkError.new("persistent_queue_error", "persistent queue could not be opened")
+    end
+
+    def self.validate_path(path)
+      unless path.is_a?(String) && !path.empty? && File.absolute_path(path) == path && File.expand_path(path) == path
+        raise SdkError.new("validation_error", "persistent_queue_path must be a normalized absolute path")
+      end
+    rescue ArgumentError
+      raise SdkError.new("validation_error", "persistent_queue_path must be a normalized absolute path")
+    end
+    private_class_method :validate_path
+
+    def initialize(path)
+      @path = path.dup.freeze
+      @owner_process_id = current_process_id
+      @mutex = Mutex.new
+      @closed = false
+      @failed = false
+      @directory_sync_pending = false
+      @records = []
+      @acknowledged_sequence = 0
+      @next_sequence = 1
+      @directory_io = nil
+      @directory_identity = nil
+      @lock_io = nil
+
+      prepare_directory
+      open_directory
+      acquire_lock
+      recover
+    rescue StandardError
+      close_resources
+      raise
+    end
+    private_class_method :new
+
+    def records
+      assert_process_ownership
+      @mutex.synchronize do
+        ensure_usable
+        assert_directory_identity
+        @records.dup.freeze
+      end
+    end
+
+    def prepare_delivery
+      assert_process_ownership
+      @mutex.synchronize do
+        ensure_usable
+        assert_directory_identity
+        confirm_directory_sync
+      end
+      nil
+    end
+
+    def append(json)
+      assert_process_ownership
+      @mutex.synchronize do
+        ensure_usable
+        assert_directory_identity
+        confirm_directory_sync
+        validate_event_json(json)
+        sequence = @next_sequence
+        directory_synced = write_atomic(event_file_name(sequence), json)
+        record = StoredRecord.new(sequence, json, json.bytesize, directory_synced)
+        @records << record
+        @next_sequence += 1
+        record
+      rescue SdkError => error
+        @failed = true unless error.code == "persistence_commit_error"
+        raise
+      rescue StandardError
+        @failed = true
+        raise SdkError.new("persistent_queue_error", "persistent queue could not store an event")
+      end
+    end
+
+    # Returns a content-free compaction error only after the accepted marker is durable.
+    def acknowledge(records)
+      assert_process_ownership
+      @mutex.synchronize do
+        ensure_usable
+        assert_directory_identity
+        return nil if records.empty?
+
+        confirm_directory_sync
+        validate_prefix(records)
+        accepted_sequence = records.last.sequence
+        marker_synced = write_atomic(ACK_FILE, "#{accepted_sequence}\n")
+        unless marker_synced
+          raise SdkError.new("persistent_queue_error", "persistent queue acknowledgement durability is incomplete")
+        end
+
+        @acknowledged_sequence = accepted_sequence
+        @records.shift(records.length)
+        compact_records(records)
+      rescue SdkError
+        raise
+      rescue StandardError
+        raise SdkError.new("persistent_queue_error", "persistent queue could not acknowledge events")
+      end
+    end
+
+    def close
+      assert_process_ownership
+      @mutex.synchronize do
+        return if @closed
+
+        @closed = true
+        close_resources
+      end
+      nil
+    end
+
+    private
+
+    def prepare_directory
+      if File.exist?(@path) || File.symlink?(@path)
+        validate_directory(File.lstat(@path))
+        return
+      end
+
+      parent = File.dirname(@path)
+      parent_stat = File.lstat(parent)
+      unless parent_stat.directory?
+        raise SdkError.new("validation_error", "persistent queue parent directory must exist")
+      end
+
+      Dir.mkdir(@path, 0o700)
+      validate_directory(File.lstat(@path))
+    rescue Errno::ENOENT
+      raise SdkError.new("validation_error", "persistent queue parent directory must exist")
+    end
+
+    def validate_directory(stat)
+      unless stat.directory? && !stat.symlink? && stat.uid == Process.uid && (stat.mode & 0o777) == 0o700
+        raise SdkError.new("persistent_queue_error", "persistent queue must use an owner-only dedicated directory")
+      end
+    end
+
+    def open_directory
+      @directory_io = File.open(@path, File::RDONLY | File::NOFOLLOW)
+      directory_stat = @directory_io.stat
+      validate_directory(directory_stat)
+      @directory_identity = [directory_stat.dev, directory_stat.ino].freeze
+    end
+
+    def acquire_lock
+      assert_directory_identity
+      lock_path = File.join(@path, LOCK_FILE)
+      @lock_io = File.open(lock_path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600)
+      validate_private_file(@lock_io.stat)
+      unless @lock_io.flock(File::LOCK_EX | File::LOCK_NB)
+        raise SdkError.new("persistent_queue_error", "persistent queue is already in use")
+      end
+    rescue Errno::EWOULDBLOCK, Errno::EAGAIN
+      raise SdkError.new("persistent_queue_error", "persistent queue is already in use")
+    end
+
+    def recover
+      assert_directory_identity
+      entries = Dir.children(@path)
+      unexpected = entries.reject do |entry|
+        entry == LOCK_FILE || entry == ACK_FILE || EVENT_FILE.match?(entry) || TEMP_FILE.match?(entry)
+      end
+      unless unexpected.empty?
+        raise SdkError.new("persistent_queue_error", "persistent queue contains unexpected entries")
+      end
+
+      entries.each { |entry| validate_known_entry(entry) }
+      @acknowledged_sequence = read_acknowledged_sequence
+
+      cleaned = false
+      entries.grep(TEMP_FILE).each do |entry|
+        File.unlink(File.join(@path, entry))
+        cleaned = true
+      end
+
+      event_entries = entries.grep(EVENT_FILE).sort
+      recovered = []
+      event_entries.each do |entry|
+        sequence = Integer(EVENT_FILE.match(entry)[1], 10)
+        if sequence <= @acknowledged_sequence
+          File.unlink(File.join(@path, entry))
+          cleaned = true
+          next
+        end
+
+        json = read_event(entry)
+        recovered << StoredRecord.new(sequence, json, json.bytesize)
+      end
+      sync_directory if cleaned
+
+      @records = recovered
+      latest_sequence = [@acknowledged_sequence, recovered.empty? ? 0 : recovered.last.sequence].max
+      @next_sequence = latest_sequence + 1
+    rescue SdkError
+      raise
+    rescue StandardError
+      raise SdkError.new("persistent_queue_error", "persistent queue contains unreadable records")
+    end
+
+    def validate_known_entry(entry)
+      path = File.join(@path, entry)
+      stat = File.lstat(path)
+      validate_private_file(stat)
+    rescue Errno::ENOENT
+      raise SdkError.new("persistent_queue_error", "persistent queue changed during recovery")
+    end
+
+    def validate_private_file(stat)
+      unless stat.file? && !stat.symlink? && stat.uid == Process.uid && (stat.mode & 0o077).zero?
+        raise SdkError.new("persistent_queue_error", "persistent queue contains unsafe files")
+      end
+    end
+
+    def read_acknowledged_sequence
+      path = File.join(@path, ACK_FILE)
+      return 0 unless File.exist?(path)
+
+      content = read_private_file(path)
+      unless /\A\d{1,20}\n?\z/.match?(content)
+        raise SdkError.new("persistent_queue_error", "persistent queue contains unreadable records")
+      end
+
+      Integer(content, 10)
+    end
+
+    def read_event(entry)
+      json = read_private_file(File.join(@path, entry))
+      json.force_encoding(Encoding::UTF_8)
+      validate_event_json(json)
+      json.freeze
+    end
+
+    def read_private_file(path)
+      File.open(path, File::RDONLY | File::NOFOLLOW) do |file|
+        validate_private_file(file.stat)
+        file.read
+      end
+    end
+
+    def validate_event_json(json)
+      unless json.is_a?(String) && json.encoding == Encoding::UTF_8 && json.valid_encoding? && !json.empty?
+        raise SdkError.new("persistent_queue_error", "persistent queue contains unreadable records")
+      end
+
+      event = JSON.parse(json)
+      valid = event.is_a?(Hash) && event["type"].is_a?(String) && !event["type"].empty? &&
+              event["timestamp"].is_a?(String) && !event["timestamp"].empty? &&
+              event["id"].is_a?(String) && !event["id"].empty? && event["attributes"].is_a?(Hash)
+      unless valid && JSON.generate(event) == json
+        raise SdkError.new("persistent_queue_error", "persistent queue contains unreadable records")
+      end
+    rescue JSON::ParserError, JSON::GeneratorError, EncodingError
+      raise SdkError.new("persistent_queue_error", "persistent queue contains unreadable records")
+    end
+
+    def validate_prefix(records)
+      expected = @records.first(records.length)
+      unless expected.length == records.length && expected.map(&:sequence) == records.map(&:sequence)
+        raise SdkError.new("persistent_queue_error", "persistent queue acknowledgement is stale")
+      end
+    end
+
+    def compact_records(records)
+      compaction_failed = false
+      records.each do |record|
+        begin
+          File.unlink(File.join(@path, event_file_name(record.sequence)))
+        rescue Errno::ENOENT
+          nil
+        rescue StandardError
+          compaction_failed = true
+        end
+      end
+
+      begin
+        sync_directory
+      rescue StandardError
+        compaction_failed = true
+      end
+
+      if compaction_failed
+        SdkError.new("persistent_queue_error", "persistent queue accepted-prefix compaction is incomplete")
+      end
+    end
+
+    def write_atomic(destination_name, content)
+      assert_directory_identity
+      temp_name = ".tmp-#{SecureRandom.hex(16)}"
+      temp_path = File.join(@path, temp_name)
+      destination_path = File.join(@path, destination_name)
+      renamed = false
+
+      begin
+        File.open(temp_path, File::WRONLY | File::CREAT | File::EXCL | File::NOFOLLOW, 0o600) do |file|
+          file.write(content)
+          file.flush
+          file.fsync
+        end
+        assert_directory_identity
+        File.rename(temp_path, destination_path)
+        renamed = true
+        begin
+          sync_directory
+          true
+        rescue StandardError
+          @directory_sync_pending = true
+          false
+        end
+      ensure
+        File.unlink(temp_path) if !renamed && File.exist?(temp_path)
+      end
+    end
+
+    def sync_directory
+      @directory_io.fsync
+    end
+
+    def confirm_directory_sync
+      return unless @directory_sync_pending
+
+      sync_directory
+      @directory_sync_pending = false
+    rescue StandardError
+      raise SdkError.new("persistence_commit_error", "persistent queue durability is unconfirmed")
+    end
+
+    def assert_directory_identity
+      stat = File.lstat(@path)
+      current_identity = [stat.dev, stat.ino]
+      unless current_identity == @directory_identity
+        raise SdkError.new("persistent_queue_error", "persistent queue directory changed while in use")
+      end
+
+      validate_directory(stat)
+    rescue SdkError
+      raise
+    rescue StandardError
+      raise SdkError.new("persistent_queue_error", "persistent queue directory changed while in use")
+    end
+
+    def event_file_name(sequence)
+      format("%020d.event", sequence)
+    end
+
+    def ensure_usable
+      raise SdkError.new("persistent_queue_error", "persistent queue is closed") if @closed
+      raise SdkError.new("persistent_queue_error", "persistent queue requires recovery") if @failed
+    end
+
+    def assert_process_ownership
+      return if current_process_id == @owner_process_id
+
+      raise SdkError.new("process_ownership_error", "persistent queue must be opened in the current process")
+    end
+
+    def current_process_id
+      process_id = Process.pid
+      unless process_id.is_a?(Integer) && process_id.positive?
+        raise SdkError.new("process_ownership_error", "persistent queue process identity is unavailable")
+      end
+
+      process_id
+    end
+
+    def close_resources
+      if @lock_io
+        @lock_io.flock(File::LOCK_UN) rescue nil
+        @lock_io.close rescue nil
+        @lock_io = nil
+      end
+      if @directory_io
+        @directory_io.close rescue nil
+        @directory_io = nil
+      end
+    end
+  end
+  private_constant :PersistentEventStore
+end

data/lib/logbrew/product_timeline.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Builders for app-owned product and network timeline action events.
+  class ProductTimeline
+    private_class_method :new
+
+    def self.product_action(
+      name:,
+      status: "success",
+      route_template: nil,
+      session_id: nil,
+      trace_id: nil,
+      screen: nil,
+      funnel: nil,
+      step: nil,
+      metadata: nil
+    )
+      action_metadata = timeline_metadata("product_timeline", metadata)
+      put_if_present(action_metadata, "routeTemplate", sanitize_optional_route_template("product route_template", route_template))
+      put_if_present(action_metadata, "sessionId", optional_label("session_id", session_id))
+      put_if_present(action_metadata, "traceId", optional_label("trace_id", trace_id))
+      put_if_present(action_metadata, "screen", optional_label("screen", screen))
+      put_if_present(action_metadata, "funnel", optional_label("funnel", funnel))
+      put_if_present(action_metadata, "step", optional_label("step", step))
+
+      {
+        "name" => required_label("product action name", name),
+        "status" => normalize_status(status),
+        "metadata" => action_metadata
+      }
+    end
+
+    def self.network_milestone(
+      route_template:,
+      method: "GET",
+      status_code: nil,
+      duration_ms: nil,
+      status: nil,
+      name: nil,
+      session_id: nil,
+      trace_id: nil,
+      metadata: nil
+    )
+      route = sanitize_route_template("network milestone route_template", route_template)
+      normalized_method = normalize_method(method)
+      validate_status_code(status_code)
+      validate_duration_ms(duration_ms)
+      normalized_status = normalize_status(status || (status_code && status_code >= 400 ? "failure" : "success"))
+
+      action_metadata = timeline_metadata("network_timeline", metadata)
+      action_metadata["routeTemplate"] = route
+      action_metadata["method"] = normalized_method
+      put_if_present(action_metadata, "statusCode", status_code)
+      put_if_present(action_metadata, "durationMs", duration_ms)
+      put_if_present(action_metadata, "sessionId", optional_label("session_id", session_id))
+      put_if_present(action_metadata, "traceId", optional_label("trace_id", trace_id))
+
+      {
+        "name" => name.nil? ? "network.#{normalized_method.downcase} #{route}" : required_label("network milestone name", name),
+        "status" => normalized_status,
+        "metadata" => action_metadata
+      }
+    end
+
+    def self.timeline_metadata(source, metadata)
+      copied = { "source" => source }
+      validated = Validation.require_metadata(metadata)
+      return copied if validated.nil?
+
+      validated.each do |key, value|
+        copied[key] = value unless key == "source"
+      end
+      copied
+    end
+
+    def self.required_label(label, value)
+      Validation.require_non_empty(label, value)
+      value.to_s.strip
+    end
+
+    def self.optional_label(label, value)
+      return nil if value.nil?
+
+      required_label(label, value)
+    end
+
+    def self.normalize_status(status)
+      Validation.require_allowed_value("action status", status, LogBrew::ACTION_STATUSES)
+      status
+    end
+
+    def self.sanitize_optional_route_template(label, route_template)
+      return nil if route_template.nil?
+
+      sanitize_route_template(label, route_template)
+    end
+
+    def self.sanitize_route_template(label, route_template)
+      Validation.require_non_empty(label, route_template)
+      trimmed = route_template.to_s.strip
+      if trimmed.match?(/\Ahttps?:\/\//i)
+        uri = URI.parse(trimmed)
+        return uri.path.nil? || uri.path.empty? ? "/" : uri.path
+      end
+
+      cutoff = first_present_index(trimmed.index("?"), trimmed.index("#"))
+      cutoff.nil? ? trimmed : (trimmed[0...cutoff].rstrip.empty? ? "/" : trimmed[0...cutoff].rstrip)
+    rescue URI::InvalidURIError => error
+      raise SdkError.new("validation_error", "route_template must be a valid route or URL: #{error.message}")
+    end
+
+    def self.normalize_method(method)
+      normalized = method.to_s.strip.upcase
+      unless normalized.match?(/\A[A-Z0-9_-]+\z/)
+        raise SdkError.new("validation_error", "network milestone method must be a valid HTTP method")
+      end
+
+      normalized
+    end
+
+    def self.validate_status_code(status_code)
+      return if status_code.nil?
+
+      unless status_code.is_a?(Integer) && status_code >= 100 && status_code <= 599
+        raise SdkError.new("validation_error", "network milestone status_code must be between 100 and 599")
+      end
+    end
+
+    def self.validate_duration_ms(duration_ms)
+      return if duration_ms.nil?
+      unless duration_ms.is_a?(Numeric) && duration_ms.finite?
+        raise SdkError.new("validation_error", "network milestone duration_ms must be a finite number")
+      end
+      raise SdkError.new("validation_error", "network milestone duration_ms must be non-negative") if duration_ms.negative?
+    end
+
+    def self.put_if_present(metadata, key, value)
+      metadata[key] = value unless value.nil?
+    end
+
+    def self.first_present_index(first, second)
+      return second if first.nil?
+      return first if second.nil?
+
+      [first, second].min
+    end
+
+    private_class_method :timeline_metadata, :required_label, :optional_label, :normalize_status,
+                         :sanitize_optional_route_template, :sanitize_route_template, :normalize_method,
+                         :validate_status_code, :validate_duration_ms, :put_if_present, :first_present_index
+  end
+end