thuban 0.3.0 → 0.4.0

data/lib/thuban/remote/fetch.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module Thuban
+  module Remote
+    class Connection
+      MAX_FETCH_RESPONSE_SIZE = Pack::MAX_PACK_SIZE
+      MAX_NEGOTIATION_OIDS = 10_000
+
+      def fetch(repository, wants:, haves: [], depth: nil, filter: nil)
+        ensure_open
+        raise TypeError, "expected Thuban::Repository" unless repository.is_a?(Repository)
+        depth = Protocol.validate_depth(depth)
+        filter = Protocol.validate_filter(filter)
+
+        wants = oid_list(wants, "wants", empty: false)
+        haves = oid_list(haves, "haves", empty: true)
+        raise ArgumentError, "have object not found" unless haves.all? { |oid| repository.odb.exist?(oid) }
+
+        refs unless @protocol_version
+        shallow = read_shallow(repository)
+        validate_fetch_capabilities(depth, filter, shallow)
+        body = if @protocol_version == 2
+          v2_fetch_request(wants, haves, shallow, depth, filter, progress: block_given?)
+        else
+          v0_fetch_request(wants, haves, shallow, depth, filter, progress: block_given?)
+        end
+        Tempfile.create(["thuban-fetch-response-", ".bin"]) do |response|
+          response.binmode
+          request_to(response, :post, "/git-upload-pack", body: body,
+            headers: {"Content-Type" => "application/x-git-upload-pack-request", "Accept" => "application/x-git-upload-pack-result",
+                      "Git-Protocol" => "version=2"}, content_type: "application/x-git-upload-pack-result",
+            limit: MAX_FETCH_RESPONSE_SIZE)
+          response.flush
+          response.rewind
+          Tempfile.create(["thuban-fetch-pack-", ".pack"]) do |pack|
+            pack.binmode
+            changes = extract_fetch_response(response, pack, allow_shallow: depth || !shallow.empty?) do |event|
+              yield event if block_given?
+            end
+            pack.flush
+            pack.rewind
+            ensure_open
+            received = Pack.read_stream(pack, repository.odb) do |current, total|
+              ensure_open
+              yield Progress.new(phase: :pack, current: current, total: total, bytes: pack.size) if block_given?
+            end
+            ensure_open
+            raise TransportError, "fetch did not provide requested objects" unless wants.all? { |oid| repository.odb.exist?(oid) }
+            update_shallow(repository, shallow, changes)
+
+            received
+          end
+        end
+      end
+
+      private
+
+      def oid_list(value, name, empty:)
+        raise TypeError, "#{name} must be enumerable" unless value.respond_to?(:each)
+
+        result = []
+        seen = {}
+        count = 0
+        value.each do |oid|
+          count += 1
+          raise ArgumentError, "too many #{name}" if count > MAX_NEGOTIATION_OIDS
+
+          oid = Protocol.validate_oid(oid)
+          result << oid unless seen[oid]
+          seen[oid] = true
+        end
+        raise ArgumentError, "at least one want is required" if !empty && result.empty?
+
+        result
+      end
+
+      def validate_fetch_capabilities(depth, filter, shallow)
+        if @protocol_version == 2
+          capability = @capabilities.find { |line| line.split("=", 2).first == "fetch" }
+          raise TransportError, "server does not support fetch" unless capability
+
+          features = capability.split("=", 2).last.to_s.split
+        else
+          features = @capabilities
+        end
+        raise TransportError, "server does not support shallow fetch" if (depth || !shallow.empty?) && !features.include?("shallow")
+        raise TransportError, "server does not support partial fetch" if filter && !features.include?("filter")
+      end
+
+      def v2_fetch_request(wants, haves, shallow, depth, filter, progress:)
+        lines = ["ofs-delta"]
+        lines << "no-progress" unless progress
+        lines.concat(shallow.map { |oid| "shallow #{oid}" })
+        lines << "deepen #{depth}" if depth
+        lines << "filter #{filter}" if filter
+        lines.concat(wants.map { |oid| "want #{oid}" })
+        lines.concat(haves.map { |oid| "have #{oid}" })
+        lines << "done"
+        Protocol.packet("command=fetch\n") + Protocol.delimiter +
+          lines.map { |line| Protocol.packet("#{line}\n") }.join + Protocol.flush
+      end
+
+      def v0_fetch_request(wants, haves, shallow, depth, filter, progress:)
+        requested = [(!progress && "no-progress"), "side-band-64k", "ofs-delta", (filter && "filter")].compact
+        capabilities = requested.select { |capability| @capabilities.include?(capability) }
+        lines = wants.each_with_index.map do |oid, index|
+          suffix = index.zero? && !capabilities.empty? ? " #{capabilities.join(' ')}" : ""
+          Protocol.packet("want #{oid}#{suffix}\n")
+        end
+        lines.concat(shallow.map { |oid| Protocol.packet("shallow #{oid}\n") })
+        lines << Protocol.packet("deepen #{depth}\n") if depth
+        lines << Protocol.packet("filter #{filter}\n") if filter
+        lines.join + Protocol.flush + haves.map { |oid| Protocol.packet("have #{oid}\n") }.join +
+          Protocol.packet("done\n")
+      end
+
+      def extract_fetch_response(input, output, allow_shallow: true)
+        reader = Protocol::Reader.new(input, max_bytes: MAX_FETCH_RESPONSE_SIZE)
+        packfile = @protocol_version.zero?
+        received = false
+        raw = false
+        terminated = false
+        section = nil
+        section_index = -1
+        shallow = []
+        unshallow = []
+        loop do
+          ensure_open
+          if packfile && raw_pack?(input)
+            copy_raw_pack(input, output) { |event| yield event if block_given? }
+            received = true
+            raw = true
+            break
+          end
+          packet = reader.read
+          break if packet.nil?
+          if packet == Protocol::RESPONSE_END
+            terminated = true
+            break
+          end
+          if packet == Protocol::FLUSH
+            if received || @protocol_version == 2
+              terminated = true
+              break
+            end
+            next
+          end
+          if packet == Protocol::DELIMITER
+            raise TransportError, "invalid fetch response delimiter" unless @protocol_version == 2 && section && section != "packfile"
+
+            section = nil
+            next
+          end
+          raise TransportError, "invalid fetch response" unless packet.is_a?(String)
+          raise TransportError, safe_message(packet.delete_prefix("ERR ")) if packet.start_with?("ERR ")
+
+          if @protocol_version == 2 && %w[acknowledgments shallow-info packfile].include?(packet.chomp)
+            next_section = packet.chomp
+            next_index = %w[acknowledgments shallow-info packfile].index(next_section)
+            raise TransportError, "invalid fetch response section" unless section.nil? && next_index > section_index
+
+            section = next_section
+            section_index = next_index
+            packfile = section == "packfile"
+          elsif packet.start_with?("shallow ", "unshallow ")
+            valid_section = @protocol_version.zero? || section == "shallow-info"
+            raise TransportError, "unexpected shallow response" unless allow_shallow && valid_section
+
+            state, oid = packet.chomp.split(" ", 2)
+            oid = Protocol.validate_oid(oid)
+            (state == "shallow" ? shallow : unshallow) << oid
+          elsif acknowledgment?(packet)
+            raise TransportError, "unexpected acknowledgment" unless @protocol_version.zero? || section == "acknowledgments"
+          elsif packfile
+            received = append_sideband(packet, output) { |event| yield event if block_given? } || received
+          else
+            raise TransportError, "unexpected fetch response section"
+          end
+        end
+        raise TransportError, "fetch response did not contain a pack" unless received
+        raise TransportError, "truncated fetch response" unless raw || terminated
+        raise TransportError, "fetch response continued after its terminator" if !raw && reader.read
+        raise TransportError, "contradictory shallow response" unless (shallow & unshallow).empty?
+
+        {shallow: shallow.uniq, unshallow: unshallow.uniq}
+      end
+
+      def acknowledgment?(packet)
+        return true if ["acknowledgments\n", "NAK\n", "ready\n"].include?(packet)
+        return false unless packet.start_with?("ACK ")
+
+        oid, state = packet.chomp.delete_prefix("ACK ").split(" ", 2)
+        Protocol.validate_oid(oid)
+        raise TransportError, "invalid ACK status" if state && !%w[continue common ready].include?(state)
+
+        true
+      end
+
+      def append_sideband(packet, output)
+        band = packet.getbyte(0)
+        data = packet.byteslice(1..).to_s
+        case band
+        when 1
+          output.write(data)
+          yield Progress.new(phase: :pack, current: nil, total: nil, bytes: output.pos) if block_given? && !data.empty?
+          !data.empty?
+        when 2
+          yield Progress.new(phase: :remote, current: nil, total: nil, bytes: data.bytesize) if block_given?
+          false
+        when 3
+          raise TransportError, "remote error: #{safe_message(data)}"
+        else
+          raise TransportError, "invalid sideband channel"
+        end
+      end
+
+      def raw_pack?(input)
+        position = input.pos
+        prefix = input.read(4)
+        input.seek(position, IO::SEEK_SET)
+        prefix == "PACK"
+      end
+
+      def copy_raw_pack(input, output)
+        while (chunk = input.read(65_536))
+          ensure_open
+          output.write(chunk)
+          yield Progress.new(phase: :pack, current: nil, total: nil, bytes: output.pos) if block_given?
+        end
+      end
+
+      def read_shallow(repository)
+        path = File.join(repository.common_dir, "shallow")
+        return [] unless File.exist?(path) || File.symlink?(path)
+        raise CorruptObject, "unsafe shallow file" unless File.file?(path) && !File.symlink?(path)
+
+        lines = File.readlines(path, chomp: true, encoding: Encoding::BINARY)
+        raise CorruptObject, "too many shallow boundaries" if lines.length > MAX_NEGOTIATION_OIDS
+        lines.map { |line| Protocol.validate_oid(line) }.uniq
+      rescue TransportError => error
+        raise CorruptObject, "invalid shallow boundary", cause: error
+      end
+
+      def update_shallow(repository, original, changes)
+        additions = changes.fetch(:shallow)
+        removals = changes.fetch(:unshallow)
+        return if additions.empty? && removals.empty?
+        raise TransportError, "server unshallowed an unknown boundary" unless (removals - original - additions).empty?
+
+        boundaries = ((original + additions).uniq - removals).sort
+        boundaries.each do |oid|
+          raise TransportError, "shallow boundary object is missing" unless repository.odb.exist?(oid)
+          type, = repository.odb.read(oid)
+          raise TransportError, "shallow boundary is not a commit" unless type == "commit"
+        end
+        path = File.join(repository.common_dir, "shallow")
+        raise CorruptObject, "unsafe shallow file" if File.symlink?(path) || File.symlink?(path + ".lock")
+        lock = File.open(path + ".lock", File::WRONLY | File::CREAT | File::EXCL | File::BINARY, 0o644)
+        raise RefLockError, "shallow boundaries changed during fetch" unless read_shallow(repository) == original
+
+        if boundaries.empty?
+          lock.close
+          File.unlink(path) if File.file?(path)
+        else
+          lock.write(boundaries.map { |oid| "#{oid}\n" }.join)
+          lock.flush
+          lock.fsync
+          lock.close
+          File.rename(lock.path, path)
+        end
+      rescue Errno::EEXIST
+        raise RefLockError, "shallow file is locked"
+      ensure
+        lock&.close unless lock&.closed?
+        File.unlink(lock.path) if lock && File.exist?(lock.path)
+      end
+
+      def request_to(output, method, suffix, query: nil, headers: {}, body: nil, content_type:, limit:)
+        request_each(method, suffix, query: query, headers: headers, body: body, content_type: content_type, limit: limit) do |chunk|
+          output.write(chunk)
+        end
+      end
+
+      def safe_message(data) = data.force_encoding(Encoding::UTF_8).scrub.strip
+    end
+  end
+end

data/lib/thuban/remote/http.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "stringio"
+require "uri"
+
+module Thuban
+  module Remote
+    class Connection
+      MAX_ADVERTISEMENT_SIZE = 8 * 1024 * 1024
+
+      def initialize(url, credentials: nil, timeout: 30)
+        @uri = parse_url(url)
+        Credentials.validate(credentials)
+        @credentials = credentials
+        @timeout = Float(timeout)
+        raise ArgumentError, "timeout must be between 0 and 300 seconds" unless @timeout.positive? && @timeout <= 300
+        @authorization_lock = Mutex.new
+        @request_lock = Mutex.new
+        @active_http = nil
+        @closed = false
+      rescue ArgumentError, TypeError => error
+        raise error if error.message.start_with?("timeout")
+
+        raise TransportError, "invalid remote URL"
+      end
+
+      def refs
+        ensure_open
+        body = request(:get, "/info/refs", query: "service=git-upload-pack",
+          headers: {"Accept" => "application/x-git-upload-pack-advertisement", "Git-Protocol" => "version=2"},
+          content_type: "application/x-git-upload-pack-advertisement", limit: MAX_ADVERTISEMENT_SIZE)
+        reader = Protocol::Reader.new(StringIO.new(body), max_bytes: MAX_ADVERTISEMENT_SIZE)
+        first = reader.read
+        if first == "# service=git-upload-pack\n"
+          raise TransportError, "invalid upload-pack advertisement" unless reader.read == Protocol::FLUSH
+          first = reader.read
+        end
+        @refs = if first == "version 2\n"
+          @protocol_version = 2
+          read_v2_refs(reader)
+        else
+          @protocol_version = 0
+          read_v0_refs(reader, first)
+        end
+      end
+
+      def close
+        http = @request_lock.synchronize do
+          @closed = true
+          @active_http
+        end
+        socket = http&.instance_variable_get(:@socket)
+        socket.io.shutdown(Socket::SHUT_RDWR) if socket && !socket.closed?
+        socket.close if socket && !socket.closed?
+        http.finish if http&.started?
+        nil
+      rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+        nil
+      end
+
+      private
+
+      def parse_url(url)
+        raise TypeError unless url.is_a?(String)
+
+        uri = URI.parse(url)
+        raise AuthenticationError, "credentials in remote URLs are not supported" if uri.userinfo
+
+        valid = %w[http https].include?(uri.scheme) && uri.host && !uri.host.empty? &&
+          !uri.fragment && !uri.query
+        raise ArgumentError unless valid
+
+        uri
+      end
+
+      def read_v2_refs(reader)
+        capabilities = []
+        loop do
+          packet = reader.read
+          break if packet == Protocol::FLUSH
+          raise TransportError, "truncated capability advertisement" unless packet.is_a?(String)
+
+          capabilities << packet.chomp
+        end
+        reject_non_sha1(capabilities)
+        raise TransportError, "server does not support ls-refs" unless capabilities.any? { |line| line.split("=", 2).first == "ls-refs" }
+
+        @capabilities = capabilities
+        body = Protocol.packet("command=ls-refs\n") + Protocol.delimiter +
+          %w[peel symrefs ref-prefix\ HEAD ref-prefix\ refs/].map { |line| Protocol.packet("#{line}\n") }.join + Protocol.flush
+        response = request(:post, "/git-upload-pack", body: body,
+          headers: {"Content-Type" => "application/x-git-upload-pack-request", "Accept" => "application/x-git-upload-pack-result",
+                    "Git-Protocol" => "version=2"}, content_type: "application/x-git-upload-pack-result", limit: MAX_ADVERTISEMENT_SIZE)
+        parse_v2_ref_lines(Protocol::Reader.new(StringIO.new(response), max_bytes: MAX_ADVERTISEMENT_SIZE))
+      end
+
+      def parse_v2_ref_lines(reader)
+        result = []
+        loop do
+          packet = reader.read
+          break if [Protocol::FLUSH, Protocol::RESPONSE_END].include?(packet)
+          raise TransportError, "truncated ls-refs response" unless packet.is_a?(String)
+          raise TransportError, safe_message(packet.delete_prefix("ERR ")) if packet.start_with?("ERR ")
+          fields = packet.chomp.split(" ")
+          oid = fields.shift
+          name = Protocol.validate_ref(fields.shift)
+          attributes = fields.to_h { |field| field.split(":", 2) }
+          result << Ref.new(name: name, oid: oid == "unborn" ? nil : Protocol.validate_oid(oid),
+            symref_target: attributes["symref-target"] && Protocol.validate_ref(attributes["symref-target"]),
+            peeled: attributes["peeled"] && Protocol.validate_oid(attributes["peeled"]))
+        end
+        result
+      end
+
+      def read_v0_refs(reader, first)
+        raise TransportError, "empty upload-pack advertisement" unless first.is_a?(String)
+
+        lines = [first]
+        loop do
+          packet = reader.read
+          break if packet == Protocol::FLUSH
+          raise TransportError, "truncated ref advertisement" unless packet.is_a?(String)
+
+          lines << packet
+        end
+        payload, capabilities = lines.first.split("\0", 2)
+        lines[0] = payload
+        @capabilities = capabilities.to_s.chomp.split(" ")
+        reject_non_sha1(@capabilities)
+        symrefs = @capabilities.grep(/\Asymref=/).to_h do |capability|
+          name, target = capability.delete_prefix("symref=").split(":", 2)
+          [Protocol.validate_ref(name), Protocol.validate_ref(target)]
+        end
+        result = []
+        peeled = {}
+        lines.each do |line|
+          raise TransportError, safe_message(line.delete_prefix("ERR ")) if line.start_with?("ERR ")
+
+          oid, name = line.chomp.split(" ", 2)
+          next if oid == "0" * 40 && name == "capabilities^{}"
+          next unless name == "HEAD" || name&.start_with?("refs/")
+
+          if name.end_with?("^{}")
+            peeled[name.delete_suffix("^{}")] = Protocol.validate_oid(oid)
+          else
+            name = Protocol.validate_ref(name)
+            result << Ref.new(name: name, oid: Protocol.validate_oid(oid), symref_target: symrefs[name])
+          end
+        end
+        result.each { |ref| ref.peeled = peeled[ref.name] }
+        result
+      end
+
+      def reject_non_sha1(capabilities)
+        format = capabilities.find { |line| line.start_with?("object-format=") }
+        raise TransportError, "remote object format is not SHA-1" if format && format != "object-format=sha1"
+      end
+
+      def request(method, suffix, query: nil, headers: {}, body: nil, content_type:, limit:)
+        result = +"".b
+        request_each(method, suffix, query: query, headers: headers, body: body, content_type: content_type, limit: limit) do |chunk|
+          result << chunk
+        end
+        result
+      end
+
+      def request_each(method, suffix, query: nil, headers: {}, body: nil, content_type:, limit:)
+        endpoint = @uri.dup
+        endpoint.path = @uri.path.sub(%r{/\z}, "") + suffix
+        endpoint.query = query
+        http = Net::HTTP.new(endpoint.host, endpoint.port, nil)
+        http.max_retries = 0
+        http.use_ssl = endpoint.scheme == "https"
+        http.open_timeout = http.read_timeout = @timeout
+        http.write_timeout = @timeout if http.respond_to?(:write_timeout=)
+        @request_lock.synchronize do
+          raise TransportError, "connection is closed" if @closed
+          @active_http = http
+        end
+        request_headers = headers.merge("Accept-Encoding" => "identity")
+        auth = authorization
+        request_headers["Authorization"] = auth if auth
+        request = (method == :get ? Net::HTTP::Get : Net::HTTP::Post).new(endpoint.request_uri, request_headers)
+        request.body = body if body
+        received = 0
+        @request_lock.synchronize { raise TransportError, "connection is closed" if @closed }
+        http.start do
+          http.request(request) do |response|
+            validate_response(response, content_type)
+            declared = response["content-length"]
+            raise TransportError, "HTTP response exceeds size limit" if declared&.match?(/\A\d+\z/) && declared.to_i > limit
+            response.read_body do |chunk|
+              received += chunk.bytesize
+              raise TransportError, "HTTP response exceeds size limit" if received > limit
+
+              yield chunk
+            end
+          end
+        end
+        received
+      rescue TransportError, AuthenticationError
+        raise
+      rescue Timeout::Error, IOError, SocketError, SystemCallError => error
+        raise TransportError, "HTTP transport failed: #{error.class}"
+      ensure
+        @request_lock&.synchronize { @active_http = nil if @active_http.equal?(http) }
+      end
+
+      def validate_response(response, content_type)
+        code = response.code.to_i
+        raise AuthenticationError, "remote authentication required" if [401, 403].include?(code)
+        raise TransportError, "HTTP redirects are not supported" if (300...400).cover?(code)
+        raise TransportError, "HTTP request failed (#{code})" unless code == 200
+        actual = response["content-type"].to_s.split(";", 2).first.downcase
+        raise TransportError, "unexpected HTTP content type" unless actual == content_type
+      end
+
+      def authorization
+        return @authorization if defined?(@authorization)
+
+        @authorization_lock.synchronize do
+          @authorization = @credentials&.send(:authorization, @uri, timeout: @timeout) unless defined?(@authorization)
+        end
+        @authorization
+      end
+
+      def ensure_open
+        raise TransportError, "connection is closed" if @closed
+      end
+    end
+  end
+end

data/lib/thuban/remote/local.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Thuban
+  module Remote
+    class LocalConnection < SSHConnection
+      def initialize(url, credentials: nil, timeout: 30)
+        raise AuthenticationError, "credentials cannot be used with local remotes" unless credentials.nil?
+
+        @path = parse_local_url(url)
+        @timeout = Float(timeout)
+        raise ArgumentError, "timeout must be between 0 and 300 seconds" unless @timeout.positive? && @timeout <= 300
+
+        @process_lock = Mutex.new
+        @process = nil
+        @closed = false
+      rescue AuthenticationError
+        raise
+      rescue ArgumentError, TypeError => error
+        raise error if error.message.start_with?("timeout")
+
+        raise TransportError, "invalid local remote"
+      end
+
+      private
+
+      def command(service) = [service, @path]
+
+      def parse_local_url(url)
+        raise TypeError unless url.is_a?(String) && !url.empty? && url.bytesize <= 8192 && !url.match?(/[\0\r\n]/)
+
+        if url.match?(/\Afile:\/\//i)
+          uri = URI.parse(url)
+          raise ArgumentError unless uri.scheme.casecmp?("file") && [nil, "", "localhost"].include?(uri.host) && !uri.query && !uri.fragment
+
+          path = URI::RFC2396_PARSER.unescape(uri.path)
+          path = path.delete_prefix("/") if Gem.win_platform? && path.match?(/\A\/[A-Za-z]:\//)
+        else
+          raise ArgumentError if url.include?("://")
+
+          path = url
+        end
+        raise ArgumentError if path.empty? || path.match?(/[\0\r\n]/)
+        File.expand_path(path)
+      end
+
+      def process_environment
+        super.merge("GIT_DIR" => nil, "GIT_WORK_TREE" => nil, "GIT_OBJECT_DIRECTORY" => nil,
+          "GIT_ALTERNATE_OBJECT_DIRECTORIES" => nil, "GIT_CONFIG_COUNT" => nil,
+          "GIT_CONFIG_GLOBAL" => nil, "GIT_CONFIG_SYSTEM" => nil)
+      end
+    end
+  end
+end

data/lib/thuban/remote/protocol.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Thuban
+  module Remote
+    module Protocol
+      MAX_PACKET_SIZE = 65_520
+      FLUSH = :flush
+      DELIMITER = :delimiter
+      RESPONSE_END = :response_end
+
+      def self.packet(data)
+        raise TypeError, "packet data must be a String" unless data.is_a?(String)
+        raise TransportError, "packet exceeds Git protocol limit" if data.bytesize > MAX_PACKET_SIZE - 4
+
+        format("%04x", data.bytesize + 4) + data.b
+      end
+
+      def self.flush = "0000".b
+      def self.delimiter = "0001".b
+
+      def self.validate_oid(oid)
+        raise TransportError, "server advertised a non-SHA-1 object ID" unless /\A[0-9a-fA-F]{40}\z/.match?(oid.to_s)
+
+        oid.downcase
+      end
+
+      def self.validate_depth(depth)
+        return if depth.nil?
+        raise ArgumentError, "depth must be an Integer between 1 and 2147483647" unless depth.is_a?(Integer) && (1..2_147_483_647).cover?(depth)
+
+        depth
+      end
+
+      def self.validate_filter(filter)
+        return if filter.nil?
+        raise ArgumentError, "filter must be blob:none" unless filter == "blob:none"
+
+        filter
+      end
+
+      def self.validate_ref(name)
+        valid = name == "HEAD" || (name.is_a?(String) && name.start_with?("refs/") &&
+          !name.end_with?("/", ".") && !name.include?("..") && !name.include?("@{") &&
+          !name.match?(/[\x00-\x20\x7f~^:?*\[\\]/) &&
+          name.split("/").none? { |part| part.empty? || part.start_with?(".") || part.downcase.end_with?(".lock") })
+        raise TransportError, "server advertised an invalid reference" unless valid
+
+        name
+      end
+
+      class Reader
+        def initialize(io, max_bytes:)
+          @io = io
+          @max_bytes = max_bytes
+          @bytes = 0
+        end
+
+        def read
+          header = read_exact(4, eof: true)
+          return if header.nil?
+          raise TransportError, "invalid packet length" unless /\A[0-9a-fA-F]{4}\z/.match?(header)
+
+          length = header.to_i(16)
+          return FLUSH if length.zero?
+          return DELIMITER if length == 1
+          return RESPONSE_END if length == 2
+          raise TransportError, "invalid packet length" unless (4..MAX_PACKET_SIZE).cover?(length)
+
+          @bytes += length
+          raise TransportError, "protocol response exceeds size limit" if @bytes > @max_bytes
+
+          read_exact(length - 4)
+        end
+
+        private
+
+        def read_exact(length, eof: false)
+          result = +"".b
+          while result.bytesize < length
+            chunk = @io.read(length - result.bytesize)
+            return if eof && result.empty? && chunk.nil?
+            raise TransportError, "truncated packet" if chunk.nil? || chunk.empty?
+
+            result << chunk
+          end
+          result
+        end
+      end
+    end
+  end
+end