Node.js is a good technology option on which to develop the interoperability layer core component for the following reasons:

• It is very lightweight
• It has a robust HTTP library
• It has robust support from 3rd party libraries for reading and modifying HTTP requests
• It is highly performant

Libraries to use

• Express - Express is a web application framework for node.js. It provides easy mechanisms to expose web endpoints.
• Connect - Connect provides middleware for node.js that allow HTTP requests and responses can be altered while in 'flight'. The express framework also uses connect middleware and middleware are exposed from the express framework as well.

General Overview

The Express library which includes the Connect middleware provides an easy way to modify HTTP request and responses as they are being processed. Each step that the OpenHIM needs to perform can be written as Connect middleware. Each middleware can handle a different aspect of processing that the OpenHIM need to perform such as authentication, authorization, message persistence and message routing. Developing each of these steps as connect middleware allows them to be easily reused and allows us to add new step for future versions.

More information on Connect middleware can be found here: http://www.senchalabs.org/connect/ and http://stephensugden.com/middleware_guide/

The express library gives us some convenience req and res objects that are designed to be used for web applications but they are equally useful for handling web services.

Logical Architecture

Authentication and Authorization

The are two possible combinations of authentication that the interoperability layer should provide to determine a users identity:

• HTTP basic authentication
• ATNAs Node Authentication (PKI)

Once identify has been established the IL core component should check if that user has the authority to access the requested service.

Authentication

User details for authentication are stored in the MongoDB database is the following format. Either a password or a certificate (in binary form) is stored in this structure depending on whether the user chooses to use PKI or HTTP basic auth to authenticate users.

{
	"userID": "Musha_OpenMRS",
	"name": "OpenMRS Mush instance",
	"roles": "OpenMRS_PoC,PoC",
	"password": "",
	"cert": ""
}

When authentication is set to HTTP basic auth then connect middleware is setup to intercept the request as soon as it enters the HIM as shown above. This middleware will read user details out of the MongoDB store to determine if the user can be authenticated. If the user is rejected an error is returned else the request is considered authenticated and is then passed onto the authorization step.

Authorization

The OpenHIM only performs simple authorization based on the path that is being requested. It should be able to restrict access to certain paths to users with particular roles. The channel description shown in the router section below shows that each path has one or more allowed roles or user associated with it. The authorization component will check if the authenticated user has the authority to access the current path. It authorized the request will be passed on, else, the request will be denied and a HTTP 401 message will be returned.

Persistence

Each request and response will be persisted so that it can be logged and so that error'd transaction may be re-run. This persistence occurs at two stages. Firstly, once a request is authenticated and authorised and secondly once a response has been received from the external service. All the metadata about a transaction is stored in a single document in MongoDB. The relevant sections are just updated as new information is received. The structure of this information is shown below.

In addition the ability to store orchestration steps exists in the structure. We anticipate exposing a web service to enable mediators to report requests and responses that they make to/receive from external services and have these stored alongside the actual transaction.

{
	"transactionId": "123",
	"status": "Processing|Failed|Completed",
	"userId": "Musha_OpenMRS",
	"request": {
		"path": "/api/test",
		"headers": [
			{ "header1": "value1" },
			{ "header2": "value2" }
		],
		"requestParams": [
			{ "param1": "value1" },
			{ "param2": "value2" }
		],
		"body": "<HTTP body>",
		"method": "POST",
		"timestamp": "<ISO 8601>"
	},
	"response": {
		"status": 201,
		"body": "<HTTP body>",
		"headers": [
			{ "header1": "value1" },
			{ "header2": "value2" }
		],
		"timestamp": "<ISO 8601>"
	},
	"orchestrationSteps": [
		{
			"orchestrationType": "<orchestrationType>"
			// Same structure as above
			"request": { ... },
			"response": { ... }
		}
	]
}

Router

TODO

[
	{
		"urlPattern": "test/sample/.+",
		"allow": "*",
		"deny": "Mallet",
		"routes": [
			{
				"host": "localhost",
				"port": 8080	
			}
			
		]
	},
	{
		"urlPattern": "test/sample2/.+/test2",
		"allow": "Alice,Bob",
		"routes": [
			{
				"host": "localhost",
				"port": 8080,
				"primary": true
			},
			{
				"host": "log-host",
				"port": 4789	
			}
		]
	}
]