droplet_kit 3.18.0 → 3.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3e2b46c0716d69015a44fc025bd61dc48b1f554ff7757c6f58517a94879d5e6
-  data.tar.gz: 55198741a7f9c1ea42bfa3dbe99c6b0479839c744d2040c01245fd537577273a
+  metadata.gz: 4fc38c8c6d69e9d358d6a5ce09f48d81f86162b21353864d111362d73ad869d0
+  data.tar.gz: 69924df50fd90082ab18b00ff46678625bf199929bf722a43a60bb6bd4d4bcc2
 SHA512:
-  metadata.gz: fcefea9fb76fb5d89181edc7044d39e1573e447dd2ad73acc0835b6c99f02559baa0412fc4f862a3c68a58299eb6fb712d140d6d5832546a5b319444e838420f
-  data.tar.gz: 98baa8e8ed6c35e86313b588ddb1e81b26e6d7ad5f563b67db377012ca79130868716ba0f633d3c1f822a8294b3116fe8831c72bcf534dc950c5525aba83fcc5
+  metadata.gz: a119768dc94088edf60b0e33fa7429496686d9494350204531b019c491fc8413ff8364cca381495646e3d72c36d39827906e06a0eac8e4eae69faaa9c2a47972
+  data.tar.gz: abd960f172d61201e42e126cf34a298d4da149f8e0b4cdc2fa19fc96c8b1666b96e81c9a0f612f8aa0cf5ee41ea78d9d304902ab3330084d33a41ecd5c6c91aa

data/README.md

@@ -52,6 +52,19 @@ require 'droplet_kit'
 client = DropletKit::Client.new(access_token: 'YOUR_TOKEN', user_agent: 'custom')
 ```
 
+### Automatically Retry Rate Limited Requests
+
+By default, DropletKit will handle requests that are rate limited by the DigitalOcean API's [burst limit](https://docs.digitalocean.com/reference/api/api-reference/#section/Introduction/Rate-Limit). When the burst rate limit is reached, DropletKit will wait according to the value of the API response's `Retry-After` header. Typically the wait time is less than one minute. When the hourly rate limit is hit, an error is raised.
+
+By default, DropletKit will retry a rate limited request three times before returning an error. If you would like to disable the retry behavior altogether, and instead raise an error when any rate limit is reached, you can set the `retry_max` config value to zero.
+
+DropletKit will also wait zero seconds until retrying a request after the `Retry-After` time has elapsed by default. To change this, set the `retry_wait_min` to a different value.
+
+```ruby
+require 'droplet_kit'
+client = DropletKit::Client.new(access_token: 'YOUR_TOKEN', retry_max: 3, retry_wait_min: 1)
+```
+
 ## Design
 
 DropletKit follows a strict design of resources as methods on your client. For examples, for droplets, you will call your client like this:
@@ -61,12 +74,22 @@ client = DropletKit::Client.new(access_token: 'YOUR_TOKEN')
 client.droplets #=> DropletsResource
 ```
 
-DropletKit will return Plain Old Ruby objects(tm) that contain the information provided by the API. For example:
+DropletKit will return Plain Old Ruby objects(tm) that contain the information provided by the API. For actions that return multiple objects, the request won't be executed until the result is accessed. For example:
 
 ```ruby
 client = DropletKit::Client.new(access_token: 'YOUR_TOKEN')
+
+# Returns an instance of a Paginated Resource.
 client.droplets.all
-# => [ DropletKit::Droplet(id: 123, name: 'something.com', ...), DropletKit::Droplet(id: 1066, name: 'bunk.com', ...) ]
+# => #<DropletKit::PaginatedResource:0x000000010d556c3a>
+
+# Returns the first Droplet.
+client.droplets.all.first
+# => <DropletKit::Droplet {:@id=>1, :@name=>"mydroplet", ...}>
+
+# Returns an array of Droplet IDs.
+client.droplets.all.map(&:id)
+# => [1]
 ```
 
 When you'd like to save objects, it's your responsibility to instantiate the objects and persist them using the resource objects. Let's use creating a Droplet as an example:
@@ -153,7 +176,7 @@ Actions supported:
 * `client.databases.list_backups(id: 'id')`
 * `client.databases.restore_from_backup(database_backup)`
 * `client.databases.delete_cluster(id: 'id')`
-* `client.database.create_db(database, id: 'id')`
+* `client.databases.create_db(database, id: 'id')`
 * `client.databases.find_db(id: 'id', name: 'name')`
 * `client.databases.all_dbs(id: 'id')`
 * `client.databases.delete_db(id: 'id', name: 'name')`

data/lib/droplet_kit/client.rb

@@ -1,23 +1,29 @@
 # frozen_string_literal: true
 
 require 'faraday'
+require 'faraday/retry'
 require 'droplet_kit/utils'
 
 module DropletKit
   class Client
     DEFAULT_OPEN_TIMEOUT = 60
     DEFAULT_TIMEOUT = 120
+    DEFAULT_RETRY_MAX = 3
+    DEFAULT_RETRY_WAIT_MIN = 0
+
     DIGITALOCEAN_API = 'https://api.digitalocean.com'
 
-    attr_reader :access_token, :api_url, :open_timeout, :timeout, :user_agent
+    attr_reader :access_token, :api_url, :open_timeout, :timeout, :user_agent, :retry_max, :retry_wait_min
 
     def initialize(options = {})
       options = DropletKit::Utils.transform_keys(options, &:to_sym)
-      @access_token = options[:access_token]
-      @api_url      = options[:api_url] || DIGITALOCEAN_API
-      @open_timeout = options[:open_timeout] || DEFAULT_OPEN_TIMEOUT
-      @timeout      = options[:timeout] || DEFAULT_TIMEOUT
-      @user_agent   = options[:user_agent]
+      @access_token   = options[:access_token]
+      @api_url        = options[:api_url] || DIGITALOCEAN_API
+      @open_timeout   = options[:open_timeout] || DEFAULT_OPEN_TIMEOUT
+      @timeout        = options[:timeout] || DEFAULT_TIMEOUT
+      @user_agent     = options[:user_agent]
+      @retry_max      = options[:retry_max] || DEFAULT_RETRY_MAX
+      @retry_wait_min = options[:retry_wait_min] || DEFAULT_RETRY_WAIT_MIN
     end
 
     def connection
@@ -25,6 +31,19 @@ module DropletKit
         req.adapter :net_http
         req.options.open_timeout = open_timeout
         req.options.timeout = timeout
+        unless retry_max.zero?
+          req.request :retry, {
+            max: @retry_max,
+            interval: @retry_wait_min,
+            retry_statuses: [429],
+            # faraday-retry supports both the Retry-After and RateLimit-Reset
+            # headers, however, it favours the RateLimit-Reset one. To force it
+            # to use the Retry-After header, we override the header that it
+            # expects for the RateLimit-Reset header to something that we know
+            # we don't set.
+            rate_limit_reset_header: 'undefined'
+          }
+        end
       end
     end
 
@@ -91,6 +110,11 @@ module DropletKit
           content_type: 'application/json',
           authorization: "Bearer #{access_token}",
           user_agent: "#{user_agent} #{default_user_agent}".strip
+        },
+        request: {
+          context: {
+            retry_max: @retry_max
+          }
         }
       }
     end

data/lib/droplet_kit/error_handling_resourcable.rb

@@ -8,11 +8,13 @@ module ErrorHandlingResourcable
         when 200...299
           next
         when 429
-          error = DropletKit::RateLimitReached.new("#{response.status}: #{response.body}")
-          error.limit = response.headers['RateLimit-Limit']
-          error.remaining = response.headers['RateLimit-Remaining']
-          error.reset_at = response.headers['RateLimit-Reset']
-          raise error
+          unless response.headers.key?('Retry-After') && !connection.options.context.key?(:retry_max)
+            error = DropletKit::RateLimitReached.new("#{response.status}: #{response.body}")
+            error.limit = response.headers['RateLimit-Limit']
+            error.remaining = response.headers['RateLimit-Remaining']
+            error.reset_at = response.headers['RateLimit-Reset']
+            raise error
+          end
         else
           raise DropletKit::Error, "#{response.status}: #{response.body}"
         end

data/lib/droplet_kit/mappings/account_mapping.rb

@@ -11,9 +11,25 @@ module DropletKit
       scoped :read do
         property :droplet_limit
         property :floating_ip_limit
+        property :name
         property :email
         property :uuid
         property :email_verified
+        property :team
+      end
+    end
+  end
+
+  class AccountTeamMapping
+    include Kartograph::DSL
+
+    kartograph do
+      root_key singular: 'team', scopes: [:read]
+      mapping AccountTeam
+
+      scoped :read do
+        property :uuid
+        property :name
       end
     end
   end

data/lib/droplet_kit/mappings/droplet_mapping.rb

@@ -24,6 +24,7 @@ module DropletKit
       property :tags, scopes: [:read]
       property :vpc_uuid, scopes: [:read]
       property :volume_ids, scopes: [:read]
+      property :size, scopes: [:read], include: SizeMapping
 
       property :region, scopes: [:read], include: RegionMapping
       property :image, scopes: [:read], include: ImageMapping

data/lib/droplet_kit/models/account.rb

@@ -4,8 +4,15 @@ module DropletKit
   class Account < BaseModel
     attribute :droplet_limit
     attribute :floating_ip_limit
+    attribute :name
     attribute :email
     attribute :uuid
     attribute :email_verified
+    attribute :team
+  end
+
+  class AccountTeam < BaseModel
+    attribute :uuid
+    attribute :name
   end
 end

data/lib/droplet_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DropletKit
-  VERSION = '3.18.0'
+  VERSION = '3.20.0'
 end

data/lib/tasks/resource_doc.rake

@@ -25,7 +25,7 @@ namespace :doc do
       puts 'Actions supported: '
       puts
       klass._resources.each do |action|
-        action_options = action.path.scan(/:[\w_\-]+/i)
+        action_options = action.path.scan(/:[\w_-]+/i)
         params = []
 
         if action.body&.arity&.positive?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: droplet_kit
 version: !ruby/object:Gem::Version
-  version: 3.18.0
+  version: 3.20.0
 platform: ruby
 authors:
 - DigitalOcean API Engineering team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-09-15 00:00:00.000000000 Z
+date: 2023-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.15'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
 - !ruby/object:Gem::Dependency
   name: kartograph
   requirement: !ruby/object:Gem::Requirement