#include <Pt/Http/WebSocketService.h>

Factory and endpoint policy for WebSocket sessions. More...

Inherited by BasicWebSocketService< S, Alloc >.

Public Member Functions
	WebSocketService ()
	Default constructor.
	~WebSocketService ()
	Destructor.
std::size_t	maxSockets () const
	Returns the maximum number of live sessions.
void	setMaxSockets (std::size_t n)
	Sets the maximum number of live sessions.
std::size_t	idleTimeout () const
	Returns the idle timeout in milliseconds.
void	setIdleTimeout (std::size_t ms)
	Sets the idle timeout in milliseconds.
std::size_t	maxMessageSize () const
	Returns the maximum data message size in bytes.
void	setMaxMessageSize (std::size_t n)
	Sets the maximum data message size in bytes.
Responder *	getResponder (const Request &)
	Creates a responder to handle request received by a server.
void	releaseResponder (Responder *)
	Destroys a responder created by a server.

Protected Member Functions
virtual Responder *	onGetResponder (const Request &)
	Creates the handshake responder.
virtual void	onReleaseResponder (Responder *responder)
	Destroys the handshake responder.
virtual WebSocketSession *	onGetSession (WebSocketServlet &servlet, System::EventLoop &loop, Stream &stream)=0
	Creates the session for stream.
virtual void	onReleaseSession (WebSocketSession *session)=0
	Destroys a session created by onGetSession().
virtual void	onUpgrade (Stream &stream) final
	Accepts or declines the upgraded stream.

Detailed Description

WebSocketService is the server-side factory. Map it with an HTTP servlet like any other service, so the handshake request reaches it. This type does not keep the sessions it creates. A separate release scope does, and that scope is destroyed before this service so the factory is still fully constructed when the last session is released. The service destructor does not release sessions. By then the derived destructor has already run, and the virtual release call and the allocator are gone.

The example is the usual server setup. The mapping servlet and the release scope are different objects.

typedef Pt::Http::BasicWebSocketService<EchoSession> EchoService;
 
EchoService service;
service.setMaxSockets(100);
service.setIdleTimeout(60000);
service.setMaxMessageSize(1 << 20);
Pt::Http::WebSocketServlet sockets(service);
Pt::Http::MapUrl mapUrl("/ws", service);
server.addServlet(mapUrl);

The handshake responder answers a WebSocket upgrade with 101, with 503 when the accepted-session limit is already reached, or with 404 when the request is not a WebSocket upgrade. The responder is released before the server opens the stream. It is not the session. setMaxSockets(), setIdleTimeout() and setMaxMessageSize() are endpoint policy. The handshake reads the session limit. The session base copies the idle timeout and the data-message limit onto the connection before the derived constructor runs. One service has one registered WebSocketServlet. A second registration replaces it. The previous servlet keeps the sessions it already holds and releases them itself.

After a finished 101 the HTTP server keeps the connection and delivers the upgraded stream to this service. This class implements that delivery and does not pass it on. It forwards the stream to the registered servlet. The servlet asks the factory for a session and passes the loop of the stream together with the stream. The session binds the stream in its constructor, which accepts the upgrade. A null session, or no registered servlet, leaves the stream unbound, and the HTTP server closes it.

BasicWebSocketService is this factory for one session type. Derive this class when the session type depends on the upgrade, or when the session constructor needs more than the servlet, the loop and the stream.

Pt::Http::WebSocketSession* ChatService::onGetSession(
    Pt::Http::WebSocketServlet& servlet,
    Pt::System::EventLoop& loop,
    Pt::Http::Stream& stream)
{
    return new ChatSession(servlet, loop, stream, _rooms);
}
 
void ChatService::onReleaseSession(Pt::Http::WebSocketSession* session)
{
    delete session;
}

onGetSession() creates the session and onReleaseSession() destroys it. The two methods must use the same allocator. A pool, or any other detach, lives in the derived service. Return null from onGetSession() to decline the upgrade.

Constructor & Destructor Documentation

◆ ~WebSocketService()

~WebSocketService ( )

Does not release sessions. The WebSocketServlet of this service does that, and it is destroyed first.

Member Function Documentation

◆ maxSockets()

std::size_t maxSockets ( ) const

Zero means no limit.

◆ setMaxSockets()

void setMaxSockets ( std::size_t n )

A handshake above this limit is answered with 503. Zero means no limit.

◆ setIdleTimeout()

void setIdleTimeout ( std::size_t ms )

An accepted socket is closed after ms without a finished transfer. A finished send or receive restarts the timeout. Zero disables it.

◆ setMaxMessageSize()

void setMaxMessageSize ( std::size_t n )

A larger data message closes the socket. Zero disables the limit. The count is the declared payload from the first data opcode to FIN.

◆ onGetSession()

virtual WebSocketSession * onGetSession	(	WebSocketServlet &	servlet,
		System::EventLoop &	loop,
		Stream &	stream )

protectedpure virtual

servlet holds the returned session. loop serializes stream. Return null to decline the upgrade.

Implemented in BasicWebSocketService< S, Alloc >.

◆ onReleaseSession()

virtual void onReleaseSession ( WebSocketSession * session )

protectedpure virtual

Called by the WebSocketServlet that holds the session, while this service is still fully constructed.

Implemented in BasicWebSocketService< S, Alloc >.

◆ onUpgrade()

virtual void onUpgrade ( Stream & stream )

finalprotectedvirtual

Implemented by this class. A derived service uses onGetSession() instead.

Reimplemented from Service.

Public Member Functions

Protected Member Functions