chimera_http_client 1.8.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b13d3c092d285089ec23e09429db2129e3095c398ed1e829800bbcd0574e5c49
-  data.tar.gz: 8a646ce583338f381130879c86801349af06de6f2b32e19ab0a6a5d6677d8303
+  metadata.gz: ca5968573054108171952f955ef7974120a4d4725ed1ca34af29e3d40e831c61
+  data.tar.gz: 3f8adfc58275d048326c4cb25c93cc46d637195da9eb042e1c6388d705e3dc54
 SHA512:
-  metadata.gz: b2813b2933fa8488973c345392fe879ac64b827180fa1d01dc872f83e13e23ebd4b9e95d9e3d7c17e457a9b73f293812d582a0fa9e22168a36abbb09439715cd
-  data.tar.gz: 5ec92f4d71bc1925f2e8b3db89b50ec237b554f7ff4d3ac65edc13dd6fd6200aa56ed1aba060e85afd325512eadfeb81fcdb83471995ca015010bbdcea8356b6
+  metadata.gz: b00e1318e81f48ea6897e384062ab4e30b9ca83d1dc4549a22ecf8df9ce1940806c47fd04f8bf2f1109cd58922bee78605622fedc61bc74e5fb15d4be7dc0184
+  data.tar.gz: 494531a305d3bb571e98d9da1f6ad69330b64de19d29ed8d4cd64a3218fdc92bc3c2c499f7b88b829f714abc5f291654b09d364dff7577e83d6ff3080b68c6ae

data/README.markdown

@@ -37,6 +37,8 @@ All information above is given for **Linux**.
 
 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.
 
+Setting `ENV['CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS']` to a JSON object string will merge those headers into every `Connection`/`Queue` in the process, e.g. `export CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS='{"X-Service-Name":"orders-api"}'`. This is meant for deployment/ops-level defaults (like identifying which service is calling), set once outside application code. See [Custom headers](#custom-headers) below.
+
 ## Table of Contents
 
 <!-- TOC depthFrom:1 depthTo:4 withLinks:1 updateOnSave:0 orderedList:0 -->
@@ -51,6 +53,8 @@ Setting the environment variable `ENV['CHIMERA_HTTP_CLIENT_LOG_REQUESTS']` to `t
       - [Mandatory initialization parameter `base_url`](#mandatory-initialization-parameter-base_url)
       - [Optional initialization parameters](#optional-initialization-parameters)
         - [Custom deserializers](#custom-deserializers)
+        - [Custom headers](#custom-headers)
+        - [Custom serializer](#custom-serializer)
         - [Monitoring, metrics, instrumentation](#monitoring-metrics-instrumentation)
     - [Request methods](#request-methods)
       - [Mandatory request parameter `endpoint`](#mandatory-request-parameter-endpoint)
@@ -100,10 +104,12 @@ The optional parameters are:
 
 * `cache` - an instance of your cache solution, can be overwritten in any request
 * `deserializers` - custom methods to deserialize the response body, below more details
+* `headers` - override/extend the default request headers (`{ "Content-Type" => "application/json" }`), can be overwritten or merged with per-request headers, 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
 * `retries` - the number of times a failed idempotent request is retried, can be overwritten in any request, the default is `0` (no retries)
 * `retry_delay` - the base delay in seconds between retries, can be overwritten in any request, the default is `1`
+* `serializer` - override how a Hash/Array request body is turned into a request, can be overwritten in any request, below more details
 * `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
@@ -118,7 +124,64 @@ A Deserializer has to be an object on which the method `call` with the parameter
 
     custom_deserializer.call(body)
 
-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.
+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. If the API you connect to does not support JSON, set `headers` (see [Custom headers](#custom-headers) below) once on the `Connection` instead of repeating it on every request - and see [Custom serializer](#custom-serializer) below for the equivalent on the request-body side.
+
+##### Custom headers
+
+Every request sends `{ "Content-Type" => "application/json" }` plus a `User-Agent` by default. Four layers apply on top of each other (each one merges in, overriding only the keys it sets, so you never have to restate headers you're not changing):
+
+1. the built-in default above (also available as `ChimeraHttpClient::Base::DEFAULT_HEADERS`)
+2. `ENV['CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS']`, a JSON object (see [ENV variables](#env-variables) above)
+3. `headers` passed to `Connection.new`/`Queue.new` - the connection's own default
+4. `headers` passed to an individual request - already documented above, unchanged
+
+```ruby
+# connecting to a non-JSON API: override just Content-Type, everything else (User-Agent, ...) still applies
+connection = ChimeraHttpClient::Connection.new(base_url: 'http://localhost:3000/v1', headers: { "Content-Type" => "application/xml" })
+```
+
+A common use for the connection-level `headers` option is a request/correlation id that should be attached to every call made for one unit of work (a background job, one inbound request being served), without every call site needing to know about it:
+
+```ruby
+connection = ChimeraHttpClient::Connection.new(base_url: 'http://localhost:3000/v1', headers: { "X-Request-Id" => job_id })
+```
+
+For something that's the same for every request in the whole process instead - e.g. identifying which of your services is calling, in a service-to-service setting - set it once via `ENV['CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS']` at the deployment level rather than in application code:
+
+```bash
+export CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS='{"X-Service-Name":"orders-api"}'
+```
+
+##### Custom serializer
+
+A `Hash` or `Array` `body` is automatically serialized before the request is sent - by default with `body.to_json`, so this now just works:
+
+```ruby
+connection.post!('users', body: { name: "Andy" }) # no more body.to_json needed
+```
+
+A `String` body (e.g. one you already serialized yourself) is always passed through completely unchanged - so any existing code still doing `body: body.to_json` keeps working exactly as before.
+
+To use a different format, pass `serializer` to `Connection.new`/`Queue.new`, or to an individual request. A Serializer has to be an object on which the method `call` with the parameter `body` can be called:
+
+    custom_serializer.call(body)
+
+```ruby
+# talking to an XML API instead
+connection = ChimeraHttpClient::Connection.new(base_url: 'http://localhost:3000/v1', serializer: ->(body) { body.to_xml })
+```
+
+The serializer normally returns a `String`, but it can also return the `Hash` unconverted - Typhoeus (via Ethon/libcurl) then form-encodes it natively as `application/x-www-form-urlencoded`, or as real multipart if a value looks file-shaped:
+
+```ruby
+# posting a plain form instead of JSON
+connection.post(
+  'login',
+  body: { username: "andy", password: "secret" },
+  serializer: ->(body) { body }, # hand the Hash to Typhoeus/Ethon unconverted
+  headers: { "Content-Type" => "application/x-www-form-urlencoded" }
+)
+```
 
 ##### Monitoring, metrics, instrumentation
 
@@ -179,6 +242,7 @@ All request methods expect a mandatory `endpoint` and an optional hash as parame
 * `cache` - optionally overwrite the cache store set in `Connection` in any request
 * `retries` - optionally overwrite the number of retries set in `Connection` for this request
 * `retry_delay` - optionally overwrite the retry delay set in `Connection` for this request
+* `serializer` - optionally overwrite the body serializer set in `Connection` for this request
 * `monitoring_context` - pass additional information you want to collect with your instrumentation `monitor`
 
 Example:
@@ -313,7 +377,7 @@ class Users
   # CREATE a new user by sending attributes in a JSON body and instantiate the new User
   #
   def create(body:)
-    response = connection.post!('users', body: body.to_json) # body.to_json (!!)
+    response = connection.post!('users', body: body) # a Hash body is serialized to JSON automatically
 
     user = response.parsed_body
     User.new(id: user['id'], name: user['name'], email: user['email'])
@@ -348,7 +412,7 @@ To create and fetch a user from a remote service with the `Users` wrapper listed
 
 Usually it does not have to be used directly. It is the class that executes the `Typhoeus::Requests`, raises `Errors` on failing and returns `Response` objects on successful calls.
 
-The `body` which it receives from the `Connection` class has to be in the in the (serialized) form in which the endpoint expects it. Usually this means you have to pass a JSON string to the `body` (it will **not** be serialized automatically).
+By the time `Request` receives `body`, it's already in the (serialized) form the endpoint expects: `Connection`/`Queue` auto-serialize a `Hash`/`Array` body to JSON (or via a custom `serializer`, see [Custom serializer](#custom-serializer)) before it ever reaches `Request`. A `String` body is passed through unchanged.
 
 ## The Response class
 

data/TODO.markdown

@@ -22,6 +22,12 @@ _none known_
 * [x] ~~use custom deserializer in #parsed_body instead of default JSON parsing~~
 * [x] ~~add example to README~~
 
+### ~~Custom serializer~~
+
+* [x] ~~allow to pass custom serializer~~
+* [x] ~~use custom serializer with body instead of default JSON serialization ~~
+* [x] ~~add example to README~~
+
 ### Queueing / running in parallel
 
 * [x] ~~allow to queue multiple requests~~
@@ -79,12 +85,12 @@ _none known_
 * [ ] enable to pass on_headers, on_body, on_complete procs
 * [ ] add example to README
 
-### HTTP Headers
+### ~~HTTP Headers~~
 
-* [ ] make Connection#default_headers configurable
-* [ ] allow to set default_headers via ENV vars
-* [ ] give example how to use default_headers (e.g. request_id)
-* [ ] explain in README how to benefit from this gem in a given setting
+* [x] ~~make Connection#default_headers configurable~~
+* [x] ~~allow to set default_headers via ENV vars~~
+* [x] ~~give example how to use default_headers (e.g. request_id)~~
+* [x] ~~explain in README how to benefit from this gem in a given setting~~
 
 ### ~~Caching~~
 

data/lib/chimera_http_client/base.rb

@@ -1,16 +1,20 @@
 module ChimeraHttpClient
   class Base
     USER_AGENT = "ChimeraHttpClient (by mediafinger)".freeze
+    DEFAULT_HEADERS = { "Content-Type" => "application/json" }.freeze
+    DEFAULT_HEADERS_ENV_VAR = "CHIMERA_HTTP_CLIENT_DEFAULT_HEADERS".freeze
 
     def initialize(options = {})
       fail(ChimeraHttpClient::ParameterMissingError, "base_url expected, but not given") if options[:base_url].nil?
 
       @base_url = options.fetch(:base_url)
       @deserializer = default_deserializer.merge(options.fetch(:deserializer, {}))
+      @serializer = options.fetch(:serializer, ::ChimeraHttpClient::Serializer.json)
       @logger = options[:logger]
       @monitor = options[:monitor]
       @timeout = options[:timeout]
       @cache = options[:cache]
+      @headers = DEFAULT_HEADERS.merge(headers_from_env).merge(options[:headers] || {})
       @user_agent = options.fetch(:user_agent, USER_AGENT)
       @verbose = options.fetch(:verbose, false)
       @retries = options[:retries] || 0
@@ -33,10 +37,13 @@ module ChimeraHttpClient
     def extract_body(options)
       body = options.delete(:body)
       body_optional = options.delete(:body_optional)
+      serializer = options.delete(:serializer) || @serializer
 
       fail(ChimeraHttpClient::ParameterMissingError, "body expected, but not given") if body.nil? && !body_optional
 
-      body
+      return body unless body.is_a?(Hash) || body.is_a?(Array)
+
+      serializer.call(body)
     end
 
     def extract_headers(options, headers)
@@ -45,7 +52,16 @@ module ChimeraHttpClient
     end
 
     def default_headers
-      { "Content-Type" => "application/json", "User-Agent" => @user_agent }
+      @headers.merge("User-Agent" => @user_agent)
+    end
+
+    def headers_from_env
+      raw = ENV[DEFAULT_HEADERS_ENV_VAR].to_s
+      return {} if raw.strip.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise(ChimeraHttpClient::ParameterMissingError, "ENV['#{DEFAULT_HEADERS_ENV_VAR}'] is not valid JSON: #{e.message}")
     end
 
     def default_deserializer

data/lib/chimera_http_client/serializer.rb

@@ -0,0 +1,23 @@
+# The default JSON serializer for request bodies.
+#
+# To use a custom serializer, pass it as a param to Connection.new or Queue.new:
+# `serializer: your_serializer`
+# or override it for a single request: `connection.post(endpoint, body: {...}, serializer: your_serializer)`
+#
+# A Serializer has to be an object on which the method `call` with the parameter `body` can be called:
+# `custom_serializer.call(body)`
+# It is only ever invoked for a Hash or Array body - anything else (e.g. an already-serialized
+# String) is passed to the request unchanged. It normally returns a String, but may also return
+# a Hash - Typhoeus/Ethon will then form-encode it natively (application/x-www-form-urlencoded,
+# or multipart if a value looks file-shaped), so an identity serializer (`->(body) { body }`) is
+# a valid way to opt into that instead of JSON.
+#
+module ChimeraHttpClient
+  class Serializer
+    class << self
+      def json
+        proc { |body| body.to_json }
+      end
+    end
+  end
+end

data/lib/chimera_http_client/version.rb

@@ -1,3 +1,3 @@
 module ChimeraHttpClient
-  VERSION = "1.8.0".freeze
+  VERSION = "1.9.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chimera_http_client
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Andreas Finger
@@ -292,6 +292,7 @@ files:
 - lib/chimera_http_client/queue.rb
 - lib/chimera_http_client/request.rb
 - lib/chimera_http_client/response.rb
+- lib/chimera_http_client/serializer.rb
 - lib/chimera_http_client/version.rb
 homepage: https://github.com/mediafinger/chimera_http_client
 licenses: