tesla 0.0.1 → 0.1.0

data/lib/tesla/json_parsing.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "errors/invalid_response"
+
+module Tesla
+  # Parses the JSON bodies of API responses, mixed into the API endpoints
+  # @api private
+  module JSONParsing
+    private
+
+    # Errors raised when the parsed JSON is not the expected shape: a key that is fetched is missing, or a value is
+    # not of the expected type
+    SHAPE_ERRORS = [KeyError, NoMethodError, TypeError].freeze
+    private_constant :SHAPE_ERRORS
+
+    # Parse a JSON response body, and read what the Fleet API answered with from it
+    #
+    # The Fleet API answers with a JSON object that carries what was asked for as its `response`, which is what is
+    # read from the body. The block reads the fields the caller needs from that, and an error it raises because the
+    # JSON is not the expected shape is reported as an invalid response with the body, rather than as a KeyError, a
+    # NoMethodError, or a TypeError, as a body without a `response` is.
+    #
+    # @api private
+    # @param body [String] the response body
+    # @yield [response] the `response` of the parsed JSON, to read the fields the caller needs
+    # @return [Object] the `response` of the parsed JSON, or what the block returns
+    # @raise [InvalidResponse] if the body is not JSON, or the JSON is not the expected shape
+    def parse_response(body)
+      response = JSON.parse(body).fetch("response")
+      block_given? ? yield(response) : response
+    rescue JSON::ParserError
+      raise InvalidResponse.new(body:)
+    rescue *SHAPE_ERRORS => e
+      raise InvalidResponse.new(body:, message: "The response body is not the expected JSON: #{e}")
+    end
+  end
+end

data/lib/tesla/nearby_charging_sites.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "charging_site"
+require_relative "resource"
+
+module Tesla
+  # The charging sites near a vehicle
+  # @api public
+  class NearbyChargingSites < Resource
+    # @!method superchargers
+    #   The Superchargers near the vehicle, nearest first
+    #   @api public
+    #   @return [Array<ChargingSite>] the Superchargers
+    #   @example
+    #     nearby_charging_sites.superchargers.first.available_stalls
+    resource_list_attribute :superchargers, ChargingSite
+
+    # @!method destination_charging
+    #   The destination chargers near the vehicle, nearest first
+    #   @api public
+    #   @return [Array<ChargingSite>] the destination chargers
+    #   @example
+    #     nearby_charging_sites.destination_charging.first.name
+    resource_list_attribute :destination_charging, ChargingSite
+
+    # @!method timestamp
+    #   The time the vehicle reported the sites
+    #   @api public
+    #   @return [Time, nil] the time the vehicle reported the sites
+    #   @raise [InvalidResponse] if the timestamp is not a number of milliseconds
+    #   @example
+    #     nearby_charging_sites.timestamp
+    time_attribute :timestamp
+  end
+end

data/lib/tesla/path_escaping.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+
+module Tesla
+  # Escapes the values interpolated into request paths, mixed into the API endpoints
+  #
+  # A vehicle tag or the name of a command is given by the caller, and may come from somewhere the caller does not
+  # control, so it is escaped rather than interpolated into a path as it is. Without escaping, a value holding a
+  # slash could walk out of the endpoint it was meant for, one holding a question mark or a number sign could add a
+  # query string or truncate the path, and one holding a space or a character outside ASCII would raise
+  # URI::InvalidURIError when the request was built.
+  #
+  # @api private
+  module PathEscaping
+    private
+
+    # Escape a value interpolated into a request path
+    #
+    # CGI.escapeURIComponent percent-encodes everything but the unreserved characters of RFC 3986, which are the
+    # characters a path segment may hold as they are.
+    #
+    # @api private
+    # @param value [Object] the value, which is read as a String
+    # @return [String] the value, with everything but the unreserved characters percent-encoded
+    def escape(value)
+      CGI.escapeURIComponent(value.to_s)
+    end
+  end
+end

data/lib/tesla/redacted_output.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Tesla
+  # Wraps the IO that receives HTTP debug output, redacting the credentials it would otherwise write in the clear
+  #
+  # Net::HTTP writes every request it sends and every response it reads to the debug output, headers and body alike,
+  # which carry the access token, the refresh token and the client secret of a request to the token endpoint, the
+  # tokens that endpoint answers with, the PIN of a command, and the credentials of a proxy.
+  # Those values are replaced before they reach the IO, so that debug output can be kept where the credentials
+  # should not be.
+  #
+  # Net::HTTP writes a response body as it reads it, a line for each read from the socket, so a credential the body
+  # carries can be split across two of those lines, where neither half matches the pattern that redacts it. A body
+  # sent in chunks is read a chunk at a time, each between the line that says how many bytes it is reading and the
+  # line that says how many it read, with the size of the next chunk and the line break that ends each one read in
+  # between, so a credential can be split across two chunks as well. The lines of a body are therefore held until
+  # the response is done, which Net::HTTP writes a line of its own for, and the parts of the body are joined into
+  # one line, written where its first part was read, before they are redacted; the lines around them are written as
+  # they were. A connection with a debug output asks for its responses uncompressed (see {Connection}), since a
+  # compressed body is written as the bytes it was sent as, which no pattern can find a credential in.
+  #
+  # @api private
+  class RedactedOutput
+    # The value written in place of a credential
+    REDACTION = "[REDACTED]"
+    # The patterns of the credentials the library sends and receives, each capturing what introduces the value it
+    # redacts
+    #
+    # Net::HTTP dumps a request as one escaped string, in which a header is preceded by an escaped newline and its
+    # value runs to the next one. It dumps bodies the same way, so the patterns also cover the credentials a body
+    # carries: the code, the PKCE verifier, the refresh token, and the client secret a request to the token endpoint
+    # sends as form fields, the tokens its response carries as JSON, and the PIN or password a command sends as
+    # JSON.
+    #
+    # The credentials of a proxy are carried by the `Proxy-Authorization` header Net::HTTP sends them as, which is
+    # among the headers of a request sent through an `http://` proxy and is written again in the CONNECT request
+    # that opens a TLS connection through one. That CONNECT is dumped as the buffer it is sent as, with newlines of
+    # its own rather than escaped ones, so it is matched by a pattern of its own.
+    CREDENTIALS = [
+      /(\\n(?:Proxy-)?Authorization: )[^\\]*/i,
+      /(\r\n(?:Proxy-)?Authorization: )[^\r\n]*/i,
+      /(\b(?:client_secret|refresh_token|code|code_verifier)=)[^&\\"]*/,
+      /(\\"(?:access_token|refresh_token|id_token|pin|password)\\":\\")[^\\]*/
+    ].freeze
+    private_constant :CREDENTIALS
+
+    # What Net::HTTP writes before the bytes it read from the socket, which it writes as an escaped string
+    READ = '-> "'
+    # What Net::HTTP writes before it reads a body, or a chunk of one, whether it reads a number of bytes or all
+    READING = "reading "
+    # What Net::HTTP writes once it has read a body, or a chunk of one
+    DONE = "read "
+    # The line break Net::HTTP reads after each chunk of a body sent in chunks, which ends the chunk rather than
+    # carrying a part of the body, as it is written escaped
+    CHUNK_END = '\r\n'
+    private_constant :READ, :READING, :DONE, :CHUNK_END
+
+    # The IO the redacted output is written to
+    # @api private
+    # @return [IO] the IO
+    # @example Get the IO
+    #   output.output
+    attr_reader :output
+
+    # Initialize a new RedactedOutput
+    #
+    # @api private
+    # @param output [IO] the IO to write the redacted output to
+    # @return [RedactedOutput] a new instance
+    # @example Wrap an IO
+    #   output = Tesla::RedactedOutput.new($stderr)
+    def initialize(output)
+      @output = output
+    end
+
+    # Write debug output, with credentials redacted
+    #
+    # The lines of a response body are held until the response is done, and written, with the parts of the body
+    # joined, before whatever is written next.
+    #
+    # @api private
+    # @param string [String] the debug output
+    # @return [RedactedOutput] self, so that writes can be chained as they can to an IO
+    # @example Write debug output
+    #   output << '<- "GET / HTTP/1.1\r\nAuthorization: key\r\n\r\n"'
+    def <<(string)
+      if string.start_with?(READING)
+        lines = @lines ||= [] #: Array[String]
+        lines << string
+        @reading = true
+      elsif (lines = @lines)
+        hold(lines, string)
+      else
+        write(string)
+      end
+      self
+    end
+
+    private
+
+    # Hold a line of a body being read, or write the body once the response is done
+    #
+    # A line that is not a part of the body, nor one Net::HTTP writes between the parts of a body sent in chunks, says
+    # the response is done.
+    #
+    # @api private
+    # @param lines [Array<String>] the lines of the body held so far
+    # @param string [String] the debug output
+    # @return [void]
+    def hold(lines, string)
+      if @reading && string.start_with?(READ)
+        read(lines, string)
+      elsif string.start_with?(READ, DONE)
+        @reading = false
+        lines << string
+      else
+        flush(lines)
+        write(string)
+      end
+    end
+
+    # Hold a part of a body, joining it to the parts read before it
+    #
+    # The line break that ends a chunk is held as a line of its own, so that it does not come between the parts of
+    # the body on either side of it.
+    #
+    # @api private
+    # @param lines [Array<String>] the lines of the body held so far
+    # @param string [String] the line Net::HTTP wrote for the part
+    # @return [void]
+    def read(lines, string)
+      part = string.delete_prefix(READ).chomp.delete_suffix('"')
+      body = @body
+      if part.eql?(CHUNK_END)
+        lines << string
+      elsif body
+        body << part
+      else
+        lines << (@body = part)
+      end
+    end
+
+    # Write the lines of a body held so far, with its parts joined into one line
+    # @api private
+    # @param lines [Array<String>] the lines of the body held so far
+    # @return [void]
+    def flush(lines)
+      body = @body
+      lines.each { |line| write(line.equal?(body) ? %(#{READ}#{line}"\n) : line) }
+      @lines = @body = nil
+    end
+
+    # Write a string to the IO, with credentials redacted
+    # @api private
+    # @param string [String] the debug output
+    # @return [void]
+    def write(string)
+      output << CREDENTIALS.reduce(string) { |redacted, pattern| redacted.gsub(pattern, "\\1#{REDACTION}") }
+    end
+  end
+end

data/lib/tesla/redirect_handler.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require_relative "authenticator"
+require_relative "connection"
+require_relative "errors/too_many_redirects"
+require_relative "request_builder"
+require_relative "settings"
+require_relative "url_validation"
+
+module Tesla
+  # Handles HTTP redirects for API requests
+  # @api private
+  class RedirectHandler
+    include Settings
+    include URLValidation
+
+    # Default maximum number of redirects to follow
+    DEFAULT_MAX_REDIRECTS = 10
+    # HTTP status codes that preserve the request method and body
+    METHOD_PRESERVING_CODES = [307, 308].freeze
+    private_constant :METHOD_PRESERVING_CODES
+
+    # @!method max_redirects
+    #   The maximum number of redirects to follow
+    #   @api private
+    #   @return [Integer] the maximum number of redirects to follow
+    #   @example Get the maximum redirects
+    #     handler.max_redirects
+    # @!method max_redirects=(max_redirects)
+    #   Set the maximum number of redirects to follow
+    #   @api private
+    #   @param max_redirects [Integer] the maximum number of redirects to follow
+    #   @return [void]
+    #   @raise [ArgumentError] if it is not a whole number of times, in which case the maximum is left as it was
+    #   @example Set the maximum redirects
+    #     handler.max_redirects = 5
+    count_setting :max_redirects
+
+    # The connection for making requests
+    # @api private
+    # @return [Connection] the connection for making requests
+    # @example Get the connection
+    #   handler.connection
+    attr_reader :connection
+
+    # The request builder for creating requests
+    # @api private
+    # @return [RequestBuilder] the request builder for creating requests
+    # @example Get the request builder
+    #   handler.request_builder
+    attr_reader :request_builder
+
+    # Initialize a new RedirectHandler
+    #
+    # @api private
+    # @param connection [Connection] the connection for making requests
+    # @param request_builder [RequestBuilder] the request builder for creating requests
+    # @param max_redirects [Integer] the maximum number of redirects to follow
+    # @return [RedirectHandler] a new instance
+    # @example Create a redirect handler
+    #   handler = Tesla::RedirectHandler.new(connection: conn, request_builder: builder)
+    def initialize(connection: Connection.new, request_builder: RequestBuilder.new,
+      max_redirects: DEFAULT_MAX_REDIRECTS)
+      @connection = connection
+      @request_builder = request_builder
+      self.max_redirects = max_redirects
+    end
+
+    # Handle redirects for an HTTP response
+    #
+    # A redirect to another scheme, host, or port is followed without the credentials of the request, as curl and
+    # browsers do, so that a redirect cannot send them to a host they were not meant for. The headers the caller
+    # asked for are dropped along with them, since a header of the caller's own may carry a credential too. A later
+    # redirect back to the original host does not restore either.
+    #
+    # A redirect that cannot be followed, such as 304 Not Modified or one whose Location header is missing, is not a
+    # valid URL, or is not an HTTP or HTTPS URL, is returned as it is, so that the caller raises the HTTPError of its
+    # status.
+    #
+    # A 307 or 308 redirect is followed with the method of the request and the body it was built from, which is
+    # given as it was given to {RequestBuilder#build}. One to another scheme, host, or port is not followed at all
+    # when the request has a body, and is returned as a redirect that cannot be followed is: a body can carry a
+    # credential of its own, such as the PIN of a command, and a command replayed to the host the redirect names
+    # would be carried out by whatever answers there.
+    #
+    # @api private
+    # @param response [Net::HTTPResponse] the HTTP response to handle
+    # @param request [Net::HTTPRequest] the original HTTP request
+    # @param authenticator [Authenticator] the authenticator for requests
+    # @param body [Hash, Array, String, nil] the body the request was built from
+    # @param headers [Hash{String => String}] the headers the request was built with
+    # @param redirect_count [Integer] the current redirect count
+    # @return [Net::HTTPResponse] the final HTTP response after following redirects
+    # @raise [TooManyRedirects] if the maximum number of redirects is exceeded
+    # @example Handle a response
+    #   response = handler.handle(response: resp, request: req)
+    def handle(response:, request:, authenticator: Authenticator.new, body: nil, headers: {}, redirect_count: 0)
+      return response unless response.is_a?(Net::HTTPRedirection)
+
+      raise TooManyRedirects, "Too many redirects" if redirect_count >= max_redirects
+
+      new_uri = build_new_uri(response, request)
+      return response if new_uri.nil?
+
+      follow(response:, request:, uri: new_uri, authenticator:, body:, headers:, redirect_count:)
+    end
+
+    private
+
+    # Send the request again to where a redirect leads
+    #
+    # A redirect to another origin that would replay the body is not followed, and its response is returned for the
+    # caller to raise the HTTPError of (see {#handle}).
+    #
+    # @api private
+    # @param response [Net::HTTPResponse] the redirect response
+    # @param request [Net::HTTPRequest] the request that was redirected
+    # @param uri [URI::HTTP] the URI the redirect leads to
+    # @param authenticator [Authenticator] the authenticator for requests
+    # @param body [Hash, Array, String, nil] the body the request was built from
+    # @param headers [Hash{String => String}] the headers the request was built with
+    # @param redirect_count [Integer] the current redirect count
+    # @return [Net::HTTPResponse] the final HTTP response after following redirects
+    # @raise [TooManyRedirects] if the maximum number of redirects is exceeded
+    def follow(response:, request:, uri:, authenticator:, body:, headers:, redirect_count:)
+      response_code = Integer(response.code)
+      unless same_origin?(request.uri, uri)
+        return response if replays_body?(response_code, body)
+
+        authenticator = Authenticator.new
+        headers = {} #: Hash[String, String]
+      end
+      new_request = build_request(request:, uri:, response_code:, authenticator:, body:, headers:)
+      new_response = connection.perform(request: new_request)
+      handle(response: new_response, request: new_request, authenticator:, body:, headers:,
+        redirect_count: redirect_count + 1)
+    end
+
+    # Whether following a redirect would send the body of the request again
+    #
+    # Only a redirect that keeps the method carries the body; the rest are followed with a GET that has none.
+    #
+    # @api private
+    # @param response_code [Integer] the HTTP response code
+    # @param body [Hash, Array, String, nil] the body the request was built from
+    # @return [Boolean] whether the body would be sent again
+    def replays_body?(response_code, body)
+      method_preserving?(response_code) && !body.nil?
+    end
+
+    # Whether a redirect keeps the method and body, rather than becoming a GET
+    # @api private
+    # @param response_code [Integer] the HTTP response code
+    # @return [Boolean] whether the method and body are kept
+    def method_preserving?(response_code)
+      METHOD_PRESERVING_CODES.include?(response_code)
+    end
+
+    # Build a new URI from the redirect response
+    # @api private
+    # @param response [Net::HTTPResponse] the redirect response
+    # @param request [Net::HTTPRequest] the original request
+    # @return [URI::HTTP, nil] the new URI, or nil if the response has no Location header or one that is not an HTTP
+    #   or HTTPS URL
+    def build_new_uri(response, request)
+      location = response["location"]
+      return if location.nil?
+
+      # If location is relative, it will join with the original URI, otherwise it will overwrite it
+      new_uri = URI.join(request.uri, location)
+      new_uri if new_uri.is_a?(URI::HTTP)
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    # Build a new request for the redirect
+    # @api private
+    # @param request [Net::HTTPRequest] the original request
+    # @param uri [URI::Generic] the new URI
+    # @param response_code [Integer] the HTTP response code
+    # @param authenticator [Authenticator] the authenticator
+    # @param body [Hash, Array, String, nil] the body the original request was built from
+    # @param headers [Hash{String => String}] the headers the new request is built with
+    # @return [Net::HTTPRequest] the new request, with the method and body of the original for a 307 or 308, or a
+    #   GET without a body otherwise
+    def build_request(request:, uri:, response_code:, authenticator:, body:, headers:)
+      if method_preserving?(response_code)
+        request_builder.build(http_method: request.method.downcase.to_sym, uri:, body:, authenticator:, headers:)
+      else
+        request_builder.build(http_method: :get, uri:, authenticator:, headers:)
+      end
+    end
+  end
+end

data/lib/tesla/region.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Tesla
+  # The region of the Fleet API an account is served by
+  # @api public
+  class Region < Resource
+    inspect_with :region
+
+    # @!method region
+    #   The name of the region, such as "na" or "eu"
+    #   @api public
+    #   @return [String, nil] the name of the region
+    #   @example
+    #     region.region
+    attribute :region
+
+    # @!method fleet_api_base_url
+    #   The host the Fleet API serves the account at, which is the `host` to configure
+    #   @api public
+    #   @return [String, nil] the host the Fleet API serves the account at
+    #   @example
+    #     region.fleet_api_base_url
+    attribute :fleet_api_base_url
+  end
+end

data/lib/tesla/request_builder.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require_relative "authenticator"
+require_relative "version"
+
+module Tesla
+  # Builds HTTP requests for the Tesla Fleet API
+  # @api private
+  class RequestBuilder
+    # The default 'User-Agent' HTTP header
+    #
+    # The Ruby it runs on is named along with the library and its version, so that the operators of the Fleet API
+    # can tell which client and which Ruby a request came from.
+    DEFAULT_USER_AGENT = "tesla/#{VERSION} (#{RUBY_ENGINE} #{RUBY_ENGINE_VERSION}; #{RUBY_PLATFORM})".freeze
+    # Content type for JSON request bodies, which the Fleet API requires of every request
+    APPLICATION_JSON = "application/json"
+    # Mapping of HTTP method symbols to Net::HTTP classes
+    HTTP_METHODS = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      put: Net::HTTP::Put,
+      patch: Net::HTTP::Patch,
+      delete: Net::HTTP::Delete
+    }.freeze
+    private_constant :HTTP_METHODS
+
+    # The 'User-Agent' HTTP header sent with requests
+    # @api private
+    # @return [String] the user agent
+    # @example Get or set the user agent
+    #   builder.user_agent = "Custom User Agent"
+    attr_accessor :user_agent
+
+    # Initialize a new RequestBuilder
+    #
+    # @api private
+    # @param user_agent [String] the 'User-Agent' HTTP header sent with requests
+    # @return [RequestBuilder] a new instance
+    # @example Create a request builder
+    #   builder = Tesla::RequestBuilder.new(user_agent: "Custom User Agent")
+    def initialize(user_agent: DEFAULT_USER_AGENT)
+      @user_agent = user_agent
+    end
+
+    # Build an HTTP request
+    #
+    # The body may be a Hash or an Array, which is sent as JSON, or a String, which is sent as it is with whatever
+    # content type the headers name.
+    #
+    # Every request is sent with a content type of JSON unless the headers name another, since the Fleet API answers
+    # a request without one with a 406 Not Acceptable, whether or not the request has a body.
+    #
+    # The headers are added after the ones of the authenticator, so that a caller with a token of its own, such as
+    # the partner token an application is registered with, sends it in place of the access token of the client.
+    #
+    # @api private
+    # @param http_method [Symbol] the HTTP method (:get, :post, :put, :patch, :delete)
+    # @param uri [URI::Generic] the request URI
+    # @param params [Hash] query parameters to append to the URI
+    # @param body [Hash, Array, String, nil] the request body
+    # @param headers [Hash] additional headers for the request
+    # @param authenticator [Authenticator] the authenticator for the request
+    # @return [Net::HTTPRequest] the built HTTP request
+    # @raise [ArgumentError] if the HTTP method is not supported
+    # @example Build a GET request
+    #   builder.build(http_method: :get, uri: URI("https://fleet-api.prd.na.vn.cloud.tesla.com/api/1/vehicles"))
+    def build(http_method:, uri:, params: {}, body: nil, headers: {}, authenticator: Authenticator.new)
+      request = create_request(http_method:, uri:, params:)
+      add_authentication(request:, authenticator:)
+      add_headers(request:, headers:)
+      add_body(request:, body:)
+      request
+    end
+
+    private
+
+    # Create an HTTP request
+    # @api private
+    # @param http_method [Symbol] the HTTP method
+    # @param uri [URI::Generic] the request URI
+    # @param params [Hash] query parameters to append to the URI
+    # @return [Net::HTTPRequest] the created request
+    def create_request(http_method:, uri:, params:)
+      http_method_class = HTTP_METHODS[http_method]
+
+      raise ArgumentError, "Unsupported HTTP method: #{http_method}" unless http_method_class
+
+      http_method_class.new(add_query_params(uri, params))
+    end
+
+    # Append query parameters to a URI
+    # @api private
+    # @param uri [URI::Generic] the URI
+    # @param params [Hash] the query parameters
+    # @return [URI::Generic] a new URI with the query parameters appended
+    def add_query_params(uri, params)
+      uri.dup.tap do |u|
+        u.query = URI.encode_www_form(params) unless params.empty?
+      end
+    end
+
+    # Add headers to a request
+    # @api private
+    # @param request [Net::HTTPRequest] the request
+    # @param headers [Hash] additional headers
+    # @return [void]
+    def add_headers(request:, headers:)
+      {"User-Agent" => user_agent, "Content-Type" => APPLICATION_JSON}.merge(headers).each do |key, value|
+        request[key] = value
+      end
+    end
+
+    # Add a body to a request
+    # @api private
+    # @param request [Net::HTTPRequest] the request
+    # @param body [Hash, Array, String, nil] the request body
+    # @return [void]
+    def add_body(request:, body:)
+      return if body.nil?
+
+      request.body = String.try_convert(body) || JSON.generate(body)
+    end
+
+    # Add authentication to a request
+    # @api private
+    # @param request [Net::HTTPRequest] the request
+    # @param authenticator [Authenticator] the authenticator
+    # @return [void]
+    def add_authentication(request:, authenticator:)
+      authenticator.header(request).each do |key, value|
+        request[key] = value
+      end
+    end
+  end
+end