promoted-ruby-client 0.1.1 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0f6d46482500c45c759f6b2965ae13a76aea2b3b0d18c069e31055fe985146f
-  data.tar.gz: 7527ed13e8306bc4f9b53fd1add1a12c478c261be30b0b0dc50d16e146f88f10
+  metadata.gz: 30ba0e172809a6aa76284b4b88980fa45dea5b2bf28cdda4fbe8e672b7510a83
+  data.tar.gz: e28586ed23f7db16b959bb9819072e502fc7af3805e68938f2bbf421fdc9e4d8
 SHA512:
-  metadata.gz: fa5105d3d057f9e949dca0fa46a47c5d701e8dabec37f1d64619969827a580994245a6a83b5fbce399be06201f29d8758c2829e1d76b066bee8a4e8ea62fc892
-  data.tar.gz: c6d29aeb9721ad09de063c21afd529495ff8c7eb3422886010124e85fc654fe711efeeb35d5b1a873f4f0ca4d56c064a119069f698f080a203daf797309ad8a9
+  metadata.gz: 4e6b42f73ff30726aa81af1c08b97a0cd0e0307685dec1f90dcce5d0d61d4009c3a2e6179af77a600038531101db187a83dc52f46a7c0ad4a99f7c6c2530b43e
+  data.tar.gz: f3d304f0a2aad7acc15229750f97b021da4c0bfe8deae40c6ac1110bc7c1621ab0db19635464ba835e4e9a9ec07b9cfa0c231a9163fa0e1dcffeeebfdc1e51fc

data/Gemfile

@@ -9,7 +9,6 @@ gem 'faraday', '~> 1.4.1'
 gem 'faraday_middleware'
 gem 'faraday-net_http'
 gem 'concurrent-ruby', require: 'concurrent'
-gem 'byebug'
 
 group :development do
     gem 'ruby-debug-ide', group: :development

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    promoted-ruby-client (0.1.1)
+    promoted-ruby-client (0.1.6)
 
 GEM
   remote: https://rubygems.org/
@@ -9,7 +9,6 @@ GEM
     ast (2.4.2)
     backport (1.2.0)
     benchmark (0.1.1)
-    byebug (11.1.3)
     concurrent-ruby (1.1.9)
     debase (0.2.5.beta2)
       debase-ruby_core_source (>= 0.10.12)
@@ -111,7 +110,6 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.17)
-  byebug
   concurrent-ruby
   debase (>= 0.2.5.beta2)
   faraday (~> 1.4.1)
@@ -126,4 +124,4 @@ DEPENDENCIES
   solargraph
 
 BUNDLED WITH
-   1.17.2
+   1.17.3

data/README.md

@@ -2,51 +2,166 @@
 
 Ruby client designed for calling Promoted's Delivery and Metrics API.
 
-This version of the library only supports preparing objects for logging.  TODO - support Delivery API.
+More information at [http://www.promoted.ai](http://www.promoted.ai)
 
-## Expected pseudo-code flow for Metrics logging
+## Installation
+```gem 'promoted-ruby-client'```
 
-This example is for the integration where we do not want to modify the list of items to include `insertionId`.  TODO - add this example too.
+## Local Development
+1. Clone or fork the repo on your local machine
+2. `cd promoted-ruby-client`
+3. `bundle`
+4. To test interactively: `irb -Ilib -rpromoted/ruby/client`
 
+## Dependencies
+
+### [Faraday](https://github.com/lostisland/faraday)
+HTTP client for calling Promoted.
+### [Concurrent Ruby](https://github.com/ruby-concurrency/concurrent-ruby)
+Provides a thread pool for making shadow traffic requests to Delivery API in the background on a subset of calls to ```prepare_for_logging```
+## Creating a Client
+```rb
+client = Promoted::Ruby::Client::PromotedClient.new
 ```
-def get_items args
-  items = retrieve_items((args))
-  async_log_request(items)
-  return items
-end
 
-# Done async
-def log_request items
-  client = Promoted::Ruby::Client::PromotedClient.new
-  log_request = client.prepare_for_logging(input)
-  # Send JSON to Metrics API.
-  log_to_promoted_event_api(log_request)
-end
+This client will suffice for building log requests. To send actually send traffing to the API, some configuration is required.
+
+```rb
+client = Promoted::Ruby::Client::PromotedClient.new({
+  :metrics_endpoint = "https://<get this from Promoted>",
+  :delivery_endpoint = "https://<get this from Promoted>",
+  :metrics_api_key = "<get this from Promoted>",
+  :delivery_api_key = "<get this from Promoted>"
+})
 ```
 
-## Naming details
+### Client Configuration Parameters
+Name | Type | Description
+---- | ---- | -----------
+```:delivery_endpoint``` | String | POST URL for the Promoted Delivery API (get this from Promoted)
+```:metrics_endpoint``` | String | POST URL for the Promoted Metrics API (get this from Promoted)
+```:metrics_api_key``` | String | Used as the ```x-api-key``` header on Metrics API requests to Promoted (get this value from Promoted)
+```:delivery_api_key``` | String | Used as the ```x-api-key``` header on Delivery API requests to Promoted (get this value from Promoted)
+```:delivery_timeout_millis``` | Number | Timeout on the Delivery API call. Defaults to 3000.
+```:metrics_timeout_millis``` | Number | Timeout on the Metrics API call. Defaults to 3000.
+```:perform_checks``` | Boolean | Whether or not to perform detailed input validation, defaults to true but may be disabled for performance
+```:logger``` | Ruby Logger-compatible logger | Defaults to nil (no logging). Example: ```Logger.new(STDERR, :progname => 'promotedai')```
+```:shadow_traffic_delivery_percent``` | Number between 0 and 1 | % of ```prepare_for_logging``` traffic that gets directed to Delivery API as "shadow traffic". Defaults to 0 (no shadow traffic).
+```:default_request_headers``` | Hash | Additional headers to send on the request beyond ```x-api-key```. Defaults to {}
+```:default_only_log``` | Boolean | If true, the ```deliver``` method will not direct traffic to Delivery API but rather return a request suitable for logging. Defaults to false.
+```:should_apply_treatment_func``` | Proc | Called during delivery, accepts an experiment and returns a Boolean indicating whether the request should be considered part of the control group (false) or in the experiment (true). If nil, the default behavior of checking the experiement ```:arm``` is applied.
 
-`full_insertion` - for `prepare_for_logging`, this is the current page of `Insertion`s with full `Insertion.properties` filled with the item details.  For v1 integrations, it is fine to not fill in the full properties.
+## Data Types
 
-## Pagination
+### UserInfo
+Basic information about the request user.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:user_id``` | String | Yes | The platform user id, cleared from Promoted logs.
+```:log_user_id``` | String | Yes | A different user id (presumably a UUID) disconnected from the platform user id, good for working with unauthenticated users or implementing right-to-be-forgotten.
 
-The `prepare_for_logging` call assumes the client has already handled pagination.  It needs a `Request.paging.offset` to be passed in for the number of items deep that the page is.
+---
+### CohortMembership
+Useful fields for experimentation during the delivery phase.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:user_info``` | UserInfo | Yes | The user info structure.
+```:arm``` | String | Yes | 'CONTROL' or one of the TREATMENT values (see [constants.rb](https://github.com/promotedai/promoted-ruby-client/blob/main/lib/promoted/ruby/client/constants.rb)).
+---
+### Properties
+Properties bag. Has the structure:
 
-## Example to run the client
+```rb
+  :struct => {
+    :product => {
+      "id": "product3",
+      "title": "Product 3",
+      "url": "www.mymarket.com/p/3"
+      # other key-value pairs...
+    }
+  }
+```
+---
+### Insertion
+Content being served at a certain position.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:user_info``` | UserInfo | Yes | The user info structure.
+```:insertion_id``` | String | Yes | Generated by the SDK (*do not set*)
+```:request_id``` | String | Yes | Generated by the SDK (*do not set*)
+```:content_id``` | String | No | Identifier for the content to be shown, must be set.
+```:properties``` | Properties | Yes | Any additional custom properties to associate. For v1 integrations, it is fine not to fill in all the properties.
 
-Install our Ruby client.
-`promoted-ruby-client (0.1.1)`
+---
+### Paging
+#### TODO
+---
+### Request
+A request for content insertions.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:user_info``` | UserInfo | Yes | The user info structure.
+```:request_id``` | String | Yes | Generated by the SDK (*do not set*)
+```:use_case``` | String | Yes | One of the use case values, i.e. 'FEED' (see [constants.rb](https://github.com/promotedai/promoted-ruby-client/blob/main/lib/promoted/ruby/client/constants.rb)).
+```:properties``` | Properties | Yes | Any additional custom properties to associate.
+```:paging``` | Paging | Yes | Paging parameters (see TODO)
+---
+### MetricsRequest
+Input to ```prepare_for_logging```
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:request``` | Request | No | The underlying request for content.
+```:full_insertion``` | [] of Insertion | No | The proposed list of insertions.
+---
 
-Or
+### DeliveryRequest
+Input to ```deliver```
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:experiment``` | CohortMembership | Yes | A cohort to evaluation in experimentation.
+```:request``` | Request | No | The underlying request for content.
+```:full_insertion``` | [] of Insertion | No | The proposed list of insertions with all metadata, will be compacted before forwarding to Promoted.
+```:only_log``` | Boolean | Yes | Defaults to false. Set to true to override whether Delivery API is called for this request.
+---
 
-1. Clone the repo on your local machine
-2. `cd promoted-ruby-client`
-3. `bundle`
-4. `irb -Ilib -rpromoted/ruby/client`
+### LogRequest
 
-A console will launch with the library loaded.  Here is example code to use.
+Output of ```prepare_for_logging``` as well as an ouput of an SDK call to ```deliver```, input to ```send_log_request``` to log to Promoted
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:request``` | Request | No | The underlying request for content to log.
+```:insertion``` | [] of Insertion | No | The insertions, which are either the original request insertions or the insertions resulting from a call to ```deliver``` if such call occurred.
+---
+
+### ClientResponse
+Output of ```deliver```, includes the insertions as well as a suitable ```LogRequest``` for forwarding to Metrics API.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:insertion``` | [] of Insertion | No | The insertions, which are from Delivery API (when ```deliver``` was called, i.e. we weren't either only-log or part of an experiment) or the input insertions (when the other conditions don't hold).
+```:log_request``` | LogRequest | Yes | A message suitable for logging to Metrics API via ```send_log_request```. If the call to ```deliver``` was made (i.e. the request was not part of the CONTROL arm of an experiment or marked to only log), ```:log_request``` will not be set, as you can assume logging was performed on the server-side by Promoted.
+---
+
+### PromotedClient
+Method | Input | Output | Description
+------ | ----- | ------ | -----------
+```prepare_for_logging``` | MetricsRequest | LogRequest | Builds a request suitable for logging locally and/or to Promoted, either via a subsequent call to ```send_log_request``` in the SDK client or by using this structure to make the call yourself. Optionally, based on client configuration may send a random subset of requests to Delivery API as shadow traffic for integration purposes.
+```send_log_request``` | LogRequest | n/a | Forwards a LogRequest to Promoted using an HTTP client.
+```deliver``` | DeliveryRequest | ClientResponse | Makes a request (subject to experimentation) to Delivery API for insertions, which are then returned along with a LogRequest.
+```close``` | n/a | n/a | Closes down the client at shutdown, currently this is just to drain the thread pool that handles shadow traffic.
+---
+
+## Metrics API
+### Pagination
+
+The `prepare_for_logging` call assumes the client has already handled pagination.  It needs a `Request.paging.offset` to be passed in for the number of items deep that the page is.
+TODO: Needs more details.
+
+### Expected flow for Metrics logging
+
+```rb
+# Retrieve a list of content (i.e. products)
+# products = fetch_my_marketplace_products()
 
-```
 products = [
   {
     id: "123",
@@ -68,169 +183,91 @@ products = [
   }
 ]
 
-# Converts the Products to a list of Insertions.
-def to_insertions products
-  @to_insertions = []
-  products.each_with_index do |product, index|
-    @to_insertions << {
-      content_id: product[:id],
-      properties: {
-        struct: {
-          product: product.reject { |k, v| [:id].include? k }
-        }
+# Transform them into an [] of Insertions.
+insertions = products.map { |product| 
+  {
+    :content_id => product[:id],
+    :properties => {
+      :struct => {
+        :type => product[:type],
+        :name => product[:name]
+        # etc
       }
     }
-  end
-  @to_insertions
-end
+  }
+}
 
-request_input = {
-  request: {
-    user_info: { user_id: "912", log_user_id: "912191"},
-    use_case: "FEED",
-    paging: {
-      offset: 10,
-      size: 5
+# Form a MetricsRequest
+metrics_request = {
+  :request => {
+    :user_info => { :user_id => "912", :log_user_id => "912191"},
+    :use_case => "FEED",
+    :paging => {
+      :offset => 0,
+      :size => 5
     },
-    properties: {
-      struct: {
-        active: true
+    :properties => {
+      :struct => {
+        :active => true
       }
     }
   },
-  full_insertion: to_insertions(products)
+  :full_insertion => insertions
 }
 
-client = Promoted::Ruby::Client::PromotedClient.new
-log_request = client.prepare_for_logging(request_input)
-log_request.to_json
-```
-
-## Pass a custom function for compact insertion
-```
-# define a function using proc and it should use one argument.
-# Example
+# OPTIONAL: You can pass a custom function to "compact" insertions before metrics logging.
+# Note that the PromotedClient has a class method helper, copy_and_remove_properties, that does just this.
 to_compact_metrics_insertion_func = Proc.new do |insertion|
   insertion.delete(:properties)
   insertion
 end
+# metrics_request[:to_compact_metrics_insertion_func] = to_compact_metrics_insertion
 
-request_input = {
-  to_compact_metrics_insertion_func: to_compact_metrics_insertion_func,
-  request: {
-    user_info: { user_id: "912", log_user_id: "912191"},
-    use_case: "FEED",
-    paging: {
-      from: 10,
-      size: 5
-    },
-    properties: {
-      struct: {
-        active: true
-      }
-    }
-  },
-  full_insertion: to_insertions(products)
-}
-
+# Create a client
 client = Promoted::Ruby::Client::PromotedClient.new
-log_request = client.prepare_for_logging(request_input)
-log_request.to_json
-```
 
-`log_request.to_json` returns a result that looks like the following
-```
-=> "{\"user_info\":{\"user_id\":\"912\",\"log_user_id\":\"912191\"},\"timing\":{\"client_log_timestamp\":1623306198},\"request\":[{\"user_info\":{\"user_id\":\"912\",\"log_user_id\":\"912191\"},\"use_case\":\"FEED\",\"paging\":{\"offset\":10,\"size\":10},\"properties\":{\"struct\":{\"active\":true}}}],\"insertion\":[{\"content_id\":\"123\",\"properties\":{\"struct\":{\"product\":{\"type\":\"SHOE\",\"name\":\"Blue shoe\",\"total_sales\":1000}}},\"user_info\":{\"user_id\":\"912\",\"log_user_id\":\"912191\"},\"timing\":{\"client_log_timestamp\":1623306198},\"insertion_id\":\"a87e1b57-a574-424f-8af6-10e0250aa7ab\",\"request_id\":\"54ff4884-2192-4180-8c72-a805a436980f\",\"position\":10},{\"content_id\":\"124\",\"properties\":{\"struct\":{\"product\":{\"type\":\"SHIRT\",\"name\":\"Green shirt\",\"total_sales\":800}}},\"user_info\":{\"user_id\":\"912\",\"log_user_id\":\"912191\"},\"timing\":{\"client_log_timestamp\":1623306198},\"insertion_id\":\"4495f72a-8101-4cb8-94ce-4db76839b8b6\",\"request_id\":\"54ff4884-2192-4180-8c72-a805a436980f\",\"position\":11},{\"content_id\":\"125\",\"properties\":{\"struct\":{\"product\":{\"type\":\"DRESS\",\"name\":\"Red dress\",\"total_sales\":1200}}},\"user_info\":{\"user_id\":\"912\",\"log_user_id\":\"912191\"},\"timing\":{\"client_log_timestamp\":1623306198},\"insertion_id\":\"d1e4f3f6-1783-4059-8fab-fdf2ba343cdf\",\"request_id\":\"54ff4884-2192-4180-8c72-a805a436980f\",\"position\":12}]}"
+# Build a log request
+log_request = client.prepare_for_logging(metrics_request)
+
+# Log (assuming you have configured your client with a :metrics_endpoint)
+client.send_log_request(log_request)
 ```
 
-## Other input syntaxes
+## Delivery API
 
-The client should also work if Hash rocket too.
-```
-products = [
-  {
-    "id"=>"123",
-    "type"=>"SHOE",
-    "name"=>"Blue shoe",
-    "totalSales"=>1000
-  },
-  {
-    "id"=>"124",
-    "type"=>"SHIRT",
-    "name"=>"Green shirt",
-    "totalSales"=>800
-  },
-  {
-    "id"=>"125",
-    "type"=>"DRESS",
-    "name"=>"Red dress",
-    "totalSales"=>1200
-  }
-]
+### Expected flow for Delivery
+
+```rb
+# (continuing from the above example for Metrics)
 
-input = {
-  "request"=>{
-    "user_info"=>{"user_id"=> "912", "log_user_id"=> "912191"},
-    "use_case"=>"FEED",
-    "properties"=>{
-      "struct"=>{
-        "active"=>true
+# Form a DeliveryRequest
+delivery_request = {
+  :request => {
+    :user_info => { :user_id => "912", :log_user_id => "912191"},
+    :use_case => "FEED",
+    :paging => {
+      :offset => 0,
+      :size => 5
+    },
+    :properties => {
+      :struct => {
+        :active => true
       }
     }
   },
-  "full_insertion"=>to_insertions(products)
+  :full_insertion => insertions,
+  :only_log => false
 }
-```
 
-Or inlined full request.
+# Request insertions from Delivery API
+client_response = client.deliver(delivery_request)
+
+# Use the resulting insertions
+client_response[:insertion]
+
+# Log if a log request was provided (if not, deliver was called successfully
+# and Promoted logged on the server-side).)
+client.send_log_request(client_response[:log_request]) if client_response[:log_request]
 ```
-input = {
-  "request"=>{
-    "user_info"=>{"user_id"=> "912", "log_user_id"=> "912191"},
-    "use_case"=>"FEED",
-    "properties"=>{
-      "struct"=>{
-        "active"=>true
-      }
-    }
-  },
-  "full_insertion"=>[
-    {
-      "contentId"=>"123",
-      "properties"=>{
-        "struct"=>{
-          "product"=>{
-            "type"=>"SHOE",
-            "name"=>"Blue shoe",
-            "totalSales"=>1000
-          }
-        }
-      }
-    },
-    {
-      "contentId"=>"124",
-      "properties"=>{
-        "struct"=>{
-          "product"=>{
-            "type"=>"SHIRT",
-            "name"=>"Green shirt",
-            "totalSales"=>800
-          }
-        }
-      }
-    },
-    {
-      "contentId"=>"125",
-      "properties"=>{
-        "struct"=>{
-          "product"=>{
-            "type"=>"DRESS",
-            "name"=>"Red dress",
-            "totalSales"=>1200
-          }
-        }
-      }
-    }
-  ]
-}
-```
+
+### TODO Experimentation example

data/dev.md

@@ -1,9 +1,8 @@
-
-## Deploy
+# Deploy
 
 1. Update version number.
 2. Get credentials for deployment from 1password.
 3. Modify `promoted-ruby-client.gemspec`'s push block.
 4. Run `gem build promoted-ruby-client.gemspec` to generate `gem`.
-5. Run (using new output) `gem push promoted-ruby-client-0.1.1.gem`
+5. Run (using new output) `gem push promoted-ruby-client-0.1.6.gem`
 6. Update README with new version.

data/lib/promoted/ruby/client.rb

@@ -6,26 +6,44 @@ module Promoted
   module Ruby
     module Client
 
-      DEFAULT_DELIVERY_TIMEOUT_MILLIS = 3000
+      DEFAULT_DELIVERY_TIMEOUT_MILLIS = 250
       DEFAULT_METRICS_TIMEOUT_MILLIS = 3000
       DEFAULT_DELIVERY_ENDPOINT = "http://delivery.example.com"
       DEFAULT_METRICS_ENDPOINT = "http://metrics.example.com"
 
+      ##
+      # Client for working with Promoted's Metrics and Delivery APIs.
+      # See {Github}[https://github.com/promotedai/promoted-ruby-client] for more info.
       class PromotedClient
   
         class Error < StandardError; end
 
         attr_reader :perform_checks, :default_only_log, :delivery_timeout_millis, :metrics_timeout_millis, :should_apply_treatment_func,
-                    :default_request_headers
+                    :default_request_headers, :http_client
         
+        ##            
+        # A common compact method implementation.
+        def self.copy_and_remove_properties
+          Proc.new do |insertion|
+            insertion = Hash[insertion]
+            insertion.delete(:properties)
+            insertion
+          end
+        end
+
+        ##
+        # Create and configure a new Promoted client.
         def initialize (params={})
           @perform_checks = true
           if params[:perform_checks] != nil
             @perform_checks = params[:perform_checks]
           end
 
+          @logger = params[:logger] # Example:  Logger.new(STDERR, :progname => "promotedai")
+
           @default_request_headers = params[:default_request_headers] || {}
-          @default_request_headers['x-api-key'] = params[:api_key] || ''
+          @metrics_api_key = params[:metrics_api_key] || ''
+          @delivery_api_key = params[:delivery_api_key] || ''
 
           @default_only_log        = params[:default_only_log] || false
           @should_apply_treatment_func  = params[:should_apply_treatment_func]
@@ -46,35 +64,34 @@ module Promoted
           @metrics_timeout_millis  = params[:metrics_timeout_millis] || DEFAULT_METRICS_TIMEOUT_MILLIS
 
           @http_client = FaradayHTTPClient.new
-          @pool = Concurrent::CachedThreadPool.new
+          @validator = Promoted::Ruby::Client::Validator.new
+
+          # Thread pool to process delivery of shadow traffic. Will silently drop excess requests beyond the queue
+          # size, and silently eat errors on the background threads.
+          @pool = Concurrent::ThreadPoolExecutor.new(
+            min_threads: 0,
+            max_threads: 10,
+            max_queue: 100,
+            fallback_policy: :discard
+          )
         end
         
+        ##
+        # Politely shut down a Promoted client.
         def close
           @pool.shutdown
           @pool.wait_for_termination
         end
 
-        def send_request payload, endpoint, timeout_millis, headers=[], send_async=false
-          use_headers = @default_request_headers.merge headers
-          
-          if send_async
-            @pool.post do
-              @http_client.send(endpoint, timeout_millis, payload, use_headers)
-            end
-          else
-            @http_client.send(endpoint, timeout_millis, payload, use_headers)
-          end
-        end
-
+        ##
+        # Make a delivery request.
         def deliver args, headers={}
           args = Promoted::Ruby::Client::Util.translate_args(args)
 
           delivery_request_builder = RequestBuilder.new
           delivery_request_builder.set_request_params(args)
 
-          if perform_checks?
-            Promoted::Ruby::Client::Settings.check_that_log_ids_not_set!(args)
-          end
+          perform_common_checks!(args) if @perform_checks
 
           pre_delivery_fillin_fields delivery_request_builder
   
@@ -83,22 +100,31 @@ module Promoted
           insertions_from_promoted = false
 
           only_log = delivery_request_builder.only_log != nil ? delivery_request_builder.only_log : @default_only_log
+          deliver_err = false
           if !only_log
             cohort_membership_to_log = delivery_request_builder.new_cohort_membership_to_log
-          end
+
+            if should_apply_treatment(cohort_membership_to_log)
+              delivery_request_params = delivery_request_builder.delivery_request_params
   
-          if should_apply_treatment(cohort_membership_to_log)
-            delivery_request_params = delivery_request_builder.delivery_request_params
-
-            # Call Delivery API
-            response = send_request(delivery_request_params, @delivery_endpoint, @delivery_timeout_millis, headers)
-            
-            response_insertions = delivery_request_builder.fill_details_from_response(response[:insertion])
-            insertions_from_promoted = true;
+              # Call Delivery API
+              begin
+                response = send_request(delivery_request_params, @delivery_endpoint, @delivery_timeout_millis, @delivery_api_key, headers)
+              rescue  StandardError => err
+                # Currently we don't propagate errors to the SDK caller, but rather default to returning
+                # the request insertions.
+                deliver_err = true
+                @logger.error("Error calling delivery: " + err.message) if @logger
+              end
+              
+              insertions_from_promoted = (response != nil && !deliver_err);
+              response_insertions = delivery_request_builder.fill_details_from_response(
+                response ? response[:insertion] : [])
+            end
           end
   
           request_to_log = nil
-          if !insertions_from_promoted
+          if !insertions_from_promoted then
             request_to_log = delivery_request_builder.request
             size = delivery_request_builder.request.dig(:paging, :size)
             response_insertions = size != nil ? delivery_request_builder.full_insertion[0..size] : delivery_request_builder.full_insertion
@@ -141,21 +167,73 @@ module Promoted
           return client_response
         end
 
-        def add_missing_ids_on_insertions! request, insertions
-          insertions.each do |insertion|
-            insertion[:insertion_id] = SecureRandom.uuid if not insertion[:insertion_id]
-            insertion[:session_id] = request[:session_id] if request[:session_id]
-            insertion[:request_id] = request[:request_id] if request[:request_id]
+        ##
+        # Generate a log request for a subsequent call to send_log_request
+        # or for logging via alternative means.
+        def prepare_for_logging args, headers={}
+          args = Promoted::Ruby::Client::Util.translate_args(args)
+
+          log_request_builder = RequestBuilder.new
+
+          # Note: This method expects as JSON (string keys) but internally, RequestBuilder
+          # transforms and works with symbol keys.
+          log_request_builder.set_request_params(args)
+          shadow_traffic_err = false
+          if @perform_checks
+            perform_common_checks! args
+
+            if @shadow_traffic_delivery_percent > 0 && args[:insertion_page_type] != Promoted::Ruby::Client::INSERTION_PAGING_TYPE['UNPAGED'] then
+              shadow_traffic_err = true
+              @logger.error(ShadowTrafficInsertionPageType.new) if @logger
+            end
           end
-        end
+          
+          pre_delivery_fillin_fields log_request_builder
 
-        def perform_checks?
-          @perform_checks
+          if !shadow_traffic_err && should_send_as_shadow_traffic?
+            deliver_shadow_traffic args, headers
+          end
+
+          log_request_builder.log_request_params
         end
 
+        ##
         # Sends a log request (previously created by a call to prepare_for_logging) to the metrics endpoint.
         def send_log_request log_request_params, headers={}
-          send_request(log_request_params, @metrics_endpoint, @metrics_timeout_millis, headers)
+          begin
+            send_request(log_request_params, @metrics_endpoint, @metrics_timeout_millis, @metrics_api_key, headers)
+          rescue  StandardError => err
+            # Currently we don't propagate errors to the SDK caller.
+            @logger.error("Error from metrics: " + err.message) if @logger
+          end
+        end
+
+        private
+
+        def send_request payload, endpoint, timeout_millis, api_key, headers={}, send_async=false
+          headers["x-api-key"] = api_key
+          use_headers = @default_request_headers.merge headers
+          
+          if send_async
+            @pool.post do
+              @http_client.send(endpoint, timeout_millis, payload, use_headers)
+            end
+          else
+            begin
+              @http_client.send(endpoint, timeout_millis, payload, use_headers)
+            rescue Faraday::Error => err
+              raise EndpointError.new(err)
+            end
+          end
+        end
+
+
+        def add_missing_ids_on_insertions! request, insertions
+          insertions.each do |insertion|
+            insertion[:insertion_id] = SecureRandom.uuid if not insertion[:insertion_id]
+            insertion[:session_id] = request[:session_id] if request[:session_id]
+            insertion[:request_id] = request[:request_id] if request[:request_id]
+          end
         end
 
         def should_send_as_shadow_traffic?
@@ -173,37 +251,22 @@ module Promoted
           delivery_request_params[:client_info][:traffic_type] = Promoted::Ruby::Client::TRAFFIC_TYPE['SHADOW']
 
           # Call Delivery API async (fire and forget)
-          send_request(delivery_request_params, @delivery_endpoint, @delivery_timeout_millis, headers, true)
+          send_request(delivery_request_params, @delivery_endpoint, @delivery_timeout_millis, @delivery_api_key, headers, true)
         end
 
-        def prepare_for_logging args, headers={}
-          args = Promoted::Ruby::Client::Util.translate_args(args)
-
-          log_request_builder = RequestBuilder.new
-
-          # Note: This method expects as JSON (string keys) but internally, RequestBuilder
-          # transforms and works with symbol keys.
-          log_request_builder.set_request_params(args)
-          if perform_checks?
-            Promoted::Ruby::Client::Settings.check_that_log_ids_not_set!(args)
-
-            if @shadow_traffic_delivery_percent > 0 && args[:insertion_page_type] != Promoted::Ruby::Client::INSERTION_PAGING_TYPE['UNPAGED'] then
-              raise ShadowTrafficInsertionPageType
-            end
-          end
-          
-          pre_delivery_fillin_fields log_request_builder
-
-          if should_send_as_shadow_traffic?
-            deliver_shadow_traffic args, headers
+        def perform_common_checks!(req)
+          begin
+            @validator.check_that_log_ids_not_set!(req)
+            @validator.validate_metrics_request!(req)
+          rescue StandardError => err
+            @logger.error(err) if @logger
+            raise
           end
-
-          log_request_builder.log_request_params
         end
 
         def should_apply_treatment(cohort_membership)
           if @should_apply_treatment_func != nil
-            @should_apply_treatment_func
+            @should_apply_treatment_func.call(cohort_membership)
           else
             return true if !cohort_membership
             return true if !cohort_membership[:arm]
@@ -217,15 +280,6 @@ module Promoted
             log_request_builder.timing[:client_log_timestamp] = Time.now.to_i
           end
         end
-
-        # A common compact method implementation.
-        def self.copy_and_remove_properties
-          Proc.new do |insertion|
-            insertion = Hash[insertion]
-            insertion.delete(:properties)
-            insertion
-          end
-        end
       end
     end
   end
@@ -234,7 +288,6 @@ end
 # dependent /libs
 require "promoted/ruby/client/request_builder"
 require "promoted/ruby/client/sampler"
-require "promoted/ruby/client/settings"
 require "promoted/ruby/client/util"
-require 'byebug'
+require "promoted/ruby/client/validator"
 require 'securerandom'

data/lib/promoted/ruby/client/errors.rb

@@ -1,40 +1,21 @@
 module Promoted
   module Ruby
     module Client
-      class RequestError < StandardError
-        def message
-          'Request.requestId should not be set'
-        end
-      end
-
-      class RequestInsertionError < StandardError
-        def message
-          'Do not set Request.insertion.  Set full_insertion.'
-        end
-      end
-
-      class InsertionRequestIdError < StandardError
-        def message
-          'Insertion.requestId should not be set'
-        end
-      end
-
-      class InsertionIdError < StandardError
+      class ShadowTrafficInsertionPageType < StandardError
         def message
-          'Insertion.insertionId should not be set'
+          'Insertions must be unpaged when shadow traffic is on'
         end
       end
 
-      class InsertionContentId < StandardError
-        def message
-          'Insertion.contentId should be set'
+      class EndpointError < StandardError
+        attr_reader :cause
+        def initialize(cause)
+          @cause = cause
+          super('Error calling Promoted.ai endpoint')
         end
       end
 
-      class ShadowTrafficInsertionPageType < StandardError
-        def message
-          'Insertions must be unpaged when shadow traffic is on'
-        end
+      class ValidationError < StandardError
       end
     end
   end

data/lib/promoted/ruby/client/faraday_http_client.rb

@@ -10,6 +10,7 @@ module Promoted
                 @conn = Faraday.new do |f|
                     f.request :json
                     f.request :retry, max: 3
+                    f.use Faraday::Response::RaiseError # raises on 4xx and 5xx responses
                     f.adapter :net_http
                 end
             end
@@ -18,12 +19,16 @@ module Promoted
                 response = @conn.post(endpoint) do |req|
                     req.headers                 = req.headers.merge(additional_headers) if additional_headers
                     req.headers['Content-Type'] = req.headers['Content-Type'] || 'application/json'
-                    req.options.timeout         = timeout_millis / 1000
+                    req.options.timeout         = timeout_millis.to_f / 1000
                     req.body                    = request.to_json
                   end
         
-                  # TODO: Check response code, rescue on ParserError, etc.
-                  JSON.parse(response.body, :symbolize_names => true)
+                  norm_headers = response.headers.transform_keys(&:downcase)
+                  if norm_headers["content-type"] != nil && norm_headers["content-type"].start_with?("application/json")
+                    JSON.parse(response.body, :symbolize_names => true)
+                  else
+                    response.body
+                  end
             end
         end
       end

data/lib/promoted/ruby/client/request_builder.rb

@@ -14,6 +14,7 @@ module Promoted
         def set_request_params args = {}
           @request                 = args[:request] || {}
           @experiment              = args[:experiment]
+          @only_log                = args[:only_log]
           @session_id              = request[:session_id]
           @platform_id             = request[:platform_id]
           @client_info             = request[:client_info] || {}
@@ -23,7 +24,6 @@ module Promoted
           @request_id              = SecureRandom.uuid
           @user_info               = request[:user_info] || { :user_id => nil, :log_user_id => nil}
           @timing                  = request[:timing] || { :client_log_timestamp => Time.now.to_i }
-          @only_log                = request[:only_log]
           @to_compact_metrics_insertion_func       = args[:to_compact_metrics_insertion_func]
           @to_compact_delivery_insertion_func      = args[:to_compact_delivery_insertion_func]
         end
@@ -48,10 +48,16 @@ module Promoted
           params = {
             user_info: user_info,
             timing: timing,
-            cohort_membership: @experiment,
-            client_info: @client_info.merge({ :client_type => Promoted::Ruby::Client::CLIENT_TYPE['PLATFORM_SERVER'] })
+            client_info: @client_info.merge({ :client_type => Promoted::Ruby::Client::CLIENT_TYPE['PLATFORM_SERVER'] }),
+            platform_id: @platform_id,
+            request_id: @request_id,
+            view_id: @view_id,
+            session_id: @session_id,
+            use_case: @use_case,
+            search_query: request[:search_query],
+            properties: request[:properties],
+            paging: request[:paging]
           }
-          params[:request] = request
           params[:insertion] = should_compact ? compact_delivery_insertions : full_insertion
 
           params.clean!
@@ -61,6 +67,10 @@ module Promoted
         # Maps the response insertions to the full insertions and re-insert the properties bag
         # to the responses.
         def fill_details_from_response response_insertions
+          if !response_insertions then
+            response_insertions = full_insertion
+          end
+
           props = @full_insertion.each_with_object({}) do |insertion, hash|
             hash[insertion[:content_id]] = insertion[:properties]
           end
@@ -77,35 +87,6 @@ module Promoted
           filled_in_copy
         end
 
-        def validate_request_params
-          # TODO
-        end
-
-        def to_compact_metrics_insertion_func
-          @to_compact_metrics_insertion_func
-        end
-
-        def to_compact_delivery_insertion_func
-          @to_compact_delivery_insertion_func
-        end
-
-        # A list of the response Insertions.  This client expects lists to be truncated
-        # already to request.paging.size.  If not truncated, this client will truncate
-        # the list.
-        def insertion
-          @insertion
-        end
-
-        # A way to turn off logging.  Defaults to true.
-        def enabled?
-          @enabled
-        end
-
-        # Default values to use on DeliveryRequests.
-        def default_request_values
-          @default_request_values
-        end
-
         def log_request_params(include_insertions: true, include_request: true)
           params = {
             user_info: user_info,
@@ -154,6 +135,14 @@ module Promoted
           @insertion
         end
 
+        private
+
+        # A list of the response Insertions.  This client expects lists to be truncated
+        # already to request.paging.size.  If not truncated, this client will truncate
+        # the list.
+        def insertion
+          @insertion
+        end
       end
     end
   end

data/lib/promoted/ruby/client/validator.rb

@@ -0,0 +1,159 @@
+module Promoted
+    module Ruby
+      module Client
+        class Validator
+            def validate_user_info!(ui)
+                validate_fields!(
+                    ui,
+                    "user info",
+                    [
+                        {
+                            :name => :user_id,
+                            :type => String
+                        },
+                        {
+                            :name => :log_user_id,
+                            :type => String
+                        }
+                    ]
+                )
+            end
+
+            def validate_insertion!(ins)
+                validate_fields!(
+                    ins,
+                    "insertion",
+                    [
+                        {
+                            :name => :platform_id,
+                            :type => Integer
+                        },
+                        {
+                            :name => :insertion_id,
+                            :type => String
+                        },
+                        {
+                            :name => :request_id,
+                            :type => String
+                        },
+                        {
+                            :name => :view_id,
+                            :type => String
+                        },
+                        {
+                            :name => :session_id,
+                            :type => String
+                        },
+                        {
+                            :name => :content_id,
+                            :type => String
+                        },
+                        {
+                            :name => :position,
+                            :type => Integer
+                        },
+                        {
+                            :name => :delivery_score,
+                            :type => Integer
+                        }
+                    ]
+                )
+
+                if ins[:user_info] then
+                    self.validate_user_info! ins[:user_info]
+                end
+            end
+
+            def validate_request!(req)
+                validate_fields!(
+                    req,
+                    "request",
+                    [
+                        {
+                            :name => :platform_id,
+                            :type => Integer
+                        },
+                        {
+                            :name => :request_id,
+                            :type => String
+                        },
+                        {
+                            :name => :view_id,
+                            :type => String
+                        },
+                        {
+                            :name => :session_id,
+                            :type => String
+                        },
+                        {
+                            :name => :insertion,
+                            :type => Array
+                        }
+                    ]
+                )
+
+                if req[:insertion] then
+                    req[:insertion].each {|ins|
+                        validate_insertion! ins
+                    }
+                end
+
+                if req[:user_info] then
+                    validate_user_info! req[:user_info]
+                end
+            end
+
+            def validate_metrics_request!(metrics_req)
+                validate_fields!(
+                    metrics_req,
+                    "metrics request",
+                    [
+                        {
+                            :name => :request,
+                            :required => true
+                        },
+                        {
+                            :name => :full_insertion,
+                            :required => true,
+                            :type => Array
+                        }
+                    ]
+                )
+
+                validate_request!(metrics_req[:request])
+                metrics_req[:full_insertion].each {|ins|
+                    validate_insertion! ins
+                }
+            end
+
+            def check_that_log_ids_not_set! req
+                raise ValidationError.new("Request.requestId should not be set") if req.dig(:request, :request_id)
+                raise ValidationError.new("Do not set Request.insertion.  Set full_insertion.") if req[:insertion]
+      
+                req[:full_insertion].each do |insertion_hash|
+                  raise ValidationError.new("Insertion.requestId should not be set") if insertion_hash[:request_id]
+                  raise ValidationError.new("'Insertion.insertionId should not be set") if insertion_hash[:insertion_id]
+                  raise ValidationError.new("Insertion.deliveryScore should not be set") if insertion_hash[:delivery_score]
+                end
+            end
+            
+            private
+
+            def validate_fields!(obj, obj_name, fields)
+                fields.each {|field|
+                    if field[:required] then
+                        raise ValidationError.new(field[:name].to_s + " is required on " + obj_name) if !obj.has_key?(field[:name])
+                    end
+
+                    # If a field is provided as non-nil, it should be of the correct type.
+                    if field[:type] && obj.has_key?(field[:name]) && obj[field[:name]] != nil then
+                        raise ValidationError.new(field[:name].to_s + " should be a " + field[:type].to_s) if !obj[field[:name]].is_a?(field[:type])
+                    end
+                }
+            end
+        end
+      end
+   end
+ end
+  
+require "promoted/ruby/client/errors"

data/lib/promoted/ruby/client/version.rb

@@ -1,7 +1,7 @@
 module Promoted
   module Ruby
     module Client
-      VERSION = "0.1.1"
+      VERSION = "0.1.6"
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: promoted-ruby-client
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.6
 platform: ruby
 authors:
 - scottmcmaster
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-06-25 00:00:00.000000000 Z
+date: 2021-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -77,8 +77,8 @@ files:
 - lib/promoted/ruby/client/faraday_http_client.rb
 - lib/promoted/ruby/client/request_builder.rb
 - lib/promoted/ruby/client/sampler.rb
-- lib/promoted/ruby/client/settings.rb
 - lib/promoted/ruby/client/util.rb
+- lib/promoted/ruby/client/validator.rb
 - lib/promoted/ruby/client/version.rb
 - promoted-ruby-client.gemspec
 homepage: https://github.com/promotedai/promoted-ruby-client

data/lib/promoted/ruby/client/settings.rb

@@ -1,21 +0,0 @@
-module Promoted
-  module Ruby
-    module Client
-      class Settings
-
-        def self.check_that_log_ids_not_set! options_hash
-          raise RequestError if options_hash.dig(:request, :request_id)
-          raise RequestInsertionError if options_hash[:insertion]
-
-          options_hash[:full_insertion].each do |insertion_hash|
-            raise InsertionRequestIdError if insertion_hash[:request_id]
-            raise InsertionIdError if insertion_hash[:insertion_id]
-          end
-          true
-        end
-      end
-    end
-  end
-end
-
-require "promoted/ruby/client/errors"