node-moleculer-web

High-performance web server integration for Moleculer based on uWebSockets.js.

📦 Features

• Built on top of ultra-fast uWebSockets.js.
• Fully compatible with Moleculer services.
• Support for controllers and middleware.
• Request and response helpers.
• Cookie and body parsing.
• Easy redirect handling.
• TypeScript support via index.d.ts.

🚀 Installation

npm install node-moleculer-web

Uses

1 Create controller in folder controllers/home.js

const {AbstractController} = require('node-moleculer-web');
class HomeController extends AbstractController {
  async index() {
    return `helo world`;
  }
}
module.exports = HomeController

2 Create service in folder services/app.service.js

const {UwsServer} = require('node-moleculer-web');
const {Service} = require('moleculer');

const HomeController = require('../controllers/home');
  
class AppService extends Service {
  constructor(broker) {
    super(broker);
    this.parseServiceSchema({
      name: 'app',
      settings: {
          // base port for server
          port: process.evn.SERVER_PORT ?? 3101,
          // on what ip to listen
          ip: process.evn.SERVER_IP ?? '127.0.0.1',
          portSchema: process.evn.SERVER_SCHEMA ?? 'node',         
          // if statics are not needed, just remove next parameters  
          publicDir: __dirname + '/../public',
          publicIndex: 'index.html', // or false
          staticCompress: true,      // support compresion gzip, br, deflate
          staticLastModified: true,  // send last modified header for static files
          // list of controllers
          controllers: {
             home: HomeController
          }
      },
      // added mixin UwsServer to current services
      mixins: [
          UwsServer
      ],
      created: this.createService
    })
  }

  createService() {
    // register routing where home is the controller and index is the method	
    this.createRoute('get / #c:home.index')
  }
}
module.exports = AppService

Router path

• <request type> / #c:<controller name>.<action>
• <request type> / #s:<service name>.<action>
• allowed request types:
• any - HTTP ALL
• connect - HTTP CONNECT
• del - HTTP DELETE
• get - HTTP GET
• head - HTTP HEAD
• options - HTTP OPTIONS
• patch - HTTP PATCH
• post - HTTP POST
• put - HTTP PUT
• trace - HTTP TRACE

Router example

• optional id param
• <request type> /articles/:id? #c:article.actionIndex
• regex id param
• <request type> /articles/:id(\d+) #c:article.actionView

get id param value in controller

  this.req.getParameter('id') // or  this.req.getParameter('0')
  // or
  // this.inidReuqstData();
  // this.requestData.parameters.id

Router Options

• cache - second http cache
• onBefore(route, req, res) - Function before call for controller or service
• onAfter(route, req, res, data) - Function after call for controller or service

Example options for createRoute

this.createRoute('get / #c:home.index', {cache: 5});

📶 AbstractController properties:

| property | description | |:-----------------|:---------------------------------------------| | requestData | read request data | | cookieData | read/write cookie | | redirectType | "header" | "meta" | "js" (default meta) | | format | default response content type default html | | statusCode | default response http code number 200 | | statusCodeText | default response http code string 200 OK | | broker | link ServiceBroker molecular.js | | req | link HttpRequest uWebsocket.js | | res | link HttpResponse uWebsocket.js |

requestData or cookieData (The property objects are available after executing the this.initRequest() method inside the controller method)

🕒 Performance Tracking

• .timer
  • An instance of Timer used to measure request processing duration.
  • .start() — Starts the timer.
  • .stop() — Stops the timer. and Returns elapsed time in milliseconds.

AbstractController methods:

🔐 JWT Methods:

• .initJWT(key, iat = false)
  • Initializes the JWT utility with a secret key and whether to include issued-at time (iat).
• .getJWT()
  • Returns the initialized JWT instance. Throws an error if not initialized.
• .createJwtToken(payload = {})
  • Creates a JWT token from the provided payload.
• .extractJwtToken(token)
  • Extracts and returns the decoded payload from a given JWT token.

📥 Request Handling:

• .initRequest()
  • Initializes requestData and cookieData objects for accessing request data and cookies. Also sets client-hints headers if enabled.
• .readBody()
  • Reads the request body asynchronously. Returns a Promise.

📤 Response Methods:

• .asJson(obj, httpCode = 200)

  • Sends a JSON response with optional HTTP status code.

• .renderRaw({ view, httpCode, format })

  • Renders raw content (string or HTML) with proper MIME type and HTTP status.

• .render({ template, params, httpCode, format })

  • Renders an EJS template with given parameters and sends it as a response.

• .setStatus(httpCode)

  • Sets the HTTP status code and its text representation.

• .writeHeader(key, value)

  • Writes a custom header to the response.

• .setCorsHeaders()

  • Sets CORS-related headers for cross-origin requests.

🔁 Redirect Methods:

• .redirect(location, httpCode = 301)
  • Performs a redirect using one of the following strategies:
  • You can set the strategy in the redirectType property of the controller.
  • REDIRECT_TYPE_META: Meta refresh redirect (HTML-based).
  • REDIRECT_TYPE_JS: JavaScript-based redirect.
  • REDIRECT_TYPE_HEADER: Standard HTTP Location header redirect.

Example Controllers

response json object

class Home extends AbstractController {
  async index() {
   return this.asJson({}, 200);
  }
}

response redirect to other url

class Home extends AbstractController {
  async index() {
    return this.redirect('https://youdomain.dev', 301 /* optional*/ , "meta" /* optional*/ );
  }
}

response ejs template

class Home extends AbstractController {
  async index() {
    return this.render({
      template, params, httpCode: 200, format: 'html'
    });
  }
}

response raw

class Home extends AbstractController {
  async index() {
    return this.renderRaw({view: 'string', httpCode: 200, format: 'html'});
  }
}

or

class Home extends AbstractController {
  async index() {
    return 'Hello World'
  }
}

🍪 Cookie Usage Example — Reading and Writing Cookies

const { AbstractController } = require('node-moleculer-web');

module.exports = class Home extends AbstractController {
  /**
   * Initialize request data and cookie handler
   */
  async index() {
    // Initialize requestData and cookieData
    this.initRequest();
    // 🔍 Read a cookie value, with fallback
    const cookieValue = this.cookieData.get('my_cookievalue', String(Date.now() /* or 1*new Date()  */   ));
    // ✍️ Set/update the cookie with a new value
    this.cookieData.set('my_cookievalue', cookieValue);
    // 📤 Return current cookie value as response
    return `Current cookie value: ${cookieValue}`;
  }
};

📥 Get Request Data Example

const { AbstractController } = require('node-moleculer-web');

module.exports = class Home extends AbstractController {
  /**
   * Handle GET request and return parsed request data
   */
  async index() {
    // Initialize request and cookie utilities
    this.initRequest();
    // Extract request data
    const headers = this.requestData.headers;       // All request headers
    const ip = this.requestData.ip;                 // Client IP address
    const query = this.requestData.query ?? {};     // Query parameters
    const referer = this.requestData.referer;       // Referrer URL
    const currentUrl = this.requestData.url;        // Current request URL
    const userAgent = this.requestData.userAgent;   // User-Agent string
  
    // Return all data as JSON response
    return this.asJson({
      headers,
      ip,
      query,
      referer,
      currentUrl,
      userAgent
    }, 200);
  }
};

🔄 Call Another Microservice from Controller

const { AbstractController } = require('node-moleculer-web');

module.exports = class Home extends AbstractController {
  /**
   * Calls another microservice and returns the result as JSON
   */
  async index() {
    try {
      const data = await this.broker.call('service-name.action', {
        email: '[email protected]'
      }) ?? {};
      return this.asJson(data, 200);
    } catch (error) {
      return this.asJson({
        error: error.message,
        code: error.code || 500
      }, error.code || 500);
    }
  }
};

📥 Read POST Request Body Example

const { AbstractController } = require('node-moleculer-web');

module.exports = class Home extends AbstractController {
  /**
   * Reads the request body and returns it as JSON
   */
  async index() {
    try {
      const body = await this.readBody();
      return this.asJson({ body }, 200);
  
    } catch (error) {
      return this.asJson({
        error: 'Failed to read request body',
        message: error.message
      }, 400);
    }
  }
};

🔐 JWT Usage Example — Create and Verify Tokens

class Home extends AbstractController {
  // create token
  async index() {
    this.initJWT('mykey');
    const payload = {userId: 0, status: true};
    const token = this.getJWT().create(payload)
    return this.asJson({token}, 200);
  }
  // extract payload for token + validation (is payload not null then token valid)
  async test() {
   this.initRequest()
   const token = this.requestData.query.token ?? '';
   this.initJWT('mykey', false);
   const payload = this.getJWT().extract(token)
   return this.asJson({payload}, 200);
  }
}

Extend rest service

• ! you still need to create an app server to use this example:

const {HttpService} = require('node-moleculer-web');
const {Service} = require('moleculer');
class RestService extends Service {
  constructor(broker) {
    super(broker);
    this.parseServiceSchema({
      name: 'rest',
      settings: {},
      mixins: [
				HttpService  // add HttpService mixin
      ],
      actions: {
        hello: {
          rest: 'GET /hello',
          handler(ctx) {
            return 'Hello1 API Gateway!'
          }
        },
        hello2: {
          rest: 'GET /hello2/:test1/:test2',
          handler(ctx) {
            // read request data for meta object
            console.log('requestData', ctx.meta.requestData)
            // read cookie
            ctx.meta.cookieData.get('test', 0);
            // write cookie 
            ctx.meta.cookieData.set('test', 2);
            // write header
            ctx.meta.headers['my-custom-header'] = 'lama';
            return 'Hello2 API Gateway!'
          }
        },
        
        testJson: {
          rest: 'GET /hello3/test/json',
          handler(ctx) {
            return this.asJson(ctx, {
              myvalue: 111
            })
          }
        },
        
        testRedirect: {
          rest: 'GET /hello3/test/redirect',
          handler(ctx) {
            return this.redirect(ctx, 'https://google.com', 301, 'meta')
          }
        }
        
      },
    });
  }
}

NGINX config if request proxying is used for once instance

server {
  listen 80;
  listen 443 ssl;
  listen [::]:80;
  listen [::]:443;

  server_name domain.com;
  
  location / {
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-NginX-Proxy true;
    proxy_pass http://127.0.0.1:3001;
    proxy_redirect off;
  }
}

NGNIX config if clustering is used

Run locally

npx moleculer-runner -i 4 services

or

node node_modules/.bin/moleculer-runner -i 4 services

• The config itself
• The ports must match from your chosen strategy. node or ( list added version 1.2.1)

upstream node_apps {
  server 127.0.0.1:3001;
  server 127.0.0.1:3002;
  server 127.0.0.1:3003;
  server 127.0.0.1:3004;
}

server {
  listen 80;
  listen 443 ssl;
  listen [::]:80;
  listen [::]:443;

  server_name domain.com;

  location / {
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-NginX-Proxy true;
    proxy_pass http://node_apps;
    proxy_redirect off;
  }
}

cluster config moleculer.config.js

module.exports = {
  nodeID: 'DEMO',
  transporter: "TCP",
  registry: {
    // type of call strategy for microservices
    strategy: "RoundRobin",
    // If set to true, then each webserver will use only its own micro-services
    preferLocal: false,      
  },
  logger: console
};

BZT Benchmark (install view docs https://gettaurus.org/)

run app

node tests/services/local.js

run strestest minimal logic

bzt tests/bzt-config.yaml

22:41:17 INFO: Test duration: 0:06:03
22:41:17 INFO: Samples count: 12909515, 0.00% failures
22:41:17 INFO: Average times: total 0.008, latency 0.008, connect 0.000
22:41:17 INFO: Percentiles:
+---------------+---------------+
| Percentile, % | Resp. Time, s |
+---------------+---------------+
|           0.0 |           0.0 |
|          50.0 |         0.006 |
|          90.0 |         0.016 |
|          95.0 |         0.018 |
|          99.0 |         0.025 |
|          99.9 |         0.038 |
|         100.0 |         0.058 |
+---------------+---------------+
22:41:17 INFO: Request label stats:
+---------------------------------------------------------------------------+--------+---------+--------+-------+
| label                                                                     | status |    succ | avg_rt | error |
+---------------------------------------------------------------------------+--------+---------+--------+-------+
| http://localhost:8080/bzt?id=39641&&hash=104bdfd40acf8d03e6b485e11b681fd4 |   OK   | 100.00% |  0.016 |       |
| http://localhost:8080/bzt?id=39641&&hash=104bdfd40acf8d03e6b485e11b681fd5 |   OK   | 100.00% |  0.006 |       |
| http://localhost:8080/bzt?id=39641&&hash=104bdfd40acf8d03e6b485e11b681fd6 |   OK   | 100.00% |  0.005 |       |
| http://localhost:8080/bzt?id=39641&&hash=104bdfd40acf8d03e6b485e11b681fd7 |   OK   | 100.00% |  0.005 |       |
| http://localhost:8080/bzt?id=39641&&hash=104bdfd40acf8d03e6b485e11b681fd8 |   OK   | 100.00% |  0.006 |       |
+---------------------------------------------------------------------------+--------+---------+--------+-------+