GitBook: [master] 7 pages modified

SUMMARY.md

@@ -100,7 +100,7 @@
   * [Monitoring](nats-server/configuration/monitoring.md)
   * [MQTT](nats-server/configuration/mqtt/README.md)
     * [Configuration](nats-server/configuration/mqtt/mqtt_config.md)
-  * [Subject Mapping and Traffic Shaping](nats-server/configuration/subject_mapping/subject_mapping.md)
+  * [Subject Mapping and Traffic Shaping](nats-server/configuration/subject_mapping.md)
   * [System Events](nats-server/configuration/sys_accounts/README.md)
     * [System Events & Decentralized JWT Tutorial](nats-server/configuration/sys_accounts/sys_accounts.md)
   * [WebSocket](nats-server/configuration/websocket/README.md)

jetstream/concepts/streams.md

@@ -16,7 +16,7 @@ When defining Streams the items below make up the entire configuration of the se
 
 | Item | Description |
 | :--- | :--- |
-| Name | A name for the Stream that may not have spaces, tabs, period (`.`), greater than (`>`) or asterix (`*`) |
+| Name | A name for the Stream that may not have spaces, tabs, period \(`.`\), greater than \(`>`\) or asterix \(`*`\) |
 | Storage | The type of storage backend, `File` and `Memory` |
 | Subjects | A list of subjects to consume, supports wildcards |
 | Replicas | How many replicas to keep for each message in a clustered JetStream, maximum 5 |

nats-protocol/nats-protocol/README.md

@@ -12,7 +12,7 @@ The NATS server implements a [zero allocation byte parser](https://youtu.be/ylRK
 
 **Control line w/Optional Content**: Each interaction between the client and server consists of a control, or protocol, line of text followed, optionally by message content. Most of the protocol messages don't require content, only `PUB` and `MSG` include payloads.
 
-**Field Delimiters**: The fields of NATS protocol messages are delimited by whitespace characters '` `'\(space\) or`\t` \(tab\). Multiple whitespace characters will be treated as a single field delimiter.
+**Field Delimiters**: The fields of NATS protocol messages are delimited by whitespace characters '```'\(space\) or``\t\` \(tab\). Multiple whitespace characters will be treated as a single field delimiter.
 
 **Newlines**: NATS uses `CR` followed by `LF` \(`CR+LF`, `\r\n`, `0x0D0A`\) to terminate protocol messages. This newline sequence is also used to mark the end of the message payload in a `PUB` or `MSG` protocol message.
 

nats-protocol/nats-server-protocol.md

@@ -12,7 +12,7 @@ The NATS cluster protocol is very similar to that of the NATS client protocol. I
 
 **Subject names and wildcards**: The NATS cluster protocol has the same features and restrictions as the client with respect to subject names and wildcards. Clients are bound to a single account, however the cluster protocol handles all accounts.
 
-**Field Delimiters**: The fields of NATS protocol messages are delimited by whitespace characters '` `'\(space\) or`\t` \(tab\). Multiple whitespace characters will be treated as a single field delimiter.
+**Field Delimiters**: The fields of NATS protocol messages are delimited by whitespace characters '```'\(space\) or``\t\` \(tab\). Multiple whitespace characters will be treated as a single field delimiter.
 
 **Newlines**: Like other text-based protocols, NATS uses `CR` followed by `LF` \(`CR+LF`, `\r\n`, `0x0D0A`\) to terminate protocol messages. This newline sequence is also used to mark the beginning of the actual message payload in a `RMSG` protocol message.
 

nats-server/configuration/subject_mapping.md

@@ -2,14 +2,11 @@
 
 _Supported since NATS Server version 2.2_
 
-Subject mapping is a very powerful feature of the NATS server, useful for
+Subject mapping is a very powerful feature of the NATS server, useful for canary deployments, A/B testing, chaos testing, and migrating to a new subject namespace.
-canary deployments, A/B testing, chaos testing, and migrating to a new
-subject namespace.
 
-The `mappings` stanza can occur at the top level to apply
+The `mappings` stanza can occur at the top level to apply to the global account or be scoped within a specific account.
-to the global account or be scoped within a specific account.
 
-```
+```text
 mappings = {
 
   # Simple direct mapping.  Messages published to foo are mapped to bar.
@@ -46,32 +43,27 @@ mappings = {
 
 ## Simple Mapping
 
-The example of `foo:bar` is straightforward.  All messages the server receives on subject
+The example of `foo:bar` is straightforward. All messages the server receives on subject `foo` are remapped and can be received by clients subscribed to `bar`.
-`foo` are remapped and can be received by clients subscribed to `bar`.
 
 ## Subject Token Reordering
 
-Wildcard tokens may be referenced via `$<position>`.  For example, the first wildcard
+Wildcard tokens may be referenced via `$<position>`. For example, the first wildcard token is $1, the second is $2, etc. Referencing these tokens can allow for reordering.
-token is $1, the second is $2, etc.  Referencing these tokens can allow for reordering.
 
 With this mapping:
-```
+
+```text
   bar.*.*: baz.$2.$1
 ```
 
-Messages that were originally published to `bar.a.b`  are remapped in the server to `baz.b.a`.
+Messages that were originally published to `bar.a.b` are remapped in the server to `baz.b.a`. Messages arriving at the server on `bar.one.two` would be mapped to `baz.two.one`, and so forth.
-Messages arriving at the server on `bar.one.two` would be mapped to `baz.two.one`, and so forth.
 
 ## Weighted Mappings for A/B Testing or Canary Releases
 
-Traffic can be split by percentage from one subject to multiple subjects.  Here's an example
+Traffic can be split by percentage from one subject to multiple subjects. Here's an example for canary deployments, starting with version 1 of your service.
-for canary deployments, starting with version 1 of your service.
 
-Applications would make requests of a service at `myservice.requests`.  The responders doing the
+Applications would make requests of a service at `myservice.requests`. The responders doing the work of the server would subscribe to `myservice.requests.v1`. Your configuration would look like this:
-work of the server would subscribe to `myservice.requests.v1`.  Your configuration would look like
-this:
 
-```
+```text
   myservice.requests: [
     { destination: myservice.requests.v1, weight: 100% }
   ]
@@ -79,28 +71,22 @@ this:
 
 All requests to `myservice.requests` will go to version 1 of your service.
 
-When version 2 comes along, you'll want to test it with a canary deployment.  Version 2 would
+When version 2 comes along, you'll want to test it with a canary deployment. Version 2 would subscribe to `myservice.requests.v2`. Launch instances of your service \(don't forget about queue subscribers and load balancing\).
-subscribe to `myservice.requests.v2`.  Launch instances of your service (don't forget
-about queue subscribers and load balancing).
 
-Update the configuration file to redirect some portion of the requests made to `myservice.requests`
+Update the configuration file to redirect some portion of the requests made to `myservice.requests` to version 2 of your service. In this case we'll use 2%.
-to version 2 of your service. In this case we'll use 2%.
 
-```
+```text
   myservice.requests: [
     { destination: myservice.requests.v1, weight: 98% },
     { destination: myservice.requests.v2, weight: 2% }
   ]
 ```
 
-You can [reload](../../nats_admin/signals.md) the server at this point to
+You can [reload](../nats_admin/signals.md) the server at this point to make the changes with zero downtime. After reloading, 2% of your requests will be serviced by the new version.
-make the changes with zero downtime.  After reloading, 2% of your requests
-will be serviced by the new version.
 
-Once you've determined Version 2 stable switch 100% of the traffic over and
+Once you've determined Version 2 stable switch 100% of the traffic over and reload the server with a new configuration.
-reload the server with a new configuration.
 
-```
+```text
   myservice.requests: [
     { destination: myservice.requests.v2, weight: 100% }
   ]
@@ -110,11 +96,9 @@ Now shutdown the version 1 instances of your service.
 
 ## Traffic Shaping in Testing
 
-Traffic shaping is useful in testing. You might have a service that runs in QA 
+Traffic shaping is useful in testing. You might have a service that runs in QA that simulates failure scenarios which could receive 20% of the traffic to test the service requestor.
-that simulates failure scenarios which could receive 20% of the traffic to test
-the service requestor.
 
-```
+```text
   myservice.requests.*: [
     { destination: myservice.requests.$1, weight: 80% },
     { destination: myservice.requests.fail.$1, weight: 20% }
@@ -123,20 +107,15 @@ the service requestor.
 
 ## Artificial Loss
 
-Alternatively, introduce loss into your system for chaos testing by
+Alternatively, introduce loss into your system for chaos testing by mapping a percentage of traffic to the same subject. In this drastic example, 50% of the traffic published to `foo.loss.a` would be artificially dropped by the server.
-mapping a percentage of traffic to the same subject.  In this
-drastic example, 50% of the traffic published to `foo.loss.a` would
-be artificially dropped by the server.
 
-```
+```text
   foo.loss.>: [ { destination: foo.loss.>, weight: 50% } ]
 ```
 
-You can both split and introduce loss for testing.  Here, 90% of requests
+You can both split and introduce loss for testing. Here, 90% of requests would go to your service, 8% would go to a service simulating failure conditions, and the unaccounted for 2% would simulate message loss.
-would go to your service, 8% would go to a service simulating failure conditions,
-and the unaccounted for 2% would simulate message loss.
 
-```
+```text
   myservice.requests: [
     { destination: myservice.requests.v3, weight: 90% },
     { destination: myservice.requests.v3.fail, weight: 8% }
@@ -144,6 +123,5 @@ and the unaccounted for 2% would simulate message loss.
   ]
 ```
 
-*Note:  Subject Mapping and Traffic Shaping are also supported in the NATS
+_Note: Subject Mapping and Traffic Shaping are also supported in the NATS JWT model, although currently only through the_ [_JWT API_](https://github.com/nats-io/jwt)_. `nsc` tooling support for subject mapping is coming soon._
-JWT model, although currently only through the [JWT API](https://github.com/nats-io/jwt).
+
-`nsc` tooling support for subject mapping is coming soon.*

whats_new_22.md

@@ -65,7 +65,7 @@ Why wait for timeouts when services aren’t available? When a request is made t
 
 ### Subject Mapping and Traffic Shaping
 
-Reduce risk when onboarding new services. Canary deployments, A/B testing, and transparent teeing of data streams are now fully supported in NATS. The NATS Server allows accounts to form subject mappings from one subject to another for both client inbound and service import invocations and allows weighted sets for the destinations. Map any percentage - 1 to 100 percent of your traffic - to other subjects, and change this at runtime with a server configuration reload. You can even artificially drop a percentage of traffic to introduce chaos testing in to your system.
+Reduce risk when onboarding new services. Canary deployments, A/B testing, and transparent teeing of data streams are now fully supported in NATS. The NATS Server allows accounts to form subject mappings from one subject to another for both client inbound and service import invocations and allows weighted sets for the destinations. Map any percentage - 1 to 100 percent of your traffic - to other subjects, and change this at runtime with a server configuration reload. You can even artificially drop a percentage of traffic to introduce chaos testing into your system. See [Subject Mapping and Traffic Shaping](nats-server/configuration/subject_mapping.md) in NATS Server configuration for more details.
 
 ### Account Monitoring - More Meaningful Metrics