No commit message

momentohq · Oct 18, 2022 · 858bd44 · 858bd44
2 parents abfcc23 + 7441786
commit 858bd44
Show file tree

Hide file tree

Showing 36 changed files with 665 additions and 124 deletions.
diff --git a/README.ja.md b/README.ja.md
@@ -0,0 +1,164 @@
+<head>
+  <meta name="Momento .NET Client Library Documentation" content=".NET client software development kit for Momento Serverless Cache">
+</head>
+<img src="https://docs.momentohq.com/img/logo.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)
+
+# Momento .NET Client Library
+
+:warning: Beta SDK :warning:
+
+こちらの SDK は Momento の公式 SDK ですが、API は Beta ステージです。詳細は上記の Beta ボタンをクリックしてください。
+
+Momento Serverless Cache の .NET クライアント SDK：従来のキャッシュが必要とするオペレーションオーバーヘッドが全く無く、速くて、シンプルで、従量課金のキャッシュです！
+
+## さあ、使用開始 :running:
+
+### 必要条件
+
+[`dotnet` runtime そしてコマンドラインツール](https://dotnet.microsoft.com/en-us/download)が必要です。インストール後は PATH に`dotnet`のコマンドがある事を確認してください。
+
+**IDE に関する注意事項**: [Microsoft Visual Studio](https://visualstudio.microsoft.com/vs), [JetBrains Rider](https://www.jetbrains.com/rider/)や[Microsoft Visual Studio Code](https://code.visualstudio.com/)の様な .NET 開発をサポートできる IDE が必要となります。
+
+### 使用方法
+
+使用開始の準備万全ですか？ではこちらの[examples](./examples/README.md)ディレクトリを参照してください！
+
+### Momento レスポンスタイプ
+
+Momento の`SimpleCacheClient`クラスの戻り値は IDE が容易にエラーを含む、有り得るレスポンスを予測できる様にデザインしてあります。[パターンマッチング](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching)を使用し、様々なレスポンスタイプを区別します。そうすることで、それらの API を使用する時、ランタイムでバグを発見するよりも、コンパイル時での安全性があります。
+
+以下が使用例です:
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Hit hitResponse)
+{
+  Console.WriteLine($"Looked up value: {hitResponse.ValueString}, Stored value: {VALUE}");
+}
+else if (getResponse is CacheGetResponse.Error getError)
+{
+  Console.WriteLine($"Error getting value: {getError.Message}");
+}
+```
+
+詳細は下記にある[エラーの対処法](#エラーの処理法)を参照してください。
+
+### インストール
+
+新規に.NET プロジェクトを作成し、Momento client library を dependency として追加してください：
+
+```bash
+mkdir my-momento-dotnet-project
+cd my-momento-dotnet-project
+dotnet new console
+dotnet add package Momento.Sdk
+```
+
+### 使用方法
+
+以下がご自身のプロジェクトに使用できるクイックスタートです：
+
+```csharp
+using System;
+using Momento.Sdk;
+using Momento.Sdk.Auth;
+using Momento.Sdk.Config;
+using Momento.Sdk.Responses;
+
+ICredentialProvider authProvider = new EnvMomentoTokenProvider("MOMENTO_AUTH_TOKEN");
+const string CACHE_NAME = "cache";
+const string KEY = "MyKey";
+const string VALUE = "MyData";
+TimeSpan DEFAULT_TTL = TimeSpan.FromSeconds(60);
+
+using (SimpleCacheClient client = new SimpleCacheClient(Configurations.Laptop.Latest(), authProvider, DEFAULT_TTL))
+{
+    var createCacheResponse = await client.CreateCacheAsync(CACHE_NAME);
+    if (createCacheResponse is CreateCacheResponse.Error createError)
+    {
+        Console.WriteLine($"Error creating cache: {createError.Message}. Exiting.");
+        Environment.Exit(1);
+    }
+
+    Console.WriteLine($"Setting key: {KEY} with value: {VALUE}");
+    var setResponse = await client.SetAsync(CACHE_NAME, KEY, VALUE);
+    if (setResponse is CacheSetResponse.Error setError)
+    {
+        Console.WriteLine($"Error setting value: {setError.Message}. Exiting.");
+        Environment.Exit(1);
+    }
+
+    Console.WriteLine($"Get value for key: {KEY}");
+    CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+    if (getResponse is CacheGetResponse.Hit hitResponse)
+    {
+        Console.WriteLine($"Looked up value: {hitResponse.ValueString}, Stored value: {VALUE}");
+    }
+    else if (getResponse is CacheGetResponse.Error getError)
+    {
+        Console.WriteLine($"Error getting value: {getError.Message}");
+    }
+}
+
+```
+
+上記のコードは MOMENTO_AUTH_TOKEN という環境変数が必要です。またこの値は有効な[Momento オーセンティケーショントークン](https://docs.momentohq.com/docs/getting-started#obtain-an-auth-token)でなければなりません。
+
+### エラーの処理法
+
+従来の例外処理とは異なり、SimpleCacheClient のメソッドを呼び出した際に起こるエラーは戻り値として浮上します。こうすることで、エラーの可視化を行い、必要なエラーのみを処理する際に IDE が更に役立つ様になります。（もっと例外についての私達の哲学を知りたい方はこちらの[例外はバグだ](https://www.gomomento.com/blog/exceptions-are-bugs)をぜひお読みください。またフィードバックもお待ちしております！）
+
+SimpleCacheClient メソッドからの戻り値の好ましい対応の仕方は[パターンマッチング](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching)を使用する方法です。こちらが簡単な例です：
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Hit hitResponse)
+{
+    Console.WriteLine($"\nLooked up value: {hitResponse.ValueString}, Stored value: {VALUE}");
+} else {
+      // `else if`内でパターンマッチングを使用し、他のケースも対処可能です。
+      // またデフォルトのケースであれば`else`ブロックで対処可能です。
+      // 各戻り値に対して、IDE上で有り得るタイプを提案してくれるはずです。
+      // この場合だと`CacheGetResponse.Miss`と `CacheGetResponse.Error`です。
+}
+```
+
+こちらのアプローチだと、キャッシュヒットの場合タイプが保証された`hitResponse`オブジェクトを受け取ります。キャッシュ読み込みの結果がミスもしくはエラーの場合でも何が起こったかの詳細な情報を含み、タイプの保証されたオブジェクトを受け取ることができます。
+
+エラーのレスポンスを受け取った場合、`Error`タイプはエラータイプを確認できる`ErrorCode` をいつも含んでいます：
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Error errorResponse)
+{
+    if (errorResponse.ErrorCode == MomentoErrorCode.TIMEOUT_ERROR) {
+       // こちらはクライアント側のタイムアウト意味しており、これが起こった場合元のデータを使用する事が可能です。
+    }
+}
+```
+
+SimpleCacheClient の戻り値以外では例外が起こる可能性があり、それらは通常通り処理する必要があるのでご注意ください。
+例えば、SimpleCacheClient のインスタンスを生成する際、無効なオーセンティケーショントークンは IllegalArgumentException の発生原因になります。
+
+### チューニング
+
+Momento client-libraries はあらかじめ用意されたコンフィグがすぐに使用できるようになっています。お客さまがビジネスにフォーカスできるよう、様々な環境に適したチューニングを私達の方で担いたいと思っています。
+(ブログシリーズも存在ます！ [ショックなほどシンプル: 大変な作業を担ってくれるキャッシュクライアント](https://www.gomomento.com/blog/shockingly-simple-cache-clients-that-do-the-hard-work-for-you))
+
+`Configurations`ネームスペースにてあらかじめ用意されたコンフィグを確認していただけます。以下がそれらのコンフィグになります：
+
+- `Configurations.Laptop` - こちらは開発環境に適しており、Momento の使用テストを行いたい場合に最適です。タイムアウトは緩く設定されているので、ネットワークレイテンシーは少し高くなる事が予想されます。
+- `Configurations.InRegion.Default` - こちらはご自身のクライアントが Momento と同じリージョンで実行されている場合に最適なデフォルト設置です。タイムアウトとリトライは Laptop 設定よりも厳しく設定してあります。
+- `Configurations.InRegion.LowLatency` - こちらの設定は p99.9 のレイテンシを最優先しており、そのためスループットが低くなる場合があります。こちらの設定はキャッシュの不可用性が高いレイテンシーを起こしたくない場合に使用してください。
+
+これらのコンフィグが大半のお客様のニーズにお応えできると思いますが、不足している部分などありましたらお気軽に GitHub でチケット作成または`[email protected]`にご連絡ください。お客様の使用例を聞いて、より優れたコンフィグを提供したいと考えております。
+
+あらかじめ用意されたコンフィグ以外にカスタムのコンフィグを作成されたい場合はこちらの
+[上級者レベルコンフィグガイド](./docs/advanced-config.md)をご覧ください。
+
+---
+
+更なる詳細は私達のウェブサイト[https://jp.gomomento.com/](https://jp.gomomento.com/)をご確認ください！
diff --git a/README.md b/README.md
@@ -19,14 +19,43 @@ any of the operational overhead required by traditional caching solutions!
 
 
 
+Japanese: [日本語](README.ja.md)
+
 ## Getting Started :running:
 
 ### Requirements
 
-You will need the [`dotnet` runtime and command line tools](https://dotnet.microsoft.com/en-us/download).  After installing them, you should have the `dotnet` command on your PATH.
+You will need the [`dotnet` runtime and command line tools](https://dotnet.microsoft.com/en-us/download). After installing them, you should have the `dotnet` command on your PATH.
 
 **IDE Notes**: You will most likely want an IDE that supports .NET development, such as [Microsoft Visual Studio](https://visualstudio.microsoft.com/vs), [JetBrains Rider](https://www.jetbrains.com/rider/), or [Microsoft Visual Studio Code](https://code.visualstudio.com/).
 
+### Examples
+
+Ready to dive right in? Just check out the [examples](./examples/README.md) directory for complete, working examples of
+how to use the SDK.
+
+### Momento Response Types
+
+The return values of the methods on the Momento `SimpleCacheClient` class are designed to allow you to use your
+IDE to help you easily discover all the possible responses, including errors. We use [pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching) to distinguish between different types of responses,
+which means that you can get compile-time safety when interacting with the API, rather than having bugs sneak in at runtime.
+
+Here's an example:
+
+```csharp
+CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
+if (getResponse is CacheGetResponse.Hit hitResponse)
+{
+  Console.WriteLine($"Looked up value: {hitResponse.ValueString}, Stored value: {VALUE}");
+}
+else if (getResponse is CacheGetResponse.Error getError)
+{
+  Console.WriteLine($"Error getting value: {getError.Message}");
+}
+```
+
+See the [Error Handling](#error-handling) section below for more details.
+
 ### Installation
 
 To create a new .NET project and add the Momento client library as a dependency:
@@ -40,8 +69,6 @@ dotnet add package Momento.Sdk
 
 ### Usage
 
-Checkout our [examples](./examples/README.md) directory for complete examples of how to use the SDK.
-
 Here is a quickstart you can use in your own project:
 
 ```csharp
@@ -91,35 +118,15 @@ using (SimpleCacheClient client = new SimpleCacheClient(Configurations.Laptop.La
 Note that the above code requires an environment variable named MOMENTO_AUTH_TOKEN which must
 be set to a valid [Momento authentication token](https://docs.momentohq.com/docs/getting-started#obtain-an-auth-token).
 
-**Momento Response Types**: The Momento `SimpleCacheClient` uses response types in a way you may not be familiar with and deserves
-a word of explanation upfront. Each response object's actual type will be a subtype (e.g., `CacheGetResponse.Hit`) of the requested response type (e.g., `CacheGetResponse`) and must be resolved to the correct subtype before accessing its properties. We recommend using [pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching) to resolve the response's subtype and allow us to access the appropriate properties for that type:
-
-```csharp
-CreateCacheResponse createResponse = client.CreateCacheAsync("example-cache");
-if (createResponse is CreateCacheResponse.CacheAlreadyExists)
-{
-      // this may or may not be expected; handle as appropriate.
-}
-else if (createResponse is CreateCacheResponse.Error createError)
-{
-      if (createError.ErrorCode == MomentoErrorCode.LIMIT_EXCEEDED_ERROR)
-      {
-            // we've used our quota of caches; we should contact [email protected]!
-      }
-}
-```
-
-See the "Error Handling" section below for more details.
-
 ### Error Handling
 
 Error that occur in calls to SimpleCacheClient methods are surfaced to developers as part of the return values of
-the calls, as opposed to by throwing exceptions.  This makes them more visible, and allows your IDE to be more
-helpful in ensuring that you've handled the ones you care about.  (For more on our philosophy about this, see our
-blog post on why [Exceptions are bugs](https://www.gomomento.com/blog/exceptions-are-bugs).  And send us any
+the calls, as opposed to by throwing exceptions. This makes them more visible, and allows your IDE to be more
+helpful in ensuring that you've handled the ones you care about. (For more on our philosophy about this, see our
+blog post on why [Exceptions are bugs](https://www.gomomento.com/blog/exceptions-are-bugs). And send us any
 feedback you have!)
 
-The preferred way of interpreting the return values from SimpleCacheClient methods is using [Pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching).  Here's a quick example:
+The preferred way of interpreting the return values from SimpleCacheClient methods is using [Pattern matching](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching). Here's a quick example:
 
 ```csharp
 CacheGetResponse getResponse = await client.GetAsync(CACHE_NAME, KEY);
@@ -134,7 +141,7 @@ if (getResponse is CacheGetResponse.Hit hitResponse)
 }
 ```
 
-Using this approach, you get a type-safe `hitResponse` object in the case of a cache hit.  But if the cache read
+Using this approach, you get a type-safe `hitResponse` object in the case of a cache hit. But if the cache read
 results in a Miss or an error, you'll also get a type-safe object that you can use to get more info about what happened.
 
 In cases where you get an error response, `Error` types will always include an `ErrorCode` that you can use to check
@@ -150,25 +157,32 @@ if (getResponse is CacheGetResponse.Error errorResponse)
 }
 ```
 
-Note that, outside of SimpleCacheClient responses, exceptions can occur and should be handled as usual. For example, trying to instantiate a SimpleCacheClient with an invalid authentication token will result in an
-IllegalArgumentException being thrown.
+Note that, outside of SimpleCacheClient responses, exceptions can occur and should be handled as usual. For example, trying
+to instantiate a SimpleCacheClient with an invalid authentication token will result in an IllegalArgumentException being thrown.
 
 ### Tuning
 
-Momento client-libraries provide pre-built configuration bundles out-of-the-box.  We want to do the hard work of
+Momento client-libraries provide pre-built configuration bundles out-of-the-box. We want to do the hard work of
 tuning for different environments for you, so that you can focus on the things that are unique to your business.
-(We even have a blog series about it!  [Shockingly simple: Cache clients that do the hard work for you](https://www.gomomento.com/blog/shockingly-simple-cache-clients-that-do-the-hard-work-for-you))
+(We even have a blog series about it! [Shockingly simple: Cache clients that do the hard work for you](https://www.gomomento.com/blog/shockingly-simple-cache-clients-that-do-the-hard-work-for-you))
 
-You can find the pre-built configurations in our `Configurations` namespace.  Some of the pre-built configurations that
+You can find the pre-built configurations in our `Configurations` namespace. Some of the pre-built configurations that
 you might be interested in:
 
-- `Configurations.Laptop` - this one is a development environment, just for poking around.  It has relaxed timeouts
-      and assumes that your network latencies might be a bit high.
+- `Configurations.Laptop` - this one is a development environment, just for poking around. It has relaxed timeouts
+  and assumes that your network latencies might be a bit high.
 - `Configurations.InRegion.Default` - provides defaults suitable for an environment where your client is running in the same region as the Momento
-      service.  It has more aggressive timeouts and retry behavior than the Laptop config.
+  service. It has more aggressive timeouts and retry behavior than the Laptop config.
 - `Configurations.InRegion.LowLatency` - This config prioritizes keeping p99.9 latencies as low as possible, potentially sacrificing
-      some throughput to achieve this.  Use this configuration if the most important factor is to ensure that cache
-      unavailability doesn't force unacceptably high latencies for your own application.
+  some throughput to achieve this. Use this configuration if the most important factor is to ensure that cache
+  unavailability doesn't force unacceptably high latencies for your own application.
+
+We hope that these configurations will meet the needs of most users, but if you find them lacking in any way, please
+open a github issue, or contact us at `[email protected]`. We would love to hear about your use case so that we
+can fix or extend the pre-built configs to support it.
+
+If you do need to customize your configuration beyond what our pre-builts provide, see the
+[Advanced Configuration Guide](./docs/advanced-config.md).
 
 ----------------------------------------------------------------------------------------
 For more info, visit our website at [https://gomomento.com](https://gomomento.com)!