ewdGateway2: Node.js Platform for EWD Web Apps

As those of you who read my blog articles will know by now, I spend a lot of time working with Node.js in conjunction with the two main Mumps implementations: GT.M and Caché.

A key focus of my work is EWD: my web application framework that is designed specifically for use with these two database platforms.  Until recently, in order to use EWD, you had to use what’s known as a gateway: a connector between a web server such as Apache or IIS and either GT.M or Caché.  Basically the choices came down to:

  • GT.M: our Open Source m_apache gateway for Apache
  • Caché: either InterSystems’ CSP gateway or their legacy WebLink gateway (both of which work with Apache, IIS and some other web servers).

These work well enough, but there are things I don’t like about them:

  • Apache configuration is pretty complex (for newbies it’s downright baffling!)
  • CSP becomes expensive in terms of the way it uses Caché licenses.  Additionally, unless you have an unlimited Caché license, it also sets you up with a Denial of Service vulnerability, since it’s easy for someone to maliciously consume all your available Caché licenses and bring your web applications to a grinding halt.
  • In order for EWD to make use of CSP, EWD has to compile your pages into CSP pages which then run under the control of CSP.  There are numerous aspects of CSP I’ve never liked, in particular its cookie-based session management that makes it very difficult to run multiple applications in separate tabs within a browser.
  • WebLink is a much more forgiving gateway in terms of its use of Caché licenses, but it’s becoming increasingly difficult to get hold of and its default URL structures are lengthy and messy

There’s also something else they don’t currently support: WebSockets.

WebSockets is one of the most exciting and potentially game-changing new features within HTML5.  The phrase that is most often used to describe what it makes possible is the “Real-time Web”.  Basically what WebSockets is all about is breaking free of the limitations of the request/response protocol of HTTP, and instead, creating a socket connection between your browser and the back-end, with event-handling implemented at each end.  This makes it possible for events to be triggered at the back-end that cause things to happen in the user’s browser, without the browser having to poll to see if anything has happened at the back-end: a message is sent via the WebSocket connection to the browser, this triggers a pre-defined event and something immediately happens in the browser.

For example, most modern browsers now have graphing and charting capabilities built into them (using technologies such as Canvas or SVG).  So, imagine a clinician by a patient’s bed-side, monitoring vital life-sign data, graphed and updated in real-time in a browser display in his/her iPad.

WebSockets are bi-directional, so events that occur in the browser can generate messages that are sent via the WebSocket connection to the back-end, effectively providing an alternative to the use of Ajax over HTTP.  This is attractive in a mobile web setting, since it means we can potentially bypass the browser’s history and cache when exchanging information with the back-end, and therefore remove one of the issues that the Bring Your Own Device (BYOD) security consultants worry about: if the mobile device is stolen, there will be nothing that can be found in the browser history or cache that will be of any use to anyone.

So, for all these reasons, for quite some time I’ve been working on a Node.js-based alternative to these “traditional” web gateways for EWD applications.

Node.js is ideal for this because it:

  • provides, “out of the box”, a simple but powerful web server capability that can be customised and made to do whatever the developer wants it to do, all using Javascript code
  • supports WebSockets.  The most common module that is used for this is socket.io which is stable and mature.  This means we can write the event-handlers for each end of the WebSocket connections in the same language: Javascript.
  • now has very fast, in-process connectors to GT.M and Caché that allow access to Mumps Globals and functions from Javascript.  I’ve described these in earlier articles.

My latest version of this Node.js gateway, known as ewdGateway2, is now, I believe, good enough for general use and evaluation, so I want to introduce it to you in this article.  ewdGateway2 is entirely written in Javascript and is released as an Open Source product (licensed under the Apache 2 license) and will work with:

  • Caché, via InterSystems’ Node.js interface that is included with versions 2012.1 and later
  • GT.M, via David Wicksell’s NodeM interface

ewdGateway2 removes the need to install and configure a web server such as IIS or Apache, and, if you’re a Caché developer, you are no longer limited to using CSP or WebLink.  It will support all your existing EWD applications:

  • if you use GT.M, your existing EWD applications will run without any changes or recompilations being necessary
  • if you use Caché, just recompile your EWD applications, but specify the technology as “ewd” instead of “csp” or “wl”

It’s worth taking a look at how ewdGateway2 works.  In many ways it adopts a similar architecture to WebLink, CSP and m_apache, in that it combines:

  • a queue into which incoming HTTP requests are placed
  • a number of pre-forked child processes that actually make the physical connections to GT.M or Caché using the appropriate Node.js interface
  • a queue processor that allocates requests in the queue to the first free child process

Critically, a child process is only allowed to handle a single request at a time, and, during this time, it is unavailable to the queue processor.

This architecture is summarised in this diagram.


Screen Shot 2013-02-12 at 10.36.52








One of the things you’ll have realised from my previous articles is that the Node.js interfaces to Caché and GT.M are both in-process and synchronous.

  • The in-process nature of the interfaces means that each of the child processes binds intimately to an instance of Caché or GT.M.  In terms of Caché licensing, you therefore determine the number of licenses you consume by determining how many worker child processes you want ewdGateway2 to spawn.  Incoming requests will be queued until a child process becomes free, so, with ewdGateway2, you’ll not see any “license exceeded” errors: if things get too busy, the queue will simply grow.
  • The synchronous nature of the Node.js interfaces seems to fly in the face of conventional Node.js wisdom and convention.  In Node.js, all I/O is meant to be carried out asynchronously.  ewdGateway2 addresses this issue by ensuring that the synchronous interfacing to Caché or GT.M takes place within the isolation of the worker child processes.  Since each worker child process is limited to handling a single request at a time, the handling of other requests is unaffected by this synchronous processing.  Meanwhile the outward-facing main Node.js parent process that provides the web server interface and queue is entirely asynchronous, as would be expected in a Node.js application.

Each of the worker child processes is capable of a variety of things, thanks to a set of request handlers that are built-in (see diagram)

Screen Shot 2013-02-12 at 10.57.01








These include:

  • handling incoming URL requests for EWD pages and fragments
  • handling incoming WebSocket requests
  • handling requests to manage ewdGateway2 (eg to add or remove worker child processes, change the logging level and destination etc)

In addition, one of the exciting new capabilities that ewdGateway2 makes possible, is for your EWD applications to be written entirely in Javascript.  Until now, the onBeforeRender methods that provide the means by which an EWD page or fragment interacts with the Caché or GT.M system had to be written in Mumps code.  Now, they can be written in Javascript, yet they can have the same level of access to the data and resources of the Caché or GT.M back-end.  I’ll explain how to use this capability in a future article.

Your EWD pages are still compiled, as before, into Mumps routines, and these run, as before, within the Caché or GT.M back-end.  However, this can now all be treated as a “black box”.  One of the features I will probably develop in the near future is an EWD-based web application that allows you to manage both the ewdGateway2 module and your EWD applications: eventually no Mumps knowledge will be required in order to use EWD-based web applications.

Using ewdGateway2 with GT.M

So how do you get your hands on ewdGateway2 and start using it?

The quickest and simplest way is to download and fire up the latest dEWDrop Virtual Machine which includes ewdGateway2, pre-configured and ready to run with GT.M.  All you need to do is as follows:

– Make a note of the IP address that has been allocated to the dEWDrop VM after it boots up.  You can find this out by typing the command:


– Start a terminal session on your host machine and ssh into the dEWDrop VM at this IP address (username vista, password ewd)

– Then do the following:

  cd /home/vista/www/node/ewdGateway2
  node ewdStart-gtm

– You should see ewdGateway2 burst into life:

*** ewdGateway Build 33 (10 January 2013) ***
*** ewdQ Build 5 (10 January 2013) ***
4 child Node processes running
Trace mode is off
ewdQ is ready!
HTTPS is enabled; listening on port 8080
   info  - socket.io started

– It’s now sitting waiting, listening for HTTPS requests on port 8080.

– Try running the ewdMgr application which is already available on the dEWDrop VM.  Start up a browser and enter the following URL (adjust the IP address to match the one allocated to your dEWDrop VM):

– You’ll initially get a warning about the SSL certificate that is pre-installed on the dEWDrop server.  Just accept it and you should see the ewdMgr application start up.  You’ll see that it just behaves like a standard web server and all your EWD applications will just work with it as before.

– To stop ewdGateway2, just type CTRL & C.  You’ll need to reset the terminal: just type:


Configuring ewdGateway2

ewdGateway2 is configured in the start-up file you used, which, for the dEWDrop example above is the file:


I’ll be providing detailed documentation on how to configure ewdGateway2 in the GitHib repository very soon.

In the meantime, many of the parameters you’ll see in the startup file will be self-explanatory, so try changing them and see what happens.


Using ewdGateway2 with Caché

If you want to use ewdGateway2 with Caché, watch this space: I’m planning to write a tutorial article on how to get it working on a Windows system with Caché 2012.2 (or later).

Watch This Space for More Information

In future articles I’ll explain how to use WebSockets in your EWD applications, and also how to create EWD applications that are written entirely in Javascript.

You’re going to find that ewdGateway2 is going to change the way you think about web applications!




Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: