files.com 1.1.783 → 1.1.784

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dc95932e61df91c8b29ba13bab73b9e81c4e272d999cad352a79b9af5880e8b
-  data.tar.gz: 5a84da44b445097b6e4741cd3e969cc8eabbc281d75188908a1c3fcb7443b789
+  metadata.gz: cd5e31f4e4c09fa7272e5c337ddc01c434546c93f177fe8fecd887839326f060
+  data.tar.gz: 143a0c464a2530296c1e67243d5f8d2e3640cff840c897ae2067517147af45b7
 SHA512:
-  metadata.gz: e0da3ee8e594c0049fd065e1d5300d5d71d67000af4acb8a10ef8409fce08874ab785c69b0f57692f512bb3b3e1b37fec0e5c5aed44e3fcbdf84410d5ed0398b
-  data.tar.gz: 82a14f3125a5317085b9261de7e4baf35dd1459921fd2c436855fc1f34f50fc1774fb4ea46576775d948e0e460b5c278949a6eea90fabd773fa4afffa1757f30
+  metadata.gz: 0d5eca777f0554ded3ad22b322bd8dcf959885c986c461a1d478c8097ffb00e2ee6d6741fd426cd36d0031796890f7d6ec7d0400f8c37072ae9079484a856fc7
+  data.tar.gz: f377e72e2cdb7e3f49391059d4c4c6115e506053cf7c371e6a0c2957018e701e8f3fd09ef8daeb099c498de22d8ce490826ea66cf596511bc43f8dd3f1fbaa89

data/_VERSION

@@ -1 +1 @@
-1.1.783
+1.1.784

data/lib/files.com/api_client.rb

@@ -8,8 +8,29 @@ module Files
     QUERY_METHODS = %i[get head delete].freeze
     private_constant :QUERY_METHODS
 
-    def initialize(conn = nil)
+    # The default for a logging option this client does not set itself.
+    USE_GLOBAL = Object.new.freeze
+    private_constant :USE_GLOBAL
+
+    # Creates a client that sends requests through +conn+, or through a new default connection when +conn+ is nil.
+    #
+    # By default the client logs its ordinary API requests, responses and errors through the library-wide Files.logger and
+    # Files.log_level, read as each message is logged. Pass either option to give this client its own setting
+    # instead, without changing the library-wide one or any other client:
+    #
+    # logger:: A Logger, or any object with the same +log+ method, that receives this client's ordinary API messages. Its own
+    #          level decides which are written, and the client never changes it. Pass nil for no logger even when
+    #          Files.logger is set.
+    # log_level:: Without a logger, the lowest level written to standard output and error: nil, Files::LEVEL_DEBUG,
+    #             Files::LEVEL_INFO or Files::LEVEL_ERROR, or "debug" or "info", as Files.log_level= accepts. It
+    #             is ignored when the client has a logger. Pass nil to write nothing there even when
+    #             Files.log_level is set.
+    #
+    # A client created with logger: nil, log_level: nil logs no ordinary API messages.
+    def initialize(conn = nil, logger: USE_GLOBAL, log_level: USE_GLOBAL)
       self.conn = conn || self.class.default_conn
+      @logger = logger
+      @log_level = log_level.equal?(USE_GLOBAL) ? log_level : Util.normalize_log_level(log_level)
       @system_profiler = SystemProfiler.new
       @last_request_metrics = nil
     end
@@ -375,7 +396,7 @@ module Files
                 else
                   "The Files.com API returned an error without a message (HTTP response code was #{resp.http_status})"
                 end
-      Util.log_error("API error", status: resp.http_status, error_message: message)
+      Util.log_error("API error", { status: resp.http_status, error_message: message }, log_settings)
 
       api_error_class(resp.data[:type]).new(message,
         http_body: resp.http_body,
@@ -462,7 +483,7 @@ module Files
                         error.message.empty? ? error.response[:body] : error.message
                       end
 
-      Util.log_error("Network error", error_message: error_message)
+      Util.log_error("Network error", { error_message: error_message }, log_settings)
       message = "Could not connect to Files.com at URL #{base_url}. Please check your internet connection and try again. If this problem persists, you should check Files.com's service status at https://status.files.com, or contact your primary account representative."
       message += " Request was retried #{num_retries} times." if num_retries > 0
       message += "\n\n(Network error: #{error_message})"
@@ -508,18 +529,25 @@ module Files
     end
 
     private def log_request(context, num_retries, no_body: false)
-      Util.log_info("Request", method: context.method, num_retries: num_retries, path: context.path)
-      Util.log_debug("Request details", body: context.body, query_params: context.query_params) unless no_body
+      Util.log_info("Request", { method: context.method, num_retries: num_retries, path: context.path }, log_settings)
+      Util.log_debug("Request details", { body: context.body, query_params: context.query_params }, log_settings) unless no_body
     end
 
     private def log_response(context, request_start, status, body, no_body: false)
-      Util.log_info("Response", elapsed: Time.now - request_start, method: context.method, path: context.path, status: status)
-      Util.log_debug("Response details", body: body) unless no_body
+      Util.log_info("Response", { elapsed: Time.now - request_start, method: context.method, path: context.path, status: status }, log_settings)
+      Util.log_debug("Response details", { body: body }, log_settings) unless no_body
     end
 
     private def log_response_error(context, request_start, error)
-      Util.log_error("Error", elapsed: Time.now - request_start, error_type: error.class, method: context.method, path: context.path)
-      Util.log_debug("Error details", error_message: error.message)
+      Util.log_error("Error", { elapsed: Time.now - request_start, error_type: error.class, method: context.method, path: context.path }, log_settings)
+      Util.log_debug("Error details", { error_message: error.message }, log_settings)
+    end
+
+    # This client's own logger and level where it set them, and the library-wide ones otherwise.
+    private def log_settings
+      Util::LogSettings.new(@logger.equal?(USE_GLOBAL) ? Files.logger : @logger,
+                            @log_level.equal?(USE_GLOBAL) ? Files.log_level : @log_level
+                           )
     end
 
     class RequestLogContext

data/lib/files.com/util.rb

@@ -34,29 +34,48 @@ module Files
       end
     end
 
-    def self.log_error(message, data = {})
-      if !Files.logger.nil? ||
-         (!Files.log_level.nil? && Files.log_level <= Files::LEVEL_ERROR)
+    # Where log messages go: to +logger+ when there is one, which then filters by its own level, and otherwise to
+    # standard output or error at +log_level+ and above. A nil +log_level+ without a logger logs nothing.
+    LogSettings = Struct.new(:logger, :log_level)
+
+    # The library-wide Files.logger and Files.log_level, read when each message is logged.
+    def self.global_log_settings
+      LogSettings.new(Files.logger, Files.log_level)
+    end
+
+    # The same values Files.log_level= accepts: nil, a level constant, or "debug" or "info".
+    def self.normalize_log_level(val)
+      val = { "debug" => LEVEL_DEBUG, "info" => LEVEL_INFO }.fetch(val, val)
+      if !val.nil? && ![ LEVEL_DEBUG, LEVEL_ERROR, LEVEL_INFO ].include?(val)
+        raise ArgumentError,
+              "log_level should only be set to `nil`, `debug` or `info`"
+      end
+      val
+    end
+
+    def self.log_error(message, data = {}, settings = global_log_settings)
+      if !settings.logger.nil? ||
+         (!settings.log_level.nil? && settings.log_level <= Files::LEVEL_ERROR)
         log_internal(message, data, color: :cyan, level: Files::LEVEL_ERROR,
-                                    logger: Files.logger, out: $stderr
+                                    logger: settings.logger, out: $stderr
         )
       end
     end
 
-    def self.log_info(message, data = {})
-      if !Files.logger.nil? ||
-         (!Files.log_level.nil? && Files.log_level <= Files::LEVEL_INFO)
+    def self.log_info(message, data = {}, settings = global_log_settings)
+      if !settings.logger.nil? ||
+         (!settings.log_level.nil? && settings.log_level <= Files::LEVEL_INFO)
         log_internal(message, data, color: :cyan, level: Files::LEVEL_INFO,
-                                    logger: Files.logger, out: $stdout
+                                    logger: settings.logger, out: $stdout
         )
       end
     end
 
-    def self.log_debug(message, data = {})
-      if !Files.logger.nil? ||
-         (!Files.log_level.nil? && Files.log_level <= Files::LEVEL_DEBUG)
+    def self.log_debug(message, data = {}, settings = global_log_settings)
+      if !settings.logger.nil? ||
+         (!settings.log_level.nil? && settings.log_level <= Files::LEVEL_DEBUG)
         log_internal(message, data, color: :blue, level: Files::LEVEL_DEBUG,
-                                    logger: Files.logger, out: $stdout
+                                    logger: settings.logger, out: $stdout
         )
       end
     end

data/lib/files.com/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Files
-  VERSION = "1.1.783"
+  VERSION = "1.1.784"
 end

data/spec/lib/api_client_spec.rb

@@ -344,6 +344,64 @@ RSpec.describe Files::ApiClient do
     end
   end
 
+  describe "client loggers" do
+    around do |example|
+      original = [ Files.logger, Files.log_level, Files.max_network_retries ]
+      Files.max_network_retries = 0
+      example.run
+    ensure
+      Files.logger, Files.log_level, Files.max_network_retries = original
+    end
+
+    it "logs each client's requests to its own logger without changing the library-wide settings" do
+      connection = Faraday.new do |builder|
+        builder.response :raise_error
+        builder.adapter :test do |stub|
+          (1..5).each do |id|
+            stub.get("/api/rest/v1/workspaces/#{id}") { [ 200, { "Content-Type" => "application/json" }, { id: id }.to_json ] }
+          end
+          stub.get("/api/rest/v1/workspaces/6") { [ 404, { "Content-Type" => "application/json" }, { error: "Not Found", type: "not-found" }.to_json ] }
+        end
+      end
+      global_output = StringIO.new
+      global_logger = Logger.new(global_output, level: Logger::INFO)
+      Files.logger = global_logger
+      Files.log_level = Files::LEVEL_INFO
+      a_output = StringIO.new
+      a_logger = Logger.new(a_output, level: Logger::INFO)
+      b_output = StringIO.new
+      b_logger = Logger.new(b_output, level: Logger::ERROR)
+      client_a = described_class.new(connection, logger: a_logger)
+      client_b = described_class.new(connection, logger: b_logger, log_level: Files::LEVEL_DEBUG)
+
+      Files::Workspace.find(1, {}, api_key: "key", client: client_a)
+      Files::Workspace.find(2, {}, api_key: "key", client: client_b)
+      Files::Workspace.find(3, {}, api_key: "key", client: client_a)
+
+      expect(a_output.string).to include("message=Request method=get num_retries=0 path=/workspaces/1", "message=Request method=get num_retries=0 path=/workspaces/3")
+      expect(a_output.string.scan(/message=Response .*status=200/).size).to eq(2)
+      expect(a_output.string).not_to include("/workspaces/2")
+      expect(b_output.string).to be_empty
+      expect(global_output.string).to be_empty
+      expect([ a_logger.level, b_logger.level ]).to eq([ Logger::INFO, Logger::ERROR ])
+      expect(Files.logger).to equal(global_logger)
+      expect(Files.log_level).to eq(Files::LEVEL_INFO)
+
+      expect { Files::Workspace.find(6, {}, api_key: "key", client: client_b) }.to raise_error(Files::NotFoundError)
+      expect(b_output.string).to include("message=API error status=404")
+      expect(a_output.string).not_to include("API error")
+      expect(global_output.string).to be_empty
+      expect([ a_logger.level, b_logger.level ]).to eq([ Logger::INFO, Logger::ERROR ])
+
+      Files::Workspace.find(4, {}, api_key: "key", client: described_class.new(connection))
+      expect(global_output.string).to include("message=Request method=get num_retries=0 path=/workspaces/4")
+
+      quiet_client = described_class.new(connection, logger: nil, log_level: nil)
+      expect { Files::Workspace.find(5, {}, api_key: "key", client: quiet_client) }.not_to output.to_stdout
+      expect(global_output.string).not_to include("/workspaces/5")
+    end
+  end
+
   describe "network timeouts" do
     around do |example|
       original = [ Files.open_timeout, Files.read_timeout ]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: files.com
 version: !ruby/object:Gem::Version
-  version: 1.1.783
+  version: 1.1.784
 platform: ruby
 authors:
 - files.com