controller

Super controller of REST API requests.
Acts as a single point of entry for all REST API requests

Assumptions / Constraints / Requirements

• REST endpoints must be specified using IDL, further gidl must be run on the IDL file and the generated lua code must be deployed in LUA_PATH (environmental variable that specifies lua deployment path)
• Request and response bodies (JSON) must be specified in XSD, further gxsd must be run on the XSD files and the generated files must be deployed in LUA_PATH (environmental variable that specifies lua deployment path)
• Each query param if present, must be defined as a schema element in the XSD
• URL of the request specifies the path of the request lua handler and the method in the request handler (last part of the URL is the method and path till the last part is the request handler classes). This is used to instantiate the request handler (using require function of lua) as well as to instantiate the interface stub generated using IDL
• In case of web sockets the handler is specified in the URL

Relevant properties

• service_utils.REST.controller.appBasePath: string: incremental path to be prepended to the path in the URL in the request
• service_utils.REST.controller.appBasePathNotToBeUsed: boolean, to control the usage of service_utils.REST.controller.appBasePath
• service_utils.REST.controller.noAuthUrls: string, (JSON) { urls: [strings] }. Specifies the set of URLS for which authentication will not be performed. e.g. { urls : [ "url1", "url2" ] }

Processing

1. Establish if the request is for HTTP Request or WEBSOCKET message based on weather the accepted socked handle is not upgrade to WEBSOCKET yet or not
2. If the HTTP request is for socket upgrade (Based on value of the header field "Connection" being "Upgrade") handle WEBSOCKET upgrade request.
3. Process the request, either HTTP or WEBSOCKET message

HTTP Request procesing

The processing steps followed in handling of a HTTP request is illustrated here

1. Deduce interface stub, request handler class and method in the handler class to be invoked
2. Parse the query params and make sure they are as per schema definition.
3. Parse the headers and validate the necessary headers (X-Auth)
4. Prepare user_context object
5. Parse the request body as per the schema definition provided in the IDL file
6. Make connections to the datase schema specified in IDL and add them to user_context object
7. BEGIN database transaction if necessary
8. Invoke the request handler method by passing appropriate inputs, <request_handler>:method(context, query_params[, input_object). The request handler method returns 2 variables. Any errors are set in the lua global variable _G.message_validation_context.status
   1. status: boolean
   2. return_object: table
9. Manage errors
10. END (COMMIT or ROLLBACK) database transaction if necessary
11. Serialize the return object to a JSON string using the definition provided in the IDL file
12. Prepare the response (statuss being 200 series, or 500 series)
13. Send response

WEBSOCKET message procesing

Processing of a WEBSOCKET message is handled bt service_utils.WS.web_socket.handle_msg

controller class

rest_controller.handle_request(request, response);

DESCRIPTION:

Single poing of entry for request handling in service_utils framework. Invokes appropriate REST endpoint implementation class developed in lua

PARAMETERS:

request, response

RETURN:

none

Potential errors:

Badly formed URL(if uri is nil).
Unable to deduce Controller class name and/or method(if class_name or func is nil which is extracted from url parts).
Unable to derserialize JSON, schema not specified.
Null message received, while expecting one(If request object doesn't have record, while the request is expecting one).
Invalid error code returned <ret_status>.(When ret_status is not a number or 200 < ret < 500).
Protocal not supported. Protocol not supported in socket implementation.

Error handling

The implementation classes can use the lua_schema.error_handler class to log errors as part of validation or as part of processing

Sturcture of the response error object in case of errors

{
    success: boolean;
    error_no: number;
    error_message: string;
    traceback: string; /* Stack trace */
    source_file: string;
    line_no: integer;
    field_path: string; /* document path of the field in the request object */
}

error_handler

class in lua_schema

local error_handler = require("lua_schema.error_handler");

error_handler.init();

DESCRIPTION:

Initializes the global variables necessary for error handling

PARAMETERS:

none

RETURN:

none

Potential errors:

error_handler.raise_validation_error(errno, message);

DESCRIPTION:

Logs a validation error (request validation)

PARAMETERS:

errno: integer
message: string

RETURN:

none

Potential errors:

error_handler.raise_error(errno, message);

DESCRIPTION:

Logs a processing error

PARAMETERS:

errno: integer
message: string

RETURN:

none

Potential errors:

error_handler.raise_fatal_error(errno, message);

DESCRIPTION:

Logs a processing error and throws exception

PARAMETERS:

errno: integer
message: string

RETURN:

none

Potential errors:

error_handler.reset();

DESCRIPTION:

Resets the global error object as if there are no erros logged so far

PARAMETERS:

errno: integer
message: string

RETURN:

none

Potential errors:

error_handler.reset_init();

DESCRIPTION:

Resets the global error object as if there are no erros logged so far and performs an init so that it is possible to continue logging fresh errors

PARAMETERS:

errno: integer
message: string

RETURN:

none

Potential errors: