durable_streams 0.1.0

data/lib/durable_streams/context.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DurableStreams
+  # Context holds a frozen configuration snapshot.
+  # Use for isolated configurations (e.g., staging vs production).
+  #
+  # Context is purely a configuration container - no flush/close methods.
+  # Stream and Producer handle their own resource management.
+  class Context
+    attr_reader :config
+
+    # @param parent_config [Configuration] Base configuration to copy from
+    # @yield [Configuration] Optional block to customize the copy
+    def initialize(parent_config = DurableStreams.configuration)
+      @config = parent_config.dup
+      yield(@config) if block_given?
+      DurableStreams.send(:deep_freeze, @config)
+    end
+
+    # Resolve a URL against the configured base_url
+    # @param url [String] URL or path
+    # @return [String] Full URL
+    # @raise [ArgumentError] If URL is blank and no base_url configured
+    def resolve_url(url)
+      raise ArgumentError, "URL required" if url.nil? || url.to_s.strip.empty?
+      return url if url.start_with?("http://", "https://")
+
+      base = @config.base_url&.chomp("/")
+      raise ArgumentError, "base_url not configured" unless base
+
+      path = url.start_with?("/") ? url : "/#{url}"
+      "#{base}#{path}"
+    end
+  end
+end

data/lib/durable_streams/errors.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module DurableStreams
+  # Base error class for all Durable Streams errors
+  class Error < StandardError
+    attr_reader :url, :status, :headers, :code
+
+    def initialize(message = nil, url: nil, status: nil, headers: nil, code: nil)
+      super(message)
+      @url = url
+      @status = status
+      @headers = headers || {}
+      @code = code
+    end
+  end
+
+  # Stream not found (404)
+  class StreamNotFoundError < Error
+    def initialize(url: nil, **opts)
+      super("Stream not found: #{url}", url: url, status: 404, code: "NOT_FOUND", **opts)
+    end
+  end
+
+  # Stream already exists with different config (409)
+  class StreamExistsError < Error
+    def initialize(url: nil, **opts)
+      super("Stream already exists: #{url}", url: url, status: 409, code: "CONFLICT_EXISTS", **opts)
+    end
+  end
+
+  # Sequence conflict (409 with Stream-Seq)
+  class SeqConflictError < Error
+    def initialize(url: nil, **opts)
+      message = url ? "Sequence conflict: #{url}" : "Sequence conflict"
+      super(message, url: url, status: 409, code: "CONFLICT_SEQ", **opts)
+    end
+  end
+
+  # Stream is closed - no more appends allowed (409 with Stream-Closed)
+  class StreamClosedError < Error
+    def initialize(url: nil, **opts)
+      message = url ? "Stream is closed: #{url}" : "Stream is closed"
+      super(message, url: url, status: 409, code: "STREAM_CLOSED", **opts)
+    end
+  end
+
+  # Content type mismatch (409)
+  class ContentTypeMismatchError < Error
+    def initialize(url: nil, expected: nil, actual: nil, **opts)
+      super("Content type mismatch: expected #{expected}, got #{actual}",
+            url: url, status: 409, code: "CONFLICT", **opts)
+    end
+  end
+
+  # Producer epoch is stale (403)
+  class StaleEpochError < Error
+    attr_reader :current_epoch
+
+    def initialize(message = "Stale producer epoch", current_epoch: nil, **opts)
+      super(message, status: 403, code: "FORBIDDEN", **opts)
+      @current_epoch = current_epoch
+    end
+  end
+
+  # Producer sequence gap (409)
+  class SequenceGapError < Error
+    attr_reader :expected_seq, :received_seq
+
+    def initialize(expected_seq: nil, received_seq: nil, url: nil, **opts)
+      message = "Sequence gap: expected #{expected_seq}, got #{received_seq}"
+      message = "#{message} (#{url})" if url
+      super(message, url: url, status: 409, code: "SEQUENCE_GAP", **opts)
+      @expected_seq = expected_seq
+      @received_seq = received_seq
+    end
+  end
+
+  # Rate limited (429)
+  class RateLimitedError < Error
+    def initialize(url: nil, **opts)
+      message = url ? "Rate limited: #{url}" : "Rate limited"
+      super(message, url: url, status: 429, code: "RATE_LIMITED", **opts)
+    end
+  end
+
+  # Bad request (400)
+  class BadRequestError < Error
+    def initialize(message = "Bad request", url: nil, **opts)
+      super(message, url: url, status: 400, code: "BAD_REQUEST", **opts)
+    end
+  end
+
+  # Network/connection error
+  class ConnectionError < Error
+    def initialize(message = "Connection error", **opts)
+      super(message, code: "NETWORK_ERROR", **opts)
+    end
+  end
+
+  # Timeout error
+  class TimeoutError < Error
+    def initialize(message = "Request timeout", **opts)
+      super(message, code: "TIMEOUT", **opts)
+    end
+  end
+
+  # Reader already consumed
+  class AlreadyConsumedError < Error
+    def initialize(**opts)
+      super("Reader already consumed", code: "ALREADY_CONSUMED", **opts)
+    end
+  end
+
+  # Producer or stream has been closed
+  class ClosedError < Error
+    def initialize(message = "Producer is closed", **opts)
+      super(message, code: "CLOSED", **opts)
+    end
+  end
+
+  # SSE not supported for this content type
+  class SSENotSupportedError < Error
+    def initialize(content_type: nil, **opts)
+      super("SSE not supported for content type: #{content_type}",
+            status: 400, code: "SSE_NOT_SUPPORTED", **opts)
+    end
+  end
+
+  # Parse error (malformed JSON, SSE, etc.)
+  class ParseError < Error
+    def initialize(message = "Parse error", **opts)
+      super(message, code: "PARSE_ERROR", **opts)
+    end
+  end
+
+  # Generic fetch error for unexpected statuses
+  class FetchError < Error
+    def initialize(message = "Fetch error", url: nil, status: nil, **opts)
+      super(message, url: url, status: status, code: "UNEXPECTED_STATUS", **opts)
+    end
+  end
+
+  # Map HTTP status to appropriate error
+  def self.error_from_status(status, url: nil, body: nil, headers: nil, operation: nil)
+    case status
+    when 400
+      BadRequestError.new(body || "Bad request", url: url, headers: headers)
+    when 403
+      StaleEpochError.new(body || "Forbidden", url: url, headers: headers)
+    when 404
+      StreamNotFoundError.new(url: url, headers: headers)
+    when 409
+      if headers && headers[STREAM_CLOSED_HEADER]&.downcase == "true"
+        StreamClosedError.new(url: url, headers: headers)
+      # Could be StreamExistsError or SeqConflictError depending on context
+      elsif headers&.key?("stream-seq")
+        SeqConflictError.new(url: url, headers: headers)
+      else
+        StreamExistsError.new(url: url, headers: headers)
+      end
+    when 429
+      RateLimitedError.new(url: url, headers: headers)
+    else
+      FetchError.new(body || "HTTP #{status}", url: url, status: status, headers: headers)
+    end
+  end
+end

data/lib/durable_streams/http/transport.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "net/http/persistent"
+require "uri"
+require "json"
+
+module DurableStreams
+  module HTTP
+    # HTTP transport layer using net-http-persistent for connection pooling
+    class Transport
+      attr_reader :retry_policy, :timeout
+
+      def initialize(retry_policy: nil, timeout: 30, name: "durable_streams")
+        @retry_policy = retry_policy || RetryPolicy.default
+        @timeout = timeout
+        @http = Net::HTTP::Persistent.new(name: name)
+        @http.open_timeout = 10
+        @http.read_timeout = timeout
+        @http.idle_timeout = 30
+      end
+
+      # Make a request with retry logic
+      # @param method [Symbol] HTTP method (:get, :post, :put, :delete, :head)
+      # @param url [String] Full URL
+      # @param headers [Hash] HTTP headers
+      # @param body [String, nil] Request body
+      # @param stream [Boolean] Whether to stream the response (ignored, use stream_request instead)
+      # @param timeout [Integer, nil] Request-specific timeout
+      # @return [Response]
+      def request(method, url, headers: {}, body: nil, stream: false, timeout: nil)
+        uri = URI.parse(url)
+        request_timeout = timeout || @timeout
+
+        attempts = 0
+        last_error = nil
+
+        loop do
+          attempts += 1
+          begin
+            response = execute_request(method, uri, headers, body, request_timeout)
+
+            # Check if we should retry based on status
+            if @retry_policy.retryable_statuses.include?(response.status) && attempts <= @retry_policy.max_retries
+              delay = calculate_delay(attempts)
+              sleep(delay)
+              next
+            end
+
+            return response
+          rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE,
+                 Net::OpenTimeout, Net::ReadTimeout, IOError,
+                 Net::HTTP::Persistent::Error => e
+            last_error = e
+            if attempts <= @retry_policy.max_retries
+              delay = calculate_delay(attempts)
+              sleep(delay)
+              next
+            end
+            raise ConnectionError.new(
+              "Failed to connect to #{uri} after #{attempts} attempts: #{e.class}: #{e.message}"
+            )
+          end
+        end
+      end
+
+      # Stream a request, yielding the response for chunk-by-chunk reading
+      # @param method [Symbol] HTTP method
+      # @param url [String] Full URL
+      # @param headers [Hash] HTTP headers
+      # @param timeout [Integer, nil] Request-specific timeout
+      # @yield [StreamingResponse] The streaming response
+      def stream_request(method, url, headers: {}, timeout: nil, &block)
+        uri = URI.parse(url)
+        request_timeout = timeout || @timeout
+
+        # Temporarily adjust read timeout for streaming
+        original_timeout = @http.read_timeout
+        @http.read_timeout = request_timeout
+
+        req = build_request(method, uri, headers, nil)
+
+        begin
+          @http.request(uri, req) do |http_response|
+            yield StreamingResponse.new(http_response)
+          end
+        rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE,
+               Net::OpenTimeout, Net::ReadTimeout, IOError,
+               Net::HTTP::Persistent::Error => e
+          raise ConnectionError.new("Streaming request to #{uri} failed: #{e.class}: #{e.message}")
+        end
+      ensure
+        @http.read_timeout = original_timeout if original_timeout
+      end
+
+      # Shutdown the persistent connection pool
+      def shutdown
+        @http.shutdown
+      end
+
+      private
+
+      def execute_request(method, uri, headers, body, request_timeout)
+        # Temporarily adjust read timeout if different from default
+        original_timeout = @http.read_timeout
+        @http.read_timeout = request_timeout if request_timeout != original_timeout
+
+        req = build_request(method, uri, headers, body)
+        http_response = @http.request(uri, req)
+
+        Response.new(http_response, http_response.body)
+      ensure
+        @http.read_timeout = original_timeout if request_timeout != original_timeout
+      end
+
+      def build_request(method, uri, headers, body)
+        path = uri.request_uri
+
+        req = case method
+              when :get then Net::HTTP::Get.new(path)
+              when :post then Net::HTTP::Post.new(path)
+              when :put then Net::HTTP::Put.new(path)
+              when :delete then Net::HTTP::Delete.new(path)
+              when :head then Net::HTTP::Head.new(path)
+              else raise ArgumentError, "Unknown method: #{method}"
+              end
+
+        headers.each { |k, v| req[k] = v }
+        req.body = body if body
+
+        req
+      end
+
+      def calculate_delay(attempt)
+        delay = @retry_policy.initial_delay * (@retry_policy.multiplier**(attempt - 1))
+        [delay, @retry_policy.max_delay].min
+      end
+    end
+
+    # Simple response wrapper
+    class Response
+      attr_reader :status, :headers, :body
+
+      def initialize(http_response, body = nil)
+        @status = http_response.code.to_i
+        @headers = {}
+        http_response.each_header { |k, v| @headers[k.downcase] = v }
+        @body = body || http_response.body || ""
+      end
+
+      def success?
+        status >= 200 && status < 300
+      end
+
+      def [](header)
+        @headers[header.to_s.downcase]
+      end
+    end
+
+    # Streaming response for SSE
+    class StreamingResponse
+      attr_reader :status, :headers
+
+      def initialize(http_response)
+        @http_response = http_response
+        @status = http_response.code.to_i
+        @headers = {}
+        http_response.each_header { |k, v| @headers[k.downcase] = v }
+      end
+
+      def success?
+        status >= 200 && status < 300
+      end
+
+      def [](header)
+        @headers[header.to_s.downcase]
+      end
+
+      # Read chunks from the response body
+      def each_chunk(&block)
+        @http_response.read_body(&block)
+      end
+    end
+
+    # Build URL with query parameters
+    def self.build_url(base_url, params = {})
+      return base_url if params.empty?
+
+      uri = URI.parse(base_url)
+      existing_params = uri.query ? URI.decode_www_form(uri.query).to_h : {}
+      merged_params = existing_params.merge(params.transform_keys(&:to_s))
+      uri.query = URI.encode_www_form(merged_params) unless merged_params.empty?
+      uri.to_s
+    end
+
+    # Resolve dynamic headers (support for callable values)
+    def self.resolve_headers(headers)
+      return {} if headers.nil?
+
+      headers.transform_values do |v|
+        v.respond_to?(:call) ? v.call : v
+      end
+    end
+
+    # Resolve dynamic params (support for callable values)
+    def self.resolve_params(params)
+      return {} if params.nil?
+
+      params.transform_values do |v|
+        v.respond_to?(:call) ? v.call : v
+      end.compact
+    end
+  end
+end

data/lib/durable_streams/json_reader.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DurableStreams
+  # Reader for JSON streams - yields parsed Ruby objects
+  class JsonReader
+    attr_reader :next_offset, :cursor, :up_to_date, :status
+
+    # @param stream [Stream] Parent stream handle
+    # @param offset [String] Starting offset
+    # @param live [Symbol, false] Live mode (:long_poll, :sse, false)
+    # @param cursor [String, nil] Initial cursor
+    def initialize(stream, offset: "-1", live: false, cursor: nil)
+      @stream = stream
+      @offset = DurableStreams.normalize_offset(offset)
+      @live = live
+      @next_offset = @offset
+      @cursor = cursor
+      @up_to_date = false
+      @closed = false
+      @status = nil
+      @sse_reader = nil
+    end
+
+    # Iterate over individual JSON messages
+    # @yield [Object] Each parsed JSON message
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      each_batch do |batch|
+        batch.items.each(&block)
+      end
+    end
+
+    # Iterate over batches with metadata
+    # @yield [JsonBatch] Each batch with items, next_offset, cursor, up_to_date
+    def each_batch(&block)
+      return enum_for(:each_batch) unless block_given?
+
+      # Handle SSE mode
+      if use_sse?
+        each_batch_sse(&block)
+        return
+      end
+
+      loop do
+        break if @closed
+
+        batch = fetch_next_json_batch
+        break if batch.nil?
+
+        @next_offset = batch.next_offset
+        @cursor = batch.cursor
+        @up_to_date = batch.up_to_date
+
+        yield batch
+
+        # Break for non-live modes when up_to_date
+        break if @live == false && @up_to_date
+        # Break for long-poll on 204 timeout (up_to_date with empty items = no new data)
+        break if @live == :long_poll && @up_to_date && batch.items.empty? && @status == 204
+        break if @closed
+      end
+    end
+
+    # Collect all messages until up_to_date
+    # @return [Array]
+    def to_a
+      result = []
+      each { |msg| result << msg }
+      result
+    end
+
+    # Cancel/close the reader
+    def close
+      @closed = true
+      @sse_reader&.close
+    end
+
+    def closed?
+      @closed
+    end
+
+    def up_to_date?
+      @up_to_date
+    end
+
+    private
+
+    def use_sse?
+      @live == :sse
+    end
+
+    def fetch_next_json_batch
+      params = { offset: @next_offset }
+      params[:cursor] = @cursor if @cursor
+
+      # Add live mode parameter
+      case @live
+      when :long_poll
+        params[:live] = "long-poll"
+      when :sse
+        # SSE is handled separately
+        return nil
+      when false
+        # No live param for catch-up only
+      end
+
+      request_url = HTTP.build_url(@stream.url, params)
+      headers = @stream.resolved_headers("accept" => "application/json")
+
+      response = @stream.transport.request(:get, request_url, headers: headers)
+      @status = response.status
+
+      if response.status == 404
+        raise StreamNotFoundError.new(url: @stream.url)
+      end
+
+      # Handle 204 No Content (long-poll timeout)
+      # Still parse headers as they contain offset info
+      if response.status == 204
+        @next_offset = response[STREAM_NEXT_OFFSET_HEADER] || @next_offset
+        @cursor = response[STREAM_CURSOR_HEADER] || @cursor
+        @up_to_date = true
+        return JsonBatch.new(items: [], next_offset: @next_offset, cursor: @cursor, up_to_date: true)
+      end
+
+      unless response.success?
+        raise DurableStreams.error_from_status(response.status, url: @stream.url, body: response.body,
+                                               headers: response.headers)
+      end
+
+      headers = DurableStreams.parse_stream_headers(response, next_offset: @next_offset, cursor: @cursor)
+      @next_offset = headers[:next_offset]
+      @cursor = headers[:cursor]
+      @up_to_date = headers[:up_to_date]
+
+      # Parse JSON body
+      items = if response.body && !response.body.empty?
+                begin
+                  JSON.parse(response.body)
+                rescue JSON::ParserError => e
+                  raise ParseError.new(
+                    "Invalid JSON response from server: #{e.message}"
+                  )
+                end
+              else
+                []
+              end
+
+      # Ensure items is an array
+      items = [items] unless items.is_a?(Array)
+
+      JsonBatch.new(
+        items: items,
+        next_offset: @next_offset,
+        cursor: @cursor,
+        up_to_date: @up_to_date
+      )
+    end
+
+    def each_batch_sse(&block)
+      @sse_reader = SSEReader.new(
+        @stream,
+        offset: @next_offset,
+        cursor: @cursor
+      )
+
+      @sse_reader.each_event do |event|
+        break if @closed
+
+        @next_offset = event[:next_offset] if event[:next_offset]
+        @cursor = event[:cursor] if event[:cursor]
+        @up_to_date = event[:up_to_date]
+        @status = 200
+
+        # Only yield if there's data
+        if event[:data] && !event[:data].empty?
+          begin
+            items = JSON.parse(event[:data])
+          rescue JSON::ParserError => e
+            raise ParseError.new(
+              "Invalid JSON in SSE event: #{e.message}"
+            )
+          end
+          items = [items] unless items.is_a?(Array)
+
+          batch = JsonBatch.new(
+            items: items,
+            next_offset: @next_offset,
+            cursor: @cursor,
+            up_to_date: @up_to_date
+          )
+          yield batch
+        elsif event[:up_to_date]
+          # Yield empty batch on control event with up_to_date
+          batch = JsonBatch.new(
+            items: [],
+            next_offset: @next_offset,
+            cursor: @cursor,
+            up_to_date: @up_to_date
+          )
+          yield batch
+        end
+      end
+    ensure
+      @sse_reader&.close
+    end
+  end
+end