scalingo 3.5.0 → 4.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98e17d7eb47e72aad2aefb6a07c6096542b1debd1533b15353b79ae7681c95f0
-  data.tar.gz: f224c29ecdeaba0fe9bba5d3bd3898fb9ed34de6c1ad6a58fddab89fcce2cedc
+  metadata.gz: 2e81dc5d1e89b30c848e17b2ef1ef0cbe73fd96555659225cf4d6bbd3558fa60
+  data.tar.gz: 6ebe2d660f1c2d696839d8db23a48932057003390fe55bedebf427898b36df27
 SHA512:
-  metadata.gz: bd981473899a583adab7c970aa2255fd0f5c70d112d3358241d512e7c300f7d710d5cc6c71ac73050f07bfe36b7aad0bf74fadc8219cfd7dbf5e245e1a9f80f5
-  data.tar.gz: 524aea983112d2e5a323151fc974104b8890e7b133f0bcaaa974a7884f93e76caf2f5a78894e831092467f4ea1de4ab5b91d1a3c9ec1becd856e9ff94e499073
+  metadata.gz: 3b851279a78169fc9ae01c8eea2c3e5ba9cf9898af057d3941a7d481fb6dd4372b4ada7beb54638c6b6fb0fb734a463bac4773cecc91af0462210a27372d3598
+  data.tar.gz: b9617375ab3230a1993874b8fc4b64e34cf07d9e1d7f9fc3341f37dd5c9d885b54cce1099d18bc51ba07fb990dedb6d950eb839efbe6881aea1e849851ba2f79

data/.rubocop.yml

@@ -3,6 +3,7 @@ require:
   - standard-custom
   - standard-performance
   - rubocop-performance
+  - rubocop-rspec
 
 inherit_gem:
   standard: config/base.yml
@@ -18,3 +19,43 @@ AllCops:
     - 'tmp/**/*'
     - 'vendor/**/*'
     - '.git/**/*'
+
+# Line-base counting is not reliable enough
+RSpec/ExampleLength:
+  Enabled: false
+
+# Deprecated cop, will be removed
+RSpec/FilePath:
+  Enabled: false
+
+# Not convinced by how strict this cop is by default
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+# Really not convinced by this one
+RSpec/NamedSubject:
+  Enabled: false
+
+# Default is 3, but 4 is used and relevant (class / method / global state / local state)
+RSpec/NestedGroups:
+  Max: 4
+
+# Not always relevant for libs
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/scalingo/faraday/**/*'
+
+# Not sure about this one - requires more research
+RSpec/MessageSpies:
+  Enabled: false
+
+# Not sure about this one - requires more research
+RSpec/StubbedMock:
+  Enabled: false
+
+# Not sure about this one - requires more research
+RSpec/SubjectStub:
+  Enabled: false

data/CHANGELOG.md

@@ -1,4 +1,17 @@
-## Unreleased
+## 4.0.beta1 - 2024-04-15
+
+* Breaking change: exceptions are raised on error responses (4xx, 5xx) and other errors (connection issue, timeouts)
+    * Trying to reach an endpoint without having the client authenticated will raise an exception without attempting the request
+    * Same when the token is expired. Expiration date is read from the token directly
+    * Associated configuration options have been removed
+* Breaking change: rework DB api exposition
+* Specs: rewrite all specs
+* Breaking change: endpoint methods declaration is simplified:
+    * based on URI templates
+    * argument and method names are unified
+    * one "main" internal method, `Endpoint#request`
+* Breaking change: automatic digging of the value if the reponse body is an object with a single key
+* Breaking change: remove `Scalingo::API::Reponse` in favor of `Faraday::Response`
 
 ## 3.5.0 - 2023-12-28
 

data/Gemfile

@@ -2,3 +2,5 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in scalingo.gemspec
 gemspec
+
+gem "simplecov"

data/README.md

@@ -2,18 +2,10 @@
 
 A ruby wrapper for the Scalingo API
 
-### Migration from v2
-
-This gem is changing its name from `scalingo-ruby-api` to `scalingo`,
-and the versioning does **not** reset; the first major version of `scalingo`
-will therefore be `3.x.x`.
-
-You can check the version 2 at [the v2 branch of this repository](https://github.com/Scalingo/scalingo-ruby-api/tree/v2)
-
 ## Installation
 
 ```ruby
-gem "scalingo", "3.0.0"
+gem "scalingo"
 ```
 
 And then execute:
@@ -29,7 +21,7 @@ require "scalingo"
 
 scalingo = Scalingo::Client.new
 scalingo.authenticate_with(access_token: ENV["SCALINGO_TOKEN"])
-scalingo.user.self
+scalingo.self
 ```
 
 ## Conventions
@@ -37,16 +29,13 @@ scalingo.user.self
 Most methods map to one (and only one) request, and their signature follows this format:
 
 ```ruby
-client.section.request(id, payload = {}, headers = nil, &block)
+client.section.request(app_id:, id:, body:)
 ```
 
 * Depending on the request, there may be no id (collection and/or singular resource, such as `user`), one, or two ids (many resources are nested under an app).
 * Most of the time, this library won't do any processing of the payload, but there's a few things to know:
-  * the root key shouldn't be specified, the library handles it
+  * the root key doesn't need to be specified, the library handles it
   * in some cases, the payload isn't passed as supplied (`metrics`, for instance, extracts the parts that are meant to be used as url fragments)
-* headers can be supplied on a per-request basis, using either the last argument or the block version:
-  * when using the last argument, you may have to pass an empty hash payload (`{}`)
-  * when using the block form, the faraday object is supplied as argument, and you can do any kind of treatment you would like
 
 ## Configuration
 
@@ -58,23 +47,13 @@ changing the configuration globally will therefore not affect already existing o
 
 ```ruby
 Scalingo.configure do |config|
-  # Default region. Must be a supported region (agora_fr1, osc_fr1, osc_secnum_fr1)
+  # Default region. Must be a supported region (osc_fr1, osc_secnum_fr1)
   config.default_region = :osc_fr1
 
   # Configure the User Agent header
   config.user_agent = "Scalingo Ruby Client v#{Scalingo::VERSION}"
 
-  # For how long is a bearer token considered valid (it will raise passed this delay).
-  # Set to nil to never raise.
-  config.exchanged_token_validity = 1.hour
-
-  # Having this setting to true prevents performing requests that would fail due to lack of authentication headers.
-  config.raise_on_missing_authentication = true
-
-  # Raise an exception when the bearer token in use is supposed to be invalid
-  config.raise_on_expired_token = false
-
-  # These headers will be added to every request. Individual methods may override them.
+  # These headers will be added to every request
   # This should be a hash or a callable object that returns a hash.
   config.additional_headers = {}
 
@@ -87,26 +66,9 @@ You can also configure each client separately.
 Values not supplied will be copied from the global configuration.
 
 ```ruby
-scalingo = Scalingo::Client.new(raise_on_expired_token: false)
+scalingo = Scalingo::Client.new(user_agent: "A new kind of agent")
 ```
 
-## Response object
-
-Responses are parsed with the keys symbolized and then encapsulated in a `Scalingo::API::Response` object:
-
-* `response.status` containts the HTTP status code
-* `response.data` contains the "relevant" data, without the json root key (when relevant)
-* `response.full_body` contains the full response body
-* `response.meta` contains the meta object, if there's any
-* `response.headers` containts all the response headers
-
-Some helper methods are defined on this object:
-* `response.successful?` returns true when the code is 2XX
-* `response.paginated?` returns true if the reponse has metadata relative to pagination
-* `response.operation?` returns true if the response contains a header relative to an ongoing operation
-* `response.operation_url` returns the URL to query to get the status of the operation
-* `response.operation` performs a request to retrieve the operation
-
 ## Other details on the code architecture
 
 * `Scalingo::Client` instances hold configuration and the token used for authentication
@@ -127,13 +89,13 @@ scalingo.authenticate_with(access_token: "my_access_token")
 scalingo.authenticate_with(bearer_token: "my_bearer_jwt")
 
 # Return your profile
-scalingo.user.self
+scalingo.self # or scalingo.auth.user.find
 
 # List your SSH Keys
 scalingo.keys.all # OR scalingo.auth.keys.all
 
 # Show one SSH Key
-scalingo.keys.show("my-key-id")
+scalingo.keys.show(id: "my-key-id")
 
 # List your apps on the default region
 scalingo.apps.all # OR scalingo.region.apps.all
@@ -151,8 +113,6 @@ Requests to the [database API](https://developers.scalingo.com/databases/) requi
 extra authentication for each addon you want to interact with. [Addon authentication
 tokens are valid for one hour](https://developers.scalingo.com/addons#get-addon-token).
 
-Supported regions for database API are `db_api_osc_fr1` and `db_api_osc_secnum_fr1`.
-
 ```ruby
 require "scalingo"
 
@@ -160,23 +120,20 @@ scalingo = Scalingo::Client.new
 scalingo.authenticate_with(access_token: "my_access_token")
 
 # First, authenticate using the `addons` API
-scalingo.osc_fr1.addons.authenticate!(app_id, addon_id)
+dbclient = scalingo.osc_fr1.addons.database_client_for(app_id:, id:)
 
 # Once authenticated for that specific addon, you can interact with
 # database and backup APIs.
 # IDs of databases are the IDs of the corresponding addons
 
 # get all information for a given database
-scalingo.db_api_osc_fr1.databases.find(addon_id)
+dbclient.databases.find(id:)
 
 # get all backups for a given database
-scalingo.db_api_osc_fr1.backups.for(addon_id)
+dbclient.backups.list(addon_id:)
 
 # get URL to download backup archive
-scalingo.db_api_osc_fr1.backups.archive(addon_id, backup_id)
-
-# you can omit the region to use the default one
-scalingo.databases.find(addon_id)
+dbclient.backups.archive(addon_id:, id:)
 
 ```
 
@@ -193,9 +150,3 @@ bundle
 ```bash
 bundle exec rspec
 ```
-
-### Release a new version
-
-```bash
-# TODO
-```

data/bin/console

@@ -3,10 +3,20 @@
 require "bundler/setup"
 require "scalingo"
 
+begin
+  require "dotenv"
+  Dotenv.load(".env.local")
+rescue LoadError
+  puts("dotenv not available - no .env.local loading")
+end
+
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
 require "pry"
 
-Pry.start
+client = Scalingo::Client.new
+client.authenticate_with(access_token: ENV["SCALINGO_API_TOKEN"]) if ENV["SCALINGO_API_TOKEN"].present?
+
+Pry.start(binding, quiet: true)

data/bin/lint

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+bundle exec rubocop $@

data/bin/setup

@@ -1,8 +1,23 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
+#!/usr/bin/env ruby
+require "fileutils"
 
-bundle install
+# path to your application root.
+GEM_ROOT = File.expand_path("..", __dir__)
 
-# Do any other automated setup that you need to do here
+def system!(*args)
+  system(*args, exception: true)
+end
+
+FileUtils.chdir GEM_ROOT do
+  # This script is a way to set up or update your development environment automatically.
+  # This script is idempotent, so that you can run it at any time and get an expectable outcome.
+  # Add necessary setup steps to this file.
+
+  puts "== Installing dependencies =="
+  system! "gem install bundler --conservative"
+  system("bundle check") || system!("bundle install")
+
+  # Creating useful but unversioned env files
+  puts "\n== Creating .env.*.local files =="
+  FileUtils.touch(".env.local")
+end

data/bin/specs

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+bundle exec rspec $@

data/lib/scalingo/api/client.rb

@@ -1,14 +1,20 @@
 require "scalingo/token_holder"
+require "scalingo/faraday/response"
+require "scalingo/faraday/extract_meta"
+require "scalingo/faraday/extract_root_value"
+require "active_support/core_ext/hash"
 
 module Scalingo
   module API
     class Client
       include TokenHolder
 
-      attr_reader :config, :token_holder, :url
+      attr_reader :config, :token_holder, :url, :region
 
-      def initialize(url, scalingo: nil, config: {})
+      def initialize(url, scalingo: nil, region: nil, config: {})
         @url = url
+        @region = region
+
         parent_config = Scalingo.config
 
         if scalingo
@@ -40,15 +46,15 @@ module Scalingo
         end
       end
 
+      # :nocov:
       def inspect
         str = %(<#{self.class}:0x#{object_id.to_s(16)} url:"#{@url}" methods:)
 
-        methods = self.class.instance_methods - Scalingo::API::Client.instance_methods
-        str << methods.to_s
-
+        str << self.class.instance_methods(false).to_s
         str << ">"
         str
       end
+      # :nocov:
 
       ## Faraday objects
       def headers
@@ -71,59 +77,35 @@ module Scalingo
         }
       end
 
-      # Note: when `config.raise_on_missing_authentication` is set to false,
-      # this method may return the unauthenticated connection
-      # even with `fallback_to_guest: false`
-      def connection(fallback_to_guest: false)
-        authenticated_connection
-      rescue Error::Unauthenticated
-        raise unless fallback_to_guest
-
-        unauthenticated_connection
-      end
-
-      def unauthenticated_connection
-        @unauthenticated_conn ||= Faraday.new(connection_options) { |conn|
+      def guest_connection
+        @guest_connection ||= Faraday.new(connection_options) { |conn|
+          conn.response :extract_root_value
+          conn.response :extract_meta
           conn.response :json, content_type: /\bjson$/, parser_options: {symbolize_names: true}
+          conn.response :raise_error
           conn.request :json
 
           conn.adapter(config.faraday_adapter) if config.faraday_adapter
         }
       end
 
-      def authenticated_connection
+      def connection
         return @connection if @connection
 
         # Missing token handling. Token expiration is handled in the `value` method.
-        unless token_holder.token&.value
-          if config.raise_on_missing_authentication
-            raise Error::Unauthenticated
-          else
-            return unauthenticated_connection
-          end
-        end
+        raise Error::Unauthenticated unless token_holder.token&.value&.present?
 
         @connection = Faraday.new(connection_options) { |conn|
+          conn.response :extract_root_value
+          conn.response :extract_meta
           conn.response :json, content_type: /\bjson$/, parser_options: {symbolize_names: true}
           conn.request :json
+          conn.response :raise_error
           conn.request :authorization, "Bearer", -> { token_holder.token&.value }
 
           conn.adapter(config.faraday_adapter) if config.faraday_adapter
         }
       end
-
-      def database_connection(database_id)
-        raise Error::Unauthenticated unless token_holder.authenticated_for_database?(database_id)
-
-        @database_connections ||= {}
-        @database_connections[database_id] ||= Faraday.new(connection_options) { |conn|
-          conn.response :json, content_type: /\bjson$/, parser_options: {symbolize_names: true}
-          conn.request :json
-          conn.request :authorization, "Bearer", -> { token_holder.database_tokens[database_id]&.value }
-
-          conn.adapter(config.faraday_adapter) if config.faraday_adapter
-        }
-      end
     end
   end
 end

data/lib/scalingo/api/endpoint.rb

@@ -1,5 +1,5 @@
+require "addressable/template"
 require "forwardable"
-require "scalingo/api/response"
 
 module Scalingo
   module API
@@ -7,28 +7,105 @@ module Scalingo
       extend Forwardable
       attr_reader :client
 
+      # Add a handler for a given endpoint
+      %i[get post put patch delete].each do |method|
+        # @example
+        # class Example < API::Endpoint
+        #   get :all, "some-endpoint/{id}/subthings{?query*}", optional: [:query]
+        #   post :create, "some-endpoint", root_key: :subthing
+        # end
+        define_singleton_method(method) do |name, path, **default_attrs, &default_block|
+          # @example
+          # endpoint = Example.new
+          # endpoint.all(id: "1", query: {page: 1})
+          # endpoint.create(name: "thing")
+          define_method(name) do |**runtime_attrs, &runtime_block|
+            params = {**default_attrs, **runtime_attrs}
+
+            request(method, path, **params) do |req|
+              default_block&.call(req, params)
+              runtime_block&.call(req, params)
+            end
+          end
+        end
+
+        # Those methods are not meant to be used outside of a class definition
+        private_class_method method
+      end
+
       def initialize(client)
         @client = client
       end
 
       def_delegator :client, :connection
-      def_delegator :client, :database_connection
 
-      def inspect
-        str = %(<#{self.class}:0x#{object_id.to_s(16)} base_url:"#{@client.url}" endpoints:)
+      # Perform a request to the API.
+      # path can be an URI template; and faraday expect valid URIs - the parser raises when templates aren't fully expanded.
+      # therefore, we have to take care of the expansion before passing the path to faraday.
+      # note: This method is not unit-tested directly, but integrations tests are covering it extensively.
+      # @see https://github.com/sporkmonger/addressable?tab=readme-ov-file#uri-templates
+      # @see https://www.rfc-editor.org/rfc/rfc6570.txt
+      # @see https://github.com/lostisland/faraday/issues/1487
+      def request(method, path, body: nil, root_key: nil, connected: true, basic: nil, dry_run: false, params_as_body: false, **params, &block)
+        template = Addressable::Template.new(path)
 
-        methods = self.class.instance_methods - Scalingo::API::Endpoint.instance_methods
+        # If the template has keys, we need to expand it with the params
+        if template.keys.present?
+          # We assume every variable in the template is required
+          expected_keys = Set.new(template.keys.map(&:to_sym))
+          # ... but we can opt out by specifying :optional when performing the request or in the endpoint definition
+          expected_keys -= params[:optional] if params[:optional].present?
 
-        str << methods.to_s
-        str << ">"
-        str
+          # if any required key is missing, raise an error with the missing keys,
+          # as if it was a regular keyword argument that was not supplied
+          if expected_keys.present?
+            received_keys = Set.new(params.keys.map(&:to_sym))
+
+            unless received_keys.superset?(expected_keys)
+              missings = (expected_keys - received_keys).map { |item| sprintf("%p", item) }.join(" ")
+              raise ArgumentError, "missing keyword: #{missings}"
+            end
+          end
+
+          # Now, we can expand the template with the supplied params
+          actual_path = template.expand(params).to_s
+        else
+          # Otherwise, it's not a template but a string to be used as it is
+          actual_path = path
+        end
+
+        # we nest the given body under the root_key if it's present
+        request_body = body
+        request_body = {root_key => body} if request_body && root_key
+
+        # We can use the client in either connected or unconnected mode
+        conn = connected ? client.connection : client.guest_connection
+
+        # We can specify basic auth credentials if needed
+        conn.request :authorization, :basic, basic[:user], basic[:password] if basic.present?
+
+        # Finally, perform the request.
+        # Faraday sends params as query string for GET/HEAD/DELETE requests and as request body for the others;
+        # in some rare cases (variables bulk-delete) we need to send them as actual body.
+        if Faraday::METHODS_WITH_QUERY.include?(method.to_s) && params_as_body
+          conn.public_send(method, actual_path) do |req|
+            req.body = request_body
+            block&.call(req) || req
+          end
+        else
+          conn.public_send(method, actual_path, request_body, &block)
+        end
       end
 
-      private
+      # :nocov:
+      def inspect
+        str = %(<#{self.class}:0x#{object_id.to_s(16)} base_url:"#{@client.url}" endpoints:)
 
-      def unpack(*keys, &block)
-        Response.unpack(client, keys: keys, &block)
+        str << self.class.instance_methods(false).to_s
+        str << ">"
+        str
       end
+      # :nocov:
     end
   end
 end

data/lib/scalingo/auth/keys.rb

@@ -2,55 +2,9 @@ require "scalingo/api/endpoint"
 
 module Scalingo
   class Auth::Keys < API::Endpoint
-    def all(headers = nil, &block)
-      data = nil
-
-      response = connection.get(
-        "keys",
-        data,
-        headers,
-        &block
-      )
-
-      unpack(:keys) { response }
-    end
-
-    def show(id, headers = nil, &block)
-      data = nil
-
-      response = connection.get(
-        "keys/#{id}",
-        data,
-        headers,
-        &block
-      )
-
-      unpack(:key) { response }
-    end
-
-    def create(payload, headers = nil, &block)
-      data = {key: payload}
-
-      response = connection.post(
-        "keys",
-        data,
-        headers,
-        &block
-      )
-
-      unpack(:key) { response }
-    end
-
-    def destroy(id, headers = nil, &block)
-      data = nil
-      response = connection.delete(
-        "keys/#{id}",
-        data,
-        headers,
-        &block
-      )
-
-      unpack { response }
-    end
+    get :list, "keys"
+    get :find, "keys/{id}"
+    post :create, "keys", root_key: :key
+    delete :delete, "keys/{id}"
   end
 end

data/lib/scalingo/auth/scm_integrations.rb

@@ -2,56 +2,9 @@ require "scalingo/api/endpoint"
 
 module Scalingo
   class Auth::ScmIntegrations < API::Endpoint
-    def all(headers = nil, &block)
-      data = nil
-
-      response = connection.get(
-        "scm_integrations",
-        data,
-        headers,
-        &block
-      )
-
-      unpack(:scm_integrations) { response }
-    end
-
-    def show(id, headers = nil, &block)
-      data = nil
-
-      response = connection.get(
-        "scm_integrations/#{id}",
-        data,
-        headers,
-        &block
-      )
-
-      unpack(:scm_integration) { response }
-    end
-
-    def create(payload, headers = nil, &block)
-      data = {scm_integration: payload}
-
-      response = connection.post(
-        "scm_integrations",
-        data,
-        headers,
-        &block
-      )
-
-      unpack(:scm_integration) { response }
-    end
-
-    def destroy(id, headers = nil, &block)
-      data = nil
-
-      response = connection.delete(
-        "scm_integrations/#{id}",
-        data,
-        headers,
-        &block
-      )
-
-      unpack { response }
-    end
+    get :list, "scm_integrations"
+    get :find, "scm_integrations/{id}"
+    post :create, "scm_integrations", root_key: :scm_integration
+    delete :delete, "scm_integrations/{id}"
   end
 end