Etch Router¶

An Etch client may connect to an Etch service to consume APIs that the service provides. The client may have to maintain connections to multiple Etch services for the following purposes:

• The client wants to consume multiple set of unique API's, and each set is provided by a different Etch service
• There are multiple Etch services that are providing the same set of API, and the Etch client wants to connect to only one of them at a time, and use the others as a backup for high availability purpose.

To simplify the client side maintenance of multiple service connections, we'll implement a generic Etch service component to sit as a middle man between Etch clients and the API providers ( the Etch servers ). Let's call this an "Etch Router".

Basics¶

Basically, an Etch Router itself is an Etch server - it has its own Etch IDL which defines APIs and data types that it implements. Any an Etch client who wants to consume API services may connect to the Etch Router - as the router's "client" - and then be registered as an "application" in the router. Any an Etch server who wants to expose its API to the Etch router's "applications" may also connect to the Etch router - as the router's "client" too - and then be registered as the Etch Router's "service plugin".

At the plugin's registration time, the Etch Router should be able to identify the set of the APIs that the plugin can provide for service. A plugin may be registered either as a "singleton" plugin - i.e. the API set that this plugin provides is unique within the router, and no other plugin is providing any duplicate API service - or, as a member plugin of a plugin group - a plugin group may contain mutiple plugin members which all provide the same set of API service and has a fixed strategy in terms of choosing a member for connection, such as failover or round-robin.

When registering an application, the Etch Router should also be able to identify the set of APIs that the application wants to consume - so that it knows whether the currently registered plugins may satisfy the API requirements. The Etch Router may map these identified APIs to one or multiple "singleton plugin" or "plugin group"'s that provide the service. Then the Etch Router will establish a dedicated client connection to each of the plugin or plugin members for this registered application. The Etch router will maintain these connections for the application: when the application shuts down its connection to the router, the router will shut down the dedicated connections to the plugins for that application as well. When a plugin shuts down its connection to the router, all its associated connections that the router creates for the registered applications will be cleaned up and another connection to a plugin member in the same plugin group (if available) will be established for each of the applications, and the affected applications will be notified of this change as well.

On the application side, the Etch Router may be the only Etch server that the application connects to during its life time. As long as the initial registration is successful, it may call the Etch router to consume any API that it claims during Etch router registration, and doesn't have to know whether those APIs are provided by the same or different plugins, or whether the connections to the plugins has been re-mapped down the road.

Implementation Details¶

A prototype implementation of this Etch-Router has been checked in at here

The "plugins" folder in Etch-Router's Home Directory¶

When the Etch-Router (a Java Etch service) is starting up, it tries loading sub-directories under "plugin" folder in its home - the full path name of the "plugins" directory is configurable in the EtchRouter.properties file, by the property named "plugins.root.dir". Each sub-directory under this "plugins" folder is treated as a profile directory of a named "plugin group" - it usually contains two files:

• One XML binding file compiled from a typical service plugin's Etch IDL - this identifies the set of types and API's that the plugin implements.

• A properties file named metadata.txt - the content of this file may look like:

  plugin.group.type=roundrobina
  plugin.member.url.no1=tcp://127.0.0.1:4001
  plugin.member.metadata.no1=location\=LA
  plugin.member.url.no2=tcp://127.0.0.1:4002
  plugin.member.metadata.no2=location\=LA&language\=French
  

  This file defines the type of plugin group (currently "roundrobin" and "failover" are supported), and the URLs of the plugin members, or the Etch services that are providing API services defined by the XML binding. Additionally, each plugin member's service may also be marked with one or multiple properties via the "plugin.member.metadata." property.

The Etch-router will create one "plugin-group" object for each sub-directory under "plugins" and map all the methods defined in the directory's XML binding file to this named plugin-group.

Plugin-group Monitor¶

While the Etch-router is running, for each plugin-group that it has loaded, the router will monitor the "up and down" status of each plugin member by establishing a client connection to each member service URL defined in the group's metadata.txt file.

Client Connections and API Method Mapping¶

Any an etch application may connect to the Etch-router service as an ordinary Etch service - it then may consume any an API method defined in any one of the router's plugin-group XML binding file. On the etch-router side, in the transport stack for each application client connection, a special "EtchRouterFilter" is added to intercept each message sent between the client and the service: if the message is a API method call sent from application client, by looking at the message ID, the router will know which plugin-group has the implementation of the method - then it will find out whether a dedicated client connection has been established to a live member service of the mapped plugin-group for the application client connection. If yes, then it will forward this message to that service connection channel, otherwise, it will ask the mapped plugin-group to create a new service connection to one of its live members (here roundrobin or failover strategy may be adopted to decide which member to choose) and book keep that mapping information for later reference.

So for each application client connected to the etch-router, the router may book keep several client connections to the plugin member services. When the application client disconnects, the router will clean up the corresponding plugin member connections associated to the application client; when any one of the plugin member connection is down, the router will ask the plugin group to re-establish another connection and maintain it for the same application client.