momento 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28402c3809544906082ae277798d4ffd2f82a20bf45fa9869edca7e3adf9bd9a
-  data.tar.gz: 4c8bac6308cc7a5ef23f025d909b6572907c4c1fc1c6386775b87006edee1a4c
+  metadata.gz: 6ae73ad26d383968c4b0335be41cc9aa1b95078cdbff65b012d54f0309573df3
+  data.tar.gz: c7717a54a117809b0c0c2cc1fbb2576a1f8046c3577627922055ec89093f38de
 SHA512:
-  metadata.gz: 9fad68ffd8d9dd81deee23655464af02014ddc3348bd07f0c95d9534d2acf7c9cac858f175a62489d121f3ebce9cd1c641f27dfdafac1665239697b5dcd326dd
-  data.tar.gz: a38ac7f169d9917e015b3da3647ec01950fb1b769a11166c16df6a1013e398c3b2e910e292c6721e204c9b3a04a5237be25bfea58e3ad5ebfed43866a990ee48
+  metadata.gz: 4723e7ebb12ae06ffd1a0c7fe75c5c5eb516bec1e9474c8283b1f4412d319a9c2e402262b4141c6bd90840f74856915182f85ae082c7b1615d85eba397aec4cf
+  data.tar.gz: 5dffb98bf9c697786ef1bd5bb2c92bd406738c1c4564cdf5e09a76f760254abd4409eadd8fc0862870b1e1a8f71af6d483315f010a1e432539d1842396a86daf

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

data/.rubocop.yml

@@ -11,13 +11,22 @@ AllCops:
     - 'lib/**/*_pb.rb'
     - 'vendor/**/*'
 
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
 Layout/MultilineMethodCallIndentation:
   EnforcedStyle: indented
 
+Layout/MultilineMethodCallBraceLayout:
+  EnforcedStyle: new_line
+
 Lint/AmbiguousBlockAssociation:
   # For rspec
   AllowedPatterns: ['change']
 
+Metrics/MethodLength:
+  Max: 15
+
 # The rspec defaults are way too tight.
 RSpec/ExampleLength:
   Max: 15
@@ -25,6 +34,9 @@ RSpec/MultipleExpectations:
   Max: 4
 RSpec/MultipleMemoizedHelpers:
   Max: 10
+# I disagree with this one. It should be clear you're using the subject.
+RSpec/NamedSubject:
+  Enabled: false
 RSpec/NestedGroups:
   Max: 4
 

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private
+--exclude _pb.rb$

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [0.2.0](https://github.com/momentohq/client-sdk-ruby/compare/momento-v0.1.0...momento/v0.2.0) (2022-12-07)
+
+### Breaking Changes
+
+* TTLs are now in seconds.
+* `response.value` was split into `response.value_bytes` and `response.value_string`
+* Stringifying a Momento::GetResponse no longer gives you the value.
+* `response.exception` is now `response.error.cause`
+
+### Features
+
+* Momento::Responses now stringfy with useful information.
+* `response.error` is a real Exception and can be raised
+* `response.error` is now a Momento::Error with expanded error information.
+* nil and non-String keys, values, and cache names are now TypeErrors.
+* Non-ASCII cache names are now InvalidArgument responses.
+* An invalid TTL will raise ArgumentError.
+* All response methods are discoverable in an IDE.
+* Improve the README
+* Complete YARD class and method documentation
+* More examples, and instructions how to run them.
+* Document how error handling works.
+
+## 0.1.0 (2022-11-21)
+
+First release.

data/CONTRIBUTING.md

@@ -36,7 +36,7 @@ This will install both the runtime and development dependencies.
 
 ## Trying it out
 
-You can run code from the repository's `lib/` directory by adding `-Ilib` to your ruby commands. For example, `ruby -Ilib examples/basic.rb` or `irb -Ilib`. This will use the repository's code even if you have the gem installed.
+You can run code from the repository's `lib/` directory by adding `-Ilib` to your ruby commands. For example, `ruby -Ilib examples/example.rb` or `irb -Ilib`. This will use the repository's code even if you have the gem installed.
 
 You can also build a gem from local sources and install it. Run `bundle exec rake install`.
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    momento (0.1.0)
+    momento (0.2.0)
       grpc (~> 1)
       jwt (~> 2)
 
@@ -23,8 +23,8 @@ GEM
       activesupport (>= 5.0.0)
     faker (3.0.0)
       i18n (>= 1.8.11, < 2)
-    google-protobuf (3.21.9-x86_64-darwin)
-    google-protobuf (3.21.9-x86_64-linux)
+    google-protobuf (3.21.10-x86_64-darwin)
+    google-protobuf (3.21.10-x86_64-linux)
     googleapis-common-protos-types (1.4.0)
       google-protobuf (~> 3.14)
     grpc (1.50.0-x86_64-darwin)
@@ -94,6 +94,9 @@ GEM
     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)
 
 PLATFORMS
   x86_64-darwin-20
@@ -113,6 +116,7 @@ DEPENDENCIES
   rubocop-rake (~> 0.6.0)
   rubocop-rspec (~> 2.15)
   simplecov (~> 0.21)
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.3.24

data/README.md

@@ -1,80 +1,175 @@
-# Momento
+<head>
+  <meta name="Momento Ruby Client Library Documentation" content="Ruby client software development kit for Momento Serverless Cache">
+</head>
+<img src="https://docs.momentohq.com/img/logo.svg" alt="logo" width="400"/>
 
-Client for Momento serverless caching service.
+[![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-alpha.svg)](https://github.com/momentohq/standards-and-practices/blob/main/docs/momento-on-github.md) 
 
-## Installation
+# Momento Ruby Client Library
+
+
+:warning: Alpha SDK :warning:
+
+This is an official Momento SDK, but the API is in an alpha stage and may be subject to backward-incompatible
+changes.  For more info, click on the alpha badge above.
+
+
+Ruby client SDK for Momento Serverless Cache: a fast, simple, pay-as-you-go caching solution without
+any of the operational overhead required by traditional caching solutions!
+
+
+
+## Getting Started :running:
+
+### Requirements
+
+- A Momento Auth Token is required, you can generate one using
+  the [Momento CLI](https://github.com/momentohq/momento-cli).
+- Ruby 2.7 or newer.
+
+An IDE with good Ruby support, such as [RubyMine](https://www.jetbrains.com/ruby/), is recommended.
+
+### Examples
+
+You can find this example code and more in [the examples directory](https://github.com/momentohq/client-sdk-ruby/tree/main/examples) of this repository.
+
+### Installation
 
 Install the gem and add to an application's Gemfile by executing:
 
-    $ bundle add momento
+```sh
+bundle add momento
+```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install momento
+```sh
+gem install momento
+```
 
-### M1 or M2 Macs
+#### Note: M1 or M2 Macs
 
-If you're using an M1 or M2 Mac, [you may have trouble installing the `grpc` gem](https://github.com/grpc/grpc/issues/31215).
+If you're using an M1 or M2 Mac, you may have trouble installing the `grpc` gem; [see this issue for more information](https://github.com/grpc/grpc/issues/31215).
 
 [A work around](https://github.com/grpc/grpc/pull/31151#issuecomment-1310321807) is to run `bundle config build.grpc --with-ldflags="-Wl,-undefined,dynamic_lookup"` before doing `bundle install`.
 
-## Requirements
-
-* A Momento Auth Token is required, you can generate one using the Momento CLI
-* Ruby >= 2.7
+### Usage
 
-## Usage
+```ruby
+# An example of the basic functionality of
+# Momento::SimpleCacheClient.
 
-```
 require 'momento'
 
 # Get your Momento token from an environment variable.
-token = ENV.fetch('MOMENTO_AUTH_TOKEN')
+TOKEN = ENV.fetch('MOMENTO_AUTH_TOKEN')
 
-# Cached items will be deleted after 30 seconds.
-ttl = 30_000
+# 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')
 
 # Instantiate a Momento client.
 client = Momento::SimpleCacheClient.new(
-  auth_token: token,
-  default_ttl: ttl
+  auth_token: TOKEN,
+  default_ttl: TTL_SECONDS
 )
 
-# Create a cache named "test_cache" to play with.
-response = client.create_cache("test_cache")
-if response.success? || response.already_exists?
-  puts "Created the cache, or it already exists."
+# 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}"
-else
-  raise
+  raise "Couldn't create a cache: #{response.error}"
 end
 
+# List our caches.
+puts "Caches: #{client.caches.to_a.join(", ")}"
+
 # Put an item in the cache.
-response = client.set("test_cache", "key", "You cached something!")
+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}"
-else
-  raise
+  raise "Couldn't set an item in the cache: #{response.error}"
 end
 
 # And get it back.
-response = client.get("test_cache", "key")
+response = client.get(CACHE_NAME, "key")
 if response.hit?
-  puts "Cache returned: #{response.value}"
+  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}"
-else
-  raise
+  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
+
+```
+
+### Error Handling
+
+[Momento::SimpleCacheClient](https://github.com/momentohq/client-sdk-ruby/blob/main/lib/momento/simple_cache_client.rb) follows the philosophy that when working with a service,
+[exceptions are bugs](https://www.gomomento.com/blog/exceptions-are-bugs). Minor outages are a fact of life; they are normal rather than exceptional.
+
+When there is a problem, Momento::SimpleCacheClient methods return an error response, the same as any other response. This makes errors more visible, allows your IDE to be more helpful in ensuring that you've handled the responses you care about.
+
+Check if a response is an error with `response.error?`, get the error with `response.error`, and it can be raised as an exception with `raise response.error`. Generally, printing `response.error` tell you what you need to know, but you might want more details. Here's a contrived example.
+
+```ruby
+# This is an invalid cache name. They must be ASCII-only.
+cache_name = 'çåché nåme'
+response = client.create_cache(cache_name)
+if response.success?
+  puts "Created the cache"
+elsif response.error?
+  error = response.error
+  puts "Creating the cache failed: #{error}"
+  case error
+  when Momento::Error::LimitExceededError
+    puts "We'll have to slow down"
+  when Momento::Error::PermissionError
+    puts "We'll have to fix our auth token"
+  when Momento::Error::InvalidArgumentError
+    puts "We can't make a cache named #{cache_name}"
+  end
 end
 ```
 
-You can run this code from [examples/basic.rb](examples/basic.rb).
+Momento::SimpleCacheClient *will* raise exceptions for programmer mistakes such as passing the wrong type, typically an ArgumentError or TypeError. The exceptions are documented for each method.
+
+See [Momento::Response](https://github.com/momentohq/client-sdk-ruby/blob/main/lib/momento/response.rb) for more about working with with error responses, and [Momento::Error](https://github.com/momentohq/client-sdk-ruby/blob/main/lib/momento/error.rb) for more about using errors.
+
+### Tuning
+
+Coming soon.
+
+## Issues
+
+Please report any bugs, issues, requests, and feedback via this repo's [issue tracker](https://github.com/momentohq/client-sdk-ruby/issues).
 
 ## Contributing
 
-See our [instructions for CONTRIBUTING](./CONTRIBUTING.md).
+See our [instructions for CONTRIBUTING](https://github.com/momentohq/client-sdk-ruby/blob/main/CONTRIBUTING.md).
+
+----------------------------------------------------------------------------------------
+For more info, visit our website at [https://gomomento.com](https://gomomento.com)!

data/README.template.md

@@ -0,0 +1,88 @@
+{{ ossHeader }}
+
+## Getting Started :running:
+
+### Requirements
+
+- A Momento Auth Token is required, you can generate one using
+  the [Momento CLI](https://github.com/momentohq/momento-cli).
+- Ruby 2.7 or newer.
+
+An IDE with good Ruby support, such as [RubyMine](https://www.jetbrains.com/ruby/), is recommended.
+
+### Examples
+
+You can find this example code and more in [the examples directory](https://github.com/momentohq/client-sdk-ruby/tree/main/examples) of this repository.
+
+### Installation
+
+Install the gem and add to an application's Gemfile by executing:
+
+```sh
+bundle add momento
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```sh
+gem install momento
+```
+
+#### Note: M1 or M2 Macs
+
+If you're using an M1 or M2 Mac, you may have trouble installing the `grpc` gem; [see this issue for more information](https://github.com/grpc/grpc/issues/31215).
+
+[A work around](https://github.com/grpc/grpc/pull/31151#issuecomment-1310321807) is to run `bundle config build.grpc --with-ldflags="-Wl,-undefined,dynamic_lookup"` before doing `bundle install`.
+
+### Usage
+
+```ruby
+{{ usageExampleCode }}
+```
+
+### Error Handling
+
+[Momento::SimpleCacheClient](https://github.com/momentohq/client-sdk-ruby/blob/main/lib/momento/simple_cache_client.rb) follows the philosophy that when working with a service,
+[exceptions are bugs](https://www.gomomento.com/blog/exceptions-are-bugs). Minor outages are a fact of life; they are normal rather than exceptional.
+
+When there is a problem, Momento::SimpleCacheClient methods return an error response, the same as any other response. This makes errors more visible, allows your IDE to be more helpful in ensuring that you've handled the responses you care about.
+
+Check if a response is an error with `response.error?`, get the error with `response.error`, and it can be raised as an exception with `raise response.error`. Generally, printing `response.error` tell you what you need to know, but you might want more details. Here's a contrived example.
+
+```ruby
+# This is an invalid cache name. They must be ASCII-only.
+cache_name = 'çåché nåme'
+response = client.create_cache(cache_name)
+if response.success?
+  puts "Created the cache"
+elsif response.error?
+  error = response.error
+  puts "Creating the cache failed: #{error}"
+  case error
+  when Momento::Error::LimitExceededError
+    puts "We'll have to slow down"
+  when Momento::Error::PermissionError
+    puts "We'll have to fix our auth token"
+  when Momento::Error::InvalidArgumentError
+    puts "We can't make a cache named #{cache_name}"
+  end
+end
+```
+
+Momento::SimpleCacheClient *will* raise exceptions for programmer mistakes such as passing the wrong type, typically an ArgumentError or TypeError. The exceptions are documented for each method.
+
+See [Momento::Response](https://github.com/momentohq/client-sdk-ruby/blob/main/lib/momento/response.rb) for more about working with with error responses, and [Momento::Error](https://github.com/momentohq/client-sdk-ruby/blob/main/lib/momento/error.rb) for more about using errors.
+
+### Tuning
+
+Coming soon.
+
+## Issues
+
+Please report any bugs, issues, requests, and feedback via this repo's [issue tracker](https://github.com/momentohq/client-sdk-ruby/issues).
+
+## Contributing
+
+See our [instructions for CONTRIBUTING](https://github.com/momentohq/client-sdk-ruby/blob/main/CONTRIBUTING.md).
+
+{{ ossFooter }}

data/examples/.gitignore

@@ -0,0 +1 @@
+test_copy.jpg

data/examples/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem 'momento', '~> 0.1.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_AUTH_TOKEN=<YOUR_AUTH_TOKEN>
+export 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,43 @@
+# This does the same work as in example.rb, but demonstrates a more compact style.
+
+require 'momento'
+
+# Get your Momento token from an environment variable.
+TOKEN = ENV.fetch('MOMENTO_AUTH_TOKEN')
+
+# 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')
+
+# Instantiate a Momento client.
+client = Momento::SimpleCacheClient.new(
+  auth_token: TOKEN,
+  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.
+puts "Caches: #{client.caches.to_a.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,66 @@
+# An example of the basic functionality of
+# Momento::SimpleCacheClient.
+
+require 'momento'
+
+# Get your Momento token from an environment variable.
+TOKEN = ENV.fetch('MOMENTO_AUTH_TOKEN')
+
+# 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')
+
+# Instantiate a Momento client.
+client = Momento::SimpleCacheClient.new(
+  auth_token: TOKEN,
+  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.
+puts "Caches: #{client.caches.to_a.join(", ")}"
+
+# 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,57 @@
+# 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'
+
+# Get your Momento token from an environment variable.
+TOKEN = ENV.fetch('MOMENTO_AUTH_TOKEN')
+
+# 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
+
+# Instantiate a Momento client.
+client = Momento::SimpleCacheClient.new(
+  auth_token: TOKEN,
+  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/momento/cacheclient_pb.rb

@@ -1,3 +1,5 @@
+# @private
+
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # source: cacheclient.proto
 

data/lib/momento/cacheclient_services_pb.rb

@@ -1,3 +1,5 @@
+# @private
+
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # Source: cacheclient.proto for package 'cache_client'
 

data/lib/momento/controlclient_pb.rb

@@ -1,3 +1,5 @@
+# @private
+
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # source: controlclient.proto
 

data/lib/momento/controlclient_services_pb.rb

@@ -1,3 +1,5 @@
+# @private
+
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
 # Source: controlclient.proto for package 'control_client'