scalingo 3.0.0.beta.1 → 3.0.0.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fd4bd22f57705fe4066a2f1de8d830c4557383777a49b7a7258a9e8c7b99077
-  data.tar.gz: fbf139e41c1a12c007e08b6c64e4e8d3b54d14500f7b44b14c7ba4ba8bfce7be
+  metadata.gz: 6582ca860b783b598a3f31874afc37958ead26c29c17c099e6cba1ef094f933d
+  data.tar.gz: c0206b25118775599be97e0c6a7ef06c40914a34711c882a21268521f964ae24
 SHA512:
-  metadata.gz: 06271d0e9010d2d4835be48fa43b49545600b63f938e75ef504d17cec8434f07a9f8a5efc15cf411c9a1729c308c99a9b3504539d134530bf93acd73ec2f4565
-  data.tar.gz: 819dd71a0fb81443f934c5ed6f500c7c03105cc1113f4df60cbdb2655d4cfd057d39d38d8535b78f58d24f6deabe4c4b800c31e1022f82d719547e7646ed33d3
+  metadata.gz: 1e7e41bb52927a17d3de0c840f281754ee1907a000db36735ec779d5115a345f91bf944aad068421e9292fcb3ab9f92db49690a25e61f4f81cd8ff45c625f550
+  data.tar.gz: e2ebc1468f18304b3086ad927db4e89f09ef1d6256395a6f72a089776eeba8643b923bec88af1690f0264786dd46d6982b421f741b99f23a86ec513a3841fba9

data/.gitignore

@@ -1,5 +1,5 @@
 *.swp
-
+Gemfile.lock
 coverage/
 /pkg
 

data/CHANGELOG.md

@@ -1,4 +1,16 @@
-## 3.0.0.beta1 - 2020/06/12
+## Unreleased
+
+## 3.0.0.beta.2 - 2020/06/18
+
+* Bugfix: do not "dig" into the response body if it is not a 2XX (#18, #19)
+* Rework configuration, add specs over it (#17)
+* Rename `BearerToken#expires_in` to `expires_at` (#16)
+* Rename argument `allow_guest:` for `API::Endpoint#connection` to `fallback_to_guest:` (#16)
+* Response objects can access the operation directly using `.operation` (#15)
+* New API: billing api (#14)
+  * New endpoint: `profile`. Methods: `show`, `create`, `update`
+
+## 3.0.0.beta.1 - 2020/06/12
 
 * Full rewrite of the gem, **zero** backwards compatibility. Refer to the `README` for more information.
 

data/README.md

@@ -13,12 +13,12 @@ You can check the version 2 at [the v2 branch of this repository](https://github
 ### The road to 3.0.0
 
 This gem is still in beta version, but its API should not change a lot until a final release.
-However, configuration may change. An issue will be opened and pinned to follow up the work that remains to be done.
+[This issue tracks the remaining work](https://github.com/Scalingo/scalingo-ruby-api/issues/13).
 
 ## Installation
 
 ```ruby
-gem "scalingo", "3.0.0.beta.1"
+gem "scalingo", "3.0.0.beta.2"
 ```
 
 And then execute:
@@ -55,18 +55,29 @@ client.section.request(id, payload = {}, headers = nil, &block)
 
 ## Configuration
 
+You can refer to the code below to configure the gem globally.
+The values displayed match the default ones.
+
+:warning: Configuration is copied when instanciating a `Scalingo::Client` object;
+changing the configuration globally will therefore not affect already existing objects.
+
 ```ruby
 Scalingo.configure do |config|
-  # Known regions. Each region should have a corresponding entry in the urls settings below
-  config.regions = %i[osc_fr1 osc_secnum_fr1]
+  # Authentication API url
+  config.auth = "https://auth.scalingo.com/v1"
+
+  # Billing API url
+  config.billing = "https://cashmachine.scalingo.com"
 
-  # Default region
-  config.defaul_region = :osc_fr1
+  # Known regions and their api's url
+  config.regions = {
+    agora_fr1: "https://api.agora-fr1.scalingo.com/v1",
+    osc_fr1: "https://api.osc-fr1.scalingo.com/v1",
+    osc_secnum_fr1: "https://api.osc-secnum-fr1.scalingo.com/v1"
+  }
 
-  # Endpoints URLS
-  config.urls.auth = "https://auth.scalingo.com/v1"
-  config.urls.osc_fr1 = "https://api.osc-fr1.scalingo.com/v1"
-  config.urls.osc_secnum_fr1 = "https://api.osc-secnum-fr1.scalingo.com/v1"
+  # Default region. Must match an entry in `regions`
+  config.default_region = :osc_fr1
 
   # Configure the User Agent header
   config.user_agent = "Scalingo Ruby Client v#{Scalingo::VERSION}"
@@ -75,38 +86,32 @@ Scalingo.configure do |config|
   # Set to nil to never raise.
   config.exchanged_token_validity = 1.hour
 
-  # Raise an exception when trying to use an authenticated connection without a bearer token set
   # 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.
   # This should be a hash or a callable object that returns a hash.
   config.additional_headers = {}
-
-  # Raise an exception when the bearer token in use is supposed to be invalid
-  config.raise_on_expired_token = false
 end
 ```
 
-:warning: If you change the settings for the list of regions, you **cannot** use `require "scalingo"`; you must follow this template :
+You can also configure each client separately.
+Values not supplied will be copied from the global configuration.
 
 ```ruby
-
-require "scalingo/config"
-
-Scalingo.configure do |config|
-  config.regions = %i[my-regions]
-end
-
-require "scalingo/client"
+scalingo = Scalingo::Client.new(raise_on_expired_token: false)
 ```
 
 ## 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_data` contains the full response body
+* `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
 
@@ -114,7 +119,16 @@ 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` returns the URL to query to get the status of the 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
+* `Scalingo::API::Client` subclasses (`Scalingo::Auth`, `Scalingo::Billing`, `Scalingo::Regional`) provides access to the APIs.
+You can use `connection` (returns a faraday instance) on those objects to perform any request freely.
+* `Scalingo::API::Endpoint` subclasses (`Scalingo::Auth::User`) instances belong to an api client (cf previous point).
+They provide quick and uniform access to expected requests.
 
 ## Examples
 
@@ -128,7 +142,7 @@ scalingo.authenticate_with(access_token: "my_access_token")
 scalingo.authenticate_with(bearer_token: "my_bearer_jwt")
 
 # Return your profile
-scalingo.self
+scalingo.user.self
 
 # List your SSH Keys
 scalingo.keys.all # OR scalingo.auth.keys.all
@@ -140,7 +154,7 @@ scalingo.keys.show("my-key-id")
 scalingo.apps.all # OR scalingo.region.apps.all
 
 # List your apps on osc-fr1
-scalingo.osc_fr1.apps.all
+scalingo.osc_fr1.apps.all # OR scalingo.region(:osc_fr1).apps.all
 
 # Preview the creation of an app on the default region
 scalingo.apps.create(name: "my-new-app", dry_run: true)

data/lib/scalingo.rb

@@ -1,2 +1,2 @@
-require "scalingo/config"
+require "scalingo/configuration"
 require "scalingo/client"

data/lib/scalingo/api/client.rb

@@ -10,40 +10,51 @@ module Scalingo
 
       def self.register_handlers!(handlers)
         handlers.each do |method_name, klass|
-          define_method(method_name) do
-            value = instance_variable_get("@#{method_name}")
+          register_handler!(method_name, klass)
+        end
+      end
 
-            if value.nil?
-              value = klass.new(self)
-              instance_variable_set("@#{method_name}", value)
-            end
+      def self.register_handler!(method_name, klass)
+        define_method(method_name) do
+          value = instance_variable_get("@#{method_name}")
 
-            value
+          if value.nil?
+            value = klass.new(self)
+            instance_variable_set("@#{method_name}", value)
           end
+
+          value
         end
       end
 
       ## Faraday objects
-      def connection_options
-        headers = {
-          "User-Agent" => Scalingo.config.user_agent
+      def headers
+        hash = {
+          "User-Agent" => scalingo.config.user_agent
         }
 
-        if (extra = Scalingo.config.additional_headers).present?
-          extra.respond_to?(:call) ? headers.update(extra.call) : headers.update(extra)
+        if (extra = scalingo.config.additional_headers).present?
+          extra.respond_to?(:call) ? hash.update(extra.call) : hash.update(extra)
         end
 
+        hash
+      end
+
+      def connection_options
         {
           url: url,
           headers: headers
         }
       end
 
-      def connection(allow_guest: false)
-        if allow_guest
+      # 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)
+        if fallback_to_guest
           begin
             authenticated_connection
-          rescue
+          rescue Error::Unauthenticated
             unauthenticated_connection
           end
         else
@@ -54,14 +65,20 @@ module Scalingo
       def unauthenticated_connection
         @unauthenticated_conn ||= Faraday.new(connection_options) { |conn|
           conn.response :json, content_type: /\bjson$/, parser_options: {symbolize_names: true}
+          conn.request :json
         }
       end
 
       def authenticated_connection
         return @connection if @connection
 
-        if Scalingo.config.raise_on_missing_authentication && !scalingo.token&.value
-          raise Error::Unauthenticated
+        # Missing token handling. Token expiration is handled in the `value` method.
+        unless scalingo.token&.value
+          if scalingo.config.raise_on_missing_authentication
+            raise Error::Unauthenticated
+          else
+            return unauthenticated_connection
+          end
         end
 
         @connection = Faraday.new(connection_options) { |conn|

data/lib/scalingo/api/endpoint.rb

@@ -16,7 +16,7 @@ module Scalingo
       private
 
       def unpack(*args)
-        Response.unpack(*args)
+        Response.unpack(client, *args)
       end
     end
   end

data/lib/scalingo/api/response.rb

@@ -1,49 +1,32 @@
 module Scalingo
   module API
     class Response
-      def self.transform_object(object, resource_class: nil)
-        resource_class&.new(object) || object
-      end
+      def self.unpack(client, response, key: nil)
+        body = response.body
+        has_hash_body = body.present? && body.respond_to?(:key)
 
-      def self.transform_body(body, resource_class: nil)
-        case body
-        when Hash
-          transform_object(body, resource_class: resource_class)
-        when Array
-          body.map { |item| transform_object(item, resource_class: resource_class) }
-        else
-          body
-        end
-      end
-
-      def self.transform_meta(body)
-        if body.present? && body.respond_to?(:key) && body.key?(:meta)
-          body[:meta]
-        end
-      end
+        data = body
+        meta = nil
 
-      def self.unpack(response, key: nil, resource_class: nil)
-        data = if response.body.respond_to?(:key?) && key.present?
-          response.body[key]
-        else
-          response.body
+        if has_hash_body
+          data = body[key] if response.success? && key.present?
+          meta = body[:meta]
         end
 
-        parsed = transform_body(data, resource_class: resource_class)
-        meta = transform_meta(response.body)
-
         new(
+          client: client,
           status: response.status,
           headers: response.headers,
-          data: parsed,
+          data: data,
           meta: meta,
-          full_body: response.body,
+          full_body: body,
         )
       end
 
-      attr_reader :status, :headers, :data, :full_body, :meta
+      attr_reader :client, :status, :headers, :data, :full_body, :meta
 
-      def initialize(status:, headers:, data:, full_body:, meta: nil)
+      def initialize(client:, status:, headers:, data:, full_body:, meta: nil)
+        @client = client
         @status = status
         @headers = headers
         @data = data
@@ -60,11 +43,17 @@ module Scalingo
       end
 
       def operation
+        if operation? && client.respond_to?(:operations)
+          client.operations.get(operation_url)
+        end
+      end
+
+      def operation_url
         headers[:location]
       end
 
       def operation?
-        operation.present
+        operation_url.present?
       end
     end
   end

data/lib/scalingo/bearer_token.rb

@@ -1,18 +1,24 @@
 module Scalingo
   class BearerToken
-    attr_reader :expires_in
+    attr_reader :expires_at
+    attr_writer :raise_on_expired
 
-    def initialize(value, expires_in: nil)
+    def initialize(value, expires_at: nil, raise_on_expired: false)
       @value = value
-      @expires_in = expires_in if expires_in
+      @expires_at = expires_at if expires_at
+      @raise_on_expired = raise_on_expired
+    end
+
+    def raise_on_expired?
+      @raise_on_expired
     end
 
     def expired?
-      expires_in && expires_in <= Time.now
+      expires_at && expires_at <= Time.now
     end
 
     def value
-      raise Error::ExpiredToken if expired? && Scalingo.config.raise_on_expired_token
+      raise Error::ExpiredToken if expired? && raise_on_expired?
 
       @value
     end

data/lib/scalingo/billing.rb

@@ -0,0 +1,11 @@
+require "scalingo/api/client"
+
+module Scalingo
+  class Billing < API::Client
+    require "scalingo/billing/profile"
+
+    register_handlers!(
+      profile: Profile,
+    )
+  end
+end

data/lib/scalingo/billing/profile.rb

@@ -0,0 +1,46 @@
+require "scalingo/api/endpoint"
+
+module Scalingo
+  class Billing::Profile < API::Endpoint
+    def show(headers = nil, &block)
+      data = nil
+
+      response = connection.get(
+        "profile",
+        data,
+        headers,
+        &block
+      )
+
+      unpack(response, key: :profile)
+    end
+
+    def create(payload = {}, headers = nil, &block)
+      data = {profile: payload}
+
+      response = connection.post(
+        "profiles",
+        data,
+        headers,
+        &block
+      )
+
+      unpack(response, key: :profile)
+    end
+
+    def update(id, payload = {}, headers = nil, &block)
+      data = {profile: payload}
+
+      response = connection.put(
+        "profiles/#{id}",
+        data,
+        headers,
+        &block
+      )
+
+      unpack(response, key: :profile)
+    end
+
+    alias_method :self, :show
+  end
+end