-
Notifications
You must be signed in to change notification settings - Fork 58
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into obj-compat-tests
# Conflicts: # NATS.Client.sln
- Loading branch information
Showing
65 changed files
with
2,955 additions
and
312 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| # Object Store | ||
|
|
||
| [The Object Store](https://docs.nats.io/nats-concepts/jetstream/obj_store) is very similar to the Key Value Store in that you put and get data using a key. | ||
| The difference being that Object store allows for the storage of objects that can be of any size. | ||
|
|
||
| Under the covers Object Store is a client side construct that allows you to store and retrieve chunks of data | ||
| by a key using JetStream as the stream persistence engine. It's a simple, yet powerful way to store | ||
| and retrieve large data like files. | ||
|
|
||
| To be able to use Object Store you need to enable JetStream by running the server with `-js` flag e.g. `nats-server -js`. | ||
|
|
||
| ## Object Store Quick Start | ||
|
|
||
| [Download the latest](https://nats.io/download/) `nats-server` for your platform and run it with JetStream enabled: | ||
|
|
||
| ```shell | ||
| $ nats-server -js | ||
| ``` | ||
|
|
||
| Install `NATS.Client.ObjectStore` preview from Nuget. | ||
|
|
||
| Before we can do anything, we need an Object Store context: | ||
|
|
||
| ```csharp | ||
| await using var nats = new NatsConnection(); | ||
| var js = new NatsJSContext(nats); | ||
| var obj = new NatsObjContext(js); | ||
| ``` | ||
|
|
||
| Let's create our store first. In Object Store, a bucket is simply a storage for key/object pairs: | ||
|
|
||
| ```csharp | ||
| var store = await obj.CreateObjectStore("test-bucket"); | ||
| ``` | ||
|
|
||
| Now that we have a bucket in our stream, let's see its status using the [NATS command | ||
| line client](https://github.com/nats-io/natscli): | ||
|
|
||
| ```shell | ||
| $ nats object ls | ||
| ╭──────────────────────────────────────────────────────────────────────╮ | ||
| │ Object Store Buckets │ | ||
| ├─────────────┬─────────────┬─────────────────────┬──────┬─────────────┤ | ||
| │ Bucket │ Description │ Created │ Size │ Last Update │ | ||
| ├─────────────┼─────────────┼─────────────────────┼──────┼─────────────┤ | ||
| │ test-bucket │ │ 2023-10-18 14:10:27 │ 0 B │ never │ | ||
| ╰─────────────┴─────────────┴─────────────────────┴──────┴─────────────╯ | ||
| ``` | ||
|
|
||
| We can save objects in a bucket by putting them using a key, which is `my/random/data.bin` in our case. We can also retrieve the | ||
| saved value by its key: | ||
|
|
||
| ```csharp | ||
| await store.PutAsync("my/random/data.bin", File.OpenRead("data.bin")); | ||
|
|
||
| await store.GetAsync("my/random/data.bin", File.OpenWrite("data_copy.bin")); | ||
| ``` | ||
|
|
||
| We can also confirm that our value is persisted by using the NATS command line: | ||
|
|
||
| ```shell | ||
| $ nats object info test-bucket my/random/data.bin | ||
| Object information for test-bucket > my/random/data.bin | ||
|
|
||
| Size: 10 MiB | ||
| Modification Time: 18 Oct 23 14:54 +0000 | ||
| Chunks: 80 | ||
| Digest: SHA-256 d34334673e4e2b2300c09550faa5e2b6d0f04245a1d0b664454bb922da56 | ||
| ``` | ||
|
|
||
| ## Other Operations | ||
|
|
||
| ### Get Info | ||
|
|
||
| We can get information about a key in a bucket: | ||
|
|
||
| ```csharp | ||
| var metadata = await store.GetInfoAsync("my/random/data.bin"); | ||
|
|
||
| Console.WriteLine("Metadata:"); | ||
| Console.WriteLine($" Bucket: {metadata.Bucket}"); | ||
| Console.WriteLine($" Name: {metadata.Name}"); | ||
| Console.WriteLine($" Size: {metadata.Size}"); | ||
| Console.WriteLine($" Time: {metadata.MTime}"); | ||
| Console.WriteLine($" Chunks: {metadata.Chunks}"); | ||
|
|
||
| // Outputs: | ||
| // Metadata: | ||
| // Bucket: test-bucket | ||
| // Name: my/random/data.bin | ||
| // Size: 10485760 | ||
| // Time: 18/10/2023 15:13:22 +00:00 | ||
| // Chunks: 80 | ||
| ``` | ||
|
|
||
| ### Delete | ||
|
|
||
| We can delete a key from a bucket: | ||
|
|
||
| ```csharp | ||
| await store.DeleteAsync("my/random/data.bin"); | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| # Services | ||
|
|
||
| [Services](https://docs.nats.io/using-nats/developer/services) is a protocol that provides first-class services support | ||
| for NATS clients and it's supported by NATS tooling. This services protocol is an agreement between clients and tooling and | ||
| doesn't require any special functionality from the NATS server or JetStream. | ||
|
|
||
| To be able to use Services you need to running the `nats-server`. | ||
|
|
||
| ## Services Quick Start | ||
|
|
||
| [Download the latest](https://nats.io/download/) `nats-server` for your platform and run it: | ||
|
|
||
| ```shell | ||
| $ nats-server | ||
| ``` | ||
|
|
||
| Install `NATS.Client.Services` preview from Nuget. | ||
|
|
||
| Before we can do anything, we need a Services context: | ||
|
|
||
| ```csharp | ||
| await using var nats = new NatsConnection(); | ||
| var svc = new NatsSvcContext(nats); | ||
| ``` | ||
|
|
||
| Let's create our first service: | ||
|
|
||
| ```csharp | ||
| await using var testService = await svc.AddServiceAsync("test", "1.0.0"); | ||
| ``` | ||
|
|
||
| Now that we have a service in our stream, let's see its status using the [NATS command | ||
| line client](https://github.com/nats-io/natscli) (make sure you have at least v0.1.1): | ||
|
|
||
| ```shell | ||
| $ nats --version | ||
| 0.1.1 | ||
| ``` | ||
|
|
||
| ```shell | ||
| $ nats micro info test | ||
| Service Information | ||
|
|
||
| Service: test (Bw6eqhVYs3dbNzZecuuFOV) | ||
| Description: | ||
| Version: 1.0.0 | ||
|
|
||
| Endpoints: | ||
|
|
||
| Statistics for 0 Endpoint(s): | ||
| ``` | ||
|
|
||
| Now we can add endpoints to our service: | ||
|
|
||
| ```csharp | ||
| await testService.AddEndPointAsync<int>(name: "divide42", handler: async m => | ||
| { | ||
| if (m.Data == 0) | ||
| { | ||
| await m.ReplyErrorAsync(400, "Division by zero"); | ||
| return; | ||
| } | ||
|
|
||
| await m.ReplyAsync(42 / m.Data); | ||
| }); | ||
| ``` | ||
|
|
||
| We can also confirm that our endpoint is registered by using the NATS command line: | ||
|
|
||
| ```shell | ||
| $ nats req divide42 2 | ||
| 11:34:03 Sending request on "divide42" | ||
| 11:34:03 Received with rtt 9.5823ms | ||
| 21 | ||
|
|
||
| $ nats micro stats test | ||
| ╭──────────────────────────────────────────────────────────────────────────────────────────────────────╮ | ||
| │ test Service Statistics │ | ||
| ├────────────────────────┬──────────┬──────────┬─────────────┬────────┬─────────────────┬──────────────┤ | ||
| │ ID │ Endpoint │ Requests │ Queue Group │ Errors │ Processing Time │ Average Time │ | ||
| ├────────────────────────┼──────────┼──────────┼─────────────┼────────┼─────────────────┼──────────────┤ | ||
| │ RH6q9Y6qM8em8m6lG2yN34 │ divide42 │ 1 │ q │ 0 │ 1ms │ 1ms │ | ||
| ├────────────────────────┼──────────┼──────────┼─────────────┼────────┼─────────────────┼──────────────┤ | ||
| │ │ │ 1 │ │ 0 │ 1MS │ 1MS │ | ||
| ╰────────────────────────┴──────────┴──────────┴─────────────┴────────┴─────────────────┴──────────────╯ | ||
| ``` | ||
|
|
||
| ## Groups | ||
|
|
||
| A group is a collection of endpoints. These are optional and can provide a logical association between endpoints | ||
| as well as an optional common subject prefix for all endpoints. | ||
|
|
||
| You can group your endpoints optionally in different [queue groups](https://docs.nats.io/nats-concepts/core-nats/queue): | ||
|
|
||
| ```csharp | ||
| var grp1 = await testService.AddGroupAsync("grp1"); | ||
|
|
||
| await grp1.AddEndPointAsync<int>(name: "ep1", handler: async m => | ||
| { | ||
| // handle message | ||
| }); | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.