blob: 78e243b003afd8b4f76c2287954596b5c39f1656 [file] [log] [blame]
Author: Tamás Levente Kiss
Version: 1551-CNL 113 865, Rev. PA1
Date: 2018-01-16
= EPTF Service Framework, Description
:author: Tamás Levente Kiss
:revnumber: 1551-CNL 113 865, Rev. PA1
:revdate: 2018-01-16
== System Requirements
EPTF Service Framework is written in python and can run on any device supporting python.
= Functionality
== General
EPTF Service Framework (ESF) can be used to build different applications by implementing and selecting the appropriate microservices to fulfill the applications requirements. ESF itself also provides built-in microservices which are the following:
* DataSource
* Authenticator
* Playlist
The framework comes with a set of tools to help microservices serve basic or `DsRestAPI` HTTP requests.
For more information on `DsRestAPI` see[DsRestAPI Function Description]
Microservices implementing `DsRestAPI` may also implement user interfaces with the help of EPTF Web GUI (EWG). If so, the application needs to implement a GUI configuration handler microservice to provide the EWG a GUI configuration descriptor. This microservice should implement a `createConfig()` function, returning a valid EWG configuration descriptor in JSON format. The function has access to the user groups of the user accessing a web application, therefore it could decide whether the user specific user has access to the web application or not.
The descriptor should also contain EWG specific customization descriptors and HTTP resource directory information.
For more information on the structure of the EPF Web GUI descriptors and on how to write a web application based on EWG, see the[EPTF Web GUI] documentation.
Overview of the ESF:
ESFs central component is the `AppAgent` module, which loads the microservices located in directory, and also serves as an HTTP server to serve microservices API, and the possible web application resources (html, js and other files).
The microservices should provide an API extension (a string value), which is unique in the applications context, and has the role of an address for a specific microservice in the application. The microservices may implement HTTP handlers (a function named `handleMessage`), where HTTP requests will be forwarded. If the function is implemented, `AppAgent` will forward the requests with the appropriate extension to the addressed microservice.
All the microservices are running on the same python context, therefore the applications performance is limited. If one of the microservices is performance-critical, it is advised to handle its critical tasks in separate threads (separate real system threads not python threads; or separate python contexts). It is not advised to block a request handler in any circumstances, because it will affect the whole applications performance.
== ESFs Built-In Microservices
=== DataSource
Serves a `DsRestAPI`. The API can return the source names registered as data sources, and the following basic operators (also as data source elements):
* not
* ==
* !=
* >
* >=
* <
* <=
* and
* or
* match
* not match
* sum
* exists
* forAll
* dataElementPresent
* sizeOf
=== Authenticator
Handles user groups and users. A user can be part of multiple user groups. If authenticated, the user and group information of a request is forwarded to the microservices handler functions, and the microservice can decide whether to serve the request as an authenticated request or not.
=== Playlist
Can issue scheduled, potentially conditional requests to any microservice which serves a `DSRestAPI` compatible interface. The scheduled commands and their relations are described by a JSON file matching the Playlists schema.
This microservice comes with a user interface part, in order to let the user edit the JSON descriptors graphically.
= Usage
== Writing an Application Over ESF
An application built with the help of ESF should implement microservices with functionalities specific to the application needs. The microservice interface has 3 functions out of which one is optional:
=== Function `getDataSourceHandlers` (optional)
Has no parameters. Should return the DsRestAPI specific handler function references: the getDataHandler and setDataHandler function references.
=== Function `close` (mandatory)
Has no parameters nor a return value. It is going to be called before AppAgent closes.
=== Function `handleMessage` (mandatory)
The function has the following function parameters:
* method HTTP method
* path HTTP full URI
* headers HTTP headers list
* body HTTP body
* userCredentials user name and group information
* response HTTP response object. In case of DsRestAPI responses, the objects `body` field needs to be filled with the JSON response string, and the `headers` fields `content-type` field needs to be set to "application/json" accordingly.
== Deployment and Configuration
There are 2 ways to run an application built up on the ESF.
1. Copying Needed Files to the Destination
The first way is to copy the frameworks files and the needed set of microservices on the destination location. The server port and address can be configured in a _config.json_ file located in the working directory.
In this case, the application can be started by running the ESFs _AppAgent.py_, with the needed subset of microservices deployed in the Microservices directory in the ESFs directory hierarchy.
2. Creating an Executor Script
Alternatively, all the microservices can be kept in the Microservices directory, and different subsets of microservices with different configurations can be run from a python script created for this purpose.
In this case, the `runAppAgent` public function located in the `AppAgent` module can be called directly from a python script. The server configuration and the microservices to be loaded had to be defined as function parameters during this function call.
== Compiling and Running
All modules are using python with `ldap` add-on. The application was tested with python version 2.7.13, and 2.7.9-addons-ldap. Should also work with the latest 2.7 versions.
= Functional Specification
== Structure of the Source Code
The source code is organized into the following directory structure:
= Abbreviations
ESF:: EPTF Service Framework
API:: Application Programming Interface
GUI:: Graphical User Iterface
JSON:: JavaScript Object Notation
= References
[1] EPTF Web GUI +
[2] DsRestAPI function description +
[3] UDsRestAPI user guide +