solid-resp-ractor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a7e50be310bd21524ea7a372f0f47b4d463d78ab6710df53a807433fa64c096
+  data.tar.gz: 88310b01fef02d445ac6a7c1c7d5b097bdcb68c80b8657c65dff638b1d9b090a
+SHA512:
+  metadata.gz: 0fe96b665160e1ea048e3fd18a1f6dc43a09423e7aceb6e5a27898590edfcbdc39ae798235cac25b5ec33a64e685dd7ccef4c8147c77823eda426aced1cd9522
+  data.tar.gz: 211d591e7acc734020c4641dd33915f7991ac55aa3bddcf674a5001eab4d1f0c91e2959e9f3beb036da17b971b970ec9dc1c4af4d11e787e279e947cf9036ee0

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.1.0] - 2026-09-29
+
+### Added
+
+- Dependency-free RESP2/RESP3 stream reader.
+- Immutable command encoder with injectable argument conversion.
+- Injectable byte sources, selectors, clocks, error mappers, and value
+  handlers.
+- Compatible and typed RESP3 handling modes.
+- Configurable limits for blob size, collection cardinality, nesting depth,
+  and line length.
+- Bounded stress coverage for large pipelines, fragmented streams, malformed
+  input, and parallel Ractors.
+- Ractor-shareable default encoder with no global mutable state.
+
+[0.1.0]: https://github.com/nicolasva/solid-resp-ractor/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolas Vandenbogaerde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,262 @@
+# Solid RESP Ractor
+
+`solid-resp-ractor` is a dependency-free RESP2/RESP3 codec for Ruby. It keeps
+protocol parsing independent from Redis client behavior and provides explicit
+extension points for transports, event loops, error hierarchies, value
+representation, and command argument conversion.
+
+The gem has no global mutable state. Immutable encoder instances can be shared
+between Ractors; readers remain local to the Ractor that owns their IO.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "solid-resp-ractor"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+## Encoding commands
+
+```ruby
+require "solid_resp_ractor"
+
+SolidRespRactor.encode(["SET", "key", "value"])
+# => "*3\r\n$3\r\nSET\r\n$3\r\nkey\r\n$5\r\nvalue\r\n"
+```
+
+Arrays are expanded by one level, which supports APIs that group command
+arguments:
+
+```ruby
+SolidRespRactor.encode(["MSET", ["first", 1], ["second", 2]])
+```
+
+Use an immutable custom encoder for domain-specific values:
+
+```ruby
+argument_encoder = Object.new
+
+def argument_encoder.call(value)
+  value.respond_to?(:to_wire) ? value.to_wire : value.to_s
+end
+
+argument_encoder.freeze
+
+encoder = SolidRespRactor::Encoder.new(argument_encoder: argument_encoder)
+encoder.encode(["SET", "key", custom_value])
+```
+
+Set `expand_arrays: false` when arrays represent individual values rather than
+argument groups.
+
+## Reusable codec configurations
+
+`Codec` groups all extension points into one immutable object:
+
+```ruby
+codec = SolidRespRactor::Codec.new(
+  encoder: custom_encoder,
+  handler: SolidRespRactor::Handlers::Typed,
+  error_mapper: error_mapper,
+  limits: SolidRespRactor::Limits.new(max_blob_size: 64 * 1024 * 1024),
+  chunk_size: 32_768,
+)
+
+payload = codec.encode(["PING"])
+reader = codec.reader(socket, read_timeout: 1.0)
+```
+
+`SolidRespRactor::DEFAULT_CODEC` is Ractor-shareable. A custom codec is also
+shareable when all injected collaborators are shareable.
+
+## Reading RESP streams
+
+The default reader accepts blocking IO objects such as `StringIO`, as well as
+non-blocking TCP, Unix, and TLS-compatible streams:
+
+```ruby
+socket = TCPSocket.new("127.0.0.1", 6379)
+reader = SolidRespRactor.reader(socket, read_timeout: 1.0)
+
+socket.write(SolidRespRactor.encode(["PING"]))
+reader.read
+# => "PONG"
+```
+
+Use `exception: false` for pipelines or proxies that need error values:
+
+```ruby
+result = reader.read(exception: false)
+
+if result.is_a?(SolidRespRactor::ResponseError)
+  warn result.message
+end
+```
+
+Nested errors are raised only after the complete aggregate has been consumed,
+so the next frame remains synchronized.
+
+## RESP3 types
+
+The compatible handler returns ordinary Ruby values and intentionally unwraps
+RESP3 sets, pushes, verbatim strings, and attributes:
+
+```ruby
+reader = SolidRespRactor::Reader.new(io)
+```
+
+Use the typed handler when those distinctions matter:
+
+```ruby
+reader = SolidRespRactor::Reader.new(
+  io,
+  handler: SolidRespRactor::Handlers::Typed,
+)
+
+case (value = reader.read)
+when SolidRespRactor::Types::Push
+  process_push(value.value)
+when SolidRespRactor::Types::Attribute
+  process(value.value, metadata: value.attributes)
+end
+```
+
+Typed values include:
+
+- `SolidRespRactor::Types::Set`
+- `SolidRespRactor::Types::Push`
+- `SolidRespRactor::Types::Verbatim`
+- `SolidRespRactor::Types::Attribute`
+
+RESP3 streamed blob strings, arrays, maps, and sets are supported as well as
+special double values (`inf`, `-inf`, and `nan`).
+
+## Resource limits
+
+The default immutable limits protect generic protocol consumers from
+unbounded allocations and nesting:
+
+| Limit | Default |
+|---|---:|
+| Blob or chunked string | 512 MiB |
+| Collection cardinality | 1,000,000 |
+| Nesting depth | 128 |
+| Line length | 64 KiB |
+
+Provide stricter limits for untrusted peers:
+
+```ruby
+limits = SolidRespRactor::Limits.new(
+  max_blob_size: 8 * 1024 * 1024,
+  max_collection_size: 10_000,
+  max_nesting_depth: 32,
+  max_line_size: 8 * 1024,
+)
+
+codec = SolidRespRactor::Codec.new(limits: limits)
+```
+
+## Extension points
+
+### Custom error mapping
+
+Map RESP error frames into an application's existing exception hierarchy:
+
+```ruby
+error_mapper = lambda do |message, blob:|
+  MyProtocolError.new(message)
+end
+
+reader = SolidRespRactor::Reader.new(io, error_mapper: error_mapper)
+```
+
+The mapper must return an `Exception`.
+
+### Custom value handling
+
+Every decoded value can be transformed:
+
+```ruby
+handler = lambda do |type, value|
+  Event.new(type:, value:)
+end
+
+reader = SolidRespRactor::Reader.new(io, handler: handler)
+```
+
+### Custom byte sources
+
+A source only needs:
+
+```ruby
+class Source
+  def read(timeout:)
+    # Return a non-empty String, or nil at EOF.
+  end
+
+  def wait_readable(timeout)
+    # Optional polling API.
+  end
+end
+
+reader = SolidRespRactor::Reader.new(source: Source.new)
+```
+
+This allows integration with event loops, in-memory transports, framed
+protocols, instrumentation, or test fixtures without changing the parser.
+
+The built-in `Sources::IO` also accepts custom `selector` and `clock` objects.
+
+## Timeouts and blocking commands
+
+`read_timeout: nil` waits indefinitely. Temporarily override a timeout without
+rebuilding the reader:
+
+```ruby
+reader.with_timeout(nil) do
+  reader.read
+end
+```
+
+`wait_readable(timeout)` polls without consuming bytes, which is useful for
+subscriptions and event-driven clients.
+
+## Ractor usage
+
+The default encoder is shareable:
+
+```ruby
+encoder = SolidRespRactor::DEFAULT_ENCODER
+
+ractor = Ractor.new(encoder) do |shared_encoder|
+  socket = TCPSocket.new("127.0.0.1", 6379)
+  reader = SolidRespRactor::Reader.new(socket, read_timeout: 1.0)
+
+  socket.write(shared_encoder.encode(["PING"]))
+  reader.read
+ensure
+  socket&.close
+end
+
+ractor.take
+```
+
+Create sockets and readers inside their owning Ractor. Custom handlers,
+encoders, selectors, and clocks must themselves be Ractor-shareable if they
+are passed between Ractors.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+```
+
+The default task runs the tests and builds the gem.

data/lib/solid_resp_ractor/codec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SolidRespRactor
+  class Codec
+    attr_reader :encoder, :handler, :error_mapper, :limits, :chunk_size,
+      :selector, :clock
+
+    def initialize(
+      encoder: DEFAULT_ENCODER,
+      handler: Handlers::Compatible,
+      error_mapper: ErrorMappers::Default,
+      limits: Limits::DEFAULT,
+      chunk_size: 16_384,
+      selector: Selectors::IOSelect,
+      clock: Clocks::Monotonic
+    )
+      @encoder = encoder
+      @handler = handler
+      @error_mapper = error_mapper
+      @limits = limits
+      @chunk_size = Integer(chunk_size)
+      raise ArgumentError, "chunk_size must be positive" unless @chunk_size.positive?
+
+      @selector = selector
+      @clock = clock
+      freeze
+    end
+
+    def encode(command)
+      @encoder.encode(command)
+    end
+
+    def reader(io = nil, source: nil, read_timeout: nil)
+      Reader.new(
+        io,
+        source: source,
+        read_timeout: read_timeout,
+        handler: @handler,
+        error_mapper: @error_mapper,
+        limits: @limits,
+        chunk_size: @chunk_size,
+        selector: @selector,
+        clock: @clock,
+      )
+    end
+  end
+
+  DEFAULT_CODEC = Codec.new
+  Ractor.make_shareable(DEFAULT_CODEC) if defined?(Ractor)
+end

data/lib/solid_resp_ractor/encoder.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SolidRespRactor
+  module ArgumentEncoders
+    module Default
+      module_function
+
+      def call(value)
+        case value
+        when String then value
+        when Symbol, Integer, Float then value.to_s
+        when true then "1"
+        when false then "0"
+        when nil then ""
+        else value.to_s
+        end
+      end
+    end
+  end
+
+  class Encoder
+    CRLF = "\r\n"
+
+    attr_reader :argument_encoder
+
+    def initialize(argument_encoder: ArgumentEncoders::Default, expand_arrays: true)
+      @argument_encoder = argument_encoder
+      @expand_arrays = expand_arrays
+      freeze
+    end
+
+    def encode(command)
+      length = command.sum { |argument| expanded?(argument) ? argument.length : 1 }
+      raise ArgumentError, "RESP command cannot be empty" if length.zero?
+
+      command.each_with_object(+"*#{length}#{CRLF}") do |argument, buffer|
+        if expanded?(argument)
+          argument.each { |value| append_argument(buffer, value) }
+        else
+          append_argument(buffer, argument)
+        end
+      end
+    end
+
+    private
+
+    def expanded?(argument)
+      @expand_arrays && argument.is_a?(Array)
+    end
+
+    def append_argument(buffer, argument)
+      value = @argument_encoder.call(argument)
+      unless value.is_a?(String)
+        raise TypeError, "argument encoder must return a String, got #{value.class}"
+      end
+
+      buffer << "$#{value.bytesize}#{CRLF}#{value}#{CRLF}"
+    end
+  end
+
+  DEFAULT_ENCODER = Encoder.new
+  Ractor.make_shareable(DEFAULT_ENCODER) if defined?(Ractor)
+end

data/lib/solid_resp_ractor/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SolidRespRactor
+  class Error < StandardError; end
+  class ConnectionError < Error; end
+  class TimeoutError < ConnectionError; end
+  class ProtocolError < Error; end
+  class ResponseError < Error; end
+  class AuthenticationError < ResponseError; end
+
+  module ErrorMappers
+    module Default
+      module_function
+
+      def call(message, blob:)
+        error_class = if message.start_with?("NOAUTH", "WRONGPASS")
+          AuthenticationError
+        else
+          ResponseError
+        end
+        error_class.new(message)
+      end
+    end
+  end
+end

data/lib/solid_resp_ractor/limits.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SolidRespRactor
+  class Limits
+    attr_reader :max_blob_size, :max_collection_size, :max_nesting_depth,
+      :max_line_size
+
+    def initialize(
+      max_blob_size: 512 * 1024 * 1024,
+      max_collection_size: 1_000_000,
+      max_nesting_depth: 128,
+      max_line_size: 64 * 1024
+    )
+      @max_blob_size = positive_integer(max_blob_size, :max_blob_size)
+      @max_collection_size = positive_integer(max_collection_size, :max_collection_size)
+      @max_nesting_depth = positive_integer(max_nesting_depth, :max_nesting_depth)
+      @max_line_size = positive_integer(max_line_size, :max_line_size)
+      freeze
+    end
+
+    private
+
+    def positive_integer(value, name)
+      value = Integer(value)
+      raise ArgumentError, "#{name} must be positive" unless value.positive?
+
+      value
+    end
+
+    DEFAULT = new
+    Ractor.make_shareable(DEFAULT) if defined?(Ractor)
+  end
+end

data/lib/solid_resp_ractor/reader.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module SolidRespRactor
+  class Reader
+    CRLF = "\r\n"
+
+    attr_reader :source
+
+    def initialize(
+      io = nil,
+      source: nil,
+      read_timeout: nil,
+      handler: Handlers::Compatible,
+      error_mapper: ErrorMappers::Default,
+      limits: Limits::DEFAULT,
+      chunk_size: 16_384,
+      selector: Selectors::IOSelect,
+      clock: Clocks::Monotonic
+    )
+      if io && source
+        raise ArgumentError, "pass either io or source, not both"
+      end
+      raise ArgumentError, "io or source is required" unless io || source
+
+      @source = source || Sources::IO.new(
+        io,
+        chunk_size: chunk_size,
+        selector: selector,
+        clock: clock,
+      )
+      @read_timeout = read_timeout
+      @handler = handler
+      @error_mapper = error_mapper
+      @limits = limits
+      @buffer = +""
+      @offset = 0
+      @read_depth = 0
+      @captured_error = nil
+    end
+
+    def with_timeout(timeout)
+      previous = @read_timeout
+      @read_timeout = timeout
+      yield
+    ensure
+      @read_timeout = previous
+    end
+
+    def wait_readable(timeout)
+      return true if available_bytes.positive?
+      return true unless @source.respond_to?(:wait_readable)
+
+      @source.wait_readable(timeout)
+    end
+
+    def read(exception: true)
+      top_level = @read_depth.zero?
+      @captured_error = nil if top_level
+      @read_depth += 1
+      if @read_depth > @limits.max_nesting_depth
+        raise ProtocolError, "RESP nesting exceeds #{@limits.max_nesting_depth}"
+      end
+      value = read_type(read_bytes(1))
+      raise @captured_error if top_level && exception && @captured_error
+
+      value
+    rescue EOFError
+      raise ConnectionError, "RESP stream closed"
+    ensure
+      @read_depth -= 1
+    end
+
+    private
+
+    def read_type(type)
+      case type
+      when "+" then handle(:simple_string, read_line)
+      when "-" then error_response(read_line, blob: false)
+      when ":" then handle(:integer, parse_integer(read_line))
+      when "$" then read_blob
+      when "*" then read_array
+      when "_" then read_null
+      when "#" then read_boolean
+      when "," then handle(:double, parse_float(read_line))
+      when "(" then handle(:big_number, parse_integer(read_line))
+      when "%" then read_map
+      when "~" then read_collection(:set)
+      when ">" then read_collection(:push)
+      when "=" then read_verbatim
+      when "!" then error_response(read_sized_string(streamed: true), blob: true)
+      when "|" then read_attribute
+      else raise ProtocolError, "Unknown RESP type byte: #{type.inspect}"
+      end
+    end
+
+    def read_blob
+      length = read_length(nullable: true, streamed: true)
+      return handle(:blob_string, nil) unless length
+
+      validate_blob_length(length) unless length == :streamed
+      value = length == :streamed ? read_chunked_string : read_sized_value(length)
+      handle(:blob_string, value)
+    end
+
+    def read_array
+      length = read_length(nullable: true, streamed: true)
+      return handle(:array, nil) unless length
+
+      validate_collection_length(length) unless length == :streamed
+      value = if length == :streamed
+        read_streamed_collection
+      else
+        Array.new(length) { read(exception: false) }
+      end
+      handle(:array, value)
+    end
+
+    def read_collection(type)
+      length = read_length(streamed: true)
+      validate_collection_length(length) unless length == :streamed
+      value = if length == :streamed
+        read_streamed_collection
+      else
+        Array.new(length) { read(exception: false) }
+      end
+      handle(type, value)
+    end
+
+    def read_map
+      length = read_length(streamed: true)
+      validate_collection_length(length) unless length == :streamed
+      value = if length == :streamed
+        read_streamed_map
+      else
+        {}.tap do |result|
+          length.times { result[read(exception: false)] = read(exception: false) }
+        end
+      end
+      handle(:map, value)
+    end
+
+    def read_streamed_collection
+      values = []
+      loop do
+        type = read_bytes(1)
+        break if aggregate_end?(type)
+
+        values << read_type(type)
+        validate_collection_length(values.length)
+      end
+      values
+    end
+
+    def read_streamed_map
+      {}.tap do |result|
+        count = 0
+        loop do
+          type = read_bytes(1)
+          break if aggregate_end?(type)
+
+          key = read_type(type)
+          result[key] = read(exception: false)
+          count += 1
+          validate_collection_length(count)
+        end
+      end
+    end
+
+    def aggregate_end?(type)
+      return false unless type == "."
+
+      value = read_line
+      raise ProtocolError, "RESP aggregate terminator must not contain data" unless value.empty?
+
+      true
+    end
+
+    def read_attribute
+      attributes = read_map
+      value = read(exception: false)
+      handle(:attribute, [attributes, value])
+    end
+
+    def read_null
+      value = read_line
+      raise ProtocolError, "RESP null must not contain data" unless value.empty?
+
+      handle(:null, nil)
+    end
+
+    def read_boolean
+      case (value = read_line)
+      when "t" then handle(:boolean, true)
+      when "f" then handle(:boolean, false)
+      else raise ProtocolError, "Invalid RESP boolean: #{value.inspect}"
+      end
+    end
+
+    def read_verbatim
+      value = read_sized_string(streamed: true)
+      unless value.bytesize >= 4 && value.byteslice(3, 1) == ":"
+        raise ProtocolError, "Invalid RESP verbatim string"
+      end
+
+      handle(:verbatim, [value.byteslice(0, 3).freeze, value.byteslice(4..)])
+    end
+
+    def read_sized_string(streamed: false)
+      length = read_length(streamed: streamed)
+      validate_blob_length(length) unless length == :streamed
+      length == :streamed ? read_chunked_string : read_sized_value(length)
+    end
+
+    def read_chunked_string
+      buffer = +""
+      loop do
+        type = read_bytes(1)
+        raise ProtocolError, "Expected RESP chunk, got #{type.inspect}" unless type == ";"
+
+        length = read_length
+        break if length.zero?
+
+        validate_blob_length(buffer.bytesize + length)
+        buffer << read_sized_value(length)
+      end
+      buffer
+    end
+
+    def read_sized_value(length)
+      value = read_bytes(length)
+      actual = read_bytes(2)
+      raise ProtocolError, "Expected CRLF, got #{actual.inspect}" unless actual == CRLF
+
+      value
+    end
+
+    def read_length(nullable: false, streamed: false)
+      value = read_line
+      return :streamed if streamed && value == "?"
+
+      length = parse_integer(value)
+      return if nullable && length == -1
+      raise ProtocolError, "Invalid RESP length: #{length}" if length.negative?
+
+      length
+    end
+
+    def parse_integer(value)
+      Integer(value)
+    rescue ArgumentError
+      raise ProtocolError, "Invalid RESP integer: #{value.inspect}"
+    end
+
+    def parse_float(value)
+      return Float::INFINITY if value == "inf"
+      return -Float::INFINITY if value == "-inf"
+      return Float::NAN if value == "nan"
+
+      Float(value)
+    rescue ArgumentError
+      raise ProtocolError, "Invalid RESP double: #{value.inspect}"
+    end
+
+    def read_line
+      loop do
+        if (index = @buffer.index(CRLF, @offset))
+          line_length = index - @offset
+          if line_length > @limits.max_line_size
+            raise ProtocolError, "RESP line exceeds #{@limits.max_line_size} bytes"
+          end
+          value = @buffer.byteslice(@offset, line_length)
+          @offset = index + 2
+          clear_consumed_buffer
+          return value
+        end
+        if available_bytes > @limits.max_line_size
+          raise ProtocolError, "RESP line exceeds #{@limits.max_line_size} bytes"
+        end
+        fill_buffer
+      end
+    end
+
+    def read_bytes(length)
+      fill_buffer while available_bytes < length
+      value = @buffer.byteslice(@offset, length)
+      @offset += length
+      clear_consumed_buffer
+      value
+    end
+
+    def fill_buffer
+      compact_buffer
+      chunk = @source.read(timeout: @read_timeout)
+      raise EOFError if chunk.nil?
+      unless chunk.is_a?(String)
+        raise ProtocolError, "RESP source must return a String or nil, got #{chunk.class}"
+      end
+      raise ProtocolError, "RESP source returned an empty chunk" if chunk.empty?
+
+      @buffer << chunk
+    end
+
+    def available_bytes
+      @buffer.bytesize - @offset
+    end
+
+    def clear_consumed_buffer
+      return unless @offset == @buffer.bytesize
+
+      @buffer.clear
+      @offset = 0
+    end
+
+    def compact_buffer
+      return if @offset.zero?
+
+      @buffer = @buffer.byteslice(@offset..) || +""
+      @offset = 0
+    end
+
+    def error_response(message, blob:)
+      error = @error_mapper.call(message, blob: blob)
+      unless error.is_a?(Exception)
+        raise TypeError, "error mapper must return an Exception, got #{error.class}"
+      end
+      @captured_error ||= error
+      error
+    end
+
+    def validate_blob_length(length)
+      return if length <= @limits.max_blob_size
+
+      raise ProtocolError, "RESP blob exceeds #{@limits.max_blob_size} bytes"
+    end
+
+    def validate_collection_length(length)
+      return if length <= @limits.max_collection_size
+
+      raise ProtocolError,
+        "RESP collection exceeds #{@limits.max_collection_size} elements"
+    end
+
+    def handle(type, value)
+      @handler.call(type, value)
+    end
+  end
+end

data/lib/solid_resp_ractor/source.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module SolidRespRactor
+  module Clocks
+    module Monotonic
+      module_function
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+
+  module Selectors
+    module IOSelect
+      module_function
+
+      def call(readers, writers, timeout)
+        IO.select(readers, writers, nil, timeout)
+      end
+    end
+  end
+
+  module Sources
+    class IO
+      def initialize(
+        io,
+        chunk_size: 16_384,
+        selector: Selectors::IOSelect,
+        clock: Clocks::Monotonic
+      )
+        @io = io
+        @chunk_size = Integer(chunk_size)
+        raise ArgumentError, "chunk_size must be positive" unless @chunk_size.positive?
+
+        @selector = selector
+        @clock = clock
+      end
+
+      def read(timeout:)
+        return blocking_read unless @io.respond_to?(:read_nonblock)
+
+        deadline = nil
+        loop do
+          chunk = @io.read_nonblock(@chunk_size, exception: false)
+          return chunk unless chunk == :wait_readable || chunk == :wait_writable
+
+          deadline ||= @clock.now + timeout if timeout
+          remaining = deadline && deadline - @clock.now
+          raise_timeout(timeout) if remaining && remaining <= 0
+
+          selectable = @io.respond_to?(:to_io) ? @io.to_io : @io
+          readers = chunk == :wait_readable ? [selectable] : nil
+          writers = chunk == :wait_writable ? [selectable] : nil
+          raise_timeout(timeout) unless @selector.call(readers, writers, remaining)
+        end
+      rescue IOError, SystemCallError => error
+        raise ConnectionError, error.message, cause: error
+      end
+
+      def wait_readable(timeout)
+        return true unless @io.respond_to?(:to_io)
+
+        !@selector.call([@io.to_io], nil, timeout).nil?
+      rescue IOError, SystemCallError => error
+        raise ConnectionError, error.message, cause: error
+      end
+
+      private
+
+      def blocking_read
+        @io.read(@chunk_size)
+      end
+
+      def raise_timeout(timeout)
+        raise TimeoutError, "RESP read timed out after #{timeout}s"
+      end
+    end
+  end
+end

data/lib/solid_resp_ractor/types.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module SolidRespRactor
+  module Types
+    class Collection
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+        freeze
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && other.value == value
+      end
+    end
+
+    class Set < Collection; end
+    class Push < Collection; end
+
+    class Verbatim
+      attr_reader :format, :data
+
+      def initialize(format, data)
+        @format = format.freeze
+        @data = data
+        freeze
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && other.format == format && other.data == data
+      end
+    end
+
+    class Attribute
+      attr_reader :attributes, :value
+
+      def initialize(attributes, value)
+        @attributes = attributes
+        @value = value
+        freeze
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) &&
+          other.attributes == attributes &&
+          other.value == value
+      end
+    end
+  end
+
+  module Handlers
+    module Compatible
+      module_function
+
+      def call(type, value)
+        case type
+        when :verbatim then value.fetch(1)
+        when :attribute then value.fetch(1)
+        else value
+        end
+      end
+    end
+
+    module Typed
+      module_function
+
+      def call(type, value)
+        case type
+        when :set then Types::Set.new(value)
+        when :push then Types::Push.new(value)
+        when :verbatim then Types::Verbatim.new(*value)
+        when :attribute then Types::Attribute.new(*value)
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/solid_resp_ractor/version.rb

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

data/lib/solid_resp_ractor.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "solid_resp_ractor/version"
+require_relative "solid_resp_ractor/errors"
+require_relative "solid_resp_ractor/types"
+require_relative "solid_resp_ractor/limits"
+require_relative "solid_resp_ractor/encoder"
+require_relative "solid_resp_ractor/source"
+require_relative "solid_resp_ractor/reader"
+require_relative "solid_resp_ractor/codec"
+
+module SolidRespRactor
+  module_function
+
+  def encode(command, encoder: DEFAULT_ENCODER)
+    encoder.encode(command)
+  end
+
+  def reader(io = nil, source: nil, read_timeout: nil, codec: DEFAULT_CODEC)
+    codec.reader(io, source: source, read_timeout: read_timeout)
+  end
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: solid-resp-ractor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nicolas Vandenbogaerde
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Dependency-free RESP command encoding and stream decoding with injectable
+  sources, selectors, clocks, error mappers, and RESP3 type handlers.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/solid_resp_ractor.rb
+- lib/solid_resp_ractor/codec.rb
+- lib/solid_resp_ractor/encoder.rb
+- lib/solid_resp_ractor/errors.rb
+- lib/solid_resp_ractor/limits.rb
+- lib/solid_resp_ractor/reader.rb
+- lib/solid_resp_ractor/source.rb
+- lib/solid_resp_ractor/types.rb
+- lib/solid_resp_ractor/version.rb
+homepage: https://github.com/nicolasva/solid-resp-ractor
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/nicolasva/solid-resp-ractor
+  changelog_uri: https://github.com/nicolasva/solid-resp-ractor/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: A modular, Ractor-friendly RESP2/RESP3 codec
+test_files: []