momento 0.1.0 → 0.4.9

data/examples/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem 'momento', '~> 0.2.0'

data/examples/README.md

@@ -0,0 +1,34 @@
+<img src="https://docs.momentohq.com/img/logo.svg" alt="Momento logo" width="400"/>
+
+# Momento Ruby Client Examples
+
+## Requirements
+
+See the [project's README](https://github.com/momentohq/client-sdk-ruby/blob/main/README.md).
+
+## Running the examples
+
+First, install the gem and its dependencies.
+
+```sh
+bundle
+```
+
+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
+
+If you wish to use the version of Momento in this repository, include the lib directory when you run the examples.
+
+```sh
+ruby -I../lib example.rb
+```

data/examples/compact.rb

@@ -0,0 +1,47 @@
+# This does the same work as in example.rb, but demonstrates a more compact style.
+
+require 'momento'
+
+# Cached items will be deleted after 10 seconds.
+TTL_SECONDS = 10
+
+# The name of the cache to create *and delete*
+CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME')
+
+# Create a credential provider that loads a Momento API Key from an environment variable.
+credential_provider = Momento::CredentialProvider.from_env_var('MOMENTO_API_KEY')
+
+# Instantiate a Momento client.
+client = Momento::CacheClient.new(
+  configuration: Momento::Cache::Configurations::Laptop.latest,
+  credential_provider: credential_provider,
+  default_ttl: TTL_SECONDS
+)
+
+# Create a cache to play with.
+# It might be created, or it might already exist.
+response = client.create_cache(CACHE_NAME)
+raise response.error if response.error?
+
+# List our caches.
+response = client.list_caches
+raise response.error if response.error?
+
+puts "Caches: #{response.cache_names&.join(", ")}"
+
+# Put an item in the cache.
+response = client.set(CACHE_NAME, "key", "You cached something!")
+raise response.error if response.error?
+
+# And get it back.
+response = client.get(CACHE_NAME, "key")
+puts response.value_string || "The item wasn't found in the cache."
+raise response.error if response.error?
+
+# Now delete it.
+response = client.delete(CACHE_NAME, "key")
+raise response.error if response.error?
+
+# And delete our test cache.
+response = client.delete_cache(CACHE_NAME)
+raise response.error if response.error?

data/examples/example.rb

@@ -0,0 +1,72 @@
+# An example of the basic functionality of
+# Momento::CacheClient.
+
+require 'momento'
+
+# Cached items will be deleted after 12.5 seconds.
+TTL_SECONDS = 12.5
+
+# The name of the cache to create *and delete*
+CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME')
+
+# Create a credential provider that loads a Momento API Key from an environment variable.
+credential_provider = Momento::CredentialProvider.from_env_var('MOMENTO_API_KEY')
+
+# Instantiate a Momento client.
+client = Momento::CacheClient.new(
+  configuration: Momento::Cache::Configurations::Laptop.latest,
+  credential_provider: credential_provider,
+  default_ttl: TTL_SECONDS
+)
+
+# Create a cache to play with.
+response = client.create_cache(CACHE_NAME)
+if response.success?
+  puts "Created the cache."
+elsif response.already_exists?
+  puts "Cache already exists."
+elsif response.error?
+  raise "Couldn't create a cache: #{response.error}"
+end
+
+# List our caches.
+response = client.list_caches
+if response.success?
+  puts "Caches: #{response.cache_names&.join(", ")}"
+elsif response.error?
+  raise "Couldn't list the caches: #{response.error}"
+end
+
+# Put an item in the cache.
+response = client.set(CACHE_NAME, "key", "You cached something!")
+if response.success?
+  puts "Set an item in the cache."
+elsif response.error?
+  raise "Couldn't set an item in the cache: #{response.error}"
+end
+
+# And get it back.
+response = client.get(CACHE_NAME, "key")
+if response.hit?
+  puts "Cache returned: #{response.value_string}"
+elsif response.miss?
+  puts "The item wasn't found in the cache."
+elsif response.error?
+  raise "Couldn't get an item from the cache: #{response.error}"
+end
+
+# Now delete it.
+response = client.delete(CACHE_NAME, "key")
+if response.success?
+  puts "Key/value deleted."
+elsif response.error?
+  raise "Couldn't delete an item from the cache: #{response.error}"
+end
+
+# And delete our test cache.
+response = client.delete_cache(CACHE_NAME)
+if response.success?
+  puts "Deleted the cache."
+elsif response.error?
+  raise "Couldn't create a cache: #{response.error}"
+end

data/examples/file.rb

@@ -0,0 +1,58 @@
+# This is an example of storing binary data.
+#
+# It will cache a test image, read it back,
+# and write it to disk as test_copy.jpg.
+
+require 'momento'
+
+# Cached items will be deleted after 12.5 seconds.
+TTL_SECONDS = 12.5
+
+# The name of the cache to create *and delete*
+CACHE_NAME = ENV.fetch('MOMENTO_CACHE_NAME')
+
+# So it can be run from the top of the repo
+# or from the examples directory.
+FILE_LOCATIONS = [
+  "spec/support/assets/test.jpg",
+  "../spec/support/assets/test.jpg"
+].freeze
+
+# Create a credential provider that loads a Momento API Key from an environment variable.
+credential_provider = Momento::CredentialProvider.from_env_var('MOMENTO_API_KEY')
+
+# Instantiate a Momento client.
+client = Momento::CacheClient.new(
+  configuration: Momento::Cache::Configurations::Laptop.latest,
+  credential_provider: credential_provider,
+  default_ttl: TTL_SECONDS
+)
+
+# Create a cache for testing, or use an already existing one.
+response = client.create_cache(CACHE_NAME)
+raise response.error if response.error?
+
+# Read an image file.
+file = FILE_LOCATIONS.find { |f| File.exist?(f) }
+contents = File.read(file)
+
+# Add the image to the cache.
+puts "Caching #{file}"
+client.set(CACHE_NAME, "test.jpg", contents)
+raise response.error if response.error?
+
+puts "Retrieving the image"
+response = client.get(CACHE_NAME, "test.jpg")
+raise "Cache image was not found!" if response.miss?
+raise response.error if response.error?
+
+puts "Writing the image as test_copy.jpg"
+f = File.open("test_copy.jpg", "wb")
+f.write(response.value_bytes)
+f.close
+
+# Delete our test cache.
+response = client.delete_cache(CACHE_NAME)
+raise response.error if response.error?
+
+puts "Now open test_copy.jpg"

data/lib/README-generating-pb.txt

@@ -25,4 +25,4 @@ Put them in their own namespace.
 1. Wrap the modules in `module Momento`.
 2. In the *_services_pb.rb files, change the module names.
   * rename ::ControlClient to ::Momento::ControlClient
-  * rename ::CacheClient to ::Momento::CacheClient
+  * rename ::CacheClient to ::MomentoProtos::CacheClient

data/lib/momento/auth/credential_provider.rb

@@ -0,0 +1,78 @@
+require "base64"
+require "json"
+
+module Momento
+  # Contains the information required for a Momento client to connect to and authenticate with Momento services.
+  class CredentialProvider
+    attr_reader :api_key, :control_endpoint, :cache_endpoint
+
+    # Creates a CredentialProvider from a Momento API key loaded from an environment variable.
+    # @param env_var_name [String] the environment variable containing the API key
+    # @return [Momento::CredentialProvider]
+    # @raise [Momento::Error::InvalidArgumentError] if the API key is invalid
+    def self.from_env_var(env_var_name)
+      api_key = ENV.fetch(env_var_name) {
+        raise Momento::Error::InvalidArgumentError, "Env var #{env_var_name} must be set"
+      }
+      new(api_key)
+    end
+
+    # Creates a CredentialProvider from a Momento API key
+    # @param api_key [String] the Momento API key
+    # @return [Momento::CredentialProvider]
+    # @raise [Momento::Error::InvalidArgumentError] if the API key is invalid
+    def self.from_string(api_key)
+      raise Momento::Error::InvalidArgumentError, 'Auth token string cannot be empty' if api_key.empty?
+
+      new(api_key)
+    end
+
+    private
+
+    def initialize(api_key)
+      decoded_token = decode_api_key(api_key)
+      @api_key = decoded_token.api_key
+      @control_endpoint = decoded_token.control_endpoint
+      @cache_endpoint = decoded_token.cache_endpoint
+    rescue StandardError => e
+      raise Momento::Error::InvalidArgumentError, e.message
+    end
+
+    AuthTokenData = Struct.new(:api_key, :cache_endpoint, :control_endpoint)
+
+    def decode_api_key(api_key)
+      decode_v1_key(api_key)
+    rescue StandardError
+      decode_legacy_key(api_key)
+    end
+
+    def decode_legacy_key(api_key)
+      key_parts = api_key.split('.')
+      raise Momento::Error::InvalidArgumentError, 'Malformed legacy API key' if key_parts.size != 3
+
+      decoded_key = Base64.decode64(key_parts[1])
+      key_json = JSON.parse(decoded_key, symbolize_names: true)
+      validate_key_json(key_json, %i[c cp])
+
+      AuthTokenData.new(api_key, key_json[:c], key_json[:cp])
+    end
+
+    def decode_v1_key(api_key)
+      decoded_key = Base64.decode64(api_key)
+      key_json = JSON.parse(decoded_key, symbolize_names: true)
+      validate_key_json(key_json, %i[api_key endpoint])
+
+      AuthTokenData.new(key_json[:api_key], "cache.#{key_json[:endpoint]}", "control.#{key_json[:endpoint]}")
+    rescue StandardError
+      raise Momento::Error::InvalidArgumentError, 'Malformed Momento API Key'
+    end
+
+    def validate_key_json(key_json, required_fields)
+      missing_fields = required_fields.reject { |field| key_json.key?(field) }
+      return if missing_fields.empty?
+
+      raise Momento::Error::InvalidArgumentError,
+        "Required fields are missing: #{missing_fields.join(', ')}"
+    end
+  end
+end