chimera_http_client 1.1.1 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 245adb27237d0970454580b14f6973ed7bf732a8ce3f4426b35978ff27eed9d8
-  data.tar.gz: 02e8646e5757b60b7d4617d58f3413bdd4b5675d8d307342fabc7ce03c90471b
+  metadata.gz: 0b68f9f3f76d137690c9f3fd9345b835efadee680ba8cd6b964095c554f9cb96
+  data.tar.gz: 7a86650670f451558d407c04a9870f522cf6805413f256dfc453622c9c55263f
 SHA512:
-  metadata.gz: 0caca4f777876526ab8fb4f1652b0643e545bd768e7722424e2007e3e1e79f397cc043dd5ad81d4319ec0703242c72a9481bcac589a48d82374a7e646cef2974
-  data.tar.gz: caf3dc496a546c75a07475148a063caf8b312f9fb63f9a65de02577c3f7b4398e8c05660660d003c6dc7a14bf50b33e5e46cba6d7c2599901b265d3df3f5155c
+  metadata.gz: 8a12bdf778c260bdfe95f529e7d94dbecf6b0d041f21da25a5f3503c185db8aaaa041d27d01b98767ddb98466e684c2fc266cab3e0bbaf8cb61b7353a8f37071
+  data.tar.gz: 7da871e77ae5d29d207c5e6c4d95f3cdc831a15202cf7bf0a3f73ee44c8610ba1760189b542f86ff161b963640d448ac7a28fbeaa04845a1c8f462a28f13245c

data/.rubocop.yml

@@ -5,46 +5,19 @@ AllCops:
       - vendor/**/*
       - config.ru
 
-Layout/AlignHash:
-  Enabled: false
-
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles, IndentationWidth.
 # SupportedStyles: special_inside_parentheses, consistent, align_braces
-Layout/IndentFirstHashElement:
+Layout/FirstHashElementIndentation:
   EnforcedStyle: consistent
 
-Metrics/AbcSize:
-  Max: 35
-
-Metrics/BlockLength:
-  Exclude:
-    - chimera_http_client.gemspec
-    - spec/**/*
-
-# Configuration parameters: CountComments.
-Metrics/ClassLength:
-  Max: 150
-
-Metrics/CyclomaticComplexity:
-  Max: 15
+Layout/HashAlignment:
+  Enabled: false
 
-# Configuration parameters: AllowHeredoc, AllowURI, URISchemes.
-# URISchemes: http, https
-Metrics/LineLength:
+Layout/LineLength:
   Max: 125
 
-# Offense count: 5
-# Configuration parameters: CountComments.
-Metrics/MethodLength:
-  Max: 32
-
-Metrics/ParameterLists:
-  Max: 7
-
-# Configuration parameters: EnforcedStyle, SupportedStyles.
-# SupportedStyles: braces, no_braces, context_dependent
-Style/BracesAroundHashParameters:
+Metrics:
   Enabled: false
 
 Style/CommentedKeyword:

data/.ruby-version

@@ -1 +1 @@
-2.6.3
+2.7.2

data/README.markdown

@@ -7,6 +7,7 @@ And what works for the internal communication between your own apps, will also w
 It offers an **easy to learn interface** and **nice error handling**. And it enables you to **queue HTTP requests to run them in parallel** for better performance and simple aggregating of distributed data.
 
 [![Build Status](https://travis-ci.com/mediafinger/chimera_http_client.svg?branch=master)](https://travis-ci.com/mediafinger/chimera_http_client)
+[![Gem Version](https://badge.fury.io/rb/chimera_http_client.svg)](https://badge.fury.io/rb/chimera_http_client)
 
 ## Dependencies
 
@@ -22,6 +23,8 @@ The only other runtime dependency is Ruby's latest code loader [**zeitwerk**](ht
 | =  1.0          | >= 2.4       |
 | <= 0.5          | >= 2.1       |
 
+The test suite of v1.3 and newer also passes on **JRuby** and on **TruffleRuby**.
+
 ### ENV variables
 
 Setting the environment variable `ENV['CHIMERA_HTTP_CLIENT_LOG_REQUESTS']` to `true` (or `'true'`) will provide more detailed error messages for logging and also add additional information to the Error JSON. It is recommended to use this only in development environments.
@@ -82,12 +85,13 @@ Setting the `base_url` is meant to be a comfort feature, as you can then pass sh
 
 The optional parameters are:
 
-* `logger` - an instance of a logger class that implements `#info` and `#warn` methods
+* `cache` - an instance of your cache solution, can be overwritten in any request
+* `deserializers` - custom methods to deserialize the response body, below more details
+* `logger` - an instance of a logger class that implements `#info`, `#warn` and `#error` methods
+* `monitor` - to collect metrics about requests, the basis for your instrumentation needs
 * `timeout` - the timeout for all requests, can be overwritten in any request, the default are 3 seconds
 * `user_agent` - if you would like your calls to identify with a specific user agent
 * `verbose` - the default is `false`, set it to true while debugging issues
-* `cache` - an instance of your cache solution, can be overwritten in any request
-* `deserializers` - custom methods to deserialize the response body, below more details
 
 ##### Custom deserializers
 
@@ -101,6 +105,23 @@ A Deserializer has to be an object on which the method `call` with the parameter
 
 where `body` is the response body (in the default case a JSON object). The class `Deserializer` contains the default objects that are used. They might help you creating your own. Don't forget to make requests with another header than the default `"Content-Type" => "application/json"`, when the API you connect to does not support JSON.
 
+##### Monitoring, metrics, instrumentation
+
+Pass an object as `:monitor` to a connection that defines the method `call` and accepts a hash as parameter.
+
+    monitor.call({...})
+
+It will receive information about every request as soon as it finished. What you do with this information is up for you to implement.
+
+| Field          | Description                                                           |
+|:---------------|:----------------------------------------------------------------------|
+| `url`          | URL of the endpoint that was called                                   |
+| `method`       | HTTP method: get, post, ...                                           |
+| `status`       | HTTP status code: 200, ...                                            |
+| `runtime`      | the time in seconds it took the request to finish                     |
+| `completed_at` | Time.now.utc.iso8601(3)                                               |
+| `context`      | Whatever you pass as `monitoring_context` to the options of a request |
+
 ### Request methods
 
 The available methods are:
@@ -141,6 +162,7 @@ All request methods expect a mandatory `endpoint` and an optional hash as parame
 * `password` - used for a BasicAuth login
 * `timeout` - set a custom timeout per request (the default is 3 seconds)
 * `cache` - optionally overwrite the cache store set in `Connection` in any request
+* `monitoring_context` - pass additional information you want to collect with your instrumentation `monitor`
 
 Example:
 
@@ -170,6 +192,17 @@ If you want to use a different timeout, you can pass the key `timeout` when init
 
 By default no logging is happening. If you need request logging, you can pass your custom Logger to the key `logger` when initializing the `Connection`. It will write to `logger.info` when starting and when completing a request.
 
+The message passed to the logger is a hash with the following fields:
+
+| Key          | Description                                 |
+|:-------------|:--------------------------------------------|
+| `message`    | indicator if a call was started or finished |
+| `method`     | the HTTP method used                        |
+| `url`        | the requested URL                           |
+| `code`       | HTTP status code                            |
+| `runtime`    | time the request took in ms                 |
+| `user_agent` | the user_agent used to open the connection  |
+
 #### Caching responses
 
 To cache all the reponses of a connection, just pass the optional parameter `cache` to its initializer. You can also overwrite the connection's cache configuration by passing the parameter `cache` to any `get` call.
@@ -387,7 +420,10 @@ When updating the version, do not forget to run
 
 After checking out the repo, run `bundle install` and then `bundle execute rake` to run the **tests and rubocop**.
 
-> The test suite uses a Sinatra server to make real HTTP requests. It is mounted via Capybara_discoball and running in the same process.
+> The test suite uses a Sinatra server to make real HTTP requests. It is mounted via Capybara_discoball and running in the same process. It is still running reasonably fast (on my MacBook Air):
+
+    Finished in 2.01 seconds (files took 1.09 seconds to load)
+    824 examples, 0 failures, 7 pending
 
 You can also run `rake console` to open an irb session with the `ChimeraHttpClient` pre-loaded that will allow you to experiment.
 

data/TODO.markdown

@@ -14,8 +14,9 @@ _none known_
 * [x] ~~include the total_time of the requests in the log~~
 * [x] ~~add (example) to README~~
 * [ ] add logger.warn / .error for error cases (?)
+* [ ] streamline log message
 
-### Custom De-serializer
+### ~~Custom De-serializer~~
 
 * [x] ~~allow to pass custom deserializer~~
 * [x] ~~use custom deserializer in #parsed_body instead of default JSON parsing~~
@@ -39,7 +40,19 @@ _none known_
 ### Miscellaneous
 
 - [ ] Determine by parameter if 3xx Redirects should be handled as an Error or not
-- [ ] Add a longer description to the gemspec file
+- [x] ~~Add a longer description to the gemspec file~~
+- [ ] Refactor README to explain simple use case vs. all the powerful options?
+
+### ~~Instrumentation~~
+
+- [x] ~~allow to pass object to collect metrics for monitoring~~
+  - [x] ~~request URL~~
+  - [x] ~~request HTTP method~~
+  - [x] ~~request response code~~
+  - [x] ~~request datetime~~
+  - [x] ~~request runtime~~
+  - [x] ~~custom context information per request~~
+- [x] ~~add example to README~~
 
 ### Enable more Typhoeus functionality
 
@@ -84,7 +97,7 @@ _none known_
 * [x] ~~allow to set custom timeout per call~~
 * [x] ~~add (example) to README~~
 
-### Release
+### ~~Release~~
 
 * [x] ~~rename module to have unique namespace~~
 * [x] ~~release to rubygems to add to the plethora of similar gems~~

data/chimera_http_client.gemspec

@@ -3,13 +3,22 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "chimera_http_client/version"
 
 Gem::Specification.new do |spec|
+  spec.required_ruby_version = ">= 2.5.0" # without Deserializer's `rescue` in block it would be 2.4.4 (because of zeitwerk)
+
   spec.name          = "chimera_http_client"
   spec.version       = ChimeraHttpClient::VERSION
   spec.authors       = ["Andreas Finger"]
   spec.email         = ["webmaster@mediafinger.com"]
 
-  spec.summary       = "Http Client to connect to REST APIs"
-  spec.description   = "General http client functionality to easily connect to JSON endpoints" # TODO: extend and polish
+  spec.summary       = "General http client functionality to quickly connect to JSON REST API endpoints and any others"
+  spec.description   = <<~DESCRIPTION
+    The Chimera http client offers an easy to learn interface and consistent error handling.
+    It is lightweight, fast and enables you to queue HTTP requests to run them in parallel
+    for better performance and simple aggregating of distributed data. Despite it's simple
+    interface it allows for advanced features like using custom deserializers, loggers,
+    caching requests individiually, and instrumentation support (soon to be implemented).
+  DESCRIPTION
+
   spec.homepage      = "https://github.com/mediafinger/chimera_http_client"
   spec.license       = "MIT"
 

data/lib/chimera_http_client/base.rb

@@ -8,6 +8,7 @@ module ChimeraHttpClient
       @base_url = options.fetch(:base_url)
       @deserializer = default_deserializer.merge(options.fetch(:deserializer, {}))
       @logger = options[:logger]
+      @monitor = options[:monitor]
       @timeout = options[:timeout]
 
       Typhoeus::Config.cache = options[:cache]

data/lib/chimera_http_client/connection.rb

@@ -12,11 +12,12 @@ module ChimeraHttpClient
 
     def request
       options = {
-        logger: @logger,
         deserializer: @deserializer,
+        logger: @logger,
+        monitor: @monitor,
       }
 
-      @request ||= Request.new(options)
+      Request.new(options)
     end
 
     private

data/lib/chimera_http_client/queue.rb

@@ -38,12 +38,13 @@ module ChimeraHttpClient
     private
 
     def create_request(method:, url:, body:, headers:, options:)
-      class_options = {
-        logger: @logger,
+      instance_options = {
         deserializer: @deserializer,
+        logger: @logger,
+        monitor: @monitor,
       }
 
-      Request.new(class_options).create(
+      Request.new(instance_options).create(
         method: method,
         url: url,
         body: body,

data/lib/chimera_http_client/request.rb

@@ -5,7 +5,6 @@ module ChimeraHttpClient
     attr_reader :request, :result
 
     def initialize(options = {})
-      @logger = options[:logger]
       @options = options
     end
 
@@ -37,13 +36,39 @@ module ChimeraHttpClient
 
       @result = nil
       @request.on_complete do |response|
-        @logger&.info("Completed HTTP request: #{method.upcase} #{url} " \
-          "in #{response.total_time&.round(3)}sec with status code #{response.code}")
+        runtime = response.total_time&.round(3)
+
+        @options[:monitor]&.call(
+          {
+            url: url, method: method, status: response.code, runtime: runtime,
+            completed_at: Time.now.utc.iso8601(3), context: options[:monitoring_context]
+          }
+        )
+
+        @options[:logger]&.info(
+          {
+            message: "Completed Chimera HTTP Request",
+            method: method.upcase,
+            url: url,
+            code: response.code,
+            runtime: runtime,
+            user_agent: Typhoeus::Config.user_agent,
+          }
+        )
 
         @result = on_complete_handler(response)
       end
 
-      @logger&.info("Starting HTTP request: #{method.upcase} #{url}")
+      @options[:logger]&.info(
+        {
+          message: "Starting Chimera HTTP Request",
+          method: method.upcase,
+          url: url,
+          code: nil,
+          runtime: 0,
+          user_agent: Typhoeus::Config.user_agent,
+        }
+      )
 
       self
     end
@@ -63,7 +88,7 @@ module ChimeraHttpClient
       when 301, 302, 303, 307
         RedirectionError.new(response, @options) # TODO: throw error conditionally
       when 200..399
-        nil
+        nil # TODO: decide to either raise error or return a Response
       when 400
         BadRequestError.new(response, @options)
       when 401

data/lib/chimera_http_client/version.rb

@@ -1,3 +1,3 @@
 module ChimeraHttpClient
-  VERSION = "1.1.1".freeze
+  VERSION = "1.3.1".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chimera_http_client
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.3.1
 platform: ruby
 authors:
 - Andreas Finger
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2019-06-15 00:00:00.000000000 Z
+date: 2021-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: typhoeus
@@ -220,7 +220,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: General http client functionality to easily connect to JSON endpoints
+description: |
+  The Chimera http client offers an easy to learn interface and consistent error handling.
+  It is lightweight, fast and enables you to queue HTTP requests to run them in parallel
+  for better performance and simple aggregating of distributed data. Despite it's simple
+  interface it allows for advanced features like using custom deserializers, loggers,
+  caching requests individiually, and instrumentation support (soon to be implemented).
 email:
 - webmaster@mediafinger.com
 executables: []
@@ -251,7 +256,7 @@ homepage: https://github.com/mediafinger/chimera_http_client
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -259,15 +264,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
-summary: Http Client to connect to REST APIs
+summary: General http client functionality to quickly connect to JSON REST API endpoints
+  and any others
 test_files: []