Create a Middleware

Owned by antoine hage
Last updated: May 19, 2020

A complete guide to build your own custom middleware for SOAJS. Let us start by going over the capabilities SOAJS Gateway provides. SOAJS Gateway provides the 3 capabilities to be consumed by a middleware:

  1. getRegistry:  Get registry is an API available by the gateway to get the registry. This super handy since you can store environment driven configuration and make them available to your services without the need to deal with files and tons of environment variables. Also you can at anytime change the registry and reload it without the need to restart neither the gateway nor the service. pretty neat no! (smile)

  2. register: Register us an API available by the gateway to automatically register your service. This is very useful when you are coding your service and you want to test it behind the gateway and you want the gateway to be aware of your service automatically without the need to manually configure this every time for every service. It is annoying no! (sad) 

  3. soajsinjectobj: The SOAJS header object that gets injected by the gateway to every request made containing lots of useful information needed by the service regarding authentication, multi tenancy, etc .... yaiii finally a super hero gateway (smile)

Environment Variables

The following are the need environment variable:

NameDescriptionExample
SOAJS_REGISTRY_API
where is SOASJ Gateway and what is the maintenance port

127.0.0.1:5000

SOAJS_DEPLOY_MANUAL
True or False if the service is being deployed manually (means you are developing on your local machine) or inside a container technology1
SOAJS_ENV
The environment in which the service is running to pull its registryDEV


1- getRegistry

URLExampleMethod
http://SOAJS_REGISTRY_API/getRegistryhttp://127.0.0.1:5000/getRegistryGET

Input 

ParamTypeDescriptionExample
env
stringThe environment to pull its registrydev
serviceName
stringThe serviceName requesting the registryshopping

Output

getRegistry output success
{
	"result": true,
	"ts": 1589888826574,
	"service": {
		"service": "soajs.controller",
		"version": "4.0.0",
		"type": "rest",
		"route": "/getRegistry"
	},
	"data": {
		"timeLoaded": 1550250987887,
		"name": "dev",
		"environment": "dev",
		"coreDB": {
			"provision": {
				"name": "core_provision",
				"prefix": "",
				"servers": [{
					"host": "127.0.0.1",
					"port": 27017
				}],
				"credentials": null,
				"streaming": {
					"batchSize": 10000,
					"colName": {
						"batchSize": 10000
					}
				},
				"URLParam": {
					"bufferMaxEntries": 0
				},
				"registryLocation": {
					"l1": "coreDB",
					"l2": "provision",
					"env": "dev"
				},
				"timeConnected": 1550250987888
			},
			"session": {
				"name": "core_session",
				"prefix": "",
				"store": {},
				"collection": "sessions",
				"stringify": false,
				"expireAfter": 1209600000,
				"registryLocation": {
					"l1": "coreDB",
					"l2": "session",
					"env": "dev"
				},
				"cluster": "cluster1",
				"servers": [{
					"host": "127.0.0.1",
					"port": 27017
				}],
				"credentials": null,
				"URLParam": {
					"connectTimeoutMS": 0,
					"socketTimeoutMS": 0,
					"maxPoolSize": 5,
					"wtimeoutMS": 0,
					"slaveOk": true
				},
				"extraParam": {
					"db": {
						"native_parser": true
					},
					"server": {
						"auto_reconnect": true
					}
				}
			}
		},
		"tenantMetaDB": {
			"urac": {
				"prefix": "",
				"cluster": "cluster1",
				"servers": [{
					"host": "127.0.0.1",
					"port": 27017
				}],
				"credentials": null,
				"streaming": null,
				"URLParam": {
					"connectTimeoutMS": 0,
					"socketTimeoutMS": 0,
					"maxPoolSize": 5,
					"wtimeoutMS": 0,
					"slaveOk": true
				},
				"extraParam": {
					"db": {
						"native_parser": true
					},
					"server": {
						"auto_reconnect": true
					}
				},
				"name": "#TENANT_NAME#_urac"
			}
		},
		"serviceConfig": {
			"awareness": {
				"healthCheckInterval": 500,
				"autoRelaodRegistry": 300000,
				"maxLogCount": 5,
				"autoRegisterService": true
			},
			"agent": {
				"topologyDir": "/opt/soajs/"
			},
			"key": {
				"algorithm": "aes256",
				"password": "soajs key lal massa"
			},
			"logger": {
				"level": "fatal",
				"formatter": {
					"outputMode": "short"
				}
			},
			"ports": {
				"controller": 4000,
				"maintenanceInc": 1000,
				"randomInc": 100
			},
			"cookie": {
				"secret": "this is a secret sentence"
			},
			"session": {
				"name": "soajsID",
				"secret": "this is antoine hage app server",
				"rolling": false,
				"unset": "keep",
				"cookie": {
					"path": "/",
					"httpOnly": true,
					"secure": false,
					"domain": "soajs.com",
					"maxAge": null
				},
				"resave": false,
				"saveUninitialized": false
			}
		},
		"deployer": {
			"type": "container",
			"selected": "container.docker.local",
			"container": {
				"docker": {
					"local": {
						"socketPath": "/var/run/docker.sock"
					},
					"remote": {
						"nodes": []
					}
				},
				"kubernetes": {
					"local": {},
					"remote": {
						"nodes": []
					}
				}
			}
		},
		"custom": {
			"c2": {
				"_id": "5c619f29d0c96c16bc2a7e26",
				"name": "c2",
				"locked": true,
				"plugged": true,
				"shared": true,
				"value": "test custom registry entry",
				"created": "DEV",
				"author": "owner"
			},
			"c5": {
				"_id": "5c619f29d0c96c16bc2a7e27",
				"name": "c5",
				"created": "DEV",
				"author": "owner",
				"locked": false,
				"plugged": true,
				"shared": false,
				"value": "test"
			}
		},
		"resources": {
			"cluster": {
				"demo": {
					"_id": "59f1ab7f89e3e94321ad2d57",
					"name": "demo",
					"type": "cluster",
					"created": "DEV",
					"author": "owner",
					"config": {
						"type": "mongo",
						"servers": [{
							"host": "127.0.0.1",
							"port": 27017
						}],
						"credentials": null,
						"URLParam": {
							"connectTimeoutMS": 0,
							"socketTimeoutMS": 0,
							"maxPoolSize": 2,
							"wtimeoutMS": 0,
							"slaveOk": true
						},
						"extraParam": {
							"db": {
								"native_parser": true,
								"bufferMaxEntries": 0
							},
							"server": {
								"socketOptions": {
									"autoReconnect": false
								}
							}
						}
					},
					"plugged": true,
					"category": "mongo"
				}
			}
		},
		"services": {
			"controller": {
				"group": "controller",
				"port": 4000
			},
			"express": {
				"group": "Custom Services",
				"port": 4381
			}
		}
	}
}


getRegistry output failure
{
	"result": false,
	"ts": 1550249913135,
	"service": {
		"service": "soajs.controller",
		"version": "4.0.0",
		"type": "rest",
		"route": "/getRegistry"
	}
}


2- register

URLExampleMethod
http://SOAJS_REGISTRY_API/registerhttp://127.0.0.1:5000/registerPOST

Input

register input
{
  "name": "express",
  "group": "Custom-Services",
  "port": 4381,
  "ip": "127.0.0.1",
  "type": "service",
  "subType": "blabla",
  "description": "this is a great service",
  "version": "1",
  "oauth": true,
  "urac": true,
  "urac_Profile": false,
  "urac_ACL": false,
  "urac_Config": false,
  "urac_GroupConfig": false,
  "tenant_profile": false,
  "provision_ACL": false,
  "extKeyRequired": true,
  "requestTimeout": 30,
  "requestTimeoutRenewal": 5,
  "mw": true,
  "maintenance": {
    "port": {
      "type": "inherit"
    },
    "readiness": "/heartbeat"
  },
  "interConnect": [{"name":"order","version":"1"}]
}

Output

register output success
{
	"result": true,
	"ts": 1550251212340,
		"service": {
		"service": "soajs.controller",
		"version": "4.0.0",
		"type": "rest",
		"route": "/getRegistry"
	},
	"data": {
		"group": "Custom-Services",
		"port": 4381,
		"requestTimeoutRenewal": 5,
		"requestTimeout": 30,
		"maintenance": {
			"port": {
				"type": "inherit"
			},
			"readiness": "/heartbeat"
		},
		"versions": {
			"1": {
				"extKeyRequired": true,
				"oauth": true,
				"provision_ACL": false,
				"urac": true,
				"urac_ACL": false,
				"urac_Profile": false
			}
		},
		"version": "1",
		"hosts": {
			"1": ["127.0.0.1"],
			"latest": "1"
		},
		"awarenessStats": {
			"127.0.0.1": {
				"lastCheck": 1550251212085,
				"healthy": false,
				"version": "1",
				"downCount": 1,
				"downSince": 1550251211581
			}
		},
		"extKeyRequired": true
	}
}
register output failure
{
	"result": false,
	"ts": 1550249913135,
	"service": {
		"service": "soajs.controller",
		"version": "4.0.0",
		"type": "rest",
		"route": "/getRegistry"
	},
}

3- soajsinjectobj


soajs inject object
{
	"tenant": {
		"id": "5c17cda54adb9ddba2a29a1d",
		"code": "DEMO",
		"locked": false,
		"roaming": {}
	},
	"key": {
		"config": {
			"shopping": {
				"subject": "anything",
				"you": "add any json object"
			}
		},
		"iKey": "972af87dc4baba8d243fa34bcf9c0a1a",
		"eKey": "313473daac2dafda50286f4179ff1752f1c8f0b1ebe7bbc9a41cb223ddb471c6c186b797d0fb5dcd13d9fea41abfb73a63b51abdd7525cd08c81b5e624a405b4e7c6d20a572e9ea654ebcec07f12ad90009cbc415afe9ac06ce93ef1101d94fe"
	},
	"application": {
		"product": "DEMO",
		"package": "DEMO_ROCKS",
		"appId": "5c17cdad4adb9ddba2a29a1e",
		"acl": {},
		"acl_all_env": {}
	},
	"package": {
		"acl": {},
		"acl_all_env": {}
	},
	"device": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36",
	"geo": {
		"ip": "127.0.0.1"
	},
	"awareness": {
		"host": "127.0.0.1",
		"port": 4000
	},
	"urac": {
		"_id": "5c17cdad4adb9ddba2a29a1e",
		"username": "name",
		"firstName": "tony",
		"lastName": "smith",
		"email": "tt@smith.com",
		"groups": ["admin"],
		"socialLogin": {},
		"tenant": {
			"id": "5c17cda54adb9ddba2a29a1d",
			"code": "DEMO"
		},
		"profile": { 
		},
		"acl": {},
		"acl_all_env": {}
	},
	"param": {
		
	}
}