tesla 0.0.1 → 0.1.0

data/lib/tesla/retry_handler.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "net/http"
+require_relative "errors/network_error"
+require_relative "retry_after"
+require_relative "settings"
+
+module Tesla
+  # Sends a request again when the server, or the network, turns it away
+  #
+  # A 429 Too Many Requests says a rate limiter turned the request away before it reached the endpoint, so sending it
+  # again is safe for any request, even one that is not idempotent, such as a command: the vehicle never saw the
+  # attempt before it.
+  #
+  # A 502 Bad Gateway, a 503 Service Unavailable, a 504 Gateway Timeout, and a request lost to the network say less.
+  # A 502 or 504 comes from a gateway that could not read an answer from the origin behind it, a 503 can come from a
+  # service that gave up waiting on a vehicle still working on the request, and a request lost to the network may
+  # have arrived and been acted on before its answer went missing. The vehicle may have acted on the request in
+  # each case, so a request that asks it to do something, such as honking the horn or opening the trunk, is not sent
+  # again for one: a trunk asked to open a second time after it opened closes again on the vehicles that can close
+  # it.
+  #
+  # Whether a request is one of those is the caller's to say, with the `retry_unanswered` argument of {#handle}:
+  # {Client} says whether the method of the request is safe, since a command cannot be sent a second time to find
+  # out whether the vehicle acted on the first. A 429 is sent again whatever the caller says, since no request
+  # reached the endpoint.
+  #
+  # A request is sent again twice by default, which is enough for the moment of rate limiting or the lost
+  # connection that a retry is for, and {#max_retries} of zero turns retrying off, so that a request that was
+  # turned away raises {TooManyRequests}, {BadGateway}, {ServiceUnavailable}, {GatewayTimeout}, or {NetworkError}
+  # rather than pausing the caller's thread. A response asking to wait longer than {#max_retry_delay} raises
+  # whatever {#max_retries} is, so the wait a caller can be held for is theirs to cap.
+  #
+  # @api private
+  class RetryHandler
+    include RetryAfter
+    include Settings
+
+    # Default number of times a request is sent again
+    DEFAULT_MAX_RETRIES = 2
+    # Default longest a request waits before it is sent again, in seconds
+    DEFAULT_MAX_RETRY_DELAY = 60 # seconds
+    # The status that says a rate limiter turned the request away before it reached the endpoint
+    THROTTLED_STATUS = 429
+    # The statuses that say a gateway read no answer from the origin, which may have acted on the request
+    UNANSWERED_STATUSES = [502, 503, 504].freeze
+    private_constant :THROTTLED_STATUS, :UNANSWERED_STATUSES
+
+    # @!method max_retries
+    #   The number of times a request is sent again
+    #   @api private
+    #   @return [Integer] the number of times a request is sent again
+    #   @example Get the maximum retries
+    #     handler.max_retries
+    # @!method max_retries=(max_retries)
+    #   Set the number of times a request is sent again
+    #   @api private
+    #   @param max_retries [Integer] the number of times a request is sent again
+    #   @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 retries
+    #     handler.max_retries = 3
+    count_setting :max_retries
+
+    # @!method max_retry_delay
+    #   The longest a request waits before it is sent again, in seconds
+    #   @api private
+    #   @return [Numeric] the longest a request waits before it is sent again, in seconds
+    #   @example Get the maximum retry delay
+    #     handler.max_retry_delay
+    # @!method max_retry_delay=(max_retry_delay)
+    #   Set the longest a request waits before it is sent again, in seconds
+    #   @api private
+    #   @param max_retry_delay [Numeric] the longest a request waits before it is sent again, in seconds
+    #   @return [void]
+    #   @raise [ArgumentError] if it is not a number of seconds, in which case the maximum is left as it was
+    #   @example Set the maximum retry delay
+    #     handler.max_retry_delay = 30
+    seconds_setting :max_retry_delay
+
+    # The source of the randomness the backoff is jittered with
+    # @api private
+    # @return [Random, Class<Random>] the source of randomness
+    # @example Get the source of randomness
+    #   handler.random
+    attr_reader :random
+
+    # Initialize a new RetryHandler
+    #
+    # @api private
+    # @param max_retries [Integer] the number of times a request is sent again
+    # @param max_retry_delay [Numeric] the longest a request waits before it is sent again, in seconds
+    # @param random [Random, Class<Random>] the source of the randomness the backoff is jittered with, which
+    #   answers `rand` with a Float between zero and one
+    # @return [RetryHandler] a new instance
+    # @example Create a retry handler
+    #   handler = Tesla::RetryHandler.new(max_retries: 3)
+    def initialize(max_retries: DEFAULT_MAX_RETRIES, max_retry_delay: DEFAULT_MAX_RETRY_DELAY, random: Random)
+      self.max_retries = max_retries
+      self.max_retry_delay = max_retry_delay
+      @random = random
+    end
+
+    # Send a request until the server and the network stop turning it away
+    #
+    # The block is called again for each retry, so a request that was redirected is followed again from the start.
+    # The wait between attempts is the one the `Retry-After` header of the response asks for, and doubles from one
+    # second otherwise, up to {#max_retry_delay}, jittered as {#backoff} describes; that is the wait after a
+    # {NetworkError} too, since a request that never reached the server has no response to read a wait from. A
+    # response that asks to wait longer than {#max_retry_delay} is returned rather than waited for, so that the
+    # caller is told what happened instead of pausing for as long as the server likes, and a {NetworkError} that
+    # has no retry left is raised as it was.
+    #
+    # A request a rate limiter turned away is told apart from one the origin may have acted on, since they are not
+    # equally safe to send again: a 429 says the request never reached the endpoint, where a 502, 503, or 504, or a
+    # request lost to the network, may have been acted on before the answer went missing. The caller says whether
+    # its request is safe to send again for those. A 429 is sent again for every request.
+    #
+    # The request is not named, since the block builds one of its own each time it is called, so that a body read
+    # as a stream is sent from the start (see {Client#perform}).
+    #
+    # @api private
+    # @param retry_unanswered [Boolean] whether a request the origin may have acted on is sent again
+    # @yield the response, each time the request is sent
+    # @return [Net::HTTPResponse] the last response
+    # @raise [NetworkError] if the request is lost to the network and is not sent again
+    # @example Send a safe request, which is safe to send again whatever happened to it
+    #   handler.handle(retry_unanswered: true) { connection.perform(request:) }
+    # @example Send a request that is safe to send again only when a rate limiter turned it away
+    #   handler.handle(retry_unanswered: false) { connection.perform(request:) }
+    def handle(retry_unanswered:)
+      retries = 0
+      loop do
+        response = attempt(retries:, retry_unanswered:) { yield }
+        return response if response
+
+        retries += 1
+      end
+    end
+
+    private
+
+    # Send a request once, waiting afterwards when it is to be sent again
+    #
+    # @api private
+    # @param retries [Integer] the number of times the request has been sent again
+    # @param retry_unanswered [Boolean] whether a request the origin may have acted on is sent again
+    # @yield the response to the request
+    # @return [Net::HTTPResponse, nil] the response, or nil once the wait before sending the request again is over
+    # @raise [NetworkError] if the request is lost to the network and is not sent again
+    def attempt(retries:, retry_unanswered:)
+      response = yield
+      delay = retry_delay(response:, retries:, unanswered: retry_unanswered)
+      delay ? wait(delay) : response
+    rescue NetworkError
+      delay = network_retry_delay(retries:, allowed: retry_unanswered)
+      raise unless delay
+
+      wait(delay)
+    end
+
+    # Wait before a request is sent again
+    #
+    # Kernel#sleep takes any Numeric, but its signature asks for the narrower interface Integer and Float happen to
+    # answer, so the seconds are passed to it unchecked rather than narrowing what {#max_retry_delay} accepts.
+    #
+    # @api private
+    # @param delay [Numeric] the seconds to wait
+    # @return [nil] nothing, so that the caller sends the request again
+    def wait(delay)
+      sleep(delay) # steep:ignore UnresolvedOverloading
+      nil
+    end
+
+    # The seconds to wait before sending a request again
+    #
+    # A wait the response asked for is given up on when it is longer than {#max_retry_delay}, where the wait the
+    # handler chose for itself is shortened to it, since a backoff that has grown past the cap is the handler
+    # asking to wait longer than the caller allowed rather than the server doing so.
+    #
+    # @api private
+    # @param response [Net::HTTPResponse] the response to the request
+    # @param retries [Integer] the number of times the request has been sent again
+    # @param unanswered [Boolean] whether a request the origin may have acted on is sent again
+    # @return [Numeric, nil] the seconds to wait, or nil when the request is not sent again
+    def retry_delay(response:, retries:, unanswered:)
+      return unless retryable?(retry?(response, unanswered), retries)
+
+      retry_after = retry_after_of(response)
+      retry_after ? capped(retry_after) : backoff(retries)
+    end
+
+    # The seconds to wait before sending a request again after a network error
+    # @api private
+    # @param retries [Integer] the number of times the request has been sent again
+    # @param allowed [Boolean] whether a request lost to the network is sent again
+    # @return [Numeric, nil] the seconds to wait, or nil when the request is not sent again
+    def network_retry_delay(retries:, allowed:)
+      return unless retryable?(allowed, retries)
+
+      backoff(retries)
+    end
+
+    # Whether a request has a retry left and is one the caller allows to be sent again
+    # @api private
+    # @param allowed [Boolean] whether the request is sent again for what happened to it
+    # @param retries [Integer] the number of times the request has been sent again
+    # @return [Boolean] whether the request is sent again
+    def retryable?(allowed, retries)
+      retries < max_retries && allowed
+    end
+
+    # The seconds a response asked for, unless longer than the caller allowed
+    # @api private
+    # @param delay [Integer] the seconds the response asked to wait
+    # @return [Integer, nil] the seconds to wait, or nil when they are longer than {#max_retry_delay}
+    def capped(delay)
+      delay unless delay > max_retry_delay
+    end
+
+    # Whether a response is one the request is sent again for
+    #
+    # A 429 says a rate limiter turned the request away before it reached the endpoint, and is sent again whatever
+    # the request; a 502, 503, or 504 says the origin may have acted on it, and is sent again only by the caller
+    # that says its request can be answered twice.
+    #
+    # @api private
+    # @param response [Net::HTTPResponse] the response to the request
+    # @param unanswered [Boolean] whether a request the origin may have acted on is sent again
+    # @return [Boolean] whether the request is sent again
+    def retry?(response, unanswered)
+      status = Integer(response.code)
+      status.eql?(THROTTLED_STATUS) || (unanswered && UNANSWERED_STATUSES.include?(status))
+    end
+
+    # The seconds to wait when the response does not ask for a wait of its own
+    #
+    # The wait doubles with each retry up to {#max_retry_delay}, and is then jittered down by up to half of itself,
+    # so that the clients a server turned away at the same moment do not all send their requests again at the same
+    # instant and turn the retry into a second wave of the load the server was shedding. A wait the response asked
+    # for is not jittered: the server named the moment it is ready for the request, and jittering that wait down
+    # would send the request again before then.
+    #
+    # @api private
+    # @param retries [Integer] the number of times the request has been sent again
+    # @return [Numeric] the seconds to wait, between half of the doubling wait and all of it
+    def backoff(retries)
+      delay = [2**retries, max_retry_delay].min
+      delay - (random.rand * delay / 2) #: Numeric
+    end
+  end
+end

data/lib/tesla/settings.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Tesla
+  # Declares the settings that are a number of seconds, a number of times, or a credential the environment can
+  # carry, and checks what is assigned to them, mixed into the configuration, the connection, and the retry handler
+  #
+  # A number is checked where it is assigned, as a host, a proxy URL, and the path of a certificate are (see
+  # {URLValidation} and {CertificateOptions}), so that the error names the assignment that was wrong rather than
+  # the request that later waits for a negative number of seconds, or compares the times it has been sent again
+  # with a String. The value that is rejected is left as it was.
+  #
+  # The settings are declared rather than written out, as the readers of a {Resource} are, since the reader and the
+  # writer of each differ only in the name they carry and the check the writer makes; each is documented where it
+  # is declared.
+  #
+  # @api private
+  module Settings
+    # The macros that declare the settings, extended into whatever includes {Settings}
+    # @api private
+    module Declaration
+      # Declare a setting that is a number of seconds
+      #
+      # @api private
+      # @param name [Symbol] the name of the setting
+      # @return [Symbol] the name of the writer
+      # @example Declare a timeout
+      #   seconds_setting :open_timeout
+      def seconds_setting(name)
+        attr_reader(name)
+
+        define_method(:"#{name}=") do |seconds|
+          # @type self: Settings
+          instance_variable_set(:"@#{name}", validate_number(name, seconds))
+        end
+      end
+
+      # Declare a setting that is a number of times
+      #
+      # @api private
+      # @param name [Symbol] the name of the setting
+      # @return [Symbol] the name of the writer
+      # @example Declare a maximum
+      #   count_setting :max_retries
+      def count_setting(name)
+        attr_reader(name)
+
+        define_method(:"#{name}=") do |count|
+          # @type self: Settings
+          instance_variable_set(:"@#{name}", validate_count(name, count))
+        end
+      end
+
+      # Declare a setting that falls back to an environment variable
+      #
+      # The environment is read each time the setting is, rather than once as the library is loaded, so that a
+      # variable set afterwards, such as one a dotenv file is read for, is the one a client is built with. A setting
+      # that has been assigned, even nil, is read as it was assigned.
+      #
+      # @api private
+      # @param name [Symbol] the name of the setting
+      # @param variable [String] the name of the environment variable the setting falls back to
+      # @return [Array<Symbol>] the name of the writer
+      # @example Declare a credential
+      #   environment_setting :client_id, "TESLA_CLIENT_ID"
+      def environment_setting(name, variable)
+        define_method(name) do
+          # @type self: Settings
+          instance_variable_defined?(:"@#{name}") ? instance_variable_get(:"@#{name}") : ENV.fetch(variable, nil)
+        end
+
+        attr_writer(name)
+      end
+    end
+
+    # Extend whatever includes the mixin with the macros that declare the settings
+    #
+    # @api private
+    # @param base [Module] the module or class including {Settings}
+    # @return [void]
+    def self.included(base)
+      base.extend(Declaration)
+    end
+
+    private
+
+    # Check that a setting is a number of zero or more
+    #
+    # Any Numeric is one, since a timeout shorter than a second is a Float, and zero is one: it turns off the wait
+    # or the retrying the setting names rather than leaving it unset.
+    #
+    # @api private
+    # @param name [Symbol] the name of the setting, which the message names
+    # @param number [Object] the value assigned
+    # @return [Numeric] the number
+    # @raise [ArgumentError] if the value is not a number of zero or more
+    def validate_number(name, number)
+      raise ArgumentError, "Invalid #{name}: #{number.inspect}" unless number.is_a?(Numeric) && number >= 0
+
+      number
+    end
+
+    # Check that a setting is a whole number of times
+    #
+    # @api private
+    # @param name [Symbol] the name of the setting, which the message names
+    # @param count [Object] the value assigned
+    # @return [Integer] the count
+    # @raise [ArgumentError] if the value is not a whole number of zero or more times
+    def validate_count(name, count)
+      raise ArgumentError, "Invalid #{name}: #{count.inspect}" unless validate_number(name, count).integer?
+
+      count
+    end
+  end
+end

data/lib/tesla/url_validation.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Tesla
+  # Checks and compares the URLs a host, a proxy, and a redirect are given as, mixed into the configuration, the
+  # client, the connection, and the redirect handler
+  #
+  # A URL is checked where it is assigned rather than when a request is made with it, so that the error names the
+  # assignment that was wrong instead of the call that happened to send the next request. The value that is rejected
+  # is left as it was.
+  #
+  # @api private
+  module URLValidation
+    private
+
+    # Check that a host is a URL requests can be sent to
+    #
+    # A host that carries a user and password, such as "https://user:pass@tesla.example.com", is refused: Net::HTTP
+    # sends neither, and the host is shown by {Client#inspect} and in error messages, which would show the
+    # password. The message the host is refused with leaves them out.
+    #
+    # @api private
+    # @param host [String] the host, including scheme
+    # @return [String] the host
+    # @raise [ArgumentError] if the host is not an HTTP or HTTPS URL, or carries a user and password
+    def validate_host(host)
+      raise ArgumentError, "Invalid host: #{redact(host.to_s)}" unless http_url?(host)
+      if URI(host).userinfo
+        raise ArgumentError, "Invalid host: #{redact(host)} carries a user and password, which are not sent"
+      end
+
+      host
+    end
+
+    # Parse and validate a proxy URL
+    #
+    # @api private
+    # @param proxy_url [String] the proxy URL
+    # @return [URI::HTTP] the proxy URI
+    # @raise [ArgumentError] if the proxy URL is not a valid HTTP or HTTPS URL; the message leaves out its user and
+    #   password
+    def parse_proxy_uri(proxy_url)
+      proxy_uri = URI(proxy_url)
+      raise ArgumentError, "Invalid proxy URL: #{redact(proxy_url)}" unless proxy_uri.is_a?(URI::HTTP)
+
+      proxy_uri
+    rescue URI::InvalidURIError
+      raise ArgumentError, "Invalid proxy URL: #{redact(proxy_url)}"
+    end
+
+    # Whether a host is an HTTP or HTTPS URL with a host
+    # @api private
+    # @param host [Object] the host
+    # @return [Boolean] whether the host is a URL requests can be sent to
+    def http_url?(host)
+      uri = URI(host)
+      uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+    rescue ArgumentError, URI::InvalidURIError
+      false
+    end
+
+    # Join a host and a request path, keeping any path prefix on the host
+    #
+    # A path that is a URL of its own is refused rather than followed to the host it names, since the access token
+    # of a request is the one issued for the host it was meant for, and a path that moved the request to another
+    # host would take the token with it.
+    #
+    # A path that climbs out of the prefix the host carries, such as "../.." for a host of
+    # "https://tesla.example.com/fleet", is refused for the same reason: the client was pointed at that prefix, and
+    # a path that leaves it asks the rest of the host with the access token of the client. A host without a prefix
+    # names the whole of its origin, so there is nothing to climb out of.
+    #
+    # @api private
+    # @param host [String] the host, optionally carrying a path prefix
+    # @param path [String] the request path
+    # @return [URI] the request URI
+    # @raise [ArgumentError] if the path is a URL of an origin other than the host, or climbs out of its prefix
+    def build_uri(host, path)
+      uri = URI.join("#{host.chomp("/")}/", path.delete_prefix("/"))
+      raise ArgumentError, "Path is not on #{host}: #{path}" unless on_host?(uri, host)
+
+      uri
+    end
+
+    # Whether two URLs share a scheme, host, and port
+    #
+    # @api private
+    # @param url [String, URI::Generic] one URL
+    # @param other [String, URI::Generic] the other URL
+    # @return [Boolean] whether the URLs share an origin
+    def same_origin?(url, other)
+      origin(url).eql?(origin(other))
+    end
+
+    # Whether a URL is the host's own, at or under the path the host names
+    #
+    # The path is compared as well as the origin, so that a URL climbing out of the prefix a host carries, such as
+    # "../.." for "https://tesla.example.com/fleet", is told from one the host was pointed at, as a URL of
+    # another scheme, host, or port is. A host that carries no prefix names the whole of its origin, so every URL
+    # of that origin is on it.
+    #
+    # The paths are read once the origins are known to match, so a URL that has none, such as a "mailto:" URL, is
+    # answered by the comparison of the origins rather than by reading the path it does not have.
+    #
+    # @api private
+    # @param uri [URI::Generic] the URL, as the URI it was read as
+    # @param host [String, URI::Generic] the host, optionally carrying a path prefix
+    # @return [Boolean] whether the URL is the host's own, at or under the path it names
+    def on_host?(uri, host)
+      same_origin?(uri, host) && uri.path.start_with?("#{URI(host).path.chomp("/")}/") # steep:ignore NoMethod
+    end
+
+    # The origin of a URL, with the scheme and host in lowercase
+    # @api private
+    # @param url [String, URI::Generic] the URL
+    # @return [Array] the scheme, host, and port
+    def origin(url)
+      uri = URI(url).normalize
+      [uri.scheme, uri.host, uri.port]
+    end
+
+    # Remove the user and password from a URL
+    # @api private
+    # @param url [String, nil] the URL
+    # @return [String, nil] the URL without its userinfo, or nil for nil
+    def redact(url)
+      url&.sub(%r{(?<=//)[^/@]*@}, "")
+    end
+  end
+end

data/lib/tesla/user.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Tesla
+  # The user of an account
+  # @api public
+  class User < Resource
+    inspect_with :email
+    identified_by :email
+
+    # @!method email
+    #   The email address of the user
+    #   @api public
+    #   @return [String, nil] the email address of the user
+    #   @example
+    #     user.email
+    attribute :email
+
+    # @!method full_name
+    #   The full name of the user
+    #   @api public
+    #   @return [String, nil] the full name of the user
+    #   @example
+    #     user.full_name
+    attribute :full_name
+
+    # @!method profile_image_url
+    #   The URL of the profile image of the user
+    #   @api public
+    #   @return [String, nil] the URL of the profile image of the user
+    #   @example
+    #     user.profile_image_url
+    attribute :profile_image_url
+  end
+end

data/lib/tesla/vehicle.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Tesla
+  # A vehicle of the account
+  # @api public
+  class Vehicle < Resource
+    inspect_with :vin, :display_name, :state
+    identified_by :vin
+
+    # @!method id
+    #   The ID the Fleet API knows the vehicle by
+    #   @api public
+    #   @return [Integer, nil] the ID the Fleet API knows the vehicle by
+    #   @example
+    #     vehicle.id
+    attribute :id
+
+    # @!method vehicle_id
+    #   The ID the streaming and Autopark APIs know the vehicle by
+    #   @api public
+    #   @return [Integer, nil] the ID the streaming and Autopark APIs know the vehicle by
+    #   @example
+    #     vehicle.vehicle_id
+    attribute :vehicle_id
+
+    # @!method vin
+    #   The vehicle identification number
+    #   @api public
+    #   @return [String, nil] the vehicle identification number
+    #   @example
+    #     vehicle.vin
+    attribute :vin
+
+    # @!method display_name
+    #   The name the owner gave the vehicle
+    #   @api public
+    #   @return [String, nil] the name the owner gave the vehicle
+    #   @example
+    #     vehicle.display_name
+    attribute :display_name
+
+    # @!method state
+    #   The state of the vehicle, such as "online", "asleep", or "offline"
+    #   @api public
+    #   @return [String, nil] the state of the vehicle
+    #   @example
+    #     vehicle.state
+    attribute :state
+
+    # @!method access_type
+    #   The access the account has to the vehicle, such as "OWNER" or "DRIVER"
+    #   @api public
+    #   @return [String, nil] the access the account has to the vehicle
+    #   @example
+    #     vehicle.access_type
+    attribute :access_type
+
+    # @!method api_version
+    #   The version of the API the vehicle speaks
+    #   @api public
+    #   @return [Integer, nil] the version of the API the vehicle speaks
+    #   @example
+    #     vehicle.api_version
+    attribute :api_version
+
+    # @!method in_service?
+    #   Whether the vehicle is being serviced
+    #   @api public
+    #   @return [Boolean] whether the vehicle is being serviced
+    #   @example
+    #     vehicle.in_service?
+    predicate :in_service
+
+    # Whether the vehicle is online
+    #
+    # A vehicle takes commands and answers with its data only while it is online.
+    #
+    # A vehicle that is asleep is woken with {API::VehicleEndpoints#wake_up}.
+    #
+    # @api public
+    # @return [Boolean] whether the state of the vehicle is "online"
+    # @example
+    #   vehicle.online?
+    def online?
+      state.eql?("online")
+    end
+  end
+end