durable_streams 0.1.0

data/lib/durable_streams/types.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module DurableStreams
+  # HTTP header names
+  STREAM_NEXT_OFFSET_HEADER = "stream-next-offset"
+  STREAM_UP_TO_DATE_HEADER = "stream-up-to-date"
+  STREAM_CURSOR_HEADER = "stream-cursor"
+  STREAM_TTL_HEADER = "stream-ttl"
+  STREAM_EXPIRES_AT_HEADER = "stream-expires-at"
+  STREAM_SEQ_HEADER = "stream-seq"
+  PRODUCER_ID_HEADER = "producer-id"
+  PRODUCER_EPOCH_HEADER = "producer-epoch"
+  PRODUCER_SEQ_HEADER = "producer-seq"
+  PRODUCER_EXPECTED_SEQ_HEADER = "producer-expected-seq"
+  PRODUCER_RECEIVED_SEQ_HEADER = "producer-received-seq"
+  STREAM_CLOSED_HEADER = "stream-closed"
+
+  # Result from HEAD request
+  # next_offset: The tail offset (position after last byte, where next append goes)
+  # stream_closed: Whether the stream has been closed (no more appends allowed)
+  HeadResult = Struct.new(:exists, :content_type, :next_offset, :etag, :cache_control, :stream_closed, keyword_init: true) do
+    def initialize(**)
+      super
+      self.stream_closed = false if stream_closed.nil?
+      freeze
+    end
+
+    def exists?
+      exists
+    end
+
+    def closed?
+      stream_closed
+    end
+  end
+
+  # Result from close operation
+  # final_offset: The final offset after closing (position after any appended data)
+  CloseResult = Struct.new(:final_offset, keyword_init: true) do
+    def initialize(**)
+      super
+      freeze
+    end
+  end
+
+  # Result from append
+  # next_offset: The new tail offset after this append (for checkpointing)
+  AppendResult = Struct.new(:next_offset, :duplicate, keyword_init: true) do
+    def initialize(**)
+      super
+      freeze
+    end
+
+    def duplicate?
+      duplicate || false
+    end
+  end
+
+  # A batch of JSON messages with metadata
+  # next_offset: Position to resume from (pass to next read)
+  JsonBatch = Struct.new(:items, :next_offset, :cursor, :up_to_date, keyword_init: true) do
+    def initialize(items: [], **)
+      super(items: Array(items).freeze, **)
+      freeze
+    end
+
+    def up_to_date?
+      up_to_date || false
+    end
+  end
+
+  # A byte chunk (for non-JSON streams)
+  # next_offset: Position to resume from (pass to next read)
+  ByteChunk = Struct.new(:data, :next_offset, :cursor, :up_to_date, keyword_init: true) do
+    def initialize(**)
+      super
+      freeze
+    end
+
+    def up_to_date?
+      up_to_date || false
+    end
+  end
+
+  # Retry policy configuration (not frozen - may be modified before use)
+  RetryPolicy = Struct.new(:max_retries, :initial_delay, :max_delay, :multiplier, :retryable_statuses,
+                           keyword_init: true) do
+    def self.default
+      new(
+        max_retries: 5,
+        initial_delay: 0.1,
+        max_delay: 30.0,
+        multiplier: 2.0,
+        retryable_statuses: [429, 500, 502, 503, 504].freeze
+      ).freeze
+    end
+  end
+
+  # Producer append result (includes epoch/seq for exactly-once tracking)
+  ProducerResult = Struct.new(:next_offset, :duplicate, :epoch, :seq, keyword_init: true) do
+    def initialize(**)
+      super
+      freeze
+    end
+
+    def duplicate?
+      duplicate || false
+    end
+  end
+
+  # Check if content type is JSON (supports vendor types like application/vnd.foo+json)
+  def self.json_content_type?(content_type)
+    return false if content_type.nil?
+
+    normalized = content_type.split(";").first&.strip&.downcase
+    normalized == "application/json" || normalized&.end_with?("+json")
+  end
+
+  # Check if content type supports SSE
+  def self.sse_compatible?(content_type)
+    return false if content_type.nil?
+
+    normalized = content_type.split(";").first&.strip&.downcase
+    normalized == "application/json" || normalized&.start_with?("text/")
+  end
+
+  # Normalize offset to a valid string (defaults to "-1" for empty/nil)
+  def self.normalize_offset(offset)
+    offset.nil? || offset.to_s.empty? ? "-1" : offset.to_s
+  end
+
+  # Parse common response headers for stream metadata
+  # @param response [HTTP::Response] HTTP response
+  # @param defaults [Hash] Default values for missing headers
+  # @return [Hash] Parsed header values
+  def self.parse_stream_headers(response, defaults = {})
+    {
+      next_offset: response[STREAM_NEXT_OFFSET_HEADER] || defaults[:next_offset],
+      cursor: response[STREAM_CURSOR_HEADER] || defaults[:cursor],
+      up_to_date: response[STREAM_UP_TO_DATE_HEADER] == "true"
+    }
+  end
+end

data/lib/durable_streams/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DurableStreams
+  VERSION = "0.1.0"
+end

data/lib/durable_streams.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "logger"
+require_relative "durable_streams/version"
+require_relative "durable_streams/errors"
+require_relative "durable_streams/types"
+require_relative "durable_streams/http/transport"
+require_relative "durable_streams/configuration"
+require_relative "durable_streams/context"
+require_relative "durable_streams/client"
+require_relative "durable_streams/stream"
+require_relative "durable_streams/json_reader"
+require_relative "durable_streams/byte_reader"
+require_relative "durable_streams/sse_reader"
+require_relative "durable_streams/producer"
+
+module DurableStreams
+  class << self
+    attr_accessor :logger
+
+    # Get the global configuration
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure DurableStreams with a block.
+    # The configuration is deep-frozen after the block completes.
+    #
+    # @example
+    #   DurableStreams.configure do |config|
+    #     config.base_url = ENV["DURABLE_STREAMS_URL"]
+    #     config.default_content_type = :json
+    #     config.default_headers = { "Authorization" => -> { "Bearer #{token}" } }
+    #   end
+    #
+    # @yield [Configuration] The configuration object to modify
+    def configure
+      new_config = configuration.dup
+      yield(new_config)
+      @configuration = deep_freeze(new_config)
+      @default_context = nil # Reset cached context on config change
+    end
+
+    # Reset configuration to defaults (mainly for testing)
+    def reset_configuration!
+      @configuration = Configuration.new
+      @default_context = nil
+    end
+
+    # Create a new context with optional customizations.
+    # Use for isolated configurations (e.g., staging vs production).
+    #
+    # @example
+    #   staging = DurableStreams.new_context do |config|
+    #     config.base_url = "https://staging.example.com"
+    #   end
+    #
+    # @yield [Configuration] Optional block to customize the context
+    # @return [Context]
+    def new_context(&block)
+      Context.new(configuration, &block)
+    end
+
+    # Get the default context (uses global configuration)
+    # @return [Context]
+    def default_context
+      @default_context ||= new_context
+    end
+
+    # Get a Stream handle for the given URL
+    # @param url [String] Full URL or path (if base_url configured)
+    # @param context [Context] Optional context (defaults to global)
+    # @return [Stream]
+    def stream(url, context: default_context)
+      Stream.new(url, context: context)
+    end
+
+    # Create a new stream on the server
+    # @param url [String] Stream URL or path
+    # @param content_type [Symbol, String] Content type (:json, :bytes, or MIME type)
+    # @param context [Context] Optional context
+    # @return [Stream]
+    def create(url, content_type:, context: default_context, **options)
+      Stream.create(url, content_type: content_type, context: context, **options)
+    end
+
+    # One-shot append to a stream
+    # @param url [String] Stream URL or path
+    # @param data [Object] Data to append
+    # @param context [Context] Optional context
+    # @return [AppendResult]
+    def append(url, data, context: default_context, **options)
+      stream(url, context: context).append(data, **options)
+    end
+
+    # Read from a stream
+    # @param url [String] Stream URL or path
+    # @param offset [String] Starting offset (default: "-1" for beginning)
+    # @param live [Boolean, Symbol] Live mode (false, :long_poll, :sse)
+    # @param format [Symbol] Format hint (:auto, :json, :bytes)
+    # @param context [Context] Optional context
+    # @return [JsonReader, ByteReader] Reader for iterating messages
+    def read(url, offset: "-1", live: false, format: :auto, context: default_context, **options)
+      stream(url, context: context).read(offset: offset, live: live, format: format, **options)
+    end
+
+    private
+
+    # Deep freeze an object and all nested mutable objects
+    def deep_freeze(obj)
+      case obj
+      when Hash
+        obj.each { |k, v| deep_freeze(k); deep_freeze(v) }
+      when Array
+        obj.each { |v| deep_freeze(v) }
+      end
+      obj.freeze
+    end
+  end
+
+  # Default logger - outputs warnings and errors to stderr
+  # Set to nil to disable, or replace with your own logger
+  self.logger = Logger.new($stderr, level: Logger::WARN)
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: durable_streams
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tokimonki
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: net-http-persistent
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: A maintained Ruby client for the Durable Streams protocol — persistent,
+  resumable event streams over HTTP. Based on the upstream reference client with manual
+  review, testing, and ongoing maintenance.
+email:
+- opensource@tokimonki.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- UPSTREAM.md
+- lib/durable_streams.rb
+- lib/durable_streams/byte_reader.rb
+- lib/durable_streams/client.rb
+- lib/durable_streams/configuration.rb
+- lib/durable_streams/context.rb
+- lib/durable_streams/errors.rb
+- lib/durable_streams/http/transport.rb
+- lib/durable_streams/json_reader.rb
+- lib/durable_streams/producer.rb
+- lib/durable_streams/sse_reader.rb
+- lib/durable_streams/stream.rb
+- lib/durable_streams/testing.rb
+- lib/durable_streams/types.rb
+- lib/durable_streams/version.rb
+homepage: https://github.com/tokimonki/durable_streams
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/tokimonki/durable_streams
+  changelog_uri: https://github.com/tokimonki/durable_streams/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for Durable Streams protocol
+test_files: []