promoted-ruby-client 3.0.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffd08d1b6e14b721172d2e30680541f1d087d14f7cdfe63dc96b60ada84b5b1a
-  data.tar.gz: d21fa553ef8e746c642605bb2de051d4bdc9901b5837c1db6f1ca11fe358fa98
+  metadata.gz: d2581fc859bd3a30b8460858e6ab95ef4be27724f60ac02cff4e15c4579ea833
+  data.tar.gz: e87f89c047284f62cdd8d1975aae5c464e096f32c752352f5d83820b8e922ea4
 SHA512:
-  metadata.gz: bf16053b5bef1560caf7e9a5eaf01b62dd4484d40069801310d4cc8b7eb0fdce91eb072ee4c8a1146188b5fc74a168b2769623379dfd8df2a9f493d1e214a012
-  data.tar.gz: f814b279bd1585402a381e8269c9c4664964381702fb5fb597845990ace9e56fdb5b8e0d24d8b2d4f3373523f764798092bcb5c324f2ca90d173b4008035993f
+  metadata.gz: 98361d750d5bf3605b4acda0c974be206ae115fa973f8d4e57d723874d2fed40eb86b4f635ce22a502c5faf36e1e6ee12456f95b9d4fc8a5e763a0747393a20e
+  data.tar.gz: ebf6134571b25c908d9dba394286a31564517d0218d3d97975e5965a85d3607c91ff37f191cbb8d1dd2942bd9c47209cbb56315bd7ea3a4e92c92d5313220b36

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    promoted-ruby-client (2.0.2)
+    promoted-ruby-client (4.0.1)
       concurrent-ruby (~> 1)
       faraday (>= 0.9.0)
       faraday_middleware (>= 0.9.0)
@@ -52,13 +52,12 @@ GEM
       rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
-    language_server-protocol (3.17.0.3)
     multipart-post (2.3.0)
     net-http-persistent (4.0.2)
       connection_pool (~> 2.2)
-    nokogiri (1.15.2-arm64-darwin)
+    nokogiri (1.15.4-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.15.2-x86_64-linux)
+    nokogiri (1.15.4-x86_64-linux)
       racc (~> 1.4)
     parallel (1.23.0)
     parser (3.2.2.3)
@@ -85,11 +84,10 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
     rspec-support (3.12.1)
-    rubocop (1.53.1)
+    rubocop (1.50.2)
       json (~> 2.3)
-      language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 3.2.2.3)
+      parser (>= 3.2.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
@@ -142,4 +140,4 @@ DEPENDENCIES
   solargraph
 
 BUNDLED WITH
-   2.4.9
+   2.4.19

data/README.md

@@ -20,7 +20,7 @@ HTTP client for calling Promoted.
 ### [Net::HTTP::Persistent](https://github.com/drbrain/net-http-persistent)
 Faraday binding (provides connection pool support)
 ### [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```
+Provides a thread pool for making shadow traffic requests to Delivery API in the background on a subset of calls to ```deliver```
 ## Creating a Client
 ```rb
 client = Promoted::Ruby::Client::PromotedClient.new
@@ -48,7 +48,7 @@ Name | Type | Description
 ```: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).
+```:shadow_traffic_delivery_percent``` | Number between 0 and 1 | % of ```deliver``` traffic that gets directed to Delivery API as "shadow traffic". Defaults to 0 (no shadow traffic).
 ```:send_shadow_traffic_for_control``` | Boolean | If true, the ```deliver``` method will send shadow traffic for users in the CONTROL arm of an experiment. Defaults to true.
 ```: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.
@@ -169,7 +169,14 @@ Field Name | Type | Optional? | Description
 ```:browser``` | Browser | Yes | Browser information
 ---
 ### Paging
-#### TODO
+Paging parameters.
+
+```DeliveryRequest.retrieval_insertion_offset``` also impacts paging.  That field indicate the offset of the retrieved insertions that are passed into ```Request.insertion```.  See [detailed documentation on paging and ```retrieval_insertion_offset```](https://docs.promoted.ai/docs/ranking-requests#sending-even-more-request-insertions).
+
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:offset``` | Integer | Yes | The 0-based, starting index for the response page.  This should be the global position.
+```:size``` | Integer | Yes | The number of items to return in a response page.
 ---
 ### Request
 A request for content insertions.
@@ -179,7 +186,7 @@ Field Name | Type | Optional? | Description
 ```:request_id``` | String | Yes | Generated by the SDK when needed (*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)
+```:paging``` | Paging | Yes | Paging parameters
 ```:device``` | Device | Yes | Device information (as available)
 ---
 
@@ -190,15 +197,12 @@ Field Name | Type | Optional? | Description
 ```:experiment``` | CohortMembership | Yes | A cohort to evaluation in experimentation.
 ```:request``` | Request | No | The underlying request for content.
 ```:only_log``` | Boolean | Yes | Defaults to false. Set to true to override whether Delivery API is called for this request.
+```:retrieval_insertion_offset``` | Integer | Yes | The index of the retrieved insertions set on ```Request.insertion``` list.  If just sending the top-N from your retrieval, this is ```0```.  If this is the next batch (e.g. ```500``` to ```999```), then the value is ```500```.  This can be used to send multiple groups of retrieved insertions.  This interacts with the ```Paging``` fields.  [More detailed documentation on paging](https://docs.promoted.ai/docs/ranking-requests#sending-even-more-request-insertions).
 ---
 
 ### LogRequest
 
-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.
+A log object that is sent as a RPC request to Promoted's Metrics API log endpoint.  This is outputted from the ```deliver``` SDK call.  Callers need to either input it into the ```send_log_request``` method or send it to the Metrics API directly.  Clients should avoid manipulating this object directly.
 ---
 
 ### ClientResponse
@@ -214,18 +218,12 @@ Field Name | Type | Optional? | Description
 ### 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.
+```deliver``` | DeliveryRequest | ClientResponse | Depending on flags, either (1) makes a request (subject to experimentation) to Delivery API for insertions, which are then returned along with a LogRequest or (2) implements SDK-side paging and prepares log records that can be logged to Promoted using ```send_log_request``` 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.
 ```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

data/dev.md

@@ -10,5 +10,5 @@ bundle exec rspec
 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-3.0.0.gem`
-6. Update README with new version.
+5. Run `bundle exec rspec`.  This updates `Gemfile.lock`.
+6. Run (using new output) `gem push promoted-ruby-client-4.0.1.gem`

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

@@ -14,9 +14,6 @@ module Promoted
                    'SELLER_CONTENT'=> 'SELLER_CONTENT',
                    'DISCOVER'=> 'DISCOVER'}
 
-      INSERTION_PAGING_TYPE = {'UNPAGED' => 'UNPAGED',
-                               'PRE_PAGED' => 'PRE_PAGED'}
-
       COHORT_ARM = {'UNKNOWN_GROUP' => 'UNKNOWN_GROUP',
                     'CONTROL' => 'CONTROL',
                     'TREATMENT' => 'TREATMENT',

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

@@ -1,18 +1,6 @@
 module Promoted
   module Ruby
     module Client
-      class ShadowTrafficInsertionPageType < StandardError
-        def message
-          'Insertions must be unpaged when shadow traffic is on'
-        end
-      end
-
-      class DeliveryInsertionPageType < StandardError
-        def message
-          'Delivery insertions must be unpaged'
-        end
-      end
-
       class EndpointError < StandardError
         attr_reader :cause
         def initialize(cause)

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

@@ -11,20 +11,30 @@ module Promoted
         end
         
         class Pager
-            def validate_paging(insertions, paging)
-              if paging && paging[:offset] && paging[:offset] >= insertions.length
-                raise InvalidPagingError.new("Invalid page offset (insertion size #{insertions.length}, offset #{paging[:offset]})", [])
+            def validate_paging(insertions, retrieval_insertion_offset, paging)
+              if paging && paging[:offset]
+                offset, retrieval_insertion_offset, index = _sanitize_offsets(retrieval_insertion_offset, paging)
+                _validate_paging(insertions, retrieval_insertion_offset, offset, index)
               end
             end
 
-            def apply_paging(insertions, insertion_page_type, paging = nil)
-              begin
-                validate_paging(insertions, paging)
-              rescue InvalidPagingError => err
-                # This is invalid input, stop it before it goes to the server.
-                return err.default_insertions_page
+            def _sanitize_offsets(retrieval_insertion_offset, paging)
+              offset = [0, paging[:offset]].max
+              retrieval_insertion_offset = [0, retrieval_insertion_offset].max
+              index = [0, offset - retrieval_insertion_offset].max
+              return [offset, retrieval_insertion_offset, index]
+            end
+
+            def _validate_paging(insertions, retrieval_insertion_offset, offset, index)
+              if offset < retrieval_insertion_offset
+                raise InvalidPagingError.new("Invalid page offset (retrieval_insertion_offset #{retrieval_insertion_offset}, offset #{offset})", [])
               end
+              if index >= insertions.length
+                raise InvalidPagingError.new("Invalid page offset (insertion size #{insertions.length}, index #{index})", [])
+              end
+            end
 
+            def apply_paging(insertions, retrieval_insertion_offset, paging = nil)
               if !paging
                 paging = {
                   :offset => 0,
@@ -32,14 +42,13 @@ module Promoted
                 }
               end
 
-              offset = [0, paging[:offset]].max
+              offset, retrieval_insertion_offset, index = _sanitize_offsets(retrieval_insertion_offset, paging)
 
-              index = offset
-              if insertion_page_type == Promoted::Ruby::Client::INSERTION_PAGING_TYPE['PRE_PAGED']
-                # When insertions are pre-paged, we don't use offset to
-                # window into the provided insertions, although we do use it when
-                # assigning positions.
-                index = 0
+              begin
+                _validate_paging(insertions, retrieval_insertion_offset, offset, index)
+              rescue InvalidPagingError => err
+                # This is invalid input, stop it before it goes to the server.
+                return err.default_insertions_page
               end
 
               size = paging[:size]

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

@@ -1,7 +1,7 @@
 module Promoted
   module Ruby
     module Client
-      VERSION = "3.0.0"
+      VERSION = "4.0.1"
       SERVER_VERSION = "rb." + VERSION
     end
   end

data/lib/promoted/ruby/client.rb

@@ -54,6 +54,7 @@ module Promoted
 
           @sampler = Sampler.new
           @pager   = Pager.new
+          @retrieval_insertion_offset = params[:retrieval_insertion_offset] || 0
 
           # HTTP Client creation
           @delivery_endpoint = params[:delivery_endpoint] || DEFAULT_DELIVERY_ENDPOINT
@@ -119,7 +120,7 @@ module Promoted
           # Respect the enabled state
           if !@enabled
             return {
-              insertion: @pager.apply_paging(args[:request][:insertion], Promoted::Ruby::Client::INSERTION_PAGING_TYPE['UNPAGED'], args[:request][:paging])
+              insertion: @pager.apply_paging(args[:request][:insertion], @retrieval_insertion_offset, args[:request][:paging])
               # No log request returned when disabled
             }
           end
@@ -134,16 +135,6 @@ module Promoted
           # perform_checks raises errors.
           if @perform_checks
             perform_common_checks!(args)
-            if !only_log && args[:insertion_page_type] == Promoted::Ruby::Client::INSERTION_PAGING_TYPE['PRE_PAGED'] then
-              err = DeliveryInsertionPageType.new
-              @logger.error(err) if @logger
-              raise err
-            end
-
-            if should_send_shadow_traffic && args[:insertion_page_type] != Promoted::Ruby::Client::INSERTION_PAGING_TYPE['UNPAGED'] then
-              should_send_shadow_traffic = false
-              @logger.error(ShadowTrafficInsertionPageType.new) if @logger
-            end
           end
 
           delivery_request_builder.ensure_client_timestamp
@@ -161,7 +152,7 @@ module Promoted
           end
 
           begin
-            @pager.validate_paging(delivery_request_builder.insertion, delivery_request_builder.request[:paging])
+            @pager.validate_paging(delivery_request_builder.insertion, @retrieval_insertion_offset, delivery_request_builder.request[:paging])
           rescue InvalidPagingError => err
             # Invalid input, log and do SDK-side delivery.
             @logger.warn(err) if @logger
@@ -234,7 +225,7 @@ module Promoted
         end
 
         ##
-        # Sends a log request (previously created by a call to prepare_for_logging) to the metrics endpoint.
+        # Sends a log request to the metrics endpoint.
         def send_log_request log_request_params, headers={}
           begin
             send_request(log_request_params, @metrics_endpoint, @metrics_timeout_millis, @metrics_api_key, headers)
@@ -249,7 +240,7 @@ module Promoted
         ##
         # Creates response insertions for SDK-side delivery, when we don't get response insertions from Delivery API.
         def build_sdk_response_insertions delivery_request_builder
-          response_insertions = @pager.apply_paging(delivery_request_builder.insertion, Promoted::Ruby::Client::INSERTION_PAGING_TYPE['UNPAGED'], delivery_request_builder.request[:paging])
+          response_insertions = @pager.apply_paging(delivery_request_builder.insertion, @retrieval_insertion_offset, delivery_request_builder.request[:paging])
           delivery_request_builder.add_missing_insertion_ids! response_insertions
           return response_insertions
         end
@@ -317,7 +308,7 @@ module Promoted
 
         # Delivers shadow traffic from the given metrics args.
         # Assumes that the args have already been normalized since this
-        # method should only be called from inside prepare_for_logging.
+        # method should only be called from inside deliver.
         def deliver_shadow_traffic args, headers
           delivery_request_builder = RequestBuilder.new
           delivery_request_builder.set_request_params args
@@ -326,7 +317,7 @@ module Promoted
           delivery_request_params[:client_info][:traffic_type] = Promoted::Ruby::Client::TRAFFIC_TYPE['SHADOW']
 
           begin
-            @pager.validate_paging(delivery_request_builder.insertion, delivery_request_builder.request[:paging])
+            @pager.validate_paging(delivery_request_builder.insertion, @retrieval_insertion_offset, delivery_request_builder.request[:paging])
           rescue InvalidPagingError => err
             # Invalid input, log and skip.
             @logger.warn("Shadow traffic call failed with invalid paging #{err}") if @logger

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: promoted-ruby-client
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.0.1
 platform: ruby
 authors:
 - scottmcmaster
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-08 00:00:00.000000000 Z
+date: 2023-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday