Merge branch 'tuxmachine-feat/msvc-header-docs'

Author: kamilmysliwiec

content/microservices/mqtt.md

@@ -118,12 +118,59 @@ getTemperature(context) {
 
 #### Record builders
 
-To configure message options, you can use the `MqttRecordBuilder` class. For example, to set `QoS` to `2` use the `setQoS` method, as follows:
+To configure message options (adjust the QoS level, set the Retain or DUP flags, or add additional properties to the payload), you can use the `MqttRecordBuilder` class. For example, to set `QoS` to `2` use the `setQoS` method, as follows:
 
 ```typescript
-const message = { event: 'USER_CREATED' };
-const record = new MqttRecordBuilder(message).setQoS(2).build();
-this.client.send('notifications', record).subscribe(...);
+const userProperties = { 'x-version': '1.0.0' };
+const record = new MqttRecordBuilder(':cat:')
+  .setProperties({ userProperties })
+  .setQoS(1)
+  .build();
+client.send('replace-emoji', record).subscribe(...);
 ```
 
 > info **Hint** `MqttRecordBuilder` class is exported from the `@nestjs/microservices` package.
+
+And you can read these options on the server-side as well, by accessing the `MqttContext`.
+
+```typescript
+@@filename()
+@MessagePattern('replace-emoji')
+replaceEmoji(@Payload() data: string, @Ctx() context: MqttContext): string {
+  const { properties: { userProperties } } = context.getPacket();
+  return userProperties['x-version'] === '1.0.0' ? '🐱' : '🐈';
+}
+@@switch
+@Bind(Payload(), Ctx())
+@MessagePattern('replace-emoji')
+replaceEmoji(data, context) {
+  const { properties: { userProperties } } = context.getPacket();
+  return userProperties['x-version'] === '1.0.0' ? '🐱' : '🐈';
+}
+```
+
+In some cases you might want to configure user properties for multiple requests, you can pass these options to the `ClientProxyFactory`.
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ClientProxyFactory, Transport } from '@nestjs/microservices';
+
+@Module({
+  providers: [
+    {
+      provide: 'API_v1',
+      useFactory: () =>
+        ClientProxyFactory.create({
+          transport: Transport.MQTT,
+          options: {
+            url: 'mqtt://localhost:1833',
+            userProperties: { 'x-version': '1.0.0' },
+          },
+        }),
+    },
+  ],
+})
+export class ApiModule {}
+```
+
+> info **Hint** You could make this provider request-scoped and thus enable things like cross-protocol request tracing.

content/microservices/nats.md

@@ -128,7 +128,7 @@ getDate(data, context) {
 
 #### Record builders
 
-To configure message options, you can use the `NatsRecordBuilder` class. For example, to add `x-version` header, use the `setHeaders` method, as follows:
+To configure message options, you can use the `NatsRecordBuilder` class (note: this is doable for event-based flows as well). For example, to add `x-version` header, use the `setHeaders` method, as follows:
 
 ```typescript
 import * as nats from 'nats';
@@ -137,9 +137,52 @@ import * as nats from 'nats';
 const headers = nats.headers();
 headers.set('x-version', '1.0.0');
 
-const message = { event: 'USER_CREATED' };
-const record = new NatsRecordBuilder(message).setHeaders(headers).build();
-this.client.send('notifications', record).subscribe(...);
+const record = new NatsRecordBuilder(':cat:').setHeaders(headers).build();
+this.client.send('replace-emoji', record).subscribe(...);
 ```
 
 > info **Hint** `NatsRecordBuilder` class is exported from the `@nestjs/microservices` package.
+
+And you can read these headers on the server-side as well, by accessing the `NatsContext`, as follows:
+
+```typescript
+@@filename()
+@MessagePattern('replace-emoji')
+replaceEmoji(@Payload() data: string, @Ctx() context: NatsContext): string {
+  const headers = context.getHeaders();
+  return headers['x-version'] === '1.0.0' ? '🐱' : '🐈';
+}
+@@switch
+@Bind(Payload(), Ctx())
+@MessagePattern('replace-emoji')
+replaceEmoji(data, context) {
+  const headers = context.getHeaders();
+  return headers['x-version'] === '1.0.0' ? '🐱' : '🐈';
+}
+```
+
+In some cases you might want to configure headers for multiple requests, you can pass these as options to the `ClientProxyFactory`:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ClientProxyFactory, Transport } from '@nestjs/microservices';
+
+@Module({
+  providers: [
+    {
+      provide: 'API_v1',
+      useFactory: () =>
+        ClientProxyFactory.create({
+          transport: Transport.NATS,
+          options: {
+            servers: ['nats://localhost:4222'],
+            headers: { 'x-version': '1.0.0' },
+          },
+        }),
+    },
+  ],
+})
+export class ApiModule {}
+```
+
+> info **Hint** You could make this provider request-scoped and thus enable things like cross-protocol request tracing.

content/microservices/rabbitmq.md

@@ -74,6 +74,10 @@ The `options` property is specific to the chosen transporter. The <strong>Rabbit
     <td><code>socketOptions</code></td>
     <td>Additional socket options (read more <a href="https://www.squaremobius.net/amqp.node/channel_api.html#socket-options" rel="nofollow" target="_blank">here</a>)</td>
   </tr>
+  <tr>
+    <td><code>headers</code></td>
+    <td>Headers to be sent along with every message</td>
+  </tr>
 </table>
 
 #### Client
@@ -198,10 +202,10 @@ getNotifications(data, context) {
 
 #### Record builders
 
-To configure message options, you can use the `RmqRecordBuilder` class. For example, to set `headers` and `priority` properties, use the `setOptions` method, as follows:
+To configure message options, you can use the `RmqRecordBuilder` class (note: this is doable for event-based flows as well). For example, to set `headers` and `priority` properties, use the `setOptions` method, as follows:
 
 ```typescript
-const message = { event: 'USER_CREATED' };
+const message = ':cat:';
 const record = new RmqRecordBuilder(message)
   .setOptions({
     headers: {
@@ -211,7 +215,25 @@ const record = new RmqRecordBuilder(message)
   })
   .build();
 
-this.client.send('notifications', record).subscribe(...);
+this.client.send('replace-emoji', record).subscribe(...);
 ```
 
 > info **Hint** `RmqRecordBuilder` class is exported from the `@nestjs/microservices` package.
+
+And you can read these values on the server-side as well, by accessing the `RmqContext`, as follows:
+
+```typescript
+@@filename()
+@MessagePattern('replace-emoji')
+replaceEmoji(@Payload() data: string, @Ctx() context: RmqContext): string {
+  const { properties: { headers } } = context.getMessage();
+  return headers['x-version'] === '1.0.0' ? '🐱' : '🐈';
+}
+@@switch
+@Bind(Payload(), Ctx())
+@MessagePattern('replace-emoji')
+replaceEmoji(data, context) {
+  const { properties: { headers } } = context.getMessage();
+  return headers['x-version'] === '1.0.0' ? '🐱' : '🐈';
+}
+```

src/app/homepage/pages/microservices/custom-transport/custom-transport.component.html

@@ -197,8 +197,8 @@ <h4 appAnchor id="message-serialization"><span>Message serialization</span></h4>
 <p>If you need to add some custom logic around the serialization of responses on the client side, you can use a custom class that extends the <code>ClientProxy</code> class or one of its child classes. For modifying successful requests you can override the <code>serializeResponse</code> method, and for modifying any errors that go through this client you can override the <code>serializeError</code> method. To make use of this custom class, you can pass the class itself to the <code>ClientsModule.register()</code> method using the <code>customClass</code> property. Below is an example of a custom <code>ClientProxy</code> that serializes each error into an <code>RpcException</code>.</p>
 
 <span class="filename">
-  {{ 'error-handling.proxy' | extension: appef748bdb0474f8314c0d2d844a046dd0b313d5bd.isJsActive }}
-<app-tabs #appef748bdb0474f8314c0d2d844a046dd0b313d5bd></app-tabs>
+  {{ 'error-handling.proxy' | extension: app37591e0f00090be59cdd04c6c4aa7f47d21ed33c.isJsActive }}
+<app-tabs #app37591e0f00090be59cdd04c6c4aa7f47d21ed33c></app-tabs>
 </span><pre><code class="language-typescript">
 import &#123; ClientTcp, RpcException &#125; from &#39;@nestjs/microservices&#39;;
 
@@ -210,8 +210,8 @@ <h4 appAnchor id="message-serialization"><span>Message serialization</span></h4>
 </code></pre><p>and then use it in the <code>ClientsModule</code> like so:</p>
 
 <span class="filename">
-  {{ 'app.module' | extension: appe71a4ea7740a397e20f1e653d6c83fd05f372e95.isJsActive }}
-<app-tabs #appe71a4ea7740a397e20f1e653d6c83fd05f372e95></app-tabs>
+  {{ 'app.module' | extension: app8e7d939eefa181bf7634362268838b383adc08c2.isJsActive }}
+<app-tabs #app8e7d939eefa181bf7634362268838b383adc08c2></app-tabs>
 </span><pre><code class="language-typescript">
 @Module(&#123;
   imports: [