momento 0.1.0 → 0.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28402c3809544906082ae277798d4ffd2f82a20bf45fa9869edca7e3adf9bd9a
-  data.tar.gz: 4c8bac6308cc7a5ef23f025d909b6572907c4c1fc1c6386775b87006edee1a4c
+  metadata.gz: 616d2ff01199640c05162ca979fb1ab260c1522c8b86a46d34c68ade3f7c430b
+  data.tar.gz: 54e756e639fd2c9fe5b5e004ccb0d1e6d9b6a9368ead7a8b4d518e908100b75a
 SHA512:
-  metadata.gz: 9fad68ffd8d9dd81deee23655464af02014ddc3348bd07f0c95d9534d2acf7c9cac858f175a62489d121f3ebce9cd1c641f27dfdafac1665239697b5dcd326dd
-  data.tar.gz: a38ac7f169d9917e015b3da3647ec01950fb1b769a11166c16df6a1013e398c3b2e910e292c6721e204c9b3a04a5237be25bfea58e3ad5ebfed43866a990ee48
+  metadata.gz: 48f6a80d7798f86b4bcd0d90dc7cb2ba0bec542554e443c2453756cb31b61fbef3f2ff38ad0933b1a71207d45a7782882829247630616605f8dd6d3c5ad68a6d
+  data.tar.gz: ab18d86ce358a2b63d67e953460dddb039c29d01412fddf730a4b55d3210910a1e43c759c78b375cf305c95e6d250f44259d0b6df7f34c1fead22ebbb4e727c7

data/.release-please-manifest.json

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

data/.rubocop.yml

@@ -8,16 +8,25 @@ AllCops:
   TargetRubyVersion: 2.7
   Exclude:
     # Generated protobuf files
-    - 'lib/**/*_pb.rb'
+    - 'lib/momento/generated/**/*'
     - '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
 
@@ -59,3 +71,16 @@ Style/WordArray:
 
 Layout/LineLength:
   Max: 120
+  Exclude:
+    - 'lib/momento/generated/**/*'
+
+Style/Documentation:
+  Exclude:
+    - 'lib/momento/generated/**/*'
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/momento/generated/**/*'
+
+RSpec/FactoryBot/FactoryClassName:
+  Enabled: false

data/.ruby-version

@@ -1 +1 @@
-ruby-3.1.2
+3.2.2

data/.yardopts

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

data/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+## [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))
+
+## [0.4.8](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.7...momento/v0.4.8) (2024-04-30)
+
+
+### Bug Fixes
+
+* check out the repo with the machine user token ([#166](https://github.com/momentohq/client-sdk-ruby/issues/166)) ([67845af](https://github.com/momentohq/client-sdk-ruby/commit/67845af1da172271ea0e604d4ab8d6e749a7d7c1))
+
+## [0.4.7](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.6...momento/v0.4.7) (2024-04-30)
+
+
+### Bug Fixes
+
+* update the grpc dependency ([#164](https://github.com/momentohq/client-sdk-ruby/issues/164)) ([00c0ee5](https://github.com/momentohq/client-sdk-ruby/commit/00c0ee578c63b2003b6de23506715447d762997a))
+
+## [0.4.6](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.5...momento/v0.4.6) (2024-04-30)
+
+
+### Bug Fixes
+
+* check for local changes on release please failure ([#162](https://github.com/momentohq/client-sdk-ruby/issues/162)) ([bf8322c](https://github.com/momentohq/client-sdk-ruby/commit/bf8322c2cbd887c595db537838e227a0e66ebeb3))
+
+## [0.4.5](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.4...momento/v0.4.5) (2024-04-30)
+
+
+### Bug Fixes
+
+* check for local changes after publishing the gem ([#160](https://github.com/momentohq/client-sdk-ruby/issues/160)) ([cd9f242](https://github.com/momentohq/client-sdk-ruby/commit/cd9f242d224b6541d11fe06df23311d7ee6f19d0))
+
+## [0.4.4](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.3...momento/v0.4.4) (2024-04-30)
+
+
+### Bug Fixes
+
+* separate 'bundle install' to see if it modifies the checkout ([#158](https://github.com/momentohq/client-sdk-ruby/issues/158)) ([dbb5d20](https://github.com/momentohq/client-sdk-ruby/commit/dbb5d20619fb556eeebec7f80ff55e02bd14c282))
+
+## [0.4.3](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.2...momento/v0.4.3) (2024-04-30)
+
+
+### Bug Fixes
+
+* verbose rubygems publishing ([#156](https://github.com/momentohq/client-sdk-ruby/issues/156)) ([0f6ec1f](https://github.com/momentohq/client-sdk-ruby/commit/0f6ec1fc958bb9473b4f508f2cb2d1e35beaf90c))
+
+## [0.4.2](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.1...momento/v0.4.2) (2024-04-30)
+
+
+### Bug Fixes
+
+* add git status for release-please troubleshooting ([#154](https://github.com/momentohq/client-sdk-ruby/issues/154)) ([115b4ef](https://github.com/momentohq/client-sdk-ruby/commit/115b4ef77c62344e1debd813d19adf47fa687f1b))
+
+## [0.4.1](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.4.0...momento/v0.4.1) (2024-04-29)
+
+
+### Bug Fixes
+
+* Update release please action versions ([#152](https://github.com/momentohq/client-sdk-ruby/issues/152)) ([c4241da](https://github.com/momentohq/client-sdk-ruby/commit/c4241daa72dcb1f73eafef9ef86618e51826c3fb))
+
+## [0.4.0](https://github.com/momentohq/client-sdk-ruby/compare/momento/v0.3.0...momento/v0.4.0) (2024-04-29)
+
+
+### Features
+
+* add a CredentialProvider ([#134](https://github.com/momentohq/client-sdk-ruby/issues/134)) ([c74f34a](https://github.com/momentohq/client-sdk-ruby/commit/c74f34a102d24b6f143376ac4c643139b2559394))
+* add a value alias in sorted_set_fetch ([#149](https://github.com/momentohq/client-sdk-ruby/issues/149)) ([f310df0](https://github.com/momentohq/client-sdk-ruby/commit/f310df08735a41bd834e27ef138897c2ac5aa5ce))
+* add cache config objects as CacheClient argument ([f8c1c86](https://github.com/momentohq/client-sdk-ruby/commit/f8c1c860fa05c83a766b0063835013b32cc35382))
+* add cache config objects as CacheClient argument ([#142](https://github.com/momentohq/client-sdk-ruby/issues/142)) ([1158039](https://github.com/momentohq/client-sdk-ruby/commit/1158039ab4caa8fb6ab491c71c82d9eae3ad4083))
+* add sorted set put and fetch by score ([#147](https://github.com/momentohq/client-sdk-ruby/issues/147)) ([a8fd259](https://github.com/momentohq/client-sdk-ruby/commit/a8fd259d09f273a3ed0c857b05610534d801673e))
+* rename SimpleCacheClient to CacheClient ([37e2183](https://github.com/momentohq/client-sdk-ruby/commit/37e2183390e3184ad6ce4429df15fdd4b8b15a74))
+* rename SimpleCacheClient to CacheClient ([#141](https://github.com/momentohq/client-sdk-ruby/issues/141)) ([f1e6d86](https://github.com/momentohq/client-sdk-ruby/commit/f1e6d86ea9665bb66164265a7baa85f729d798a8))
+* support UTF-8 cache names instead of just ASCII ([#148](https://github.com/momentohq/client-sdk-ruby/issues/148)) ([5627f52](https://github.com/momentohq/client-sdk-ruby/commit/5627f526ccb269383289f8b3a033890f868f936d))
+
+
+### Bug Fixes
+
+* change the ruby versions in the test action to strings ([4700338](https://github.com/momentohq/client-sdk-ruby/commit/47003387cbab0739361eedcdad9662f0a0753757))
+* change the ruby versions in the test action to strings ([#136](https://github.com/momentohq/client-sdk-ruby/issues/136)) ([975be89](https://github.com/momentohq/client-sdk-ruby/commit/975be891c7cea139b6365698cf80d74db718bc3f))
+* fill out credential provider method docs ([#151](https://github.com/momentohq/client-sdk-ruby/issues/151)) ([90a8a39](https://github.com/momentohq/client-sdk-ruby/commit/90a8a39a50c908cc927fbdb8307fb50d29d7b960))
+
+## [0.3.0](https://github.com/momentohq/client-sdk-ruby/compare/momento-v0.2.0...momento/v0.3.0) (2023-11-09)
+
+
+### Features
+
+* add support for v1 tokens ([0a98c34](https://github.com/momentohq/client-sdk-ruby/commit/0a98c3404972966a7c4c2017908f2c204532712d))
+
+## [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,17 +36,16 @@ 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`.
 
-## Running unit tests
+## Running tests
 
-Run `rspec`. These tests will make no network calls and do not require a Momento account.
-
-## Running integration tests
-
-TODO
+You will need a momento API key that you can generate on the [Momento Console](https://console.gomomento.com/api-keys).
+1. Set the environment variable `MOMENTO_API_KEY` to your Momento API key.
+2. Optionally set the environment variable `TEST_CACHE_NAME` to a cache that is safe to test with and delete. If you don't do this, the cache 'ruby-test-cache' will be used by default.
+3. Run `rspec` from the command line to execute the tests.
 
 ## Bug reports
 

data/Gemfile

@@ -2,10 +2,5 @@
 
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in momento-client.gemspec
+# Specify your gem's dependencies in momento.gemspec
 gemspec
-
-gem "pry-byebug"
-gem "rake", "~> 13.0"
-gem "rspec", "~> 3.0"
-gem "rubocop", "~> 1.38"

data/Gemfile.lock

@@ -1,9 +1,8 @@
 PATH
   remote: .
   specs:
-    momento (0.1.0)
-      grpc (~> 1)
-      jwt (~> 2)
+    momento (0.4.9)
+      grpc (~> 1.62)
 
 GEM
   remote: https://rubygems.org/
@@ -23,15 +22,19 @@ 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)
-    googleapis-common-protos-types (1.4.0)
-      google-protobuf (~> 3.14)
-    grpc (1.50.0-x86_64-darwin)
-      google-protobuf (~> 3.21)
+    google-protobuf (3.25.3-arm64-darwin)
+    google-protobuf (3.25.3-x86_64-darwin)
+    google-protobuf (3.25.3-x86_64-linux)
+    googleapis-common-protos-types (1.14.0)
+      google-protobuf (~> 3.18)
+    grpc (1.62.0-arm64-darwin)
+      google-protobuf (~> 3.25)
       googleapis-common-protos-types (~> 1.0)
-    grpc (1.50.0-x86_64-linux)
-      google-protobuf (~> 3.21)
+    grpc (1.62.0-x86_64-darwin)
+      google-protobuf (~> 3.25)
+      googleapis-common-protos-types (~> 1.0)
+    grpc (1.62.0-x86_64-linux)
+      google-protobuf (~> 3.25)
       googleapis-common-protos-types (~> 1.0)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
@@ -52,19 +55,19 @@ GEM
     rake (13.0.6)
     regexp_parser (2.6.0)
     rexml (3.2.5)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.0)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.1)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
     rubocop (1.38.0)
       json (~> 2.3)
       parallel (~> 1.10)
@@ -94,8 +97,13 @@ 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
+  arm64-darwin-22
+  arm64-darwin-23
   x86_64-darwin-20
   x86_64-darwin-21
   x86_64-linux
@@ -104,15 +112,17 @@ DEPENDENCIES
   bundler (~> 2.3)
   factory_bot (~> 6.2.1)
   faker (~> 3.0)
+  jwt (~> 2)
   momento!
-  pry-byebug
+  pry-byebug (~> 3)
   rake (~> 13.0)
-  rspec (~> 3.0)
+  rspec (~> 3.12)
   rubocop (~> 1.38)
   rubocop-performance (~> 1.15)
   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,185 @@
-# Momento
+<head>
+  <meta name="Momento Ruby Client Library Documentation" content="Ruby client software development kit for Momento Cache">
+</head>
+<img src="https://docs.momentohq.com/img/momento-logo-forest.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-beta.svg)](https://github.com/momentohq/standards-and-practices/blob/main/docs/momento-on-github.md)
 
-## Installation
+# Momento Ruby Client Library
+
+Momento Cache is a fast, simple, pay-as-you-go caching solution without any of the operational overhead
+required by traditional caching solutions.  This repo contains the source code for the Momento Ruby client library.
+
+To get started with Momento you will need a Momento Auth Token. You can get one from the [Momento Console](https://console.gomomento.com).
+
+* Website: [https://www.gomomento.com/](https://www.gomomento.com/)
+* Momento Documentation: [https://docs.momentohq.com/](https://docs.momentohq.com/)
+* Getting Started: [https://docs.momentohq.com/getting-started](https://docs.momentohq.com/getting-started)
+* Ruby SDK Documentation: [https://docs.momentohq.com/sdks/ruby](https://docs.momentohq.com/sdks/ruby)
+* Discuss: [Momento Discord](https://discord.gg/3HkAKjUZGq)
+
+# Momento Ruby SDK
+
+To get started with Momento you will need a Momento API key. You can get one from the [Momento Console](https://console.gomomento.com/api-keys).
+
+* Website: [https://www.gomomento.com/](https://www.gomomento.com/)
+* Momento Documentation: [https://docs.momentohq.com/](https://docs.momentohq.com/)
+* Getting Started: [https://docs.momentohq.com/getting-started](https://docs.momentohq.com/getting-started)
+* Discuss: [Momento Discord](https://discord.gg/3HkAKjUZGq)
+
+## Packages
+
+The Momento Ruby SDK is available on [RubyGems](https://rubygems.org/gems/momento) 
 
 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
+```
+
+You will need Ruby 2.7 or newer.
 
-### M1 or M2 Macs
+An IDE with good Ruby support, such as [RubyMine](https://www.jetbrains.com/ruby/), is recommended.
 
-If you're using an M1 or M2 Mac, [you may have trouble installing the `grpc` gem](https://github.com/grpc/grpc/issues/31215).
+**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`.
 
-## Requirements
+## Usage
 
-* A Momento Auth Token is required, you can generate one using the Momento CLI
-* Ruby >= 2.7
+You can find this example code and more in [the examples directory](./examples) of this repository.
 
-## Usage
+```ruby
+# An example of the basic functionality of
+# Momento::CacheClient.
 
-```
 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')
 
-# Cached items will be deleted after 30 seconds.
-ttl = 30_000
+# 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::SimpleCacheClient.new(
-  auth_token: token,
-  default_ttl: ttl
+client = Momento::CacheClient.new(
+  configuration: Momento::Cache::Configurations::Laptop.latest,
+  credential_provider: credential_provider,
+  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.
+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("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
+
 ```
 
-You can run this code from [examples/basic.rb](examples/basic.rb).
+## Getting Started and Documentation
+
+General documentation on Momento and the Momento SDKs is available on the [Momento Docs website](https://docs.momentohq.com/). Specific usage examples for the Ruby SDK are coming soon!
+
+## Examples
+
+Check out full working code in the [example](./example/) directory of this repository!
+
+## Error Handling
+
+[Momento::CacheClient](https://github.com/momentohq/client-sdk-ruby/blob/main/lib/momento/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::CacheClient 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::CacheClient *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.
+
+## Issues
+
+Please report any bugs, issues, requests, and feedback via this repo's [issue tracker](https://github.com/momentohq/client-sdk-ruby/issues).
+
+## Developing
 
-## Contributing
+If you are interested in contributing to the SDK, please see the [CONTRIBUTING](./CONTRIBUTING.md) docs.
 
-See our [instructions for CONTRIBUTING](./CONTRIBUTING.md).
+----------------------------------------------------------------------------------------
+For more info, visit our website at [https://gomomento.com](https://gomomento.com)!

data/README.template.md

@@ -0,0 +1,93 @@
+{{ ossHeader }}
+
+# Momento Ruby SDK
+
+To get started with Momento you will need a Momento API key. You can get one from the [Momento Console](https://console.gomomento.com/api-keys).
+
+* Website: [https://www.gomomento.com/](https://www.gomomento.com/)
+* Momento Documentation: [https://docs.momentohq.com/](https://docs.momentohq.com/)
+* Getting Started: [https://docs.momentohq.com/getting-started](https://docs.momentohq.com/getting-started)
+* Discuss: [Momento Discord](https://discord.gg/3HkAKjUZGq)
+
+## Packages
+
+The Momento Ruby SDK is available on [RubyGems](https://rubygems.org/gems/momento) 
+
+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
+```
+
+You will need Ruby 2.7 or newer.
+
+An IDE with good Ruby support, such as [RubyMine](https://www.jetbrains.com/ruby/), is recommended.
+
+**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
+
+You can find this example code and more in [the examples directory](./examples) of this repository.
+
+```ruby
+{% include "./examples/example.rb" %}
+```
+
+## Getting Started and Documentation
+
+General documentation on Momento and the Momento SDKs is available on the [Momento Docs website](https://docs.momentohq.com/). Specific usage examples for the Ruby SDK are coming soon!
+
+## Examples
+
+Check out full working code in the [example](./example/) directory of this repository!
+
+## Error Handling
+
+[Momento::CacheClient](https://github.com/momentohq/client-sdk-ruby/blob/main/lib/momento/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::CacheClient 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::CacheClient *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.
+
+## Issues
+
+Please report any bugs, issues, requests, and feedback via this repo's [issue tracker](https://github.com/momentohq/client-sdk-ruby/issues).
+
+## Developing
+
+If you are interested in contributing to the SDK, please see the [CONTRIBUTING](./CONTRIBUTING.md) docs.
+
+{{ ossFooter }}

data/examples/.gitignore

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