tesla 0.0.1 → 0.1.0

data/lib/tesla/connection.rb

@@ -0,0 +1,361 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require_relative "certificate_options"
+require_relative "connection_pool"
+require_relative "errors/network_error"
+require_relative "redacted_output"
+require_relative "settings"
+require_relative "url_validation"
+
+module Tesla
+  # Manages HTTP connections to the Tesla Fleet API
+  #
+  # The connection of a client is its own, and cannot be given to it or read from it, so this class can change
+  # within 0.x as the rest of the internals can. Its settings are options of {Client} and of the {Tesla} module,
+  # such as `open_timeout` and `proxy_url`, which is where they are configured.
+  #
+  # TLS certificates are verified, and no option turns that off: a host whose certificate OpenSSL does not already
+  # trust, such as the vehicle command proxy with a certificate of its own, is reached by naming that certificate
+  # with `ca_file`.
+  #
+  # @api private
+  class Connection
+    include CertificateOptions
+    include Settings
+    include URLValidation
+
+    # Default timeout for opening connections in seconds
+    DEFAULT_OPEN_TIMEOUT = 60 # seconds
+    # Default timeout for reading responses in seconds
+    DEFAULT_READ_TIMEOUT = 60 # seconds
+    # Default timeout for writing requests in seconds
+    DEFAULT_WRITE_TIMEOUT = 60 # seconds
+    # Default seconds an idle connection is kept open for another request
+    DEFAULT_KEEP_ALIVE_TIMEOUT = 2 # seconds
+
+    # @!method open_timeout
+    #   The timeout for opening connections in seconds
+    #   @api private
+    #   @return [Numeric] the timeout for opening connections in seconds
+    #   @example Get the open timeout
+    #     connection.open_timeout
+    # @!method open_timeout=(open_timeout)
+    #   Set the timeout for opening connections in seconds
+    #   @api private
+    #   @param open_timeout [Numeric] the timeout for opening connections in seconds
+    #   @return [void]
+    #   @raise [ArgumentError] if it is not a number of seconds, in which case the timeout is left as it was
+    #   @example Set the open timeout
+    #     connection.open_timeout = 30
+    seconds_setting :open_timeout
+
+    # @!method read_timeout
+    #   The timeout for reading responses in seconds
+    #   @api private
+    #   @return [Numeric] the timeout for reading responses in seconds
+    #   @example Get the read timeout
+    #     connection.read_timeout
+    # @!method read_timeout=(read_timeout)
+    #   Set the timeout for reading responses in seconds
+    #   @api private
+    #   @param read_timeout [Numeric] the timeout for reading responses in seconds
+    #   @return [void]
+    #   @raise [ArgumentError] if it is not a number of seconds, in which case the timeout is left as it was
+    #   @example Set the read timeout
+    #     connection.read_timeout = 30
+    seconds_setting :read_timeout
+
+    # @!method write_timeout
+    #   The timeout for writing requests in seconds
+    #   @api private
+    #   @return [Numeric] the timeout for writing requests in seconds
+    #   @example Get the write timeout
+    #     connection.write_timeout
+    # @!method write_timeout=(write_timeout)
+    #   Set the timeout for writing requests in seconds
+    #   @api private
+    #   @param write_timeout [Numeric] the timeout for writing requests in seconds
+    #   @return [void]
+    #   @raise [ArgumentError] if it is not a number of seconds, in which case the timeout is left as it was
+    #   @example Set the write timeout
+    #     connection.write_timeout = 30
+    seconds_setting :write_timeout
+
+    # @!method keep_alive_timeout
+    #   The seconds an idle connection is kept open for another request
+    #
+    #   A request is sent on the connection kept open for its host when one was used within this many seconds, so
+    #   that a series of requests does not open a connection each. Zero closes every connection when its request is
+    #   done.
+    #
+    #   @api private
+    #   @return [Numeric] the seconds an idle connection is kept open
+    #   @example Get the keep-alive timeout
+    #     connection.keep_alive_timeout
+    # @!method keep_alive_timeout=(keep_alive_timeout)
+    #   Set the seconds an idle connection is kept open for another request
+    #   @api private
+    #   @param keep_alive_timeout [Numeric] the seconds an idle connection is kept open
+    #   @return [void]
+    #   @raise [ArgumentError] if it is not a number of seconds, in which case the timeout is left as it was
+    #   @example Set the keep-alive timeout
+    #     connection.keep_alive_timeout = 0
+    seconds_setting :keep_alive_timeout
+
+    # The IO object for debug output
+    #
+    # The credentials requests and responses carry are redacted from what is written to it (see {RedactedOutput}).
+    #
+    # @api private
+    # @return [IO, nil] the IO object for debug output
+    # @example Get or set the debug output
+    #   connection.debug_output = $stderr
+    attr_accessor :debug_output
+
+    # The proxy URL for requests
+    # @api private
+    # @return [String, nil] the proxy URL for requests
+    # @example Get the proxy URL
+    #   connection.proxy_url
+    attr_reader :proxy_url
+
+    # The parsed proxy URI
+    # @api private
+    # @return [URI::Generic, nil] the parsed proxy URI
+    # @example Get the proxy URI
+    #   connection.proxy_uri
+    attr_reader :proxy_uri
+
+    # Summarize the connection for the console
+    #
+    # @api private
+    # @return [String] the summary, which includes the proxy URL without its user and password
+    # @example Inspect a connection
+    #   connection.inspect # => #<Tesla::Connection proxy_url=nil open_timeout=60 read_timeout=60 write_timeout=60 keep_alive_timeout=2>
+    def inspect
+      "#<#{self.class} proxy_url=#{redact(proxy_url).inspect} open_timeout=#{open_timeout} " \
+        "read_timeout=#{read_timeout} write_timeout=#{write_timeout} keep_alive_timeout=#{keep_alive_timeout}>"
+    end
+
+    # Initialize a new connection
+    #
+    # @api private
+    # @param open_timeout [Numeric] the timeout for opening connections in seconds
+    # @param read_timeout [Numeric] the timeout for reading responses in seconds
+    # @param write_timeout [Numeric] the timeout for writing requests in seconds
+    # @param debug_output [IO, nil] the IO object for debug output
+    # @param proxy_url [String, nil] the proxy URL for requests
+    # @param keep_alive_timeout [Numeric] the seconds an idle connection is kept open for another request
+    # @param ca_file [String, nil] the path of a file of certificates TLS is verified with
+    # @return [Connection] a new connection instance
+    # @raise [ArgumentError] if the proxy URL is invalid, or the certificate path names nothing
+    # @example Create a connection with default settings
+    #   connection = Tesla::Connection.new
+    # @example Create a connection with custom timeouts
+    #   connection = Tesla::Connection.new(open_timeout: 30, read_timeout: 30)
+    # @example Create a connection that trusts the certificate of the vehicle command proxy
+    #   connection = Tesla::Connection.new(ca_file: "config/tls-cert.pem")
+    def initialize(open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT,
+      write_timeout: DEFAULT_WRITE_TIMEOUT, debug_output: nil, proxy_url: nil,
+      keep_alive_timeout: DEFAULT_KEEP_ALIVE_TIMEOUT, ca_file: nil)
+      self.open_timeout = open_timeout
+      self.read_timeout = read_timeout
+      self.write_timeout = write_timeout
+      @debug_output = debug_output
+      self.keep_alive_timeout = keep_alive_timeout
+      @pool = ConnectionPool.new
+      self.proxy_url = proxy_url
+      self.ca_file = ca_file
+    end
+
+    # Perform an HTTP request
+    #
+    # The request is sent on the connection kept open for its host, when there is one it can be sent on, and that
+    # connection is kept open for the next request (see {#keep_alive_timeout}).
+    #
+    # The settings are read once, before the connection is taken, and a connection that has to be opened is opened
+    # with them and kept under them, so that a setting changed while the request is being sent, from another thread,
+    # closes the connection when the next request is sent rather than keeping it as though it had been opened with
+    # the setting as it is now, and a connection is never opened with one setting and kept under another.
+    #
+    # @api private
+    # @param request [Net::HTTPRequest] the HTTP request to perform
+    # @return [Net::HTTPResponse] the HTTP response
+    # @raise [NetworkError] if a network error occurs
+    # @example Perform a request
+    #   response = connection.perform(request: request)
+    def perform(request:)
+      send_request(request, settings_for(request.uri))
+    rescue *NetworkError::WRAPPED => e
+      raise NetworkError, "Network error: #{e}"
+    end
+
+    # Close the connections kept open for the next request
+    #
+    # The connections are opened again as they are needed, so a connection that is closed while it is being used is
+    # not interrupted, and requests can still be made afterwards.
+    #
+    # @api private
+    # @return [Connection] the connection
+    # @example Close the connections a client keeps open
+    #   connection.close
+    def close
+      pool.close
+      self
+    end
+
+    # Set the proxy URL for requests
+    #
+    # @api private
+    # @param proxy_url [String, nil] the proxy URL, or nil to read proxies from the environment again
+    # @return [void]
+    # @raise [ArgumentError] if the proxy URL is invalid, in which case the proxy is left as it was
+    # @example Set the proxy URL
+    #   connection.proxy_url = "http://proxy.example.com:8080"
+    # @example Clear the proxy URL
+    #   connection.proxy_url = nil
+    def proxy_url=(proxy_url)
+      proxy_uri = proxy_url && parse_proxy_uri(proxy_url)
+      @proxy_url = proxy_url
+      @proxy_uri = proxy_uri
+    end
+
+    private
+
+    # The connections kept open for the next request
+    # @api private
+    # @return [ConnectionPool] the pool
+    attr_reader :pool
+
+    # The settings a connection to a URI is opened with
+    #
+    # A connection kept open must still have them to be reused. The proxy is the one a request to the URI is sent
+    # through, which is read from the http_proxy, https_proxy, and no_proxy environment variables when no proxy URL
+    # is configured, so that a connection kept open is not reused past a change to the environment either.
+    #
+    # @api private
+    # @param uri [URI::Generic] the URI a request is sent to
+    # @return [Hash{Symbol => Object}] the settings
+    def settings_for(uri)
+      {open_timeout:, read_timeout:, write_timeout:, keep_alive_timeout:, debug_output:,
+       proxy: proxy_uri || uri.find_proxy, ca_file:}
+    end
+
+    # Send a request on a connection opened with the settings given
+    #
+    # A connection that has to be opened is opened with those settings, and the connection is kept under them
+    # afterwards, rather than under the settings as they are then.
+    #
+    # A request sent on a connection with a debug output asks for its response uncompressed, since the debug output
+    # is written the body as it was sent, and the credentials of a compressed body could not be redacted from it
+    # (see {RedactedOutput}).
+    #
+    # @api private
+    # @param request [Net::HTTPRequest] the HTTP request to send
+    # @param opened_with [Hash{Symbol => Object}] the settings a connection must have been opened with to send it on
+    # @return [Net::HTTPResponse] the HTTP response
+    def send_request(request, opened_with)
+      kept_for = opened_with.fetch(:keep_alive_timeout)
+      request["Accept-Encoding"] = "identity" if opened_with.fetch(:debug_output)
+      http_client = pool.checkout(request:, settings: opened_with, keep_alive_timeout: kept_for) do
+        build_http_client(request.uri, opened_with)
+      end
+      response = request_on(http_client, request)
+      pool.checkin(request:, http_client:, settings: opened_with, keep_alive_timeout: kept_for)
+      response
+    end
+
+    # Send a request on a connection, and close the connection if the request raises
+    #
+    # The connection is closed whatever the request raises, rather than left open with a response half read: a
+    # timeout of the caller's own, a Thread#raise, or an interrupt stops a request as surely as the network does.
+    #
+    # @api private
+    # @param http_client [Net::HTTP] the connection
+    # @param request [Net::HTTPRequest] the HTTP request to send
+    # @return [Net::HTTPResponse] the HTTP response
+    def request_on(http_client, request)
+      http_client.request(request)
+    rescue Exception # rubocop:disable Lint/RescueException
+      pool.discard(http_client)
+      raise
+    end
+
+    # Decode a percent-encoded component of a URL
+    # @api private
+    # @param component [String, nil] the component
+    # @return [String, nil] the decoded component, or nil for nil
+    def decode(component)
+      component && URI.decode_uri_component(component)
+    end
+
+    # Build an HTTP client for the given URI, with the settings given
+    #
+    # An https:// proxy is connected to over TLS.
+    #
+    # @api private
+    # @param uri [URI::Generic] the URI to connect to
+    # @param opened_with [Hash{Symbol => Object}] the settings to open the connection with
+    # @return [Net::HTTP] the HTTP client
+    # @raise [ArgumentError] if the URI has no host
+    def build_http_client(uri, opened_with)
+      host = uri.host
+      raise ArgumentError, "URI has no host: #{uri}" if host.nil?
+
+      proxy_host, proxy_port, proxy_user, proxy_pass, proxy_use_ssl = proxy_arguments_for(opened_with.fetch(:proxy))
+      http_client = Net::HTTP.new(host, uri.port, proxy_host, proxy_port, proxy_user, proxy_pass, nil, proxy_use_ssl)
+      http_client.use_ssl = uri.scheme.eql?("https")
+      configure_http_client(http_client, opened_with)
+    end
+
+    # The proxy host, port, user, password, and whether to use TLS for a proxy
+    #
+    # The user and password are decoded from the proxy URL, and an https:// proxy is connected to over TLS.
+    #
+    # @api private
+    # @param proxy [URI::Generic, nil] the proxy, or nil to connect directly
+    # @return [Array] the proxy host, port, user, password, and whether to use TLS, each nil without a proxy
+    def proxy_arguments_for(proxy)
+      [proxy&.host, proxy&.port, decode(proxy&.user), decode(proxy&.password), proxy&.instance_of?(URI::HTTPS)]
+    end
+
+    # Configure an HTTP client with the timeouts given
+    #
+    # @api private
+    # @param http_client [Net::HTTP] the HTTP client to configure
+    # @param opened_with [Hash{Symbol => Object}] the settings to configure it with
+    # @return [Net::HTTP] the configured HTTP client
+    def configure_timeouts(http_client, opened_with)
+      http_client.tap do |c|
+        c.open_timeout = opened_with.fetch(:open_timeout)
+        c.read_timeout = opened_with.fetch(:read_timeout)
+        c.write_timeout = opened_with.fetch(:write_timeout)
+        c.keep_alive_timeout = opened_with.fetch(:keep_alive_timeout)
+      end
+    end
+
+    # Configure an HTTP client with the timeouts, debug output, and CA file given
+    #
+    # The debug output is wrapped, so that the credentials Net::HTTP writes with the headers of a request do not
+    # reach the IO.
+    #
+    # Net::HTTP sends an idempotent request again once on its own when the connection it was sent on fails, which
+    # the retries of {RetryHandler} would otherwise come on top of, so a request that timed out reading its response
+    # would wait twice as many read timeouts as `max_retries` allows for. It is left to {RetryHandler} alone.
+    #
+    # @api private
+    # @param http_client [Net::HTTP] the HTTP client to configure
+    # @param opened_with [Hash{Symbol => Object}] the settings to configure it with
+    # @return [Net::HTTP] the configured HTTP client
+    def configure_http_client(http_client, opened_with)
+      debug_output = opened_with.fetch(:debug_output)
+      configure_timeouts(http_client, opened_with).tap do |c|
+        c.max_retries = 0
+        c.set_debug_output(debug_output && RedactedOutput.new(debug_output))
+        c.ca_file = opened_with.fetch(:ca_file)
+      end
+    end
+  end
+end

data/lib/tesla/connection_pool.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "net/http"
+require_relative "idempotence"
+
+module Tesla
+  # Keeps the connections a {Connection} is not using, so that a request can be sent on one that is already open
+  #
+  # One connection is kept for each host, so that requests made at the same time are sent on connections of their
+  # own rather than waiting for one another, and the connections they opened are closed when they are given back.
+  # A connection opened with settings that have since changed is closed rather than reused.
+  #
+  # A process forked from one that kept a connection open shares the socket of that connection with it, so the
+  # connection is kept for the process that opened it alone: a forked process opens one of its own, rather than
+  # reading the responses to the requests of the other process, and leaves the one it inherited alone, rather than
+  # closing it under the process still using it.
+  #
+  # @api private
+  class ConnectionPool
+    include Idempotence
+
+    # Initialize a new ConnectionPool
+    #
+    # @api private
+    # @return [ConnectionPool] a new instance
+    # @example Create a connection pool
+    #   pool = Tesla::ConnectionPool.new
+    def initialize
+      @connections = {}
+      @mutex = Mutex.new
+    end
+
+    # The connection to send a request on
+    #
+    # A connection kept open for the host of the request is used when the request can be sent on one, and one is
+    # opened with the block otherwise.
+    #
+    # @api private
+    # @param request [Net::HTTPRequest] the request
+    # @param settings [Object] the settings a connection must have been opened with to be reused
+    # @param keep_alive_timeout [Numeric] the seconds an idle connection is kept open, or zero to open one each time
+    # @yield the connection to open when none is kept for the host of the request
+    # @return [Net::HTTP] the connection, which is open
+    # @example Take the connection to send a request on
+    #   pool.checkout(request:, settings:, keep_alive_timeout: 2) { Net::HTTP.new(uri.host, uri.port) }
+    def checkout(request:, settings:, keep_alive_timeout:)
+      http_client = take(pool_key(request), settings) if keep_alive?(request, keep_alive_timeout)
+      http_client || yield.tap(&:start)
+    end
+
+    # Keep the connection a request was sent on, or close it
+    #
+    # @api private
+    # @param request [Net::HTTPRequest] the request
+    # @param http_client [Net::HTTP] the connection it was sent on
+    # @param settings [Object] the settings the connection was opened with
+    # @param keep_alive_timeout [Numeric] the seconds an idle connection is kept open, or zero to close it
+    # @return [void]
+    # @example Give back the connection a request was sent on
+    #   pool.checkin(request:, http_client:, settings:, keep_alive_timeout: 2)
+    def checkin(request:, http_client:, settings:, keep_alive_timeout:)
+      return discard(http_client) unless keep_alive?(request, keep_alive_timeout)
+
+      store(pool_key(request), http_client, settings)
+    end
+
+    # Close a connection
+    #
+    # @api private
+    # @param http_client [Net::HTTP, nil] the connection, or nil when none was opened
+    # @return [void]
+    # @example Close the connection a request failed on
+    #   pool.discard(http_client)
+    def discard(http_client)
+      http_client.finish if http_client&.started?
+    end
+
+    # Take the connection kept for a key
+    #
+    # The connection is removed from the pool, so that it is used by one request at a time, and is given back with
+    # {#store}. A connection opened with other settings is closed instead of returned, and one opened by the process
+    # this one was forked from is left to that process.
+    #
+    # @api private
+    # @param key [Object] the key the connection is kept under
+    # @param settings [Object] the settings a connection must have been opened with to be reused
+    # @return [Net::HTTP, nil] the connection, or nil when none is kept for the key
+    # @example Take the connection kept for a host
+    #   pool.take(["https", "fleet-api.prd.na.vn.cloud.tesla.com", 443], settings)
+    def take(key, settings)
+      http_client, kept_settings, pid = @mutex.synchronize { @connections.delete(key) }
+      return unless opened_here?(pid)
+      return http_client if settings.eql?(kept_settings)
+
+      discard(http_client)
+      nil
+    end
+
+    # Keep a connection for a key
+    #
+    # A connection is kept only when none is kept for the key already, so that the pool holds one connection per
+    # host; a connection it cannot keep is closed. One kept by the process this one was forked from does not count,
+    # and is replaced.
+    #
+    # @api private
+    # @param key [Object] the key to keep the connection under
+    # @param http_client [Net::HTTP] the connection
+    # @param settings [Object] the settings the connection was opened with
+    # @return [Boolean] whether the connection was kept
+    # @example Keep a connection for a host
+    #   pool.store(["https", "fleet-api.prd.na.vn.cloud.tesla.com", 443], http_client, settings)
+    def store(key, http_client, settings)
+      stored = @mutex.synchronize do
+        @connections[key] = [http_client, settings, Process.pid] unless opened_here?(@connections.dig(key, 2))
+      end
+      discard(http_client) if stored.nil?
+      !stored.nil?
+    end
+
+    # Close every connection the pool keeps
+    #
+    # The keys are read under the lock, as every other read and write of the connections is, since a request giving
+    # its connection back at that moment writes to them from another thread. The connections are then taken one at a
+    # time, so that a connection given back while the pool is closing is either closed with the rest or kept for the
+    # next request, rather than dropped without being closed. The connections opened by the process this one was
+    # forked from are forgotten rather than closed, since that process may still be using them.
+    #
+    # @api private
+    # @return [ConnectionPool] the pool
+    # @example Close the connections of a pool
+    #   pool.close
+    def close
+      keys = @mutex.synchronize { @connections.keys }
+      keys.each { |key| discard(delete(key)) }
+      self
+    end
+
+    private
+
+    # Take the connection kept for a key, whatever settings it was opened with
+    # @api private
+    # @param key [Object] the key the connection is kept under
+    # @return [Net::HTTP, nil] the connection, or nil when none is kept for the key or the one kept was opened by the
+    #   process this one was forked from
+    def delete(key)
+      http_client, _settings, pid = @mutex.synchronize { @connections.delete(key) }
+      http_client if opened_here?(pid)
+    end
+
+    # Whether a connection was opened by this process
+    #
+    # A connection opened by the process this one was forked from was not, and shares its socket with that process.
+    #
+    # @api private
+    # @param pid [Integer, nil] the ID of the process that opened the connection, or nil when none is kept
+    # @return [Boolean] whether it is the ID of this process
+    def opened_here?(pid)
+      Process.pid.eql?(pid)
+    end
+
+    # Whether a request can be sent on a connection that is kept open
+    #
+    # The connection it is sent on is kept open afterwards too. A request that asks the server to do something is
+    # sent on a connection of its own and that connection is closed afterwards: Net::HTTP reconnects before it reuses
+    # a connection the server has closed, and {RetryHandler} sends a safe request whose connection breaks again, but
+    # a request that asks the server to do something cannot be sent again to find out whether the server acted on
+    # the first one.
+    #
+    # @api private
+    # @param request [Net::HTTPRequest] the request
+    # @param keep_alive_timeout [Numeric] the seconds an idle connection is kept open
+    # @return [Boolean] whether the connection is kept open
+    def keep_alive?(request, keep_alive_timeout)
+      keep_alive_timeout.positive? && safe?(request.method)
+    end
+
+    # The key a connection is kept under, which is the host it is open to
+    # @api private
+    # @param request [Net::HTTPRequest] the request
+    # @return [Array] the scheme, host, and port
+    def pool_key(request)
+      uri = request.uri
+      [uri.scheme, uri.host, uri.port]
+    end
+  end
+end

data/lib/tesla/deep_copy.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Tesla
+  # The copies a {Resource} is made of and answers with: frozen for the resource, and unfrozen for the caller
+  # @api private
+  module DeepCopy
+    private
+
+    # Copy a value, freezing the copy and everything nested inside it
+    #
+    # The keys of hashes are converted to strings. Everything a parsed JSON response holds other than hashes, arrays, and strings is already immutable.
+    #
+    # @api private
+    # @param value [Object] the value to copy
+    # @return [Object] the frozen copy
+    def deep_freeze(value)
+      case value
+      when Hash then value.to_h { |key, nested| [key.to_s, deep_freeze(nested)] }.freeze
+      when Array then value.map { |nested| deep_freeze(nested) }.freeze
+      when String then value.dup.freeze
+      else value
+      end
+    end
+
+    # Copy a value and everything nested inside it, for the caller to change
+    #
+    # The keys of hashes are left as they are, since a hash freezes the strings it is keyed by itself. Everything a
+    # parsed JSON response holds other than hashes, arrays, and strings answers `dup` with itself.
+    #
+    # @api private
+    # @param value [Object] the value to copy
+    # @return [Object] the copy, which is not frozen
+    def deep_dup(value)
+      case value
+      when Hash then value.transform_values { |nested| deep_dup(nested) }
+      when Array then value.map { |nested| deep_dup(nested) }
+      else value.dup
+      end
+    end
+  end
+end

data/lib/tesla/drive_state.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Tesla
+  # The position and the driving state of a vehicle
+  # @api public
+  class DriveState < Resource
+    inspect_with :latitude, :longitude, :shift_state
+
+    # @!method latitude
+    #   The latitude of the vehicle
+    #
+    #   The Fleet API answers with it when it is asked for "location_data", for a token with the vehicle_location scope.
+    #
+    #   @api public
+    #   @return [Float, nil] the latitude of the vehicle
+    #   @example
+    #     drive_state.latitude
+    attribute :latitude
+
+    # @!method longitude
+    #   The longitude of the vehicle
+    #
+    #   The Fleet API answers with it when it is asked for "location_data", for a token with the vehicle_location scope.
+    #
+    #   @api public
+    #   @return [Float, nil] the longitude of the vehicle
+    #   @example
+    #     drive_state.longitude
+    attribute :longitude
+
+    # @!method heading
+    #   The compass heading of the vehicle in degrees
+    #   @api public
+    #   @return [Integer, nil] the compass heading of the vehicle
+    #   @example
+    #     drive_state.heading
+    attribute :heading
+
+    # @!method speed
+    #   The speed of the vehicle in miles per hour, or nil when it is parked
+    #   @api public
+    #   @return [Integer, nil] the speed of the vehicle
+    #   @example
+    #     drive_state.speed
+    attribute :speed
+
+    # @!method power
+    #   The power the vehicle is drawing in kilowatts
+    #
+    #   It is negative while the vehicle charges or regenerates.
+    #
+    #   @api public
+    #   @return [Integer, nil] the power the vehicle is drawing
+    #   @example
+    #     drive_state.power
+    attribute :power
+
+    # @!method shift_state
+    #   The gear the vehicle is in, "P", "R", "N", or "D"
+    #
+    #   It is nil when the vehicle is parked and idle.
+    #
+    #   @api public
+    #   @return [String, nil] the gear the vehicle is in
+    #   @example
+    #     drive_state.shift_state
+    attribute :shift_state
+
+    # @!method timestamp
+    #   The time the vehicle reported the state
+    #   @api public
+    #   @return [Time, nil] the time the vehicle reported the state
+    #   @raise [InvalidResponse] if the timestamp is not a number of milliseconds
+    #   @example
+    #     drive_state.timestamp
+    time_attribute :timestamp
+  end
+end

data/lib/tesla/errors/bad_gateway.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "server_error"
+
+module Tesla
+  # Error raised for HTTP 502 Bad Gateway responses
+  # @api public
+  class BadGateway < ServerError; end
+end

data/lib/tesla/errors/bad_request.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "client_error"
+
+module Tesla
+  # Error raised for HTTP 400 Bad Request responses
+  # @api public
+  class BadRequest < ClientError; end
+end