voiceml 0.9.2 → 0.9.3

data/lib/voiceml/transport.rb

@@ -1,323 +1,361 @@
 # frozen_string_literal: true
 
+require 'date'
 require 'json'
 require 'net/http'
+require 'openssl'
+require 'time'
 require 'uri'
 
 require_relative 'errors'
 require_relative 'version'
 
 module VoiceML
-  # HTTP transport for the VoiceML REST API.
-  #
-  # - Auth: HTTP Basic with `account_sid` (Twilio-format `AC` + 32 hex) as the username and the
-  #   per-tenant API key as the password. Drop-in compatible with the Twilio SDK constructor.
-  # - Wire format: requests are form-urlencoded by default (Twilio convention). The server also
-  #   accepts JSON; pass `json: <hash>` to send JSON instead. Responses are always JSON.
-  # - Retries: 429 + 5xx are retried up to `max_retries` times with exponential backoff,
-  #   honoring the `Retry-After` header when the server emits one.
-  # - Binary fetch: `fetch_bytes` follows the 302 -> S3 redirect that
-  #   `GET /Recordings/{sid}.wav` issues when audio has been archived. Callers usually only
-  #   care about the final bytes.
-  #
+  # HTTP transport with exclusive connection use, per-host keep-alive, and
+  # method-aware retries. Caller-supplied connections remain caller-owned.
   # @api private
   class Transport
-    DEFAULT_BASE_URL    = 'https://voiceml.voicetel.com'
-    DEFAULT_TIMEOUT     = 30
+    DEFAULT_BASE_URL = 'https://voiceml.voicetel.com'
+    DEFAULT_TIMEOUT = 30
     DEFAULT_MAX_RETRIES = 2
-    RETRYABLE_STATUSES  = [429, 500, 502, 503, 504].freeze
-
-    # Linear-time trailing-slash strip. Equivalent to `base_url.sub(%r{/+\z}, '')` but
-    # without the polynomial-backtracking shape CodeQL flags (`rb/polynomial-redos`).
-    def self.strip_trailing_slashes(s)
-      i = s.length
-      i -= 1 while i.positive? && s.getbyte(i - 1) == 47 # '/'
-      i == s.length ? s : s[0, i]
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+    IDEMPOTENT_METHODS = %w[GET HEAD DELETE PUT].freeze
+    RETRY_AFTER_CAP = 60.0
+    MAX_REDIRECTS = 5
+
+    # Carries the phase separately from the exception type: an SSL error or
+    # ETIMEDOUT during a response is not proof that a POST was never sent.
+    class NetworkFailure < StandardError
+      attr_reader :original, :connecting
+
+      def initialize(original, connecting)
+        super(original.message)
+        @original = original
+        @connecting = connecting
+      end
+    end
+    private_constant :NetworkFailure
+
+    def self.strip_trailing_slashes(value)
+      i = value.length
+      i -= 1 while i.positive? && value.getbyte(i - 1) == 47
+      value[0, i]
     end
 
     attr_reader :account_sid, :base_url, :max_retries, :timeout, :user_agent
 
-    def initialize(account_sid:, api_key:, base_url: DEFAULT_BASE_URL,
+    # `http_client:` is a Net::HTTP for one origin, or a factory
+    # `->(host, port) { Net::HTTP.new(host, port) }` for multiple origins.
+    # A one-argument factory receiving a URI is also accepted.
+    def initialize(account_sid: nil, api_key: nil, base_url: DEFAULT_BASE_URL,
                    timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES,
                    user_agent: nil, http_client: nil)
-      raise ConfigurationError, 'account_sid is required' if account_sid.nil? || account_sid.empty?
-      raise ConfigurationError, 'api_key is required'     if api_key.nil? || api_key.empty?
-      raise ConfigurationError, 'max_retries must be >= 0' if max_retries.negative?
+      if !account_sid.nil? && (!account_sid.is_a?(String) || account_sid.empty?)
+        raise ConfigurationError, 'account_sid must not be empty'
+      end
+      if !api_key.nil? && (!api_key.is_a?(String) || api_key.empty?)
+        raise ConfigurationError, 'api_key must not be empty'
+      end
+      unless max_retries.is_a?(Integer) && max_retries >= 0
+        raise ConfigurationError, 'max_retries must be an integer >= 0'
+      end
+      unless timeout.is_a?(Numeric) && timeout.positive? && timeout.finite?
+        raise ConfigurationError, 'timeout must be positive and finite'
+      end
+      unless http_client.nil? || http_client.is_a?(Net::HTTP) || http_client.respond_to?(:call)
+        raise ConfigurationError, 'http_client must be a Net::HTTP or a callable'
+      end
 
       @account_sid = account_sid
-      @api_key     = api_key
-      @base_url    = self.class.strip_trailing_slashes(base_url)
-      @timeout     = timeout
+      @credential = -> { api_key }
+      begin
+        uri = URI.parse(base_url)
+        unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
+          raise ArgumentError, 'expected an HTTP(S) base URL without credentials, query, or fragment'
+        end
+        @base_url = self.class.strip_trailing_slashes(base_url)
+      rescue URI::Error, ArgumentError, TypeError => e
+        raise ConfigurationError, "invalid base_url: #{e.message}"
+      end
+      @timeout = timeout
       @max_retries = max_retries
-      @user_agent  = user_agent || "voiceml-ruby/#{VoiceML::VERSION}"
-      @uri_base    = URI.parse(@base_url)
-      @conn_mutex  = Mutex.new
-      @owns_client = http_client.nil?
-      @persistent  = http_client
+      @user_agent = user_agent || "voiceml-ruby/#{VoiceML::VERSION}"
+      @http_client = http_client
+      @connections = {}
+      @mutex = Mutex.new
     end
 
-    # Close the persistent connection, releasing the underlying socket.
-    # Safe to call multiple times. The transport remains usable — the next
-    # request will transparently open a fresh connection.
+    # Release SDK-owned sockets. In-flight requests finish before close runs;
+    # caller-owned clients are retained and never finished by this method.
     def close
-      @conn_mutex.synchronize { finish_connection } if @owns_client
+      @mutex.synchronize do
+        @connections.delete_if do |_origin, (http, owned)|
+          finish(http) if owned
+          owned
+        end
+      end
     end
 
-    # Perform a request. Pass `form:` for a form-urlencoded POST body, `json:` for a JSON body,
-    # or neither for a plain GET/DELETE. `params:` are query-string params.
-    #
-    # `base_url:` overrides the client's default host for this one call (used to route product
-    # resources at their subdomain — Conversations, Messaging Service). When set, the request
-    # goes to an absolute URL so the correct host/SNI is used per request; see `ScopedTransport`.
-    #
-    # @return [Hash, Array, nil] the parsed JSON body (or `nil` for empty 2xx).
-    # @raise [VoiceML::ApiError] for non-2xx responses (subclasses by status family).
-    def request(method, path, params: nil, form: nil, json: nil, base_url: nil)
-      uri = build_uri(request_path(path, base_url), params)
-
-      attempt = 0
-      loop do
-        response = perform_request(method, uri, form: form, json: json)
-
-        if RETRYABLE_STATUSES.include?(response.code.to_i) && attempt < @max_retries
-          sleep(backoff_delay(attempt, response))
-          attempt += 1
-          next
-        end
+    def request(method, path, params: nil, form: nil, json: nil, base_url: nil, auth: true)
+      uri = build_uri(path, base_url, params)
+      parse_response(send_with_retries(method, uri, form: form, json: json, auth: auth))
+    end
 
-        return parse_response(response)
-      rescue *transport_errors => e
-        raise ApiError.new("transport error after #{attempt + 1} attempts: #{e.message}",
-                           status_code: 0) if attempt >= @max_retries
+    # Raw text and JSON use the same client, timeout, auth and retry policy.
+    def request_raw(method, path, params: nil, base_url: nil, auth: true)
+      uri = build_uri(path, base_url, params)
+      response = send_with_retries(method, uri, auth: auth, accept: '*/*')
+      raise_for_response(response) unless response.is_a?(Net::HTTPSuccess)
 
-        sleep(backoff_delay(attempt))
-        attempt += 1
-      end
+      [response.code.to_i, response.body.to_s, response.each_header.to_h]
     end
 
-    # Fetch a binary payload (audio/wav recordings). Follows the single 302 -> presigned S3
-    # redirect that `GET /Recordings/{sid}.wav` issues when audio has been archived.
-    #
-    # @return [Array(Integer, String, Hash)] status code, response body bytes, header hash.
+    # Authenticated binary GET with manual, origin-aware redirect handling.
     def fetch_bytes(path, base_url: nil)
-      uri = build_uri(request_path(path, base_url), nil)
-      visited = []
+      origin = build_uri(path, base_url, nil)
+      uri = origin
+      redirects = 0
       loop do
-        raise ApiError.new('too many redirects', status_code: 0) if visited.length > 5
+        response = send_with_retries(:get, uri, auth: same_origin?(origin, uri), accept: '*/*')
+        unless response.is_a?(Net::HTTPRedirection)
+          raise_for_response(response) unless response.is_a?(Net::HTTPSuccess)
 
-        req = Net::HTTP::Get.new(uri)
-        apply_common_headers(req, auth: !visited.any? { |u| u.host != uri.host })
-        response = send_on_persistent(uri, req)
+          return [response.code.to_i, response.body.to_s, response.each_header.to_h]
+        end
+        raise ConnectionError.new('too many redirects', status_code: 0) if redirects >= MAX_REDIRECTS
 
-        case response
-        when Net::HTTPRedirection
-          visited << uri
-          uri = URI.parse(response['location'])
-          next
-        when Net::HTTPSuccess
-          headers = response.each_header.to_h
-          return [response.code.to_i, response.body || '', headers]
-        else
-          raise_for_response(response)
+        target = resolve_redirect(uri, response['location'])
+        if uri.scheme == 'https' && target.scheme == 'http'
+          raise ConnectionError.new('refusing an https -> http redirect', status_code: 0)
         end
+        uri = target
+        redirects += 1
       end
     end
 
+    def inspect
+      "#<#{self.class.name} account_sid=#{@account_sid} base_url=#{@base_url}>"
+    end
+    alias to_s inspect
+
     private
 
-    def transport_errors
-      [Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, Errno::ECONNRESET,
-       Errno::EHOSTUNREACH, SocketError, EOFError]
+    def build_uri(path, override, params)
+      base = override || @base_url
+      uri = URI.parse(path)
+      uri = URI.join("#{base}/", path) unless uri.absolute?
+      unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo
+        raise ArgumentError, 'expected an HTTP(S) request URL without userinfo'
+      end
+      uri.query = encode_values(params) if params && !params.empty?
+      uri
+    rescue URI::Error, ArgumentError, TypeError => e
+      raise ConnectionError.new("invalid request URI: #{e.message}", status_code: 0)
     end
 
-    # Prefix `path` with a per-request `base_url` override, if any. Leaves absolute paths and
-    # the default-host case untouched so `build_uri` handles them as before.
-    def request_path(path, base_url)
-      return path if base_url.nil? || base_url.empty?
+    def send_with_retries(method, uri, form: nil, json: nil, auth: true, accept: 'application/json')
+      verb = method.to_s.upcase
+      idempotent = IDEMPOTENT_METHODS.include?(verb)
+      attempt = 0
+      loop do
+        req = build_net_request(verb, uri)
+        req['Accept'] = accept
+        req['User-Agent'] = @user_agent
+        if auth
+          key = @credential.call
+          unless @account_sid && key
+            raise ConfigurationError, 'account_sid and api_key are required for authenticated requests'
+          end
+          req.basic_auth(@account_sid, key)
+        end
+        if json
+          req['Content-Type'] = 'application/json'
+          req.body = JSON.generate(json)
+        elsif form
+          req['Content-Type'] = 'application/x-www-form-urlencoded'
+          req.body = encode_values(form)
+        end
+
+        response = exchange(uri, req)
+        status = response.code.to_i
+        retry_after = retry_after_seconds(response)
+        if status == 429 && retry_after && retry_after > RETRY_AFTER_CAP
+          raise_for_response(response)
+        end
+        if attempt < @max_retries && (status == 429 || (idempotent && RETRYABLE_STATUSES.include?(status)))
+          response.body # Net::HTTP buffers the complete body before releasing the connection.
+          delay = retry_after || backoff_delay(attempt)
+          sleep_for(delay) if delay.positive?
+          attempt += 1
+          next
+        end
+        return response
+      rescue NetworkFailure => e
+        # These failures can only occur while establishing the connection
+        # (DNS, routing, TCP connect, TLS handshake), so the request was
+        # provably never sent — safe to retry even for POST.
+        safe_connect = [SocketError, Net::OpenTimeout, OpenSSL::SSL::SSLError,
+                        Errno::ECONNREFUSED, Errno::ETIMEDOUT,
+                        Errno::ENETUNREACH, Errno::EHOSTUNREACH].any? { |c| e.original.is_a?(c) }
+        if attempt < @max_retries && (idempotent || safe_connect)
+          sleep_for(backoff_delay(attempt))
+          attempt += 1
+          next
+        end
+        raise ConnectionError.new("transport error after #{attempt + 1} attempt(s): #{e.original.message}",
+                                  status_code: 0), cause: e.original
+      end
+    end
 
-      "#{base_url}#{path}"
+    # The lock covers both connection selection and the entire response read.
+    # Host changes do not finish connections belonging to another origin.
+    def exchange(uri, req)
+      @mutex.synchronize do
+        origin = [uri.scheme, uri.host, uri.port]
+        connecting = true
+        http, owned = @connections[origin] ||= connection_for(uri)
+        http.max_retries = 0 # Only the counted SDK retry loop may resend a request.
+        http.start unless http.started?
+        connecting = false
+        http.request(req)
+      rescue Error
+        raise
+      rescue StandardError => e
+        @connections.delete(origin)
+        finish(http) if http && owned
+        raise NetworkFailure.new(e, connecting), cause: e
+      end
     end
 
-    def build_uri(path, params)
-      uri = if path.start_with?('http://', 'https://')
-              URI.parse(path)
-            else
-              URI.parse("#{@base_url}#{path}")
-            end
-      if params && !params.empty?
-        encoded = encode_query(params)
-        uri.query = encoded unless encoded.empty?
+    def connection_for(uri)
+      owned = @http_client.nil?
+      http = if owned
+               Net::HTTP.new(uri.host, uri.port)
+             elsif @http_client.is_a?(Net::HTTP)
+               @http_client
+             elsif @http_client.method(:call).arity == 1 || (@http_client.respond_to?(:arity) && @http_client.arity == 1)
+               @http_client.call(uri)
+             else
+               @http_client.call(uri.host, uri.port)
+             end
+      unless http.is_a?(Net::HTTP) && http.address == uri.host && http.port == uri.port
+        raise ConfigurationError, 'http_client must match the requested host/port; use a factory for multiple hosts'
       end
-      uri
+      if !http.started?
+        http.use_ssl = uri.scheme == 'https'
+      elsif http.use_ssl? != (uri.scheme == 'https')
+        raise ConfigurationError, 'http_client TLS scheme does not match the requested origin'
+      end
+      if owned
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+        http.write_timeout = @timeout
+        http.keep_alive_timeout = 30
+      end
+      [http, owned]
     end
 
-    def encode_query(params)
-      pairs = []
-      params.each do |k, v|
-        next if v.nil?
+    def finish(http)
+      http.finish if http.started?
+    rescue IOError, SystemCallError
+      nil # A closed socket already satisfies close's postcondition.
+    end
 
-        if v.is_a?(Array)
-          v.each { |entry| pairs << [k.to_s, format_scalar(entry)] }
-        else
-          pairs << [k.to_s, format_scalar(v)]
-        end
-      end
-      URI.encode_www_form(pairs)
+    def build_net_request(verb, uri)
+      klass = { 'GET' => Net::HTTP::Get, 'HEAD' => Net::HTTP::Head, 'POST' => Net::HTTP::Post,
+                'PUT' => Net::HTTP::Put, 'PATCH' => Net::HTTP::Patch, 'DELETE' => Net::HTTP::Delete }[verb]
+      raise ArgumentError, "unsupported HTTP method: #{verb}" unless klass
+
+      klass.new(uri)
     end
 
-    def encode_form(form)
+    def encode_values(values)
       pairs = []
-      form.each do |k, v|
-        next if v.nil?
+      values.each do |key, value|
+        next if value.nil?
 
-        if v.is_a?(Array)
-          v.each { |entry| pairs << [k.to_s, format_scalar(entry)] }
-        else
-          pairs << [k.to_s, format_scalar(v)]
-        end
+        (value.is_a?(Array) ? value : [value]).each { |v| pairs << [key.to_s, format_scalar(v)] }
       end
       URI.encode_www_form(pairs)
     end
 
     def format_scalar(value)
       case value
-      when true  then 'true'
-      when false then 'false'
+      when Time then value.getutc.iso8601
+      when DateTime then value.new_offset(0).iso8601
+      when Date then value.iso8601
+      when Hash then JSON.generate(value)
       else value.to_s
       end
     end
 
-    def perform_request(method, uri, form:, json:)
-      req = build_net_request(method, uri)
-      apply_common_headers(req, auth: true)
-
-      if !json.nil?
-        req['Content-Type'] = 'application/json'
-        req.body = JSON.generate(json)
-      elsif !form.nil? && method.to_s.upcase != 'GET' && method.to_s.upcase != 'DELETE'
-        req['Content-Type'] = 'application/x-www-form-urlencoded'
-        req.body = encode_form(form)
-      end
+    def retry_after_seconds(response)
+      text = response['retry-after']
+      return nil unless text
+      return text.to_f if text.match?(/\A\d+(?:\.\d+)?\z/)
 
-      send_on_persistent(uri, req)
+      [Time.httpdate(text) - Time.now, 0.0].max
+    rescue ArgumentError
+      nil
     end
 
-    def build_net_request(method, uri)
-      case method.to_s.upcase
-      when 'GET'    then Net::HTTP::Get.new(uri)
-      when 'POST'   then Net::HTTP::Post.new(uri)
-      when 'PUT'    then Net::HTTP::Put.new(uri)
-      when 'DELETE' then Net::HTTP::Delete.new(uri)
-      when 'PATCH'  then Net::HTTP::Patch.new(uri)
-      else
-        raise ArgumentError, "unsupported HTTP method: #{method}"
-      end
+    def backoff_delay(attempt)
+      rand * [8.0, 0.5 * (2**[attempt, 5].min)].min
     end
 
-    def apply_common_headers(req, auth:)
-      req['Accept']     = 'application/json'
-      req['User-Agent'] = @user_agent
-      req.basic_auth(@account_sid, @api_key) if auth
+    def sleep_for(seconds)
+      sleep(seconds)
     end
 
-    def send_on_persistent(uri, req)
-      conn = persistent_connection(uri)
-      conn.request(req)
-    rescue IOError, Errno::EPIPE, Errno::ECONNRESET
-      @conn_mutex.synchronize { finish_connection }
-      persistent_connection(uri).request(req)
-    end
+    def resolve_redirect(uri, location)
+      raise ArgumentError, 'redirect missing Location' if location.nil? || location.empty?
 
-    def persistent_connection(uri)
-      @conn_mutex.synchronize do
-        if @persistent&.started? &&
-           @persistent.address == uri.host &&
-           @persistent.port == uri.port
-          return @persistent
-        end
-        finish_connection
-        h = Net::HTTP.new(uri.host, uri.port)
-        h.use_ssl = uri.scheme == 'https'
-        h.open_timeout = @timeout
-        h.read_timeout = @timeout
-        h.keep_alive_timeout = 30
-        h.start
-        @persistent = h
-      end
+      target = URI.join(uri.to_s, location)
+      raise ArgumentError, 'redirect must use HTTP(S) without userinfo' unless target.is_a?(URI::HTTP) && target.host && !target.userinfo
+
+      target
+    rescue URI::Error, ArgumentError => e
+      raise ConnectionError.new("invalid redirect: #{e.message}", status_code: 0)
     end
 
-    def finish_connection
-      @persistent&.finish rescue nil
-      @persistent = nil
+    def same_origin?(a, b)
+      a.scheme == b.scheme && a.host == b.host && a.port == b.port
     end
 
     def parse_response(response)
-      status = response.code.to_i
-      return nil if status >= 200 && status < 300 && (response.body.nil? || response.body.empty?)
-
-      if status >= 200 && status < 300
-        begin
-          return JSON.parse(response.body)
-        rescue JSON::ParserError => e
-          raise ApiError.new("non-JSON success response (#{e.message}): #{response.body.to_s[0, 200]}",
-                             status_code: status, body: response.body)
-        end
-      end
+      raise_for_response(response) unless response.is_a?(Net::HTTPSuccess)
+      return nil if response.body.nil? || response.body.empty?
 
-      raise_for_response(response)
+      JSON.parse(response.body)
+    rescue JSON::ParserError => e
+      raise ApiError.new("could not decode success response as JSON: #{e.message}",
+                         status_code: response.code.to_i, body: response.body)
     end
 
     def raise_for_response(response)
-      status = response.code.to_i
-      raw_body = response.body
+      raw = response.body
       body = begin
-        raw_body && !raw_body.empty? ? JSON.parse(raw_body) : raw_body
+        raw.nil? || raw.empty? ? raw : JSON.parse(raw)
       rescue JSON::ParserError
-        raw_body
+        raw
       end
-
-      code = nil
-      message = "HTTP #{status}"
-      more_info = nil
-      if body.is_a?(Hash)
-        rc = body['code']
-        code = rc if rc.is_a?(Integer) || rc.is_a?(String)
-        m = body['message']
-        message = m if m.is_a?(String) && !m.empty?
-        mi = body['more_info']
-        more_info = mi if mi.is_a?(String) && !mi.empty?
-      end
-
-      raise VoiceML.error_from_response(status, message, code: code, body: body, more_info: more_info)
-    end
-
-    def backoff_delay(attempt, response = nil)
-      if response
-        ra = response['retry-after']
-        if ra
-          begin
-            return [Float(ra), 0.0].max
-          rescue ArgumentError, TypeError
-            # fall through
-          end
-        end
-      end
-      [8.0, 0.5 * (2**attempt)].min
+      data = body.is_a?(Hash) ? body : {}
+      code = data['code']
+      code = code.to_i if code.is_a?(String) && code.match?(/\A\d+\z/)
+      error = VoiceML.error_from_response(response.code.to_i, data['message'] || "HTTP #{response.code}",
+                                          code: code, body: body, more_info: data['more_info'])
+      error.retry_after = retry_after_seconds(response) if error.is_a?(RateLimitError)
+      raise error
     end
   end
 
-  # A transport view pinned to a specific product base URL.
-  #
-  # Wraps a real `Transport` and forwards every call, injecting a `base_url` override so an
-  # entire resource group lands on its product subdomain (`conversations.voicetel.com` /
-  # `messaging.voicetel.com`) without each resource needing to know its own host.
-  #
+  # A redacting transport view pinned to one product origin.
   # @api private
   class ScopedTransport
     attr_reader :base_url
 
     def initialize(inner, base_url)
-      @inner    = inner
+      @inner = inner
       @base_url = Transport.strip_trailing_slashes(base_url)
     end
 
@@ -325,12 +363,21 @@ module VoiceML
       @inner.account_sid
     end
 
-    def request(method, path, params: nil, form: nil, json: nil)
-      @inner.request(method, path, params: params, form: form, json: json, base_url: @base_url)
+    def request(method, path, **options)
+      @inner.request(method, path, **options, base_url: @base_url)
+    end
+
+    def request_raw(method, path, **options)
+      @inner.request_raw(method, path, **options, base_url: @base_url)
     end
 
     def fetch_bytes(path)
       @inner.fetch_bytes(path, base_url: @base_url)
     end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url}>"
+    end
+    alias to_s inspect
   end
 end

data/lib/voiceml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VoiceML
-  VERSION = '0.9.2'
+  VERSION = '0.9.3'
 end