docs(microservices): document custom msg options

Author: rickdgeerling

content/microservices/mqtt.md

@@ -115,3 +115,62 @@ getTemperature(context) {
   console.log(`Topic: ${context.getTopic()}`);
 }
 ```
+
+#### Message options
+
+It's possible to customize the message sent to the MQTT server to e.g.: adjust the QoS level, set the Retain or DUP flags, or add additional properties to the payload
+
+```typescript
+import { MqttRecordBuilder } from '@nestjs/microservices';
+
+const userProperties = { 'x-version': '1.0.0' };
+const record = new MqttRecordBuilder(':cat:')
+  .setProperties({ userProperties })
+  .setQoS(1)
+  .build();
+client.send('replace-emoji', record);
+```
+
+And you can read those options 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 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.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

@@ -125,3 +125,61 @@ getDate(data, context) {
   return new Date().toLocaleTimeString(...);
 }
 ```
+
+#### Headers
+
+It's possible to send headers with both request-response and event-based flows.
+
+```typescript
+import nats from 'nats';
+import { NatsRecordBuilder } from '@nestjs/microservices';
+
+const headers = nats.headers();
+headers.set('x-version', '1.0.0');
+const record = new NatsRecordBuilder(':cat:').setHeaders(headers).build();
+client.send('replace-emoji', record);
+```
+
+And you can read those headers server-side as well, by accessing the NatsContext
+
+```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
@@ -195,3 +199,37 @@ getNotifications(data, context) {
   channel.ack(originalMsg);
 }
 ```
+
+#### Message options
+
+It's possible to customize the message sent to the RabbitMQ server to e.g.: add headers or configure priority
+
+```typescript
+import { RmqRecordBuilder } from '@nestjs/microservices';
+
+const record = new RmqRecordBuilder(':cat:')
+  .setOptions({
+    headers: { 'x-version': '1.0.0' },
+    priority: 3,
+  })
+  .build();
+client.send('replace-emoji', record);
+```
+
+And you can read those values server-side as well, by accessing the RmqContext
+
+```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' ? '🐱' : '🐈';
+}
+```