momento 0.4.9 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 616d2ff01199640c05162ca979fb1ab260c1522c8b86a46d34c68ade3f7c430b
-  data.tar.gz: 54e756e639fd2c9fe5b5e004ccb0d1e6d9b6a9368ead7a8b4d518e908100b75a
+  metadata.gz: 8c0a2e256e81604bf29029b9b7e280ad7447a988b030e2b0e4597f1203ab1716
+  data.tar.gz: fcec32b5f2994ec2cd4c36a55b6e832d795347c9e4b7ce953b9ab364abbbc6d1
 SHA512:
-  metadata.gz: 48f6a80d7798f86b4bcd0d90dc7cb2ba0bec542554e443c2453756cb31b61fbef3f2ff38ad0933b1a71207d45a7782882829247630616605f8dd6d3c5ad68a6d
-  data.tar.gz: ab18d86ce358a2b63d67e953460dddb039c29d01412fddf730a4b55d3210910a1e43c759c78b375cf305c95e6d250f44259d0b6df7f34c1fead22ebbb4e727c7
+  metadata.gz: 4e41395f678e2b7cd093b26e0770d76883c4066479ab1beebb85ce6da66c78f0706965b6779d11a15838aa796f1bb73ba8d110b7527ba7ef6012ff6692f9568a
+  data.tar.gz: 907ecfb588f18ea17b34ac4d4e9539b451614f2ac0b14bed7500d2671f5cdf016981413d69473ac3cc09d173d2c46c1a924adcbcf21c92adb507629328880df0

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.9"
+  ".": "0.5.0"
 }

data/CHANGELOG.md

@@ -1,8 +1,22 @@
 # Changelog
 
-## [0.4.9](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.8...momento/v0.4.9) (2024-04-30)
+## [0.5.0](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.9...momento/v0.5.0) (2024-06-18)
+
+
+### Features
+
+* add InRegion pre-built config ([#180](https://github.com/momentohq/client-sdk-ruby/issues/180)) ([6dd2ef4](https://github.com/momentohq/client-sdk-ruby/commit/6dd2ef47443dbbd0cae28e1d4451c74352310aa3))
+* add runtime version header, only send agent headers on first request ([#177](https://github.com/momentohq/client-sdk-ruby/issues/177)) ([2292a35](https://github.com/momentohq/client-sdk-ruby/commit/2292a3575c551a2a36c9c3f1a31f0c6870e1c4d1))
+* add support for multiple grpc channels, fix configuration modifiers ([#176](https://github.com/momentohq/client-sdk-ruby/issues/176)) ([5753247](https://github.com/momentohq/client-sdk-ruby/commit/57532472d418db54c6eadd046ea6cbf0a53e4e96))
 
 
+### Bug Fixes
+
+* add Gemfile.lock to .gitignore ([45e0b6c](https://github.com/momentohq/client-sdk-ruby/commit/45e0b6cdfb19a337f6cb6c17afe2f21fd86b1eb5))
+* improve error handling for env var cred provider, other fixes ([#173](https://github.com/momentohq/client-sdk-ruby/issues/173)) ([c0b691b](https://github.com/momentohq/client-sdk-ruby/commit/c0b691b8c925d99b6a95a9cecee160b777b9dfab))
+
+## [0.4.9](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.8...momento/v0.4.9) (2024-04-30)
+
 ### Bug Fixes
 
 * remove token and specify email for the redundant tag ([#168](https://github.com/momentohq/client-sdk-ruby/issues/168)) ([c119376](https://github.com/momentohq/client-sdk-ruby/commit/c11937641acce6b55dbb7e59f87f548769ad9313))

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    momento (0.4.9)
+    momento (0.5.0)
       grpc (~> 1.62)
 
 GEM
@@ -54,7 +54,8 @@ GEM
     rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.6.0)
-    rexml (3.2.5)
+    rexml (3.2.8)
+      strscan (>= 3.0.9)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -94,12 +95,11 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
+    strscan (3.1.0)
     tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.3.0)
-    webrick (1.7.0)
-    yard (0.9.28)
-      webrick (~> 1.7.0)
+    yard (0.9.36)
 
 PLATFORMS
   arm64-darwin-22

data/README.md

@@ -4,7 +4,7 @@
 <img src="https://docs.momentohq.com/img/momento-logo-forest.svg" alt="logo" width="400"/>
 
 [![project status](https://momentohq.github.io/standards-and-practices/badges/project-status-official.svg)](https://github.com/momentohq/standards-and-practices/blob/main/docs/momento-on-github.md)
-[![project stability](https://momentohq.github.io/standards-and-practices/badges/project-stability-beta.svg)](https://github.com/momentohq/standards-and-practices/blob/main/docs/momento-on-github.md)
+[![project stability](https://momentohq.github.io/standards-and-practices/badges/project-stability-stable.svg)](https://github.com/momentohq/standards-and-practices/blob/main/docs/momento-on-github.md)
 
 # Momento Ruby Client Library
 
@@ -66,14 +66,24 @@ require 'momento'
 TTL_SECONDS = 12.5
 
 # The name of the cache to create *and delete*
-CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME')
+CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME', 'ruby-examples')
 
 # Create a credential provider that loads a Momento API Key from an environment variable.
 credential_provider = Momento::CredentialProvider.from_env_var('MOMENTO_API_KEY')
 
+# This is a reasonable configuration for dev work on a laptop.
+configuration = Momento::Cache::Configurations::Laptop.latest
+# This configuration might be better for a production where you want more aggressive timeouts
+# configuration = Momento::Cache::Configuration::InRegion.latest
+# To set a custom timeout, you can use the with_timeout method.
+# configuration = configuration.with_timeout(10_000)
+# To increase the number of TCP connections for a client where you expect a high volume of traffic,
+# you can use the with_num_connections method.
+# configuration = configuration.with_num_connections(4)
+
 # Instantiate a Momento client.
 client = Momento::CacheClient.new(
-  configuration: Momento::Cache::Configurations::Laptop.latest,
+  configuration: configuration,
   credential_provider: credential_provider,
   default_ttl: TTL_SECONDS
 )

data/examples/.gitignore

@@ -1 +1,2 @@
 test_copy.jpg
+Gemfile.lock

data/examples/Gemfile

@@ -2,4 +2,4 @@
 
 source "https://rubygems.org"
 
-gem 'momento', '~> 0.2.0'
+gem 'momento', '~> 0.4.9'

data/examples/README.md

@@ -18,14 +18,13 @@ Then, set the required environment variables:
 
 ```bash
 export MOMENTO_API_KEY=<YOUR_API_KEY>
-export MOMENTO_CACHE_NAME=<YOUR_CACHE_NAME>
 ```
 
 And now you can run the example programs.
 
-* example.rb - shows off all the basic functionality
-* compact.rb - the same, written in a compact style
-* file.rb - demonstrates how to cache a file
+* `ruby ./example.rb` - shows off all the basic functionality
+* `ruby ./compact.rb` - the same, written in a compact style
+* `ruby ./file.rb` - demonstrates how to cache a file
 
 If you wish to use the version of Momento in this repository, include the lib directory when you run the examples.
 

data/examples/compact.rb

@@ -6,7 +6,7 @@ require 'momento'
 TTL_SECONDS = 10
 
 # The name of the cache to create *and delete*
-CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME')
+CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME', 'ruby-examples')
 
 # Create a credential provider that loads a Momento API Key from an environment variable.
 credential_provider = Momento::CredentialProvider.from_env_var('MOMENTO_API_KEY')

data/examples/example.rb

@@ -7,14 +7,24 @@ require 'momento'
 TTL_SECONDS = 12.5
 
 # The name of the cache to create *and delete*
-CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME')
+CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME', 'ruby-examples')
 
 # Create a credential provider that loads a Momento API Key from an environment variable.
 credential_provider = Momento::CredentialProvider.from_env_var('MOMENTO_API_KEY')
 
+# This is a reasonable configuration for dev work on a laptop.
+configuration = Momento::Cache::Configurations::Laptop.latest
+# This configuration might be better for a production where you want more aggressive timeouts
+# configuration = Momento::Cache::Configuration::InRegion.latest
+# To set a custom timeout, you can use the with_timeout method.
+# configuration = configuration.with_timeout(10_000)
+# To increase the number of TCP connections for a client where you expect a high volume of traffic,
+# you can use the with_num_connections method.
+# configuration = configuration.with_num_connections(4)
+
 # Instantiate a Momento client.
 client = Momento::CacheClient.new(
-  configuration: Momento::Cache::Configurations::Laptop.latest,
+  configuration: configuration,
   credential_provider: credential_provider,
   default_ttl: TTL_SECONDS
 )

data/examples/file.rb

@@ -9,7 +9,7 @@ require 'momento'
 TTL_SECONDS = 12.5
 
 # The name of the cache to create *and delete*
-CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME')
+CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME', 'ruby-examples')
 
 # So it can be run from the top of the repo
 # or from the examples directory.

data/lib/momento/cache_client.rb

@@ -67,6 +67,9 @@ module Momento
       @control_endpoint = credential_provider.control_endpoint
       @cache_endpoint = credential_provider.cache_endpoint
       @configuration = configuration
+      @next_cache_stub_index = 0
+      @num_cache_stubs = @configuration.transport_strategy.grpc_configuration.num_grpc_channels
+      @is_first_request = true
     end
 
     # Get a value in a cache.
@@ -95,7 +98,7 @@ module Momento
       builder.from_block do
         cache_stub.get(
           MomentoProtos::CacheClient::PB__GetRequest.new(cache_key: to_bytes(key)),
-          metadata: { cache: validate_cache_name(cache_name) }
+          metadata: grpc_metadata(cache_name)
         )
       end
     end
@@ -129,7 +132,7 @@ module Momento
           ttl_milliseconds: ttl.milliseconds
         )
 
-        cache_stub.set(req, metadata: { cache: validate_cache_name(cache_name) })
+        cache_stub.set(req, metadata: grpc_metadata(cache_name))
       end
     end
 
@@ -153,7 +156,7 @@ module Momento
       builder.from_block do
         cache_stub.delete(
           MomentoProtos::CacheClient::PB__DeleteRequest.new(cache_key: to_bytes(key)),
-          metadata: { cache: validate_cache_name(cache_name) }
+          metadata: grpc_metadata(cache_name)
         )
       end
     end
@@ -254,7 +257,7 @@ module Momento
         )
 
         # noinspection RubyResolve
-        cache_stub.sorted_set_put(req, metadata: { cache: validate_cache_name(cache_name) })
+        cache_stub.sorted_set_put(req, metadata: grpc_metadata(cache_name))
       end
     end
 
@@ -291,7 +294,7 @@ module Momento
         )
 
         # noinspection RubyResolve
-        cache_stub.sorted_set_put(req, metadata: { cache: validate_cache_name(cache_name) })
+        cache_stub.sorted_set_put(req, metadata: grpc_metadata(cache_name))
       end
     end
 
@@ -331,7 +334,7 @@ module Momento
         )
 
         # noinspection RubyResolve
-        cache_stub.sorted_set_fetch(req, metadata: { cache: validate_cache_name(cache_name) })
+        cache_stub.sorted_set_fetch(req, metadata: grpc_metadata(cache_name))
       end
     end
     # rubocop:enable Metrics/ParameterLists
@@ -339,9 +342,14 @@ module Momento
     private
 
     def cache_stub
-      @cache_stub ||= CACHE_CLIENT_STUB_CLASS.new(@cache_endpoint, combined_credentials,
-        timeout: @configuration.transport_strategy.grpc_configuration.deadline
-      )
+      @cache_stubs ||= (1..@num_cache_stubs).map {
+        CACHE_CLIENT_STUB_CLASS.new(@cache_endpoint, combined_credentials,
+          timeout: @configuration.transport_strategy.grpc_configuration.deadline,
+          channel_args: { 'grpc.use_local_subchannel_pool' => 1 }
+        )
+      }
+      @next_cache_stub_index = (@next_cache_stub_index + 1) % @num_cache_stubs
+      @cache_stubs[@next_cache_stub_index]
     end
 
     def control_stub
@@ -355,7 +363,7 @@ module Momento
     def make_combined_credentials
       # :nocov:
       auth_proc = proc do
-        { authorization: @api_key, agent: "ruby:#{VERSION}" }
+        { authorization: @api_key }
       end
       # :nocov:
 
@@ -439,6 +447,19 @@ module Momento
       end
     end
 
+    def grpc_metadata(cache_name)
+      if @is_first_request
+        @is_first_request = false
+        {
+          cache: validate_cache_name(cache_name),
+          Agent: "ruby:cache:#{VERSION}",
+          'Runtime-Version': "ruby:#{RUBY_VERSION}"
+        }
+      else
+        { cache: validate_cache_name(cache_name) }
+      end
+    end
+
     # Return a UTF-8 version of the cache name.
     #
     # @param name [String] the cache name to validate

data/lib/momento/config/configuration.rb

@@ -4,8 +4,34 @@ module Momento
     class Configuration
       attr_reader :transport_strategy
 
-      def self.with_transport_strategy(transport_strategy)
-        return Configuration.new(transport_strategy)
+      # Convenience function to set the client timeout in milliseconds. If the server has not responded within the
+      # specified time, the client will terminate the request with a DeadlineExceeded error.
+      def with_timeout(timeout_millis)
+        transport_strategy = @transport_strategy
+        grpc_config = transport_strategy.grpc_configuration
+        Configuration.new(
+          transport_strategy.with_grpc_configuration(
+            grpc_config.with_deadline(timeout_millis)
+          )
+        )
+      end
+
+      # Convenience function to set the number of TCP connections for the client. Each connection can multiplex up
+      # to 100 concurrent requests. The default is 1, and this should not be overridden unless you are making a high
+      # volume of requests. Can help distribute traffic more evenly for high-throughput use cases.
+      def with_num_connections(num_connections)
+        transport_strategy = @transport_strategy
+        grpc_config = transport_strategy.grpc_configuration
+        Configuration.new(
+          transport_strategy.with_grpc_configuration(
+            grpc_config.with_num_grpc_channels(num_connections)
+          )
+        )
+      end
+
+      # Copy constructor; creates a new Configuration with the specified transport strategy
+      def with_transport_strategy(transport_strategy)
+        Configuration.new(transport_strategy)
       end
 
       def initialize(transport_strategy)

data/lib/momento/config/configurations.rb

@@ -12,6 +12,13 @@ module Momento
           return Configuration.new(StaticTransportStrategy.new(GrpcConfiguration.new(5000)))
         end
       end
+
+      # Default Laptop configuration with 1100ms client timeout
+      class InRegion < Cache::Configuration
+        def self.latest
+          return Configuration.new(StaticTransportStrategy.new(GrpcConfiguration.new(1100)))
+        end
+      end
     end
   end
 end

data/lib/momento/config/transport/grpc_configuration.rb

@@ -5,11 +5,20 @@ module Momento
     # complete before it is terminated with a DeadlineExceeded error
     attr_reader :deadline
 
-    def self.with_deadline(deadline)
-      return GrpcConfiguration.new(deadline)
+    # Number of gRPC channels to create. Each channel can multiplex up to
+    # 100 concurrent requests. The default is 1, and this should not be
+    # overridden unless you are making a high volume of requests.
+    attr_reader :num_grpc_channels
+
+    def with_deadline(deadline)
+      return GrpcConfiguration.new(deadline, @num_grpc_channels)
+    end
+
+    def with_num_grpc_channels(num_grpc_channels)
+      return GrpcConfiguration.new(@deadline, num_grpc_channels)
     end
 
-    def initialize(deadline)
+    def initialize(deadline, num_grpc_channels = 1)
       unless deadline.is_a? Integer
         raise Momento::Error::InvalidArgumentError,
           'Client timeout must be an integer'
@@ -20,6 +29,7 @@ module Momento
       end
 
       @deadline = deadline
+      @num_grpc_channels = num_grpc_channels
     end
   end
 end

data/lib/momento/config/transport/static_transport_strategy.rb

@@ -5,7 +5,7 @@ module Momento
   class StaticTransportStrategy < TransportStrategy
     attr_reader :grpc_configuration
 
-    def self.with_grpc_configuration(grpc_configuration)
+    def with_grpc_configuration(grpc_configuration)
       return StaticTransportStrategy.new(grpc_configuration)
     end
   end

data/lib/momento/config/transport/transport_strategy.rb

@@ -3,7 +3,7 @@ module Momento
   class TransportStrategy
     attr_reader :grpc_configuration
 
-    def self.with_grpc_configuration(grpc_configuration)
+    def with_grpc_configuration(grpc_configuration)
       return TransportStrategy.new(grpc_configuration)
     end
 

data/lib/momento/error/types.rb

@@ -126,11 +126,18 @@ module Momento
     class InvalidArgumentError < ArgumentError
       include Momento::Error
 
+      def initialize(details = "")
+        @details = details
+        super(message)
+      end
+
       # (see Momento::Error#error_code)
       def error_code
         :INVALID_ARGUMENT_ERROR
       end
 
+      attr_reader :details
+
       # (see Momento::Error#message)
       def message
         "Invalid argument passed to Momento client: #{details}"

data/lib/momento/version.rb

@@ -2,5 +2,5 @@
 
 module Momento
   # This gem's version.
-  VERSION = "0.4.9"
+  VERSION = "0.5.0"
 end

data/sig/momento/cache_client.rbs

@@ -1,6 +1,5 @@
 module Momento
   class CacheClient
-
     def sorted_set_fetch_by_score: (cache_name: String, sorted_set_name: String, min_score: Float | nil, max_score: Float | nil, sort_order: Symbol, offset: Integer, count: Integer) -> SortedSetFetchResponse
 
     def sorted_set_put_element: (cache_name: String, sorted_set_name: String, value: String, score: Float, collection_ttl: CollectionTtl) -> SortedSetPutElementResponse

data/sig/momento/config/configuration.rbs

@@ -1,7 +1,11 @@
 module Momento
   module Cache
     class Configuration
-      def self.with_transport_strategy: -> Cache::Configuration
+      def with_timeout: -> Configuration
+
+      def with_num_connections: -> Configuration
+
+      def with_transport_strategy: -> Configuration
 
       attr_reader transport_strategy: TransportStrategy
     end

data/sig/momento/config/transport/grpc_configuration.rbs

@@ -2,6 +2,8 @@ module Momento
   class GrpcConfiguration
     def self.with_deadline: -> GrpcConfiguration
 
+    def self.with_num_grpc_channels: -> GrpcConfiguration
+
     attr_reader deadline: Integer
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: momento
 version: !ruby/object:Gem::Version
-  version: 0.4.9
+  version: 0.5.0
 platform: ruby
 authors:
 - Momento
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-30 00:00:00.000000000 Z
+date: 2024-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -321,7 +321,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Client for Momento Serverless Cache