From 3f18d4179ddec292ac678f9e630247a0bca4c077 Mon Sep 17 00:00:00 2001 From: Kaushik Rishi Manchukonda Date: Mon, 25 Mar 2024 10:06:55 +0530 Subject: [PATCH] update documentation --- README.md | 14 ++---- template/README.md.js | 107 ++++++++++++++++++++++++++++++++++++++---- 2 files changed, 101 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 2222e811..a9ab7db9 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,8 @@ - [Specification requirements](#specification-requirements) - [Supported protocols](#supported-protocols) - [How to use the template](#how-to-use-the-template) - * [CLI](#cli) - * [Adding custom code / handlers](#adding-custom-code--handlers) + - [CLI](#cli) + - [Adding custom code / handlers](#adding-custom-code--handlers) - [Template configuration](#template-configuration) - [Development](#development) - [Contributors](#contributors) @@ -80,15 +80,9 @@ $ cd output # Build generated application $ npm i -# Start server -# To enable production settings start the server with "NODE_ENV=production npm start" -$ npm start +# Import the library and add your custom code and handlers -## -## Start the client -## - -#for testing your server you can use mqtt client. open a new terminal and install it using: +# for testing your server you can use mqtt client. open a new terminal and install it using: $ npm install mqtt -g #publish an invalid message. diff --git a/template/README.md.js b/template/README.md.js index 808523df..4a8f36f5 100644 --- a/template/README.md.js +++ b/template/README.md.js @@ -6,22 +6,109 @@ export default function readmeFile({asyncapi, params}) { ${ asyncapi.info().description() || '' } -## Running the server +## Set up your template 1. Install dependencies \`\`\`sh npm i \`\`\` ${(params.securityScheme && (asyncapi.server(params.server).protocol() === 'kafka' || asyncapi.server(params.server).protocol() === 'kafka-secure') && asyncapi.components().securityScheme(params.securityScheme).type() === 'X509') ? '1. (Optional) For X509 security provide files with all data required to establish secure connection using certificates. Place files like `ca.pem`, `service.cert`, `service.key` in the root of the project or the location that you explicitly specified during generation.' : ''} -1. Start the server with default configuration - \`\`\`sh - npm start - \`\`\` -1. (Optional) Start server with secure production configuration - \`\`\`sh - NODE_ENV=production npm start - \`\`\` -> NODE_ENV=production relates to \`config/common.yml\` that contains different configurations for different environments. Starting server without \`NODE_ENV\` applies default configuration while starting the server as \`NODE_ENV=production npm start\` applies default configuration supplemented by configuration settings called \`production\`.`} +## Use the generated template by adding custom code / handlers + +- use the \`client.registerMiddleware\` method as a bridge between the user-written handlers and the generated code. This can be used to register middlewares for specific methods on specific channels. + +> The AsyncAPI file used for the example is [here](https://bit.ly/asyncapi) + +\`\`\`js +// output refers to the generated template folder +// You require the generated server. Running this code starts the server +// App exposes API to send messages +const { client } = require("./output"); + +// to start the app +client.init(); + +// Generated handlers that we use to react on consumer / produced messages are attached to the client +// through which we can register middleware functions + +/** + * + * + * Example of how to process a message before it is sent to the broker + * + * + */ +function testPublish() { + // mosquitto_sub -h test.mosquitto.org -p 1883 -t "smartylighting/streetlights/1/0/action/12/turn/on" + + // Registering your custom logic in a channel-specific handler + // the passed handler function is called once the app sends a message to the channel + // For example \`client.app.send\` sends a message to some channel using and before it is sent, you want to perform some other actions + // in such a case, you can register middlewares like below + client.registerTurnOnMiddleware((message) => { // \`turnOn\` is the respective operationId + console.log("hitting the middleware before publishing the message"); + console.log( + \`sending turn on message to streetlight \${message.params.streetlightId}\`, + message.payload + ); + }); + + client.app.send( + { command: "off" }, + {}, + "smartylighting/streetlights/1/0/action/12/turn/on" + ); +} + + +/** + * + * + * Example of how to work with generated code as a consumer + * + * +*/ +function testSubscribe() { + // mosquitto_pub -h test.mosquitto.org -p 1883 -t "smartylighting/streetlights/1/0/event/101/lighting/measured" -m '{"lumens": 10}' + + // Writing your custom logic that should be triggered when your app receives as message from a given channel + // Registering your custom logic in a channel-specific handler + // the passed handler functions are called once the app gets message sent to the channel + + client.registerReceiveLightMeasurementMiddleware((message) => { // \`recieveLightMeasurement\` is the respective operationId + console.log("recieved in middleware 1", message.payload); + }); + + client.registerReceiveLightMeasurementMiddleware((message) => { + console.log("recieved in middleware 2", message.payload); + }); +} + +testPublish(); +testSubscribe(); + +/** + * + * + * Example of how to produce a message using API of generated app independently from the handlers + * + * +*/ + +(function myLoop (i) { + setTimeout(() => { + console.log('producing custom message'); + client.app.send({percentage: 1}, {}, 'smartylighting/streetlights/1/0/action/1/turn/on'); + if (--i) myLoop(i); + }, 1000); +}(3)); +\`\`\` + +You can run the above code and test the working of the handlers by sending a message using the mqtt cli / mosquitto broker software to the \`smartylighting/streetlights/1/0/event/123/lighting/measured\` channel using this command +\`mosquitto_pub -h test.mosquitto.org -p 1883 -t "smartylighting/streetlights/1/0/event/101/lighting/measured" -m '{"lumens": 10, "sentAt": "2017-06-07T12:34:32.000Z"}'\` +or +\`mqtt pub -t 'smartylighting/streetlights/1/0/event/123/lighting/measured' -h 'test.mosquitto.org' -m '{"id": 1, "lumens": 3, }'\` (if you are using the mqtt cli) +`} ; }