runtype 0.1.0

data/lib/runtype/streaming/connection.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module Runtype
+  module Streaming
+    # A single streaming HTTP request, exposing the response status and headers
+    # before the body is read.
+    #
+    # Net::HTTP only streams a response body inside the block form of
+    # `#request`, which would force the whole read loop to live inside one
+    # method. Driving that block from a Fiber inverts the control flow: the
+    # request runs to the point where headers are available and then suspends,
+    # so a caller can inspect the status, decide to abort on an error response,
+    # and otherwise pull chunks one at a time.
+    #
+    # @api private
+    class Connection
+      # @return [Integer, nil] the HTTP status code, after {#start}.
+      attr_reader :status
+
+      # @return [Hash] the response headers, after {#start}.
+      attr_reader :response_headers
+
+      # @param url [String] the absolute request URL.
+      # @param headers [Hash] request headers.
+      # @param body [String, nil] the request body.
+      # @param timeout [Numeric, nil] per-operation socket timeout in seconds.
+      # @param method [String] the HTTP method.
+      def initialize(url:, headers: {}, body: nil, timeout: nil, method: "POST")
+        @url = url
+        @headers = headers
+        @body = body
+        @timeout = timeout
+        @method = method
+        @closed = false
+        @response_headers = {}
+      end
+
+      # Sends the request and reads the response head.
+      #
+      # @return [self]
+      # @raise [Runtype::APITimeoutError, Runtype::APIConnectionError]
+      def start
+        uri = URI.parse(@url)
+        @http = build_http(uri)
+        request = build_request(uri)
+
+        @fiber = Fiber.new do
+          @http.request(request) do |response|
+            Fiber.yield(response)
+            response.read_body { |chunk| Fiber.yield(chunk) }
+          end
+          nil
+        end
+
+        response = pump
+        @status = response.code.to_i
+        @response_headers = response.each_header.to_h
+        self
+      rescue StandardError => e
+        close
+        raise e
+      end
+
+      # Yields body chunks until the response ends.
+      #
+      # @yieldparam chunk [String] raw bytes.
+      # @return [void]
+      # @raise [Runtype::APITimeoutError, Runtype::APIConnectionError]
+      def each_chunk
+        return if @closed
+
+        loop do
+          chunk = pump
+          break if chunk.nil?
+
+          yield chunk
+        end
+      end
+
+      # Drains and returns the whole body. Used for non-streaming responses and
+      # for error bodies, which have to be read before the socket is discarded.
+      #
+      # Chunks arrive as binary and are concatenated as binary, then tagged
+      # UTF-8 once. Appending a binary chunk onto a UTF-8 buffer that already
+      # holds non-ASCII text raises Encoding::CompatibilityError, so a response
+      # body carrying non-ASCII text across a chunk boundary must not be joined
+      # in UTF-8.
+      #
+      # @return [String] the body, tagged UTF-8.
+      def read_body
+        body = +""
+        body.force_encoding(Encoding::BINARY)
+        each_chunk { |chunk| body << chunk.dup.force_encoding(Encoding::BINARY) }
+        body.force_encoding(Encoding::UTF_8)
+      end
+
+      # Closes the socket. Safe to call more than once, and safe to call while
+      # the response is only partially read: the suspended fiber is dropped and
+      # the connection is torn down under it.
+      #
+      # @return [void]
+      def close
+        return if @closed
+
+        @closed = true
+        @fiber = nil
+        begin
+          @http.finish if @http&.started?
+        rescue IOError, SystemCallError
+          nil
+        end
+        @http = nil
+      end
+
+      # @return [Boolean]
+      def closed?
+        @closed
+      end
+
+      private
+
+      # Resumes the request fiber, mapping transport failures onto the curated
+      # error surface.
+      #
+      # @return [Object, nil] the response, the next chunk, or nil at the end.
+      def pump
+        return nil if @fiber.nil? || !@fiber.alive?
+
+        @fiber.resume
+      # Net::OpenTimeout, Net::ReadTimeout and Net::WriteTimeout all descend
+      # from Timeout::Error, so this one clause covers connect, read and write.
+      rescue Timeout::Error => e
+        close
+        raise Runtype::APITimeoutError, "Request timed out: #{e.message}"
+      rescue OpenSSL::SSL::SSLError, SocketError, SystemCallError, IOError => e
+        close
+        raise Runtype::APIConnectionError, "Connection failed: #{e.message}"
+      end
+
+      # @param uri [URI::Generic]
+      # @return [Net::HTTP]
+      def build_http(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+        # Retrying a dispatch would run the execution twice, so the streaming
+        # path never replays a request.
+        http.max_retries = 0
+        if @timeout
+          http.open_timeout = @timeout
+          http.read_timeout = @timeout
+          http.write_timeout = @timeout
+        end
+        http
+      end
+
+      # @param uri [URI::Generic]
+      # @return [Net::HTTPGenericRequest]
+      def build_request(uri)
+        klass = Net::HTTP.const_get(@method.capitalize)
+        request = klass.new(uri)
+        @headers.each { |name, value| request[name.to_s] = value.to_s }
+        request.body = @body if @body
+        request
+      end
+    end
+  end
+end

data/lib/runtype/streaming/event.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Runtype
+  module Streaming
+    # One frame off an execution stream.
+    #
+    # Execution streams speak the unified 33-event vocabulary defined by
+    # `unifiedSSEEventSchema` in `@runtypelabs/shared`. Rather than mirror those
+    # 33 shapes as Ruby classes (they evolve with the platform and would go
+    # stale between releases), an event keeps its payload as a plain Hash with
+    # string keys, exactly as it arrived on the wire, and exposes the envelope
+    # fields every unified event carries.
+    class Event
+      # The two frames that end a stream. A producer emits exactly one, and it
+      # is always its final frame.
+      TERMINAL_TYPES = %w[execution_complete execution_error].freeze
+
+      # `await` with this reason means a Claude Managed watch budget expired.
+      # The stream ends but the execution keeps running server-side, so this is
+      # never an error: hold the reconnect handle and render "still working".
+      DETACHED_AWAIT_REASON = "detached"
+
+      # @return [String] the event type, e.g. "text_delta".
+      attr_reader :type
+
+      # @return [Hash] the decoded JSON payload, string keys.
+      attr_reader :data
+
+      # @return [String] the payload exactly as it arrived.
+      attr_reader :raw_data
+
+      # @return [String, nil] the SSE `id:` in effect for this event.
+      attr_reader :id
+
+      # @return [Integer, nil] the SSE `retry:` in effect, in milliseconds.
+      attr_reader :retry_ms
+
+      # Builds an event from a dispatched SSE frame.
+      #
+      # @param event_type [String, nil] the SSE `event:` field.
+      # @param raw_data [String] the joined `data:` lines.
+      # @param id [String, nil]
+      # @param retry_ms [Integer, nil]
+      # @return [Runtype::Streaming::Event, nil] nil for the `[DONE]` sentinel.
+      def self.from_frame(event_type:, raw_data:, id: nil, retry_ms: nil)
+        trimmed = raw_data.strip
+        return nil if trimmed.empty? || trimmed == "[DONE]"
+
+        new(event_type: event_type, data: decode(trimmed), raw_data: raw_data, id: id, retry_ms: retry_ms)
+      end
+
+      # @param payload [String]
+      # @return [Hash]
+      def self.decode(payload)
+        parsed = JSON.parse(payload)
+        parsed.is_a?(Hash) ? parsed : { "data" => parsed }
+      rescue JSON::ParserError
+        { "data" => payload }
+      end
+      private_class_method :decode
+
+      # @param event_type [String, nil]
+      # @param data [Hash]
+      # @param raw_data [String]
+      # @param id [String, nil]
+      # @param retry_ms [Integer, nil]
+      def initialize(event_type:, data:, raw_data:, id: nil, retry_ms: nil)
+        @data = data
+        @raw_data = raw_data
+        @id = id
+        @retry_ms = retry_ms
+        # The SSE `event:` line and the payload's own `type` agree on every
+        # unified frame. Prefer the line, fall back to the payload, and only
+        # then to the SSE default type.
+        @type = event_type || data["type"] || "message"
+      end
+
+      # Reads a payload field.
+      #
+      # @param key [String, Symbol]
+      # @return [Object, nil]
+      def [](key)
+        @data[key.to_s]
+      end
+
+      # @return [String, nil] the execution this event belongs to.
+      def execution_id
+        @data["executionId"]
+      end
+
+      # @return [Integer, nil] the request-scoped, 0-based sequence number.
+      def seq
+        @data["seq"]
+      end
+
+      # @return [Boolean] whether this frame ends the stream.
+      def terminal?
+        TERMINAL_TYPES.include?(@type)
+      end
+
+      # @return [Boolean] whether the execution continues server-side after the
+      #   stream closes. See {DETACHED_AWAIT_REASON}.
+      def detached?
+        @type == "await" && @data["awaitReason"] == DETACHED_AWAIT_REASON
+      end
+
+      # @return [Hash] the payload.
+      def to_h
+        @data
+      end
+
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} type=#{@type.inspect} seq=#{seq.inspect} id=#{@id.inspect}>"
+      end
+    end
+  end
+end

data/lib/runtype/streaming/event_parser.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Runtype
+  module Streaming
+    # WHATWG-conformant SSE field parser.
+    #
+    # Lines arrive one at a time (see {LineDecoder}) and an event is dispatched
+    # on the blank line that terminates a frame. Follows the HTML Standard's
+    # "interpret the event stream" algorithm:
+    #
+    # - a line starting with ":" is a comment and is ignored
+    # - a line without a colon is a field name with an empty value
+    # - one leading space is stripped from the value
+    # - multiple `data:` lines are joined with "\n"; the trailing newline is
+    #   removed when the event is dispatched
+    # - `id` persists across events until the next `id` field (a value
+    #   containing a NUL is ignored); `retry` persists likewise
+    # - a frame with an empty data buffer dispatches nothing but still resets
+    #   the event type
+    class EventParser
+      # A NUL in an SSE `id` value makes the field invalid per the HTML
+      # Standard, so the previous id stays in effect.
+      NUL = "\u0000"
+
+      def initialize
+        reset_frame
+        @last_event_id = nil
+        @retry_ms = nil
+      end
+
+      # @return [String, nil] the most recent SSE `id:` value.
+      attr_reader :last_event_id
+
+      # @return [Integer, nil] the most recent SSE `retry:` value, in ms.
+      attr_reader :retry_ms
+
+      # Feeds one line.
+      #
+      # @param line [String] a line with its terminator already stripped.
+      # @return [Runtype::Streaming::Event, nil] the dispatched event, when this
+      #   line ended a frame that carried data.
+      def feed(line)
+        return dispatch if line.empty?
+        return nil if line.start_with?(":")
+
+        name, value = split_field(line)
+        case name
+        when "event" then @event_type = value
+        when "data" then @data << value << "\n"
+        when "id" then @last_event_id = value unless value.include?(NUL)
+        when "retry" then @retry_ms = value.to_i if value.match?(/\A\d+\z/)
+        end
+        nil
+      end
+
+      # Dispatches a frame that the stream ended without a blank line after.
+      #
+      # @return [Runtype::Streaming::Event, nil]
+      def flush
+        dispatch
+      end
+
+      private
+
+      # @return [Runtype::Streaming::Event, nil]
+      def dispatch
+        if @data.empty?
+          reset_frame
+          return nil
+        end
+
+        # delete_suffix, not chomp: chomp would also eat a trailing CR that was
+        # part of the data value rather than the framing.
+        raw = @data.delete_suffix("\n")
+        event_type = @event_type
+        reset_frame
+        Event.from_frame(event_type: event_type, raw_data: raw, id: @last_event_id, retry_ms: @retry_ms)
+      end
+
+      # @param line [String]
+      # @return [Array(String, String)] field name and value.
+      def split_field(line)
+        index = line.index(":")
+        return [line, ""] if index.nil?
+
+        value = line[(index + 1)..] || ""
+        value = value[1..] || "" if value.start_with?(" ")
+        [line[0...index], value]
+      end
+
+      def reset_frame
+        @event_type = nil
+        @data = +""
+      end
+    end
+  end
+end

data/lib/runtype/streaming/event_stream.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Runtype
+  module Streaming
+    # An execution stream: chunks off the socket, fused with the line decoder
+    # and the SSE parser, exposed as an Enumerable of {Event}.
+    #
+    # The socket is closed when iteration ends, including when the caller
+    # breaks out of the block or an exception unwinds through it. A stream is
+    # single-use; iterating a consumed stream raises.
+    #
+    #   stream = client.dispatch_stream(flow: flow, record: record)
+    #   stream.each do |event|
+    #     puts event["delta"] if event.type == "text_delta"
+    #     break if event.type == "tool_start"   # socket still gets closed
+    #   end
+    class EventStream
+      include Enumerable
+
+      # @return [String, nil] the execution these events belong to. Available
+      #   once the first event carrying an `executionId` has been yielded.
+      attr_reader :execution_id
+
+      # @return [String, nil] the SSE id of the most recent event. Together
+      #   with {#execution_id} this is the reconnect handle: replay from where
+      #   the stream left off with `?after=<last_event_id>`.
+      attr_reader :last_event_id
+
+      # @param connection [Runtype::Streaming::Connection] a started connection.
+      def initialize(connection)
+        @connection = connection
+        @decoder = LineDecoder.new
+        @parser = EventParser.new
+        @consumed = false
+        @execution_id = nil
+        @last_event_id = nil
+      end
+
+      # @return [Integer, nil] the HTTP status of the streaming response.
+      def status
+        @connection.status
+      end
+
+      # @return [Hash] the response headers.
+      def headers
+        @connection.response_headers
+      end
+
+      # Yields every event, then closes the socket.
+      #
+      # @yieldparam event [Runtype::Streaming::Event]
+      # @return [self]
+      # @raise [ArgumentError] when called without a block. A stream cannot hand
+      #   out an external Enumerator without giving up the close guarantee.
+      # @raise [Runtype::Error] when the stream was already consumed.
+      def each
+        raise ArgumentError, "Runtype::Streaming::EventStream#each requires a block" unless block_given?
+        raise Runtype::Error, "This event stream has already been consumed" if @consumed
+
+        @consumed = true
+        begin
+          @connection.each_chunk do |chunk|
+            @decoder.decode(chunk).each do |line|
+              event = @parser.feed(line)
+              yield track(event) if event
+            end
+          end
+          @decoder.flush.each do |line|
+            event = @parser.feed(line)
+            yield track(event) if event
+          end
+          trailing = @parser.flush
+          yield track(trailing) if trailing
+        ensure
+          close
+        end
+        self
+      end
+
+      # Closes the underlying socket. Idempotent.
+      #
+      # @return [void]
+      def close
+        @connection.close
+      end
+
+      # @return [Boolean]
+      def closed?
+        @connection.closed?
+      end
+
+      # @return [Boolean] whether iteration has started.
+      def consumed?
+        @consumed
+      end
+
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} status=#{status.inspect} execution_id=#{@execution_id.inspect} closed=#{closed?}>"
+      end
+
+      private
+
+      # Records the reconnect handle carried by an event.
+      #
+      # @param event [Runtype::Streaming::Event]
+      # @return [Runtype::Streaming::Event]
+      def track(event)
+        @execution_id ||= event.execution_id
+        @last_event_id = event.id if event.id
+        event
+      end
+    end
+  end
+end

data/lib/runtype/streaming/line_decoder.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Runtype
+  module Streaming
+    # Reassembles a sequence of arbitrary byte chunks into complete SSE lines.
+    #
+    # Chunk boundaries fall wherever the network puts them, which means a single
+    # line, a CRLF pair, or a multi-byte UTF-8 character can straddle two
+    # chunks. Buffering happens on binary strings and splitting happens on the
+    # ASCII terminators only, so a multi-byte sequence is never cut in half: no
+    # UTF-8 byte other than the leading one falls in the ASCII range.
+    #
+    # All three SSE terminators are recognized: LF, CRLF, and a bare CR. A CR at
+    # the very end of the buffer is held back, because the LF completing a CRLF
+    # pair may arrive in the next chunk.
+    class LineDecoder
+      CR = 0x0D
+      LF = 0x0A
+
+      def initialize
+        @buffer = +""
+        @buffer.force_encoding(Encoding::BINARY)
+      end
+
+      # Feeds a chunk and returns every line it completed.
+      #
+      # @param chunk [String, nil] raw bytes from the socket.
+      # @return [Array<String>] complete lines, terminators stripped, UTF-8.
+      def decode(chunk)
+        return [] if chunk.nil? || chunk.empty?
+
+        @buffer << to_binary(chunk)
+        lines = []
+        while (index = terminator_index)
+          break if @buffer.getbyte(index) == CR && index == @buffer.bytesize - 1
+
+          lines << to_utf8(@buffer.byteslice(0, index))
+          consume(index + terminator_width(index))
+        end
+        lines
+      end
+
+      # Returns whatever is left in the buffer as a final, unterminated line.
+      # Called once the socket closes so a stream that does not end with a
+      # newline still surfaces its last frame.
+      #
+      # @return [Array<String>] zero or one line.
+      def flush
+        return [] if @buffer.empty?
+
+        remaining = @buffer
+        reset_buffer
+        remaining = remaining.byteslice(0, remaining.bytesize - 1) if remaining.getbyte(-1) == CR
+        [to_utf8(remaining)]
+      end
+
+      private
+
+      # @return [Integer, nil] byte offset of the earliest terminator, if any.
+      def terminator_index
+        [@buffer.index("\n".b), @buffer.index("\r".b)].compact.min
+      end
+
+      # @param index [Integer] offset of the terminator byte.
+      # @return [Integer] 2 for CRLF, 1 otherwise.
+      def terminator_width(index)
+        @buffer.getbyte(index) == CR && @buffer.getbyte(index + 1) == LF ? 2 : 1
+      end
+
+      # @param count [Integer] bytes to drop from the front of the buffer.
+      def consume(count)
+        rest = @buffer.byteslice(count, @buffer.bytesize - count)
+        if rest.nil? || rest.empty?
+          reset_buffer
+        else
+          @buffer = rest
+        end
+      end
+
+      def reset_buffer
+        @buffer = +""
+        @buffer.force_encoding(Encoding::BINARY)
+      end
+
+      # @param value [String]
+      # @return [String]
+      def to_binary(value)
+        value.to_s.dup.force_encoding(Encoding::BINARY)
+      end
+
+      # @param value [String]
+      # @return [String]
+      def to_utf8(value)
+        value.dup.force_encoding(Encoding::UTF_8)
+      end
+    end
+  end
+end

data/lib/runtype.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Runtype Ruby SDK.
+#
+# The gem ships two layers:
+#
+# - the generated low-level core (Fern, from the OpenAPI spec) under
+#   `generated/lib`: `Runtype::BaseClient`, one client per resource group, and
+#   typed models for every documented endpoint. Regenerated from the spec, never
+#   edited by hand.
+# - the hand-written overlay under `lib`: {Runtype::Client}, the `/v1/dispatch`
+#   SSE streaming path, and the curated error hierarchy. The generated core has
+#   no streaming support, so everything under {Runtype::Streaming} is
+#   hand-written on Net::HTTP.
+#
+# Requiring this file loads both.
+#
+#   require "runtype"
+#
+#   client = Runtype::Client.new(api_key: ENV["RUNTYPE_API_KEY"])
+#   client.dispatch_stream(agent: { id: "agt_123" }, messages: [...]) do |event|
+#     print event["delta"] if event.type == "text_delta"
+#   end
+require_relative "../generated/lib/runtype"
+
+require_relative "runtype/sdk_version"
+require_relative "runtype/errors"
+require_relative "runtype/streaming/event"
+require_relative "runtype/streaming/line_decoder"
+require_relative "runtype/streaming/event_parser"
+require_relative "runtype/streaming/connection"
+require_relative "runtype/streaming/event_stream"
+require_relative "runtype/client"
+
+module Runtype
+  # SSE streaming for execution endpoints.
+  module Streaming
+  end
+end