synthient 1.0.0

data/lib/synthient/client.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Synthient
+  # A client for the Synthient API.
+  #
+  # A client holds a pool of keep-alive connections and is safe to share
+  # between threads, so create one and reuse it. Call #close on shutdown. In a
+  # forking server, connections inherited from the parent are never reused.
+  #
+  # Lookups are billed and are never resent after a network failure, because
+  # the API may already have done the work. They are retried only when the API
+  # answers 429 with a Retry-After header, which it does before any work.
+  # Account and feed requests are also retried on 500, 502, 503, and 504
+  # responses and on network failures other than TLS errors before a response
+  # arrives. Retries wait with jittered exponential backoff, or as long as
+  # Retry-After asks, and stop when Retry-After exceeds 60 seconds.
+  #
+  # @example
+  #   client = Synthient::Client.new # reads SYNTHIENT_API_KEY
+  #   info = client.lookup_ip("8.8.8.8")
+  #   puts info.intelligence&.risk_score
+  class Client
+    MAX_BATCH_SIZE = 1000
+
+    # @return [Feed<ProxyEvent>] proxy sightings
+    attr_reader :proxies
+    # @return [Feed<AnonymizerEvent>] VPN and anonymizer address ranges
+    attr_reader :anonymizers
+    # @return [Feed<TorrentEvent>] torrents seen on the BitTorrent DHT and trackers
+    attr_reader :torrents
+    # @return [Feed<JA4TEvent>] JA4T TCP fingerprint sightings
+    attr_reader :ja4t
+    # @return [Feed<HeliosHTTPEvent>] HTTP requests captured by Helios honeypots
+    attr_reader :helios_http
+    # @return [Feed<HeliosHTTPSEvent>] TLS ClientHellos captured by Helios honeypots
+    attr_reader :helios_https
+    # @return [Feed<HeliosDNSEvent>] destinations Helios honeypot tunnels were asked to reach
+    attr_reader :helios_dns
+    # @return [Feed<HeliosADBEvent>] ADB shell commands captured by Helios honeypots
+    attr_reader :helios_adb
+
+    # Makes no network requests.
+    #
+    # @param max_retries [Integer] retries after the first attempt; 0 disables them
+    # @param timeout [Numeric] seconds to wait for each read or write
+    # @param open_timeout [Numeric] seconds to wait for a connection
+    # @param user_agent [String, nil] appended to the SDK's User-Agent
+    # @param response_hook [#call, nil] called with a ResponseMetadata for every
+    #   API response, before its body is read. Exceptions it raises propagate.
+    # @raise [ArgumentError] if the API key is missing or an option is invalid
+    def initialize(api_key: ENV.fetch("SYNTHIENT_API_KEY", nil), base_url: DEFAULT_BASE_URL, max_retries: 2,
+                   timeout: 60, open_timeout: 10, user_agent: nil, response_hook: nil)
+      raise TypeError, "api_key must be a String" unless api_key.nil? || api_key.is_a?(String)
+
+      api_key = api_key.to_s.strip
+      raise ArgumentError, "missing API key: pass api_key: or set SYNTHIENT_API_KEY" if api_key.empty?
+      raise ArgumentError, "API key contains a line break" if api_key.match?(/[\r\n]/)
+
+      base_url = base_url.to_s.delete_suffix("/")
+      uri = begin
+        URI.parse(base_url)
+      rescue URI::InvalidURIError
+        nil
+      end
+      unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty? && uri.query.nil? && uri.fragment.nil? && uri.userinfo.nil?
+        raise ArgumentError, "invalid base URL #{base_url.inspect}"
+      end
+      raise ArgumentError, "max_retries must be a non-negative Integer" unless max_retries.is_a?(Integer) && max_retries >= 0
+
+      { timeout:, open_timeout: }.each do |name, value|
+        unless value.is_a?(Numeric) && value.positive? && value.finite?
+          raise ArgumentError, "#{name} must be a positive finite number of seconds"
+        end
+      end
+      raise TypeError, "response_hook must respond to call" unless response_hook.nil? || response_hook.respond_to?(:call)
+      raise ArgumentError, "user_agent contains a line break" if user_agent.to_s.match?(/[\r\n]/)
+
+      agent = ["synthient-ruby/#{VERSION}", user_agent.to_s.strip].reject(&:empty?).join(" ")
+      @base_url = base_url
+      @transport = Transport.new(base_url:, api_key:, user_agent: agent, max_retries:, timeout:, open_timeout:,
+                                 response_hook:)
+      @proxies = Feed.new(@transport, "/feeds/proxies", ProxyEvent)
+      @anonymizers = Feed.new(@transport, "/feeds/anonymizers", AnonymizerEvent)
+      @torrents = Feed.new(@transport, "/feeds/torrents", TorrentEvent)
+      @ja4t = Feed.new(@transport, "/feeds/ja4t", JA4TEvent)
+      @helios_http = Feed.new(@transport, "/feeds/helio/http", HeliosHTTPEvent)
+      @helios_https = Feed.new(@transport, "/feeds/helio/https", HeliosHTTPSEvent)
+      @helios_dns = Feed.new(@transport, "/feeds/helio/dns", HeliosDNSEvent)
+      @helios_adb = Feed.new(@transport, "/feeds/helio/adb", HeliosADBEvent)
+    end
+
+    # Costs one lookup credit; failed lookups are free.
+    #
+    # @param ip [String, IPAddr] an IPv4 or IPv6 address, without a prefix or zone
+    # @return [IPInfo]
+    # @raise [APIError] for example 402 when credits run out
+    def lookup_ip(ip)
+      json = @transport.json("GET", "/lookup/ip/#{escape_path(canonical_ip(ip))}", policy: :rate_limit)
+      Model.decode(IPInfo, json)
+    end
+
+    # Looks up to 1000 addresses in one request. The API drops duplicate,
+    # private, and reserved addresses, so match results by +ip+, not position.
+    # An invalid address raises ArgumentError before the request. Costs
+    # ceil(n * 0.9) credits for n distinct usable addresses, and nothing if the
+    # request fails. An empty list returns [] without a request.
+    #
+    # @param ips [Enumerable<String, IPAddr>]
+    # @return [Array<IPInfo>]
+    def lookup_ips(ips)
+      raise TypeError, "ips must be Enumerable" unless ips.is_a?(Enumerable)
+
+      ips = ips.to_a
+      raise ArgumentError, "#{ips.size} addresses exceed the batch limit of #{MAX_BATCH_SIZE}" if ips.size > MAX_BATCH_SIZE
+      return [] if ips.empty?
+
+      addresses = ips.each_with_index.map do |ip, index|
+        canonical_ip(ip)
+      rescue ArgumentError, TypeError => e
+        raise e.class, "#{e.message} at index #{index}"
+      end
+      json = @transport.json("POST", "/lookup/ips", policy: :rate_limit, body: JSON.generate({ ips: addresses }))
+      Model.decode_value([IPInfo], json["results"] || raise(DecodeError, "IPBatch.results is required"), "IPBatch.results")
+    end
+
+    # Looks up the honeypot traffic Synthient has observed for a domain. Costs
+    # one lookup credit.
+    #
+    # @param limit [Integer, nil] how many recent events to return; the API defaults to 50 and clamps values above 1000
+    # @return [DomainInfo]
+    def lookup_domain(domain, limit: nil)
+      raise TypeError, "domain must be a String" unless domain.is_a?(String)
+      raise ArgumentError, "invalid domain" if ["", ".", ".."].include?(domain)
+      raise ArgumentError, "limit must be a positive Integer" unless limit.nil? || (limit.is_a?(Integer) && limit.positive?)
+
+      json = @transport.json("GET", "/lookup/domain/#{escape_path(domain)}", policy: :rate_limit, query: { limit: }.compact)
+      Model.decode(DomainInfo, json)
+    end
+
+    # Returns the account that owns the API key, including its remaining
+    # lookup credits. Free.
+    #
+    # @return [Account]
+    def account
+      Model.decode(Account, @transport.json("GET", "/account/me", policy: :transient))
+    end
+
+    # Raises APIError when the API is unhealthy. A 503 is not retried, since it
+    # is the answer.
+    #
+    # @return [nil]
+    def health
+      @transport.json("GET", "/health", policy: :rate_limit)
+      nil
+    end
+
+    # Closes idle connections. Idempotent. Requests after close raise IOError.
+    #
+    # @return [nil]
+    def close
+      @transport.close
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+    end
+
+    private
+
+    def canonical_ip(ip)
+      if ip.is_a?(IPAddr)
+        raise ArgumentError, "IP address must not have a prefix" unless ip.prefix == (ip.ipv4? ? 32 : 128)
+
+        ip = ip.to_s
+      end
+      raise TypeError, "IP address must be a String or IPAddr" unless ip.is_a?(String)
+      raise ArgumentError, "invalid IP address" if ip.include?("/") || ip.include?("%")
+
+      IPAddr.new(ip).to_s
+    rescue IPAddr::InvalidAddressError
+      raise ArgumentError, "invalid IP address"
+    end
+
+    def escape_path(value)
+      value.b.gsub(/[^A-Za-z0-9\-._~$&+:=@]/n) { |char| format("%%%02X", char.ord) }
+    end
+  end
+end

data/lib/synthient/errors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Synthient
+  # The base class of every error the SDK raises for a failed request.
+  # Invalid arguments raise ArgumentError or TypeError instead.
+  class Error < StandardError; end
+
+  # The request could not be sent, or the response could not be read. The
+  # underlying exception is available as +cause+.
+  class ConnectionError < Error; end
+
+  # Connecting, sending, or waiting for response data took longer than the
+  # client's timeout.
+  class TimeoutError < ConnectionError; end
+
+  # A successful response did not match the API schema.
+  class DecodeError < Error; end
+
+  # The API, or export storage, answered with an error status.
+  #
+  # The message holds only the status, such as "429 Too Many Requests", so it
+  # is safe to log. The problem details the API sent are available as
+  # attributes.
+  class APIError < Error
+    STATUS_TEXT = {
+      300 => "Multiple Choices", 301 => "Moved Permanently", 302 => "Found", 303 => "See Other",
+      304 => "Not Modified", 307 => "Temporary Redirect", 308 => "Permanent Redirect",
+      400 => "Bad Request", 401 => "Unauthorized", 402 => "Payment Required", 403 => "Forbidden",
+      404 => "Not Found", 405 => "Method Not Allowed", 406 => "Not Acceptable", 408 => "Request Timeout",
+      409 => "Conflict", 410 => "Gone", 413 => "Request Entity Too Large", 415 => "Unsupported Media Type",
+      422 => "Unprocessable Entity", 429 => "Too Many Requests", 500 => "Internal Server Error",
+      501 => "Not Implemented", 502 => "Bad Gateway", 503 => "Service Unavailable", 504 => "Gateway Timeout"
+    }.freeze
+
+    attr_reader :status
+    # @return [String, nil] the problem type URI
+    attr_reader :type
+    # @return [String, nil] a short summary of the problem
+    attr_reader :title
+    # @return [String, nil] an explanation of this occurrence of the problem
+    attr_reader :detail
+    # @return [Hash{String => Array<String>}] validation errors by field, from a 422
+    attr_reader :errors
+    # @return [String, nil] the X-Request-Id of the response, for support requests
+    attr_reader :request_id
+    # @return [Numeric, nil] seconds the server asked to wait before retrying
+    attr_reader :retry_after
+
+    def initialize(status:, type: nil, title: nil, detail: nil, errors: {}, request_id: nil, retry_after: nil)
+      @status = status
+      @type = type
+      @title = title
+      @detail = detail
+      @errors = errors
+      @request_id = request_id
+      @retry_after = retry_after
+      super([status, STATUS_TEXT[status]].compact.join(" "))
+    end
+  end
+end

data/lib/synthient/feed.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Synthient
+  # A Synthient data feed: a real-time stream of events and hourly parquet
+  # exports that roll up into daily exports. Access feeds through the client,
+  # such as Client#proxies.
+  #
+  # An export is identified by "latest", a UTC day as a Date or
+  # "YYYY-MM-DD", or a UTC hour as a Time or "YYYY-MM-DD/H", where a
+  # zero-padded hour is also accepted. Export#id values can be passed as they
+  # are. "latest" is the newest hourly export during the day, or the daily
+  # export once that day's hours are rolled up.
+  #
+  # An hourly export is available until its day's daily export is rolled up,
+  # shortly after 00:30 UTC the next day. After that, requests for the hour
+  # raise a 400 APIError. While a daily export is being rolled up, requests
+  # for it raise a 404 APIError with +retry_after+ set.
+  class Feed
+    # @api private
+    def initialize(transport, path, event_type)
+      @transport = transport
+      @path = path
+      @event_type = event_type
+    end
+
+    # Needs the feed's stream scope, such as PROXY_FIREHOSE.
+    #
+    # The server ends each stream after up to 30 minutes, and the call then
+    # returns normally. Events sent while disconnected are missed, so
+    # reconnect in a loop. Breaking out of the block closes the connection.
+    # Without a block, returns an Enumerator that opens the connection when
+    # iterated.
+    #
+    # @yieldparam event [Object] an event of this feed's type
+    # @return [nil]
+    def stream
+      return enum_for(:stream) unless block_given?
+
+      @transport.stream("#{@path}/stream") { |object| yield Model.decode(@event_type, object) }
+      nil
+    end
+
+    # Returns one page of the feed's exports, newest first.
+    #
+    # @param limit [Integer, nil] exports per page; the API defaults to 100 and clamps values above 500
+    # @param cursor [String, nil] the +next_cursor+ of the previous page
+    # @return [ExportPage]
+    def list_exports(limit: nil, cursor: nil)
+      raise ArgumentError, "limit must be a positive Integer" unless limit.nil? || (limit.is_a?(Integer) && limit.positive?)
+      raise TypeError, "cursor must be a String" unless cursor.nil? || cursor.is_a?(String)
+
+      query = { limit:, cursor: }.reject { |_, value| value.nil? || value == "" }
+      Model.decode(ExportPage, @transport.json("GET", "#{@path}/export", policy: :transient, query:))
+    end
+
+    # Yields every export, newest first, fetching pages as they are needed.
+    # Breaking out of the block stops fetching. Without a block, returns an
+    # Enumerator.
+    #
+    # @param limit [Integer, nil] exports per page
+    # @param cursor [String, nil] a +next_cursor+ to resume from
+    # @yieldparam export [Export]
+    # @return [nil]
+    # @raise [Error] if the API returns a cursor it already returned
+    def each_export(limit: nil, cursor: nil, &block)
+      return enum_for(:each_export, limit:, cursor:) unless block
+
+      seen = Set.new
+      while seen.add?(cursor)
+        page = list_exports(limit:, cursor:)
+        page.exports.each(&block)
+        cursor = page.next_cursor
+        return if cursor.nil? || cursor.empty?
+      end
+      raise Error, "export listing returned a repeated cursor"
+    end
+
+    # Returns an export's metadata, including its parquet schema.
+    #
+    # @param export [String, Date, Time]
+    # @return [ExportMeta]
+    def export_meta(export)
+      Model.decode(ExportMeta, @transport.json("GET", "#{@path}/export/#{export_path(export)}/meta", policy: :transient))
+    end
+
+    # Returns a presigned URL for downloading an export. The URL is valid for
+    # 24 hours and grants access without an API key, so treat it as a secret.
+    #
+    # @param export [String, Date, Time]
+    # @return [URI::HTTP]
+    def download_url(export)
+      @transport.redirect_location("#{@path}/export/#{export_path(export)}")
+    end
+
+    # Downloads an export, yielding the parquet file's bytes in chunks as they
+    # arrive. The SDK does not verify them: compare a SHA-256 of the bytes
+    # with Export#checksum or ExportMeta#checksum. Breaking out of the block
+    # closes the connection. Without a block, returns an Enumerator.
+    #
+    # @param export [String, Date, Time]
+    # @yieldparam chunk [String] binary bytes
+    # @return [nil]
+    def download(export, &)
+      return enum_for(:download, export) unless block_given?
+
+      @transport.download(download_url(export), &)
+      nil
+    end
+
+    private
+
+    def export_path(export)
+      case export
+      when Time
+        time = export.getutc
+        "#{time.strftime("%Y-%m-%d")}/#{time.hour}"
+      when DateTime
+        raise TypeError, "export must be a Time or Date, not a DateTime"
+      when Date
+        export.strftime("%Y-%m-%d")
+      when String
+        return export if export == "latest"
+
+        match = %r{\A(\d{4})-(\d{2})-(\d{2})(?:/(\d{1,2}))?\z}.match(export)
+        unless match && Date.valid_date?(match[1].to_i, match[2].to_i, match[3].to_i) && match[4].to_i <= 23
+          raise ArgumentError, "invalid export ID #{export.inspect}"
+        end
+
+        match[4] ? "#{match[1]}-#{match[2]}-#{match[3]}/#{match[4].to_i}" : export
+      else
+        raise TypeError, "export must be a String, Date, or Time"
+      end
+    end
+  end
+end

data/lib/synthient/grpcschema.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "synthient"
+
+begin
+  require "grpc"
+  require "google/protobuf"
+  require "google/protobuf/descriptor_pb"
+rescue LoadError => e
+  raise LoadError, "synthient/grpcschema needs the grpc and google-protobuf gems: " \
+                   "add them to your Gemfile or run `gem install grpc google-protobuf` (#{e.message})"
+end
+
+module Synthient
+  # Fetches the protobuf schema of the Synthient gRPC API using gRPC server
+  # reflection. Load it with <tt>require "synthient/grpcschema"</tt>; it needs
+  # the grpc and google-protobuf gems, which the synthient gem does not
+  # depend on.
+  #
+  # @example
+  #   schema = Synthient::GRPCSchema.fetch
+  #   schema.descriptor_set.file.each { |file| puts file.name }
+  module GRPCSchema
+    DEFAULT_ENDPOINT = "grpc.synthient.com:443"
+    MAX_MESSAGE_SIZE = 32 << 20
+
+    EXPLANATIONS = {
+      GRPC::Core::StatusCodes::UNAUTHENTICATED => "Missing or invalid API key.",
+      GRPC::Core::StatusCodes::PERMISSION_DENIED => "This API key does not have permission to inspect gRPC schemas.",
+      GRPC::Core::StatusCodes::NOT_FOUND =>
+        "No protobuf schema found for the requested symbol. Fetch without symbols to list the available services.",
+      GRPC::Core::StatusCodes::UNIMPLEMENTED => "The gRPC endpoint does not expose server reflection.",
+      GRPC::Core::StatusCodes::UNAVAILABLE =>
+        "Could not reach the gRPC endpoint. Check the address, network access, and TLS settings.",
+      GRPC::Core::StatusCodes::DEADLINE_EXCEEDED =>
+        "Timed out reading protobuf schemas from gRPC reflection. Use a longer timeout."
+    }.freeze
+
+    # +endpoint+ is the normalized address that was queried, +symbols+ the
+    # names that were resolved, and +descriptor_set+ a
+    # Google::Protobuf::FileDescriptorSet holding the resolved files in
+    # dependency order, each after the files it imports.
+    Schema = Data.define(:endpoint, :symbols, :descriptor_set)
+
+    # +code+ is the gRPC status code, or nil when the server's reflection
+    # responses were unusable.
+    class SchemaError < Synthient::Error
+      attr_reader :code
+
+      def initialize(message = nil, code: nil)
+        super(message)
+        @code = code
+      end
+    end
+
+    # The reflection v1 messages, built in a private descriptor pool so they
+    # never clash with an application's own generated reflection classes.
+    # Only the fields the SDK uses are declared.
+    # @api private
+    MESSAGES = begin
+      proto = Google::Protobuf
+      field = lambda do |name, number, type, label: :LABEL_OPTIONAL, type_name: nil, oneof: nil|
+        proto::FieldDescriptorProto.new(name:, number:, type:, label:, oneof_index: oneof,
+                                        type_name: type_name && ".grpc.reflection.v1.#{type_name}")
+      end
+      file = proto::FileDescriptorProto.new(
+        name: "synthient/grpc_reflection_v1.proto", package: "grpc.reflection.v1", syntax: "proto3",
+        message_type: [
+          proto::DescriptorProto.new(
+            name: "ServerReflectionRequest", oneof_decl: [proto::OneofDescriptorProto.new(name: "message_request")],
+            field: [
+              field.call("host", 1, :TYPE_STRING),
+              field.call("file_by_filename", 3, :TYPE_STRING, oneof: 0),
+              field.call("file_containing_symbol", 4, :TYPE_STRING, oneof: 0),
+              field.call("list_services", 7, :TYPE_STRING, oneof: 0)
+            ]
+          ),
+          proto::DescriptorProto.new(
+            name: "ServerReflectionResponse", oneof_decl: [proto::OneofDescriptorProto.new(name: "message_response")],
+            field: [
+              field.call("file_descriptor_response", 4, :TYPE_MESSAGE, type_name: "FileDescriptorResponse", oneof: 0),
+              field.call("list_services_response", 6, :TYPE_MESSAGE, type_name: "ListServiceResponse", oneof: 0),
+              field.call("error_response", 7, :TYPE_MESSAGE, type_name: "ErrorResponse", oneof: 0)
+            ]
+          ),
+          proto::DescriptorProto.new(
+            name: "FileDescriptorResponse",
+            field: [field.call("file_descriptor_proto", 1, :TYPE_BYTES, label: :LABEL_REPEATED)]
+          ),
+          proto::DescriptorProto.new(
+            name: "ListServiceResponse",
+            field: [field.call("service", 1, :TYPE_MESSAGE, label: :LABEL_REPEATED, type_name: "ServiceResponse")]
+          ),
+          proto::DescriptorProto.new(name: "ServiceResponse", field: [field.call("name", 1, :TYPE_STRING)]),
+          proto::DescriptorProto.new(
+            name: "ErrorResponse",
+            field: [field.call("error_code", 1, :TYPE_INT32), field.call("error_message", 2, :TYPE_STRING)]
+          )
+        ]
+      )
+      pool = proto::DescriptorPool.new
+      pool.add_serialized_file(proto::FileDescriptorProto.encode(file))
+      file.message_type.to_h { |message| [message.name, pool.lookup("grpc.reflection.v1.#{message.name}").msgclass] }.freeze
+    end
+
+    # Fetches the protobuf files that define +symbols+, or every service the
+    # server lists when +symbols+ is empty, along with all of their imports.
+    # Listing skips the grpc.reflection services; name one in +symbols+ to
+    # fetch it.
+    #
+    # @param api_key [String, nil] sent as x-api-key metadata unless blank;
+    #   by default from SYNTHIENT_API_KEY
+    # @param endpoint [String] host:port, a bare host (port 443 is assumed), or
+    #   a grpc:// or https:// URL
+    # @param plaintext [Boolean] disables TLS, for local development servers
+    # @param symbols [Array<String>] fully qualified service or message names
+    # @param timeout [Numeric] seconds the whole fetch may take
+    # @return [Schema]
+    # @raise [SchemaError] with the gRPC status code when the server rejects a request
+    def self.fetch(api_key: ENV.fetch("SYNTHIENT_API_KEY", nil), endpoint: DEFAULT_ENDPOINT, plaintext: false,
+                   symbols: [], timeout: 30)
+      raise ArgumentError, "timeout must be a positive number of seconds" unless timeout.is_a?(Numeric) && timeout.positive?
+
+      endpoint, host = normalize_endpoint(endpoint)
+      credentials = plaintext ? :this_channel_is_insecure : GRPC::Core::ChannelCredentials.new
+      channel = GRPC::Core::Channel.new(endpoint, { "grpc.max_receive_message_length" => MAX_MESSAGE_SIZE }, credentials)
+      stub = GRPC::ClientStub.new(endpoint, credentials, channel_override: channel)
+      deadline = Time.now + timeout
+      metadata = api_key.to_s.strip.empty? ? {} : { "x-api-key" => api_key.strip }
+      # Each request gets its own stream, because a shared open request stream
+      # hangs grpc's client if the server ends the call early.
+      exchange = lambda do |request|
+        response, = stub.bidi_streamer(
+          "/grpc.reflection.v1.ServerReflection/ServerReflectionInfo",
+          [MESSAGES["ServerReflectionRequest"].new(host:, **request)],
+          MESSAGES["ServerReflectionRequest"].method(:encode), MESSAGES["ServerReflectionResponse"].method(:decode),
+          deadline:, metadata:
+        ).to_a
+        raise SchemaError, "reflection stream ended early" unless response
+
+        error = response.error_response
+        raise SchemaError.new(error.error_message, code: error.error_code) if error
+
+        response
+      end
+
+      symbols = symbols.map { |symbol| symbol.to_s.strip }.reject(&:empty?).uniq
+      if symbols.empty?
+        list = exchange.call(list_services: "").list_services_response
+        raise SchemaError, "reflection response has no service list" unless list
+
+        symbols = list.service.map { |service| service.name.strip }
+        symbols = symbols.reject { |name| name.empty? || name.start_with?("grpc.reflection.") }.sort
+      end
+      raise SchemaError, "server lists no services" if symbols.empty?
+
+      files = {}
+      add_files = lambda do |response|
+        list = response.file_descriptor_response
+        raise SchemaError, "reflection response has no file descriptors" unless list
+
+        list.file_descriptor_proto.each do |data|
+          file = Google::Protobuf::FileDescriptorProto.decode(data)
+          raise SchemaError, "reflection returned a file descriptor without a name" if file.name.empty?
+
+          files[file.name] ||= file
+        end
+      end
+      symbols.each { |symbol| add_files.call(exchange.call(file_containing_symbol: symbol)) }
+      until (missing = files.each_value.flat_map { |file| file.dependency.to_a }.uniq - files.keys).empty?
+        missing.sort.each do |name|
+          add_files.call(exchange.call(file_by_filename: name))
+          raise SchemaError, "reflection did not return dependency #{name}" unless files.key?(name)
+        end
+      end
+
+      ordered = []
+      visited = Set.new
+      visit = lambda do |name|
+        next unless files.key?(name) && visited.add?(name)
+
+        files[name].dependency.to_a.sort.each { |dependency| visit.call(dependency) }
+        ordered << files[name]
+      end
+      files.keys.sort.each { |name| visit.call(name) }
+      Schema.new(endpoint:, symbols: symbols.freeze,
+                 descriptor_set: Google::Protobuf::FileDescriptorSet.new(file: ordered))
+    rescue GRPC::BadStatus => e
+      raise SchemaError.new(e.details, code: e.code)
+    rescue Google::Protobuf::ParseError
+      raise SchemaError, "reflection returned an invalid file descriptor"
+    ensure
+      channel&.close
+    end
+
+    # Converts an endpoint to host:port form, and returns it with the bare
+    # host that reflection requests carry in their host field.
+    #
+    # @return [Array(String, String)] the endpoint and its host
+    # @raise [ArgumentError] if the endpoint is empty or not a valid URL
+    def self.normalize_endpoint(raw)
+      raw = raw.to_s.strip
+      raw = DEFAULT_ENDPOINT if raw.empty?
+      if raw.include?("://")
+        uri = URI.parse(raw)
+        raw = uri.port ? "#{uri.host}:#{uri.port}" : uri.host.to_s
+      end
+      raw = raw.delete_suffix("/")
+      raise ArgumentError, "empty gRPC endpoint" if raw.empty?
+
+      if raw.start_with?("[")
+        host, port = raw.delete_prefix("[").split("]", 2)
+        return port.to_s.start_with?(":") ? [raw, host] : ["[#{host}]:443", host]
+      end
+      return [raw, raw.split(":").first] if raw.count(":") == 1
+
+      raw.include?(":") ? ["[#{raw}]:443", raw] : ["#{raw}:443", raw]
+    rescue URI::InvalidURIError
+      raise ArgumentError, "invalid gRPC endpoint #{raw.inspect}"
+    end
+    private_class_method :normalize_endpoint
+
+    # Returns a human-readable explanation of a common fetch failure, or nil.
+    #
+    # @param error [SchemaError, GRPC::BadStatus]
+    # @return [String, nil]
+    def self.explain(error)
+      EXPLANATIONS[error.code] if error.respond_to?(:code)
+    end
+  end
+end