+
+
API overview
+
Main application
+
Each application has an entry point. You may implement the main entry point like this:
+
import { Logger, Platform, RestAutomation } from 'mercury';
+import { ComposableLoader } from './preload/preload.js';
+
+const log = Logger.getInstance();
+
+async function main() {
+ // Load composable functions into memory and initialize configuration management
+ ComposableLoader.initialize();
+ // start REST automation engine
+ const server = new RestAutomation();
+ server.start();
+ // keep the server running
+ const platform = Platform.getInstance();
+ platform.runForever();
+ log.info('Hello world application started');
+}
+
+// run the application
+main();
+
+
In this example, the ComposableLoader will initialize the configuration management system,
+search and register available user functions into the event system. The default location
+of the system files is the "src/resources" folder.
+
+
+
+| File / bundle |
+Purpose |
+
+
+
+
+| application.yml |
+Base configuration file is assumed to be under the "src/resources" folder |
+
+
+| rest.yaml |
+REST endpoint configuration file is assumed to be under the "src/resources" folder |
+
+
+| HTML bundle |
+HTML/CSS/JS files, if any, can be placed under the "src/resources/public" folder |
+
+
+
+
To tell the system to use a different application.yml, you can use this following statement before
+running the ComposableLoader.initialize() command.
+
// resourcePath should be a fully qualified file path to the application's "resources" folder.
+const appConfig = AppConfig.getInstance(resourcePath);
+log.info(`Base configuration ${appConfig.getId()}`);
+
+
You may override the file path for REST endpoint configuration and HTML bundle with the following:
+
yaml.rest.automation: 'classpath:/rest.yaml'
+static.html.folder: 'classpath:/public'
+
+
To enable the REST automation engine, you must use the server.start() command.
+
To run the application as a service, use the platform.runForever() command. The application can be
+stopped with Control-C in interactive mode or the Kill command at the kernel level by a container
+management system such as Kubernetes.
+
Event envelope
+
A composable application is a collection of functions that communicate with each other in events.
+Each event is transported by an event envelope. Let's examine the envelope.
+
There are 3 elements in an event envelope:
+
+
+
+| Element |
+Type |
+Purpose |
+
+
+
+
+| 1 |
+metadata |
+Includes unique ID, target function name, reply address
correlation ID, status, exception, trace ID and path |
+
+
+| 2 |
+headers |
+User defined key-value pairs |
+
+
+| 3 |
+body |
+Event payload (primitive or JSON object) |
+
+
+
+
Headers and body are optional, but you must provide at least one of them.
+
Custom exception using AppException
+
To reject an incoming request, you can throw an AppException like this:
+
throw new AppException(400, "My custom error message");
+
+
As a best practice, we recommend using error codes that are compatible with HTTP status codes.
+
Defining a user function in TypeScript
+
You can write a function like this:
+
import { preload, Composable, EventEnvelope, AsyncHttpRequest, Logger } from 'mercury';
+
+const log = Logger.getInstance();
+
+export class DemoAuth implements Composable {
+
+ @preload('v1.api.auth', 5)
+ initialize(): DemoAuth {
+ return this;
+ }
+
+ async handleEvent(evt: EventEnvelope) {
+ const req = new AsyncHttpRequest(evt.getBody() as object);
+ const method = req.getMethod();
+ const url = req.getUrl();
+ log.info(`${method} ${url} authenticated`);
+ // this is a demo so we approve all requests
+ return true;
+ }
+}
+
+
You can define route name, instances, isPublic and isInterceptor in the preload annotation.
+The default values are instances=1, isPublic=false and isInterceptor=false. In the example,
+the number of instances is set to 5. You can set the number of instances from 1 to 500.
+
The above example is a demo "API authentication" function. The event body is an AsyncHttpRequest object
+from the user because the "rest.yaml" routes the HTTP request to the function via its unique "route name".
+
+
There are some reserved metadata for route name ("my_route"), trace ID ("my_trace_id") and trace path ("my_trace_path")
+in the event's headers. They do not exist in the incoming event envelope. The system automatically
+insert them as read-only metadata.
+
You may inspect other event metadata such as the replyTo address and correlation ID.
+
Note that the "replyTo" address is optional. It only exists when the caller is making an RPC request or callback to
+your function. If the caller sends an asynchronous drop-n-forget request, the "replyTo" value is null.
+
+
You can obtain a singleton instance of the Platform object to do the following:
+
Register a function
+
We recommend using the ComposableLoader to search and load your functions.
+
In some use cases where you want to create and destroy functions on demand, you can register them programmatically.
+
What is a public function?
+
A public function is visible by any application instances in the same network. When a function is declared as
+"public", the function is reachable through the Event-over-HTTP API REST endpoint.
+
A private function is invisible outside the memory space of the application instance that it resides.
+This allows application to encapsulate business logic according to domain boundary. You can assemble closely
+related functions as a composable application that can be deployed independently.
+
Release a function
+
In some use cases, you want to release a function on-demand when it is no longer required.
+
platform.release("another.function");
+
+
The above API will unload the function from memory and release it from the "event loop".
+
Obtain the unique application instance ID
+
When an application instance starts, a unique ID is generated. We call this the "Origin ID".
+
const originId = po.getOrigin();
+
+
PostOffice API
+
You can obtain an instance of the PostOffice from the input "headers" parameters in the input
+arguments of your function.
+
const po = new PostOffice(evt.getHeaders());
+
+
The PostOffice is the event manager that you can use to send asynchronous events or to make RPC requests.
+The constructor uses the READ only metadata in the "headers" argument in the "handleEvent" method of your function.
+
Check if a function is available
+
You can check if a function with the named route has been deployed.
+
if (po.exists("another.function")) {
+ // do something
+}
+
+
Obtain the class instance of a function
+
Since a composable function is executed as an anonymous function, the this reference is protected inside the
+functional scope and thus no longer relevant to the class scope.
+
To invoke other methods in the same class holding the composable function, the "getMyClass()" API can be used.
+
async handleEvent(evt: EventEnvelope) {
+ const po = new PostOffice(evt.getHeaders());
+ const self = po.getMyClass() as HelloWorldService;
+ // business logic here
+ const len = await self.downloadFile(request.getStreamRoute(), request.getFileName());
+}
+
+
In the above example, HelloWorldService is the Composable class and the downloadFile is a non-static method
+in the same class. Note that you must use the event headers to instantiate the PostOffice object.
+
+
The following code segment demonstrates that you can retrieve the function's route name, worker number,
+optional traceId and tracePath.
+
async handleEvent(evt: EventEnvelope) {
+ const po = new PostOffice(evt.getHeaders());
+ const route = po.getMyRoute();
+ const workerNumber = po.getMyInstance();
+ const traceId = po.getMyTraceId();
+ const tracePath = po.getMyTracePath();
+ // processing logic here
+}
+
+
Send an asynchronous event to a function
+
You can send an asynchronous event like this.
+
// example-1
+const event = new EventEnvelope().setTo('hello.world').setBody('test message');
+po.send(event);
+
+// example-2
+po.sendLater(event, 5000);
+
+
+- Example-1 sends the text string "test message" to the target service named "hello.world".
+- Example-2 schedules an event to be sent 5 seconds later.
+
+
Make a RPC call
+
You can make RPC call like this:
+
// example-1
+const event = new EventEnvelope().setTo('hello.world').setBody('test message');
+const result = await po.request(event, 5000);
+
+// example-2
+const result = await po.remoteRequest(event, 'http://peer/api/event');
+
+// API signatures
+request(event: EventEnvelope, timeout = 60000): Promise<EventEnvelope>
+remoteRequest(event: EventEnvelope, endpoint: string,
+ securityHeaders: object = {}, rpc=true, timeout = 60000): Promise<EventEnvelope>
+
+
+- Example-1 makes a RPC call with a 5-second timeout to "hello.world".
+- Example-2 makes an "event over HTTP" RPC call to "hello.world" in another application instance called "peer".
+
+
"Event over HTTP" is an important topic. Please refer to Chapter 5 for more details.
+
Retrieve trace ID and path
+
If you want to know the route name and optional trace ID and path, you can inspect the incoming event headers.
+
const po = new PostOffice(evt.getHeaders());
+const myRoute = po.getMyRoute();
+const traceId = po.getMyTraceId();
+const tracePath = po.getMyTracePath();
+const myInstance = po.getMyInstance();
+
+
Configuration API
+
Your function can access the main application configuration management system like this:
+
const config = AppConfig.getInstance().getReader();
+// the value can be string or a primitive
+const value = config.get('my.parameter');
+// the return value will be converted to a string
+const text = config.getProperty('my.parameter');
+
+
The system uses the standard dot-bracket format for a parameter name.
+
+e.g. "hello.world", "some.key[2]"
+
+
You can also override the main application configuration using the set method.
+
Additional configuration files can be added with the ConfigReader API like this:
+
const myConfig = new ConfigReader(filePath);
+
+
where filePath can use the classpath:/ or file:/ prefix.
+
The configuration system supports environment variable or reference to the main application configuration
+using the dollar-bracket syntax ${reference:default_value}.
+
+e.g. "some.key=${MY_ENV_VARIABLE}", "some.key=${my.key}"
+
+
Override configuration parameters at run-time
+
You can override any configuration parameter from the command line when starting your application.
+
node my-app.js -Dsome.key=some_value -Danother.key=another_value
+
+
You can point your application to use a different base configuration file like this:
+
node my-app.js -C/opt/config/application.yml
+
+
The -C command line argument tells the system to use the configuration file in "/opt/config/application.yml".
+
+Exercise: try this command "node hello-world.js -Dlog.format=json" to start the demo app
+
+
This will tell the Logger system to use JSON format instead of plain text output. The log output may look like this:
+
{
+ "time": "2023-06-10 09:51:20.884",
+ "level": "INFO",
+ "message": "Event system started - 9f5c99c4d21a42cfb0115cfbaf533820",
+ "module": "platform.js:441"
+}
+{
+ "time": "2023-06-10 09:51:21.037",
+ "level": "INFO",
+ "message": "REST automation service started on port 8085",
+ "module": "rest-automation.js:226"
+}
+
+
Logger
+
The system includes a built-in logger that can log in either text or json format.
+
The default log format is "text". You can override the value in the "src/resources/application.yml" config file.
+The following example sets the log format to "json".
+
log.format: json
+
+
Alternatively you can also override it at run-time using the "-D" parameter like this:
+
node my-app.js -Dlog.format=json
+
+
The logger supports line-numbering. When you run your executable javascript main program, the line number for each
+log message is derived from the ".js" file.
+
If you want to show the line number in the source ".ts" file for easy debug, you can run your application using
+"nodemon". This is illustrated in the "npm start" command in the package.json file.
+
For simplicity, the logger is implemented without any additional library dependencies.
+
Minimalist API design for event orchestration
+
As a best practice, we advocate a minimalist approach in API integration.
+To build powerful composable applications, the above set of APIs is sufficient to perform
+"event orchestration" where you write code to coordinate how the various functions work together as a
+single "executable". Please refer to Chapter-4 for more details about event orchestration.
+
Since Mercury is used in production installations, we will exercise the best effort to keep the core API stable.
+
Other APIs in the toolkits are used internally to build the engine itself, and they may change from time to time.
+They are mostly convenient methods and utilities. The engine is fully encapsulated and any internal API changes
+are not likely to impact your applications.
+
Optional Event Scripting
+
To further reduce coding effort, you can perform "event orchestration" by configuration using "Event Script".
+
Co-existence with other development frameworks
+
Mercury libraries are designed to co-exist with your favorite frameworks and tools. Inside a class implementing
+a composable function, you can use any coding style and frameworks as you like, including sequential, object-oriented
+and reactive programming styles.
+
Mercury has a built-in lightweight non-blocking HTTP server based on Express, but you can also use other
+application server framework with it.
+
Template application for quick start
+
You can use the hello world project as a template to start writing your own applications.
+
Source code update frequency
+
This project is licensed under the Apache 2.0 open sources license. We will update the public codebase after
+it passes regression tests and meets stability and performance benchmarks in our production systems.
+
The source code is provided as is, meaning that breaking API changes may be introduced from time to time.
+
Technical support
+
For enterprise clients, technical support is available. Please contact your Accenture representative
+for details.
+
+
+
+
