GITBOOK-101: add Rethinkconn

bk62 · Dec 7, 2023 · c801cd4 · c801cd4
1 parent a747e82
commit c801cd4
Show file tree

Hide file tree

Showing 28 changed files with 546 additions and 475 deletions.
diff --git a/.gitbook/assets/image (1).png b/.gitbook/assets/image (1).png
diff --git a/.gitbook/assets/image (2).png b/.gitbook/assets/image (2).png
diff --git a/.gitbook/assets/image.png b/.gitbook/assets/image.png
diff --git a/README.md b/README.md
@@ -1,12 +1,34 @@
-# Hello 👋
+---
+layout:
+  title:
+    visible: true
+  description:
+    visible: true
+  tableOfContents:
+    visible: true
+  outline:
+    visible: true
+  pagination:
+    visible: true
+---
+
+# Welcome
+
+## Upcoming Event | RethinkConn 2024
+
+> Don't miss RethinkConn 2024 | A free virtual event for NATS developers and end-users\
+> January 11, 2024 Register today! [https://www.crowdcast.io/c/rethinkconn-2024](https://www.crowdcast.io/c/rethinkconn-2024)\
+> \
+> ![](<.gitbook/assets/image (2).png>)
+
 ## Welcome to the Official NATS Documentation
 
 Here you will find everything you need to know about the Connective Technology for Adaptive Edge & Distributed Systems - NATS!
 
 NATS is Open Source as is this documentation. Please [let us know](mailto:[email protected]) if you have updates and/or suggestions for these docs. You can also create a Pull Request using the `Edit on GitHub` link on each page.
 
 ### Additional questions?
-Feel free to chat with us on Slack [slack.nats.io](https://slack.nats.io).
 
+Feel free to chat with us on Slack [slack.nats.io](https://slack.nats.io).
 
 Thank you from the entire NATS Team of Maintainers for your interest in NATS!
diff --git a/nats-concepts/core-nats/queue-groups/queue.md b/nats-concepts/core-nats/queue-groups/queue.md
@@ -1,14 +1,17 @@
-# Queue Groups  
-When subscribers register themselves to receive messages from a publisher, the 1:N fan-out pattern of messaging ensures that any message sent by a publisher, reaches all subscribers that have registered. NATS provides an additional feature named "queue", which allows subscribers to register themselves as part of a queue. Subscribers that are part of a queue, form the "queue group".  
-
-## How queue groups function  
-As an example, consider message delivery occurring in the 1:N pattern to all subscribers based on the subject name (delivery happens even to subscribers that are not part of a queue group). If a subscriber is registered based on a queue name, it will always receive messages it is subscribed to, based on the subject name. However, if more subscribers are added to the same queue name, they become a queue group, and only one randomly chosen subscriber of the queue group will consume a message each time a message is received by the queue group. Such distributed queues are a built-in load balancing feature that NATS provides.  
-
-**Advantages**  
-- Ensures application fault tolerance
-- Workload processing can be scaled up or down
-- No extra configuration required
-- Queue groups are defined by the application and their queue subscribers, rather than the server configuration
+# Queue Groups
+
+When subscribers register themselves to receive messages from a publisher, the 1:N fan-out pattern of messaging ensures that any message sent by a publisher, reaches all subscribers that have registered. NATS provides an additional feature named "queue", which allows subscribers to register themselves as part of a queue. Subscribers that are part of a queue, form the "queue group".
+
+## How queue groups function
+
+As an example, consider message delivery occurring in the 1:N pattern to all subscribers based on the subject name (delivery happens even to subscribers that are not part of a queue group). If a subscriber is registered based on a queue name, it will always receive messages it is subscribed to, based on the subject name. However, if more subscribers are added to the same queue name, they become a queue group, and only one randomly chosen subscriber of the queue group will consume a message each time a message is received by the queue group. Such distributed queues are a built-in load balancing feature that NATS provides.
+
+**Advantages**
+
+* Ensures application fault tolerance
+* Workload processing can be scaled up or down
+* No extra configuration required
+* Queue groups are defined by the application and their queue subscribers, rather than the server configuration
 
 Queue group names follow the same naming rules as [subjects](../../subjects.md). Foremost, they are case sensitive and cannot contain whitespace. Consider structuring queue groups hierarchically using a period `.`. Some server functionalities can use [wildcard matching](../../subjects.md#wildcards) on them.
 
@@ -20,7 +23,7 @@ When a request is made to a service (request/reply) and the NATS Server knows th
 
 ## Stream as a queue
 
-With [JetStream](../../jetstream/readme.md) a stream can also be used as a queue by setting the retention policy to `WorkQueuePolicy` and leveraging [`pull` consumers](../../jetstream/consumers.md) to get easy horizontal scalability of the processing (or using an explicit ack push consumer with a queue group of subscribers).
+With [JetStream](../../jetstream/) a stream can also be used as a queue by setting the retention policy to `WorkQueuePolicy` and leveraging [`pull` consumers](../../jetstream/consumers.md) to get easy horizontal scalability of the processing (or using an explicit ack push consumer with a queue group of subscribers).
 
 ![](../../../.gitbook/assets/queue.svg)
 
@@ -30,4 +33,4 @@ When connecting to a globally distributed NATS super-cluster, there is an automa
 
 ### Tutorial
 
-Try NATS queue subscriptions on your own, using a live server by walking through the [queueing walkthrough](queues_walkthrough.md).
+Try NATS queue subscriptions on your own, using a live server by walking through the [queueing walkthrough](queues\_walkthrough.md).
diff --git a/nats-concepts/core-nats/request-reply/reqreply.md b/nats-concepts/core-nats/request-reply/reqreply.md
@@ -1,29 +1,26 @@
 # Request-Reply
 
-Request-Reply is a common pattern in modern distributed systems. A request is sent, and the application either waits on the response with a certain timeout, or receives a response asynchronously.  
-  
-The increased complexity of modern systems necessitates features like [location transparency](https://en.wikipedia.org/wiki/Location_transparency), scale-up and scale-down, observability (measuring a system's state based on the data it generates) and more. In order to implement this feature-set, various other technologies needed to incorporate additional components, sidecars (processes or services that support the primary application) and proxies. NATS on the other hand, implemented Request-Reply much more easily.   
-  
+Request-Reply is a common pattern in modern distributed systems. A request is sent, and the application either waits on the response with a certain timeout, or receives a response asynchronously.
+
+The increased complexity of modern systems necessitates features like [location transparency](https://en.wikipedia.org/wiki/Location\_transparency), scale-up and scale-down, observability (measuring a system's state based on the data it generates) and more. In order to implement this feature-set, various other technologies needed to incorporate additional components, sidecars (processes or services that support the primary application) and proxies. NATS on the other hand, implemented Request-Reply much more easily.
+
 ### NATS makes Request-Reply simple and powerful
-- NATS supports the Request-Reply pattern using its core communication mechanism — publish and subscribe. A request is published on a given subject using a reply subject. Responders listen on that subject and send responses to the reply subject. Reply subjects are called "**inbox**". These are unique subjects that are dynamically directed back to the requester, regardless of the location of either party.  
-
-- Multiple NATS responders can form dynamic queue groups. Therefore, it's not necessary to manually add or remove subscribers from the group for them to start or stop being distributed messages. It’s done automatically. This allows responders to scale up or down as per demand.  
-
-- NATS applications "drain before exiting" (processing buffered messages before closing the connection). This allows the applications to scale down without dropping requests.   
-
-- Since NATS is based on publish-subscribe, observability is as simple as running another application that can view requests and responses to measure latency, watch for anomalies, direct scalability and more.  
-
-- The power of NATS even allows multiple responses, where the first response is utilized and the system efficiently discards the additional ones. This allows for a sophisticated pattern to have multiple responders, reduce response latency and jitter. 
+
+* NATS supports the Request-Reply pattern using its core communication mechanism — publish and subscribe. A request is published on a given subject using a reply subject. Responders listen on that subject and send responses to the reply subject. Reply subjects are called "**inbox**". These are unique subjects that are dynamically directed back to the requester, regardless of the location of either party.
+* Multiple NATS responders can form dynamic queue groups. Therefore, it's not necessary to manually add or remove subscribers from the group for them to start or stop being distributed messages. It’s done automatically. This allows responders to scale up or down as per demand.
+* NATS applications "drain before exiting" (processing buffered messages before closing the connection). This allows the applications to scale down without dropping requests.
+* Since NATS is based on publish-subscribe, observability is as simple as running another application that can view requests and responses to measure latency, watch for anomalies, direct scalability and more.
+* The power of NATS even allows multiple responses, where the first response is utilized and the system efficiently discards the additional ones. This allows for a sophisticated pattern to have multiple responders, reduce response latency and jitter.
 
 ### The pattern
 
 ![](../../../.gitbook/assets/reqrepl.svg)
 
-Try NATS request-reply on your own, using a live server by walking through the [request-reply walkthrough.](reqreply_walkthrough.md)
+Try NATS request-reply on your own, using a live server by walking through the [request-reply walkthrough.](reqreply\_walkthrough.md)
 
 ### No responders
 
-When a request is sent to a subject that has no subscribers, it can be convenient to know about it right away. For this use-case, a NATS client can [opt-into no_responder messages](reference/reference-protocols/nats-protocol#syntax-1). This requires a server and client that support headers. When enabled, a request sent to a subject with no subscribers will immediately receive a reply that has no body, and a `503` status.
+When a request is sent to a subject that has no subscribers, it can be convenient to know about it right away. For this use-case, a NATS client can [opt-into no\_responder messages](../../../reference/nats-protocol/nats-protocol/#syntax-1). This requires a server and client that support headers. When enabled, a request sent to a subject with no subscribers will immediately receive a reply that has no body, and a `503` status.
 
 Most clients will represent this case by raising or returning an error. For example:
 

diff --git a/nats-concepts/jetstream/key-value-store/kv_walkthrough.md b/nats-concepts/jetstream/key-value-store/kv_walkthrough.md
@@ -1,4 +1,4 @@
-# NATS Key/Value Store Walkthrough
+# Key/Value Store Walkthrough
 
 ## Prerequisite: enabling JetStream
 
@@ -8,7 +8,8 @@ You can then check that JetStream is enabled by using
 
 ```shell
 nats account info
-``` 
+```
+
 ```
 Connection Information:
 
@@ -31,7 +32,7 @@ JetStream Account Information:
 
 If you see the below instead then JetStream is _not_ enabled
 
-```text
+```
 JetStream Account Information:
 
    JetStream is not supported in this account
@@ -44,7 +45,8 @@ Just like you have to create streams before you can use them, you need to first
 ```shell
 nats kv add my_kv
 ```
-```text
+
+```
 my_kv Key-Value Store Status
 
          Bucket Name: my_kv
@@ -65,18 +67,19 @@ nats kv put my_kv Key1 Value1
 ```
 
 which should return `Value1`
+
 ## Getting a value
 
 Now that we have value stored at key "Key1" we can retrieve that value with a 'get':
 
 ```shell
 nats kv get my_kv Key1
 ```
+
 ```
 my_kv > Key1 created @ 12 Oct 21 20:08 UTC
 
 Value1
-
 ```
 
 ## Deleting a value
@@ -92,6 +95,7 @@ For example run `nats kv watch my_kv`: this will start a watcher on the bucket w
 ```shell
 nats kv watch my_kv
 ```
+
 ```
 [2021-10-12 13:15:03] DEL my_kv > Key1
 ```
@@ -114,4 +118,4 @@ Once you are finished playing, you can easily delete the KV bucket and release t
 
 ```shell
 nats kv rm my_kv
-```
+```
diff --git a/nats-concepts/jetstream/object-store/obj_walkthrough.md b/nats-concepts/jetstream/object-store/obj_walkthrough.md
@@ -1,4 +1,5 @@
-# NATS Object Store Walkthrough
+# Object Store Walkthrough
+
 **NOTICE: Experimental Preview**
 
 ## Prerequisite: enabling JetStream
@@ -9,8 +10,10 @@ You can then check that JetStream is enabled by using
 
 ```shell
 nats account info
-``` 
+```
+
 Which should output something like:
+
 ```
 Connection Information:
 
@@ -33,7 +36,7 @@ JetStream Account Information:
 
 If you see the below instead then JetStream is _not_ enabled
 
-```text
+```
 JetStream Account Information:
 
    JetStream is not supported in this account
@@ -46,7 +49,9 @@ Just like you need to create streams before you can use them you need to first c
 ```shell
 nats object add myobjbucket
 ```
+
 which outputs
+
 ```
 myobjbucket Object Store Status
 
@@ -64,8 +69,8 @@ myobjbucket Object Store Status
 ```shell
 nats object put myobjbucket ~/Movies/NATS-logo.mov
 ```
-```
 
+```
 1.5 GiB / 1.5 GiB [====================================================================================]
 
 Object information for myobjbucket > /Users/jnmoyne/Movies/NATS-logo.mov
@@ -81,6 +86,7 @@ Object information for myobjbucket > /Users/jnmoyne/Movies/NATS-logo.mov
 ```shell
 nats object ls myobjbucket
 ```
+
 ```
 ╭───────────────────────────────────────────────────────────────────────────╮
 │                              Bucket Contents                              │
@@ -96,8 +102,8 @@ nats object ls myobjbucket
 ```shell
 nats object get myobjbucket ~/Movies/NATS-logo.mov
 ```
-```
 
+```
 1.5 GiB / 1.5 GiB [====================================================================================]
 
 Wrote: 1.5 GiB to /Users/jnmoyne/NATS-logo.mov in 5.68s average 279 MiB/s
@@ -108,6 +114,7 @@ Wrote: 1.5 GiB to /Users/jnmoyne/NATS-logo.mov in 5.68s average 279 MiB/s
 ```shell
 nats object rm myobjbucket ~/Movies/NATS-logo.mov
 ```
+
 ```
 ? Delete 1.5 GiB byte file myobjbucket > /Users/jnmoyne/Movies/NATS-logo.mov? Yes
 Removed myobjbucket > /Users/jnmoyne/Movies/NATS-logo.mov
@@ -127,6 +134,7 @@ myobjbucket Object Store Status
 ```shell
 nats object info myobjbucket
 ```
+
 ```
 myobjbucket Object Store Status
 
@@ -144,6 +152,7 @@ myobjbucket Object Store Status
 ```shell
 nats object watch myobjbucket
 ```
+
 ```
 [2022-04-13 17:51:28] PUT myobjbucket > /Users/jnmoyne/Movies/NATS-logo.mov: 1.5 GiB bytes in 12,656 chunks
 [2022-04-13 17:53:27] DEL myobjbucket > /Users/jnmoyne/Movies/NATS-logo.mov
@@ -156,6 +165,7 @@ You can seal a bucket, meaning that no further changes are allowed on that bucke
 ```shell
 nats object seal myobjbucket
 ```
+
 ```
 ? Really seal Bucket myobjbucket, sealed buckets can not be unsealed or modified Yes
 myobjbucket has been sealed
@@ -172,4 +182,4 @@ myobjbucket Object Store Status
 
 ## Deleting a bucket
 
-Using `nats object rm myobjbucket` will delete the bucket and all the files stored in it.
+Using `nats object rm myobjbucket` will delete the bucket and all the files stored in it.
diff --git a/nats-concepts/subject_mapping.md b/nats-concepts/subject_mapping.md
@@ -1,8 +1,9 @@
-# Subject Mapping and Transforms
+# Subject Mapping and Partitioning
 
 Subject mapping and transforms is a very powerful feature of the NATS server, useful for scaling some forms of distributed message processing through partitioning, for canary deployments, A/B testing, chaos testing, and migrating to a new subject namespace.
 
-There are multiple places where you can apply subject transforms: 
+There are multiple places where you can apply subject transforms:
+
 * At the Core NATS level each account has its own set of subject transforms, which will apply to any message published by client applications for that account, and you can also use subject transforms as part of the imports and exports between accounts.
 * At the JetStream level you can define subject transforms as part of the stream configuration, which will apply to any message published to that stream, and you can also use subject transforms as part of the mirror and source configurations and for message republishing.
 
@@ -11,7 +12,7 @@ When not using operator JWT security, you can define the Core NATS account level
 When using operator JWT security with the built-in resolver you define the transforms and the import/exports in the account JWT so after modifying them they will take effect as soon as you push the updated account JWT to the servers.
 
 {% hint style="info" %}
-You can easily test subject transforms using the [`nats`](../using-nats/nats-tools/nats_cli/readme.md) CLI tool command `nats server mapping`.
+You can easily test subject transforms using the [`nats`](../using-nats/nats-tools/nats\_cli/) CLI tool command `nats server mapping`.
 {% endhint %}
 
 ## Simple Mapping
@@ -46,26 +47,26 @@ You can split a token on each occurrence of a separator string using the `split(
 
 Examples:
 
-- Split on '-': `nats server mapping "*" "{{split(1,-)}}" foo-bar` returns `foo.bar`.
-- Split on '--': `nats server mapping "*" "{{split(1,--)}}" foo--bar` returns `foo.bar`.
+* Split on '-': `nats server mapping "*" "{{split(1,-)}}" foo-bar` returns `foo.bar`.
+* Split on '--': `nats server mapping "*" "{{split(1,--)}}" foo--bar` returns `foo.bar`.
 
 ### Splitting at an offset
 
 You can split a token in two at a specific location from the start or the end of the token using the `SplitFromLeft(wildcard index, offset)` and `SplitFromRight(wildcard index, offset)` transform functions (note that the upper camel case on all subject transform function names is optional you can also use all lowercase function names if you prefer).
 
 Examples:
 
-- Split the token at 4 from the left: `nats server mapping "*" "{{splitfromleft(1,4)}}" 1234567` returns `1234.567`.
-- Split the token at 4 from the right: `nats server mapping "*" "{{splitfromright(1,4)}}" 1234567` returns `123.4567`.
+* Split the token at 4 from the left: `nats server mapping "*" "{{splitfromleft(1,4)}}" 1234567` returns `1234.567`.
+* Split the token at 4 from the right: `nats server mapping "*" "{{splitfromright(1,4)}}" 1234567` returns `123.4567`.
 
 ## Slicing Tokens
 
 You can slice tokens into multiple parts at a specific interval from the start or the end of the token by using the `SliceFromLeft(wildcard index, number of characters)` and `SliceFromRight(wildcard index, number of characters)` mapping functions.
 
 Examples:
 
-- Split every 2 characters from the left: `nats server mapping "*" "{{slicefromleft(1,2)}}" 1234567` returns `12.34.56.7`.
-- Split every 2 characters from the right: `nats server mapping "*" "{{slicefromright(1,2)}}" 1234567` returns `1.23.45.67`.
+* Split every 2 characters from the left: `nats server mapping "*" "{{slicefromleft(1,2)}}" 1234567` returns `12.34.56.7`.
+* Split every 2 characters from the right: `nats server mapping "*" "{{slicefromright(1,2)}}" 1234567` returns `1.23.45.67`.
 
 ## Deterministic Subject token Partitioning
 
@@ -186,9 +187,10 @@ This means that the application can be portable in terms of deployment and does
 
 ## Subject Mapping and Transforms in Streams
 
-You can define subject mapping transforms as part of the stream configuration. 
+You can define subject mapping transforms as part of the stream configuration.
 
 Transforms can be applied in multiple places in the stream configuration:
+
 * You can apply a subject mapping transformation as part of a Stream mirror.
 * You can apply a subject mapping transformation as part of a Stream source.
 * You can apply an overall stream ingress subject mapping transformation that applies to all matching messages regardless of how they are ingested into the stream.