The implementation class that runs the websocket server. More...

#include <WSServer.hpp>

Collaboration diagram for Leosac::Module::WebSockAPI::WSServer:

Public Types
using	Server = websocketpp::server< websocketpp::config::asio >

using	ConnectionAPIMap = std::map< websocketpp::connection_hdl, APIPtr, std::owner_less< websocketpp::connection_hdl > >

Public Member Functions
	WSServer (WebSockAPIModule &module, DBPtr database)

	~WSServer ()

void	run (const std::string &interface, uint16_t port)

void	start_shutdown ()
	Start the process of shutting down the server. More...

bool	register_asio_handler (const Service::WSHandler &handler, const std::string &name)
	This function block the calling thread until the WebSocket thread has processed the handler registration. More...

void	register_crud_handler_external (const std::string &resource_name, CRUDResourceHandler::Factory factory)
	Register a CRUD handler from an external thread. More...

void	unregister_handler (const std::string &name)
	Remove an Asio based handler. More...

APIAuth &	auth ()
	Retrieve the authentication helper. More...

DBPtr	db ()
	Retrieve database handle. More...

DBServicePtr	dbsrv ()
	Retrieve database service pointer. More...

CoreUtilsPtr	core_utils ()
	Retrieve the CoreUtils pointer. More...

void	clear_user_sessions (Auth::UserPtr user, APIPtr exception)
	Deauthenticate all the connections of `user`, except the `exception` APISession. More...

Public Attributes
Server	srv_

Private Member Functions
void	on_open (websocketpp::connection_hdl hdl)

void	on_close (websocketpp::connection_hdl hdl)

void	attempt_unregister_ws_service ()

void	on_message (websocketpp::connection_hdl hdl, Server::message_ptr msg)
	A websocket message has been received. More...

boost::optional< ServerMessage >	handle_request (APIPtr api_handle, const ClientMessage &msg, Audit::IAuditEntryPtr)
	Handle a request. More...

ClientMessage	parse_request (const json &in)
	Create a ClientMessage object from a json request. More...

void	send_message (websocketpp::connection_hdl hdl, const ServerMessage &msg)
	Send a message over a connection. More...

void	register_crud_handler (const std::string &resource_name, CRUDResourceHandler::Factory factory)
	An internal helper function to register a CRUD resource handler. More...

boost::optional< json >	dispatch_request (APIPtr api_handle, const ClientMessage &in, Audit::IAuditEntryPtr)
	Dispatch the request from a client, so that it is processed by the appropriate handler. More...

bool	has_handler (const std::string &name) const
	Returns true if an handler named `name` already exists. More...

void	finalize_audit (const Audit::IWSAPICallPtr &audit, ServerMessage &msg)
	Extract values from the `msg` and finalizes the `audit` object with them. More...

Private Attributes
ConnectionAPIMap	connection_session_

APIAuth	auth_

std::map< std::string, json(APISession::*)(const json &)>	handlers_
	This maps (string) command name to API method. More...

std::map< std::string, MethodHandler::Factory >	individual_handlers_

std::map< std::string, CRUDResourceHandler::Factory >	crud_handlers_

std::map< std::string, Service::WSHandler >	asio_handlers_
	Handlers registered through the WebSockAPI::Service object. More...

DBServicePtr	dbsrv_
	Database service object. More...

WebSockAPIModule &	module_
	A reference to the module. More...

std::unique_ptr< boost::asio::io_service::work >	work_
	Work used to keep the io_service alive while someone has a reference to (WS) Service object. More...

Detailed Description

The implementation class that runs the websocket server.

The run() method is invoked in its own thread, and from this point on, the object lives its life independently in this thread.

The WebSockAPIModule object can communicate with WSServer by calling any of the thread safe method.

The WebSockAPI::Service class communicates with the WSServer object through the asio loop.

Note: Unless specified otherwise, the methods in this class ARE NOT thread-safe.

Definition at line 61 of file WSServer.hpp.

Member Typedef Documentation

◆ ConnectionAPIMap

using Leosac::Module::WebSockAPI::WSServer::ConnectionAPIMap = std::map<websocketpp::connection_hdl, APIPtr, std::owner_less<websocketpp::connection_hdl> >

Definition at line 73 of file WSServer.hpp.

◆ Server

using Leosac::Module::WebSockAPI::WSServer::Server = websocketpp::server<websocketpp::config::asio>

Definition at line 71 of file WSServer.hpp.

Constructor & Destructor Documentation

◆ WSServer()

WSServer::WSServer	(	WebSockAPIModule &	module,
		DBPtr	database
	)

Parameters

database A (non-null) pointer to the database.

Definition at line 78 of file WSServer.cpp.

◆ ~WSServer()

WSServer::~WSServer ( )

Definition at line 137 of file WSServer.cpp.

Member Function Documentation

◆ attempt_unregister_ws_service()

void WSServer::attempt_unregister_ws_service ( )

private

Definition at line 539 of file WSServer.cpp.

◆ auth()

APIAuth & WSServer::auth ( )

Retrieve the authentication helper.

Definition at line 264 of file WSServer.cpp.

◆ clear_user_sessions()

void WSServer::clear_user_sessions	(	Auth::UserPtr	user,
		APIPtr	exception
	)

Deauthenticate all the connections of user, except the exception APISession.

Definition at line 410 of file WSServer.cpp.

◆ core_utils()

CoreUtilsPtr WSServer::core_utils ( )

Retrieve the CoreUtils pointer.

Definition at line 342 of file WSServer.cpp.

◆ db()

DBPtr WSServer::db ( )

Retrieve database handle.

Definition at line 337 of file WSServer.cpp.

◆ dbsrv()

DBServicePtr WSServer::dbsrv ( )

Retrieve database service pointer.

Definition at line 454 of file WSServer.cpp.

◆ dispatch_request()

boost::optional< json > WSServer::dispatch_request	(	APIPtr	api_handle,
		const ClientMessage &	in,
		Audit::IAuditEntryPtr	audit
	)

private

Dispatch the request from a client, so that it is processed by the appropriate handler.

This method returns an optional json object. If the handler is external, then no json is returned.

Definition at line 269 of file WSServer.cpp.

◆ finalize_audit()

void WSServer::finalize_audit	(	const Audit::IWSAPICallPtr &	audit,
		ServerMessage &	msg
	)

private

Extract values from the msg and finalizes the audit object with them.

The msg may be modified if finalizing the audit object fails.

Definition at line 465 of file WSServer.cpp.

◆ handle_request()

boost::optional< ServerMessage > WSServer::handle_request	(	APIPtr	api_handle,
		const ClientMessage &	msg,
		Audit::IAuditEntryPtr	audit
	)

private

Handle a request.

Extract request header, set-up exception handling for api handler invocation.

Optionally returns a ServerMessage that must be send to the client.

Definition at line 383 of file WSServer.cpp.

◆ has_handler()

bool WSServer::has_handler ( const std::string & name ) const

private

Returns true if an handler named name already exists.

Definition at line 459 of file WSServer.cpp.

◆ on_close()

void WSServer::on_close ( websocketpp::connection_hdl hdl )

private

Definition at line 150 of file WSServer.cpp.

◆ on_message()

void WSServer::on_message	(	websocketpp::connection_hdl	hdl,
		Server::message_ptr	msg
	)

private

A websocket message has been received.

At this point, all error handling happens through the use of exception. Non-exceptional event, such as:

Malformed packet
Unsuficient permission to perform a given API call
... are also reported through exceptions.

While this may not be the best performance wise, it's unlikely to be a bottleneck, but it helps keep things clean.

Note: This method is responsible for saving the WSAPICall Audit event.

Definition at line 156 of file WSServer.cpp.

◆ on_open()

void WSServer::on_open ( websocketpp::connection_hdl hdl )

private

Definition at line 143 of file WSServer.cpp.

◆ parse_request()

ClientMessage WSServer::parse_request ( const json & in )

private

Create a ClientMessage object from a json request.

Definition at line 361 of file WSServer.cpp.

◆ register_asio_handler()

bool WSServer::register_asio_handler	(	const Service::WSHandler &	handler,
		const std::string &	name
	)

This function block the calling thread until the WebSocket thread has processed the handler registration.

Note: This method is thread-safe.

Definition at line 492 of file WSServer.cpp.

◆ register_crud_handler()

void WSServer::register_crud_handler	(	const std::string &	resource_name,
		CRUDResourceHandler::Factory	factory
	)

private

An internal helper function to register a CRUD resource handler.

The resource name will be expanded to create handler for multiple type of requests:

"resource_name"_read
"resource_name"_create
...

Parameters

resource_name
factory

Definition at line 442 of file WSServer.cpp.

◆ register_crud_handler_external()

void WSServer::register_crud_handler_external	(	const std::string &	resource_name,
		CRUDResourceHandler::Factory	factory
	)

Register a CRUD handler from an external thread.

The handler will be invoked on the Websocket thread.

This method should only be called by WebSockAPI::Service.

Note: This method is thread-safe and will block the calling thread until the registration is done.

Definition at line 526 of file WSServer.cpp.

◆ run()

void WSServer::run	(	const std::string &	interface,
		uint16_t	port
	)

Definition at line 223 of file WSServer.cpp.

◆ send_message()

void WSServer::send_message	(	websocketpp::connection_hdl	hdl,
		const ServerMessage &	msg
	)

private

Send a message over a connection.

Parameters

hdl	The connection
msg	The message.

Definition at line 347 of file WSServer.cpp.

◆ start_shutdown()

void WSServer::start_shutdown ( )

Start the process of shutting down the server.

The server will stop listening for new connection and will attempt to close existing one.

Note: This method can safely be called from an other thread.

Definition at line 243 of file WSServer.cpp.

◆ unregister_handler()

void WSServer::unregister_handler ( const std::string & name )

Remove an Asio based handler.

Note: This method is thread-safe and runs the removal code into the WSServer's io_service.

Definition at line 510 of file WSServer.cpp.

Member Data Documentation

◆ asio_handlers_

std::map<std::string, Service::WSHandler> Leosac::Module::WebSockAPI::WSServer::asio_handlers_

private

Handlers registered through the WebSockAPI::Service object.

Definition at line 246 of file WSServer.hpp.

◆ auth_

APIAuth Leosac::Module::WebSockAPI::WSServer::auth_

private

Definition at line 232 of file WSServer.hpp.

◆ connection_session_

ConnectionAPIMap Leosac::Module::WebSockAPI::WSServer::connection_session_

private

Definition at line 231 of file WSServer.hpp.

◆ crud_handlers_

std::map<std::string, CRUDResourceHandler::Factory> Leosac::Module::WebSockAPI::WSServer::crud_handlers_

private

Definition at line 241 of file WSServer.hpp.

◆ dbsrv_

DBServicePtr Leosac::Module::WebSockAPI::WSServer::dbsrv_

private

Database service object.

Definition at line 251 of file WSServer.hpp.

◆ handlers_

std::map<std::string, json (APISession::*)(const json &)> Leosac::Module::WebSockAPI::WSServer::handlers_

private

This maps (string) command name to API method.

Definition at line 237 of file WSServer.hpp.

◆ individual_handlers_

std::map<std::string, MethodHandler::Factory> Leosac::Module::WebSockAPI::WSServer::individual_handlers_

private

Definition at line 239 of file WSServer.hpp.

◆ module_

WebSockAPIModule& Leosac::Module::WebSockAPI::WSServer::module_

private

A reference to the module.

The module is guaranteed to outlive the WSServer.

Definition at line 258 of file WSServer.hpp.

◆ srv_

Server Leosac::Module::WebSockAPI::WSServer::srv_

Definition at line 77 of file WSServer.hpp.

◆ work_

std::unique_ptr<boost::asio::io_service::work> Leosac::Module::WebSockAPI::WSServer::work_

private

Work used to keep the io_service alive while someone has a reference to (WS) Service object.

Definition at line 264 of file WSServer.hpp.

The documentation for this class was generated from the following files:

src/modules/websock-api/WSServer.hpp
src/modules/websock-api/WSServer.cpp

Public Types

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ ConnectionAPIMap

◆ Server

Constructor & Destructor Documentation

◆ WSServer()

◆ ~WSServer()

Member Function Documentation

◆ attempt_unregister_ws_service()

◆ auth()

◆ clear_user_sessions()

◆ core_utils()

◆ db()

◆ dbsrv()

◆ dispatch_request()

◆ finalize_audit()

◆ handle_request()

◆ has_handler()

◆ on_close()

◆ on_message()

◆ on_open()

◆ parse_request()

◆ register_asio_handler()

◆ register_crud_handler()

◆ register_crud_handler_external()

◆ run()

◆ send_message()

◆ start_shutdown()

◆ unregister_handler()

Member Data Documentation

◆ asio_handlers_

◆ auth_

◆ connection_session_

◆ crud_handlers_

◆ dbsrv_

◆ handlers_

◆ individual_handlers_

◆ module_

◆ srv_

◆ work_