globus_client 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65d27626412e2eff8ff6514be3ece81fd5f27e471137fcfd8409e51cd6e0f105
-  data.tar.gz: 321b1d89734daacb8ad54487836a68f1fdf1af931fad426d72ec35bc2f355ec8
+  metadata.gz: 9129e55c5e5e6f4f62fc0d8912eca9310eff036e1c0095d24cae07367947054c
+  data.tar.gz: 1265f2f6c1b68bb6d76634f7bd636ed920b1095fd3bfd5ab6702525d994bf295
 SHA512:
-  metadata.gz: a4ce82aac85e8c00df5310cdb3b4f821cd1415ee0d525938562b20d97c86f330707691a8ee69dcbfeee53d0e20064f78fd902678d5aa4a0113cc7ce38f209c9a
-  data.tar.gz: 75888830f1b0660f78d551eb3fd2a323f40fb21e5ac9a361c0f8ea22be0b32a11a014dd42719e4b25c33f5f497e2d1b6b296c8db15f5dc89abaed5d4f03ff5e1
+  metadata.gz: 407e55c907f990f0492898e636525c8238221167fabf6d0b4bccef0c9eb163f0d75b5bb3b05b58130be46bb823b809a524490f762cbd5b3c56143e2abf9fd7c4
+  data.tar.gz: e7300d3adbaa6b75d43cafe1faae5eccfc212f558ce7d38889438d3ceaac99becc55242d2a10f2ec3eba759d2038649fe2b80585e97cba4e58ebd215b4767594

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    globus_client (0.12.1)
+    globus_client (0.13.0)
       activesupport (>= 4.2, < 8)
       faraday
       faraday-retry
@@ -76,14 +76,14 @@ GEM
       unicode-display_width (>= 2.4.0, < 3.0)
     rubocop-ast (1.29.0)
       parser (>= 3.2.1.0)
-    rubocop-capybara (2.18.0)
+    rubocop-capybara (2.19.0)
       rubocop (~> 1.41)
     rubocop-factory_bot (2.24.0)
       rubocop (~> 1.33)
     rubocop-performance (1.19.1)
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
-    rubocop-rspec (2.24.0)
+    rubocop-rspec (2.24.1)
       rubocop (~> 1.33)
       rubocop-capybara (~> 2.17)
       rubocop-factory_bot (~> 2.22)

data/api_test.rb

@@ -27,7 +27,7 @@ Benchmark.bm(20) do |benchmark|
 
   benchmark.report("before_perms:") do
     # Not part of the public API but this allows us to test access changes
-    @before_permissions = GlobusClient::Endpoint.new(GlobusClient.config, user_id:, path:).send(:access_rule)["permissions"]
+    @before_permissions = GlobusClient::Endpoint.new(GlobusClient.instance, user_id:, path:).send(:access_rule)["permissions"]
   end
 
   benchmark.report("has_files?:") do
@@ -48,7 +48,7 @@ Benchmark.bm(20) do |benchmark|
 
   benchmark.report("after_perms:") do
     # Not part of the public API but this allows us to test access changes
-    @after_permissions = GlobusClient::Endpoint.new(GlobusClient.config, user_id:, path:).send(:access_rule)["permissions"]
+    @after_permissions = GlobusClient::Endpoint.new(GlobusClient.instance, user_id:, path:).send(:access_rule)["permissions"]
   end
 
   puts "User #{user_id} exists: #{@user_exists}"

data/lib/globus_client/authenticator.rb

@@ -17,6 +17,8 @@ class GlobusClient
     def token
       response = connection.post("/v2/oauth2/token", form_data)
 
+      UnexpectedResponse.call(response) unless response.success?
+
       JSON.parse(response.body)["access_token"]
     end
 

data/lib/globus_client/endpoint.rb

@@ -7,11 +7,11 @@ class GlobusClient
 
     FileInfo = Struct.new(:name, :size)
 
-    # @param config [#token, #uploads_directory, #transfer_endpoint_id, #transfer_url, #auth_url] configuration for the gem
+    # @param client [GlobusClient] a configured instance of the GlobusClient
     # @param path [String] the path to operate on
     # @param user_id [String] a Globus user ID (e.g., a @stanford.edu email address)
-    def initialize(config, path:, user_id:)
-      @config = config
+    def initialize(client, path:, user_id:)
+      @client = client
       @user_id = user_id
       @path = path
     end
@@ -30,23 +30,12 @@ class GlobusClient
     def mkdir
       # transfer API does not support recursive directory creation
       paths.each do |path|
-        response = connection.post("#{transfer_path}/mkdir") do |req|
-          req.headers["Content-Type"] = "application/json"
-          req.body = {
-            DATA_TYPE: "mkdir",
-            path:
-          }.to_json
-        end
-
-        next if response.success?
-
-        # Ignore error if directory already exists
-        if response.status == 502
-          error = JSON.parse(response.body)
-          next if error["code"] == "ExternalError.MkdirFailed.Exists"
-        end
-
-        UnexpectedResponse.call(response)
+        client.post(
+          base_url: client.config.transfer_url,
+          path: "#{transfer_path}/mkdir",
+          body: {DATA_TYPE: "mkdir", path:},
+          expected_response: ->(resp) { resp.status == 502 && JSON.parse(resp.body)["code"] == "ExternalError.MkdirFailed.Exists" }
+        )
       end
     end
 
@@ -64,35 +53,18 @@ class GlobusClient
     def delete_access_rule
       raise(StandardError, "Access rule not found for #{path}") if !access_rule_id
 
-      response = connection.delete("#{access_path}/#{access_rule_id}")
-      return true if response.success?
-
-      UnexpectedResponse.call(response)
+      client.delete(
+        base_url: client.config.transfer_url,
+        path: "#{access_path}/#{access_rule_id}"
+      )
     end
 
     private
 
-    attr_reader :config, :path, :user_id
-
-    def connection
-      # faraday/retry is used here to catch Faraday::ConnectionFailed exceptions
-      # see: https://github.com/sul-dlss/happy-heron/issues/3008
-      @connection ||= Faraday.new(
-        url: config.transfer_url,
-        headers: {Authorization: "Bearer #{config.token}"}
-      ) do |faraday|
-        faraday.request :retry, {
-          max: 10,
-          interval: 0.05,
-          interval_randomness: 0.5,
-          backoff_factor: 2,
-          exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed]
-        }
-      end
-    end
+    attr_reader :client, :path, :user_id
 
     def globus_identity_id
-      Identity.new(config).get_identity_id(user_id)
+      Identity.new(client).get_identity_id(user_id)
     end
 
     # Builds up a path from a list of path elements. E.g., input would look like:
@@ -102,7 +74,7 @@ class GlobusClient
     def paths
       @paths ||= path_segments.map.with_index do |_segment, index|
         File
-          .join(config.uploads_directory, path_segments.slice(..index))
+          .join(client.config.uploads_directory, path_segments.slice(..index))
           .concat(PATH_SEPARATOR)
       end
     end
@@ -123,18 +95,21 @@ class GlobusClient
     # @param files [Array<FileInfo>] an array of FileInfo structs, each of which has a name and a size
     # @param return_presence [Boolean] if true, return a boolean to indicate if any files at all are present, short-circuiting the recursive operation
     def ls_path(filepath, files, return_presence: false)
-      response = connection.get("#{transfer_path}/ls?path=#{CGI.escape(filepath)}")
-      return UnexpectedResponse.call(response) unless response.success?
+      response = client.get(
+        base_url: client.config.transfer_url,
+        path: "#{transfer_path}/ls",
+        params: {path: filepath}
+      )
 
-      data = JSON.parse(response.body)["DATA"]
-      data
+      response["DATA"]
         .select { |object| object["type"] == "file" }
         .each do |file|
         return true if return_presence
 
         files << FileInfo.new("#{filepath}#{file["name"]}", file["size"])
       end
-      data
+
+      response["DATA"]
         .select { |object| object["type"] == "dir" }
         .each do |dir|
         # NOTE: This allows the recursive method to short-circuit iff ls_path
@@ -149,62 +124,45 @@ class GlobusClient
     end
 
     def access_request(permissions:)
-      response = if access_rule_id
-        connection.put("#{access_path}/#{access_rule_id}") do |req|
-          req.body = {
-            DATA_TYPE: "access",
-            permissions:
-          }.to_json
-          req.headers["Content-Type"] = "application/json"
-        end
+      if access_rule_id
+        update_access_request(permissions:)
       else
-        connection.post(access_path) do |req|
-          req.body = {
+        client.post(
+          base_url: client.config.transfer_url,
+          path: access_path,
+          body: {
             DATA_TYPE: "access",
             principal_type: "identity",
             principal: globus_identity_id,
             path: full_path,
             permissions:,
             notify_email: user_id
-          }.to_json
-          req.headers["Content-Type"] = "application/json"
-        end
+          }
+        )
       end
-
-      return true if response.success?
-
-      UnexpectedResponse.call(response)
     end
 
     def update_access_request(permissions:)
       raise(StandardError, "Access rule not found for #{path}") if !access_rule_id
 
-      response = connection.put("#{access_path}/#{access_rule_id}") do |req|
-        req.body = {
+      client.put(
+        base_url: client.config.transfer_url,
+        path: "#{access_path}/#{access_rule_id}",
+        body: {
           DATA_TYPE: "access",
           permissions:
-        }.to_json
-        req.headers["Content-Type"] = "application/json"
-      end
-
-      return true if response.success?
-
-      UnexpectedResponse.call(response)
+        }
+      )
     end
 
     def access_rule
-      response = connection.get(access_list_path) do |req|
-        req.headers["Content-Type"] = "application/json"
-      end
-
-      # debugging of Globus responses
-      response_body = JSON.parse(response.body)
-
-      UnexpectedResponse.call(response, message: "Response is missing DATA in: #{response_body}") unless response.success? && response_body.key?("DATA")
+      response = client.get(
+        base_url: client.config.transfer_url,
+        path: access_list_path,
+        content_type: "application/json"
+      )
 
-      JSON
-        .parse(response.body)["DATA"]
-        .find { |acl| acl["path"] == full_path }
+      response.fetch("DATA").find { |acl| acl["path"] == full_path }
     end
 
     def access_rule_id
@@ -212,15 +170,15 @@ class GlobusClient
     end
 
     def transfer_path
-      "/v0.10/operation/endpoint/#{config.transfer_endpoint_id}"
+      "/v0.10/operation/endpoint/#{client.config.transfer_endpoint_id}"
     end
 
     def access_path
-      "/v0.10/endpoint/#{config.transfer_endpoint_id}/access"
+      "/v0.10/endpoint/#{client.config.transfer_endpoint_id}/access"
     end
 
     def access_list_path
-      "/v0.10/endpoint/#{config.transfer_endpoint_id}/access_list"
+      "/v0.10/endpoint/#{client.config.transfer_endpoint_id}/access_list"
     end
   end
 end

data/lib/globus_client/identity.rb

@@ -3,19 +3,20 @@
 class GlobusClient
   # Lookup of a Globus identity ID
   class Identity
-    def initialize(config)
-      @config = config
+    def initialize(client)
+      @client = client
     end
 
     # @param user_id [String] the username in the form of an email addresss
     # @return [Hash] id and status of Globus identity
     def get_identity(user_id)
-      @email = user_id
-      response = lookup_identity
-      UnexpectedResponse.call(response) unless response.success?
+      response = client.get(
+        base_url: client.config.auth_url,
+        path: "/v2/api/identities",
+        params: {usernames: user_id}
+      )
 
-      data = JSON.parse(response.body)
-      extract_id(data)
+      response["identities"].find { |id| id["username"] == user_id }
     end
 
     # @param user_id [String] the username in the form of an email addresss
@@ -32,23 +33,6 @@ class GlobusClient
 
     private
 
-    attr_reader :config
-
-    def connection
-      Faraday.new(url: config.auth_url)
-    end
-
-    def lookup_identity
-      id_endpoint = "/v2/api/identities"
-      connection.get(id_endpoint) do |req|
-        req.params["usernames"] = @email
-        req.headers["Authorization"] = "Bearer #{config.token}"
-      end
-    end
-
-    def extract_id(data)
-      identities = data["identities"]
-      identities.find { |id| id["username"] == @email }
-    end
+    attr_reader :client
   end
 end

data/lib/globus_client/unexpected_response.rb

@@ -26,7 +26,7 @@ class GlobusClient
     # https://docs.globus.org/api/transfer/file_operations/#errors
     # https://docs.globus.org/api/transfer/acl/#common_errors
     # https://docs.globus.org/api/auth/reference/
-    def self.call(response, message: "")
+    def self.call(response)
       case response.status
       when 400
         raise BadRequestError, "Invalid path or another error with the request: #{response.body}"
@@ -37,11 +37,11 @@ class GlobusClient
       when 404
         raise ResourceNotFound, "Endpoint ID not found or resource does not exist: #{response.body}"
       when 502
-        raise EndpointError, "Other error with endpoint: #{response.status} #{response.body}. #{message}"
+        raise EndpointError, "Other error with endpoint: #{response.status} #{response.body}."
       when 503
         raise ServiceUnavailable, "The service is down for maintenance."
       else
-        raise StandardError, "Unexpected response: #{response.status} #{response.body}. #{message}"
+        raise StandardError, "Unexpected response: #{response.status} #{response.body}."
       end
     end
   end

data/lib/globus_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class GlobusClient
-  VERSION = "0.12.1"
+  VERSION = "0.13.0"
 end

data/lib/globus_client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/object/blank"
 require "faraday"
 require "faraday/retry"
 require "ostruct"
@@ -24,15 +25,15 @@ class GlobusClient
     def configure(client_id:, client_secret:, uploads_directory:, transfer_endpoint_id:, transfer_url: default_transfer_url, auth_url: default_auth_url)
       instance.config = OpenStruct.new(
         # For the initial token, use a dummy value to avoid hitting any APIs
-        # during configuration, allowing the `TokenWrapper` to handle auto-magic
-        # token refreshing. Why not immediately get a valid token? Our apps
+        # during configuration, allowing `with_token_refresh_when_unauthorized` to handle
+        # auto-magic token refreshing. Why not immediately get a valid token? Our apps
         # commonly invoke client `.configure` methods in the initializer in all
         # application environments, even those that are never expected to
         # connect to production APIs, such as local development machines.
         #
         # NOTE: `nil` and blank string cannot be used as dummy values here as
         # they lead to a malformed request to be sent, which triggers an
-        # exception not rescued by `TokenWrapper`
+        # exception not rescued by `with_token_refresh_when_unauthorized`
         token: "a temporary dummy token to avoid hitting the API before it is needed",
         client_id:,
         client_secret:,
@@ -46,7 +47,7 @@ class GlobusClient
     end
 
     delegate :config, :disallow_writes, :delete_access_rule, :file_count, :list_files, :mkdir, :total_size,
-      :user_valid?, :get_filenames, :has_files?, to: :instance
+      :user_valid?, :get_filenames, :has_files?, :delete, :get, :post, :put, to: :instance
 
     def default_transfer_url
       "https://transfer.api.globusonline.org"
@@ -59,70 +60,176 @@ class GlobusClient
 
   attr_accessor :config
 
+  # Send an authenticated GET request
+  # @param base_url [String] the base URL of the Globus API
+  # @param path [String] the path to the Globus API request
+  # @param params [Hash] params to get to the API
+  def get(base_url:, path:, params: {}, content_type: nil)
+    response = with_token_refresh_when_unauthorized do
+      connection(base_url).get(path, params) do |request|
+        request.headers["Authorization"] = "Bearer #{config.token}"
+        request.headers["Content-Type"] = content_type if content_type
+      end
+    end
+
+    UnexpectedResponse.call(response) unless response.success?
+
+    return nil if response.body.blank?
+
+    JSON.parse(response.body)
+  end
+
+  # Send an authenticated POST request
+  # @param base_url [String] the base URL of the Globus API
+  # @param path [String] the path to the Globus API request
+  # @param body [String] the body of the Globus API request
+  # @param expected_response [#call] an expected response handler to allow short-circuiting the unexpected response
+  def post(base_url:, path:, body:, expected_response: ->(resp) { false })
+    response = with_token_refresh_when_unauthorized do
+      connection(base_url).post(path) do |request|
+        request.headers["Authorization"] = "Bearer #{config.token}"
+        request.headers["Content-Type"] = "application/json"
+        request.body = body.to_json
+      end
+    end
+
+    UnexpectedResponse.call(response) unless response.success? || expected_response.call(response)
+
+    return nil if response.body.blank?
+
+    JSON.parse(response.body)
+  end
+
+  # Send an authenticated PUT request
+  # @param base_url [String] the base URL of the Globus API
+  # @param path [String] the path to the Globus API request
+  # @param body [String] the body of the Globus API request
+  def put(base_url:, path:, body:)
+    response = with_token_refresh_when_unauthorized do
+      connection(base_url).put(path) do |request|
+        request.headers["Authorization"] = "Bearer #{config.token}"
+        request.headers["Content-Type"] = "application/json"
+        request.body = body.to_json
+      end
+    end
+
+    UnexpectedResponse.call(response) unless response.success?
+
+    return nil if response.body.blank?
+
+    JSON.parse(response.body)
+  end
+
+  # Send an authenticated DELETE request
+  # @param base_url [String] the base URL of the Globus API
+  # @param path [String] the path to the Globus API request
+  def delete(base_url:, path:)
+    response = with_token_refresh_when_unauthorized do
+      connection(base_url).delete(path) do |request|
+        request.headers["Authorization"] = "Bearer #{config.token}"
+      end
+    end
+
+    UnexpectedResponse.call(response) unless response.success?
+
+    return nil if response.body.blank?
+
+    JSON.parse(response.body)
+  end
+
   def mkdir(...)
-    TokenWrapper.refresh(config) do
-      endpoint = Endpoint.new(config, ...)
+    Endpoint.new(self, ...).tap do |endpoint|
       endpoint.mkdir
       endpoint.allow_writes
     end
   end
 
   def disallow_writes(...)
-    TokenWrapper.refresh(config) do
-      endpoint = Endpoint.new(config, ...)
-      endpoint.disallow_writes
-    end
+    Endpoint
+      .new(self, ...)
+      .disallow_writes
   end
 
   def delete_access_rule(...)
-    TokenWrapper.refresh(config) do
-      endpoint = Endpoint.new(config, ...)
-      endpoint.delete_access_rule
-    end
+    Endpoint
+      .new(self, ...)
+      .delete_access_rule
   end
 
   # NOTE: Can't use the `...` (argument forwarding) operator here because we
   #       want to route the keyword args to `Endpoint#new` and the block arg to
   #       `Endpoint#list_files`
   def list_files(**keywords, &block)
-    TokenWrapper.refresh(config) do
-      endpoint = Endpoint.new(config, **keywords)
-      endpoint.list_files(&block)
-    end
+    Endpoint
+      .new(self, **keywords)
+      .list_files(&block)
   end
 
   def file_count(...)
-    TokenWrapper.refresh(config) do
-      endpoint = Endpoint.new(config, ...)
-      endpoint.list_files { |files| return files.count }
-    end
+    Endpoint
+      .new(self, ...)
+      .list_files { |files| return files.count }
   end
 
   def total_size(...)
-    TokenWrapper.refresh(config) do
-      endpoint = Endpoint.new(config, ...)
-      endpoint.list_files { |files| return files.sum(&:size) }
-    end
+    Endpoint
+      .new(self, ...)
+      .list_files { |files| return files.sum(&:size) }
   end
 
   def get_filenames(...)
-    TokenWrapper.refresh(config) do
-      endpoint = Endpoint.new(config, ...)
-      endpoint.list_files { |files| return files.map(&:name) }
-    end
+    Endpoint
+      .new(self, ...)
+      .list_files { |files| return files.map(&:name) }
   end
 
   def has_files?(...)
-    TokenWrapper.refresh(config) do
-      endpoint = Endpoint.new(config, ...)
-      endpoint.has_files?
-    end
+    Endpoint
+      .new(self, ...)
+      .has_files?
   end
 
   def user_valid?(...)
-    TokenWrapper.refresh(config) do
-      identity = Identity.new(config)
-      identity.valid?(...)
+    Identity
+      .new(self)
+      .valid?(...)
+  end
+
+  private
+
+  def connection(base_url)
+    Faraday.new(url: base_url) do |conn|
+      conn.request :retry, {
+        max: 10,
+        interval: 0.05,
+        interval_randomness: 0.5,
+        backoff_factor: 2,
+        exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed]
+      }
     end
   end
+
+  # Wraps API operations to request new access token if expired.
+  # @yieldreturn response [Faraday::Response] the response to inspect
+  #
+  # @note You likely want to make sure you're wrapping a _single_ HTTP request in this
+  # method, because 1) all calls in the block will be retried from the top if there's
+  # an authN failure detected, and 2) only the response returned by the block will be
+  # inspected for authN failure.
+  # Related: consider that the client instance and its token will live across many
+  # invocations of the GlobusClient methods once the client is configured by a consuming application,
+  # since this class is a Singleton.  Thus, a token may expire between any two calls (i.e. it
+  # isn't necessary for a set of operations to collectively take longer than the token lifetime for
+  # expiry to fall in the middle of that related set of HTTP calls).
+  def with_token_refresh_when_unauthorized
+    response = yield
+
+    # if unauthorized, token has likely expired. try to get a new token and then retry the same request(s).
+    if response.status == 401
+      config.token = Authenticator.token(config.client_id, config.client_secret, config.auth_url)
+      response = yield
+    end
+
+    response
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: globus_client
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Aaron Collier
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-22 00:00:00.000000000 Z
+date: 2023-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -183,7 +183,6 @@ files:
 - lib/globus_client/authenticator.rb
 - lib/globus_client/endpoint.rb
 - lib/globus_client/identity.rb
-- lib/globus_client/token_wrapper.rb
 - lib/globus_client/unexpected_response.rb
 - lib/globus_client/version.rb
 homepage: https://github.com/sul-dlss/globus_client
@@ -208,7 +207,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.13
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Interface for interacting with the Globus API.

data/lib/globus_client/token_wrapper.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-class GlobusClient
-  # Wraps API operations to request new access token if expired
-  class TokenWrapper
-    def self.refresh(config)
-      yield
-    rescue UnexpectedResponse::UnauthorizedError
-      config.token = Authenticator.token(config.client_id, config.client_secret, config.auth_url)
-      yield
-    end
-  end
-end