web_socket

Implementation of lifecylce methods of the evlua websocket module

Synopsis

Contains methods fresh connection and acceptance of upgrade requests and stub for processing of incoming frames on server side

local ws = require('service_utils.WS.web_socket');

The implementation allows

ws_connection:

A lua class that encapsulates an underlying ss (stream socket) and a set of properties specific to a websocket, viz

• ss
• host
• port
• is_TLS
• message handler

Methods

ws.accept(request, response, uc):

DESCRIPTION:

Processes WEBSOCKET upgrade request. Called upon arrival of an Upgrade request in evluaserver

reponse is generated with status and header fields (status:101[success] status:400[failure])

PARAMETERS:

request: userdata(httpsreq)
response: userdata(httpsresp)
user_context: table, User context

RETURN:

status: boolean, true(if connection is accepted) / false(if connection fails).

ERROR:

Missing Sec-WebSocket-Version(tells the server, the subprotocols that are supported in a particular version) in handshake request (if Websocket version is not present in the request header).
Unsupported WebSocket version requested(version 13 is used).
Missing Sec-WebSocket-Key in handshake request(if Sec-WebSocket key is not present in the request).
Path empty: Unable to deduce message handler(if the request does not have a url or is nil).

ws.connect(inputs):

DESCRIPTION:

This function upgrades a HTTP session to WEBSOCKET

PARAMETERS:

input: table, containing following elements:

• input.url: string, this also specifies the path of the WEBSOCKET message handler on server side
• [input.msg_handler]: string, the message handler class on the client side.
• input.hdrs: table, additional request headers
• input.external: boolean, meaning if the URL is outside the implementation of product services
• input.secure: boolean, if HTTPS should be used
• input.timeout: number, connection timeout

RETURN:

connection: table
response: status
hdrs: table, response headers
In case of any error connection will be returned as nil and the second return value will have the message

ERROR:

Assertions: all the above parameters should be not nil and should be of correct type.
No Connection: Upgrade header in handshake response(response header does not contain Connection key or it's value is not equal to Upgrade).
No Upgrade: websocket header in handshake response(response header does not contain Upgrade key or it's value is not equal to websocket).
Invalid or missing Sec-WebSocket-Accept header in handshake response(response header does not contain Sec-WebSocket-Accept key or it's value is not equal to nonce).

ws.handle_msg(request, response):

DESCRIPTION:

This function is invoked at the receiver side, upon a new message arrival. Since, websocket is a bidirectional full duplex function, both client and server can recieve messages. This method is used by framework implementation and provides the initial and generic part of WEBSOCKET messsage processing (stub). It calls appropriate lua class and method based on what is specified during connection or as part of URL in the server side

PARAMETERS:

request: userdata(httpsreq)
response: userdata(httpsresp)

RETURN:

none

ERROR:

Invalid Op_Code(Op code in the accepted stream socket object is not equal to 0x09(frame_op_ping))