abstract class that all HTTP dedicated socket handler objects must inherit from More...

Inheritance diagram for HttpServer::AbstractHttpSocketHandler:

Public Member Methods
	constructor (*AbstractAuthenticator auth)
	create the object optionally with the given AbstractAuthenticator More...

abstract hash	handleRequest (hash< auto > cx, hash< auto > hdr, *data b)
	called by the HTTP server to handle incoming HTTP requests More...

	start (softstring lid, hash< auto > cx, hash< auto > hdr, Socket s)
	called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established More...

	stop (softstring lid)
	called from the HTTP server when the socket should be closed due to an HTTP listener being stopped; the start() method for all connections on the particular listener should return as soon as possible after this method is called More...

	stop ()
	called from the HTTP server when the socket should be closed due to an external request; the start() method should return as soon as possible after this method is called More...

Public Member Methods inherited from HttpServer::AbstractHttpRequestHandler
	constructor (*AbstractAuthenticator n_auth, softbool n_stream=False)
	create the object optionally with the given AbstractAuthenticator More...

*data	getMessageBody (Socket s, hash< auto > hdr, *data body, bool decode=True)
	optionally retrieves and post-processes any message body

hash< HttpResponseInfo >	handleRequest (hash< auto > cx, hash< auto > hdr, *data body)
	will be called when a request is received that should be directed to the handler More...

hash< HttpResponseInfo >	handleRequest (HttpListenerInterface listener, Socket s, hash< auto > cx, hash< auto > hdr, *data body)
	top-level request handling method

bool	isPersistent ()
	returns True if the current connection is persistent, False if not

string	maskData (string msg)
	this method can be used to mask data in debug messages More...

	notifyClosed (*code c)
	calls the argument when the persistent connection is closed

nothing	persistentClosed ()
	called externally when a persistent connection is closed

	restoreThreadLocalData (*hash< auto > data)
	called after handleRequest() with any data returned from saveThreadData() More...

*hash< auto >	saveThreadLocalData ()
	called before handleRequest() any data returned here will be given to restoreThreadLocalData() after the handleRequest() call More...

	setPersistent (bool p=True)
	called externally to notify the handler that the connection will be persistent

Private Member Methods
Mutex	m ()
	listener reference hash mutex

abstract	startImpl (softstring lid, hash< auto > cx, hash< auto > hdr, Socket s)
	called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established More...

	stopImpl (string lid)
	called from the HTTP server when the socket should be closed because the listener is stopping; the start() method for all connections handled by the given listener should return as soon as possible after this method is called More...

	stopImpl ()
	called from the HTTP server when the socket should be closed due to an external request; the start() method should return as soon as possible after this method is called

Private Member Methods inherited from HttpServer::AbstractHttpRequestHandler
nothing	checkPersistent (hash< auto > cx, hash< auto > hdr)
	this method will throw an exception if a persistent connection cannot be granted

AbstractStreamRequest	getStreamRequestImpl (HttpListenerInterface listener, Socket s, hash< auto > cx, hash< auto > hdr, *data body)
	returns the AbstractStreamRequest object for handling chunked requests

Private Attributes
hash< string, int >	lh
	hash of listener references; this is to stop all connections associated with a particular listener

hash< string, bool >	lsh
	hash of listener stop flags

bool	stop = False
	stop listener flag

Additional Inherited Members
Static Public Member Methods inherited from HttpServer::AbstractHttpRequestHandler
static data	decodeBody (string content_encoding, binary body, *string string_encoding)
	decodes a message body with content-encoding

static binary	encodeBody (string content_encoding, data body)
	encodes a message body with content-encoding

static *string	getLogMessage (hash< auto > cx, hash api, reference params, *reference< string > args)
	helper method for handling log messages More...

static hash< HttpResponseInfo >	make200 (string fmt)
	creates a hash for an HTTP 200 OK error response with the response message body as a string

static hash< HttpResponseInfo >	make200 (hash< auto > hdr, string fmt)
	creates a hash for an HTTP 200 OK error response with the response message body as a string

static hash< HttpResponseInfo >	make200 (hash< auto > hdr, InputStream chunked_body)
	creates a hash for an HTTP 200 OK error response with the response message body from an input stream

static hash< HttpResponseInfo >	make200 (InputStream chunked_body)
	creates a hash for an HTTP 200 OK error response with the response message body from an input stream

static hash< HttpResponseInfo >	make400 (string fmt)
	creates a hash for an HTTP 400 error response with the response message body as a string

static hash< HttpResponseInfo >	make400 (hash< auto > hdr, string fmt)
	creates a hash for an HTTP 400 error response with the response message body as a string

static hash< HttpResponseInfo >	make500 (string fmt)
	creates a hash for an HTTP 500 error response with the response message body as a string

static hash< HttpResponseInfo >	make500 (hash< auto > hdr, string fmt)
	creates a hash for an HTTP 500 error response with the response message body as a string

static hash< HttpResponseInfo >	make501 (string fmt)
	creates a hash for an HTTP 501 error response with the response message body as a string

static hash< HttpResponseInfo >	make501 (hash< auto > hdr, string fmt)
	creates a hash for an HTTP 501 error response with the response message body as a string

static hash< HttpResponseInfo >	makeResponse (int code, string fmt)
	creates a hash for an HTTP response with the response code and the response message body as a formatted string

static hash< HttpResponseInfo >	makeResponse (hash< auto > hdr, int code, string fmt)
	creates a hash for an HTTP response with the response code and the response message body as a formatted string

static hash< HttpResponseInfo >	makeResponse (int code, data body, hash< auto > hdr)
	creates a hash for an HTTP response with the response code and a literal response message body

static hash< HttpResponseInfo >	makeResponse (int code, InputStream chunked_body, hash< auto > hdr)
	creates a hash for an HTTP response with the response code and a response message body from an input stream More...

static hash< HttpResponseInfo >	redirect (hash< auto > cx, hash< auto > request_hdr, string path, int status_code=301, *hash< auto > response_hdr)
	generates a redirect hash for the given path

static	staticNotificationCleanup ()
	removes the thread-local data key in case the object is destroyed in another thread

static	staticPersistenceCleanup ()
	removes the thread-local data key in case the object is destroyed in another thread

Public Attributes inherited from HttpServer::AbstractHttpRequestHandler
*AbstractAuthenticator	auth
	the optional AbstractAuthenticator for requests to this handler

bool	decompress = True
	if POSTed data should be decompressed automatically if there is content-encoding

bool	decompress_to_string = True
	if automatically decompressed POSTed data should be converted to a string (if False, then it will be decompressed to a binary)

const	NotificationThreadKey = "_AHRH_pc"
	thread-local key string for notification callbacks

const	PersistenceThreadKey = "_AHRH_p"
	thread-local key string for the persistent flag

bool	stream
	if the handler supports streaming requests/responses with chunked data

timeout	timeout_ms = HttpServer::DefaultTimeout
	send and receive socket timeout in milliseconds

Detailed Description

abstract class that all HTTP dedicated socket handler objects must inherit from

reimplement at least handleRequest() and startImpl() in subclasses

Member Function Documentation

◆ constructor()

HttpServer::AbstractHttpSocketHandler::constructor ( *AbstractAuthenticator auth )

create the object optionally with the given AbstractAuthenticator

Parameters

auth	the authentication object to use to authenticate connections (see AbstractAuthenticator); if no AbstractAuthenticator object is passed, then by default no authentication will be required

◆ handleRequest()

abstract hash HttpServer::AbstractHttpSocketHandler::handleRequest	(	hash< auto >	cx,
		hash< auto >	hdr,
		*data	b
	)

pure virtual

called by the HTTP server to handle incoming HTTP requests

To accept a new dedicated socket connection, make sure the return value returns code 101 (ie "Switching Protocols"); after which this class's start() (and then startImpl()) methods are called

Parameters

cx	call context hash; this hash will have the following keys: `header-info`: a hash of information about the request header with the following keys: `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list `accept-encoding`: a hash where keys are values from any `"Accept-Encoding"` header and the values are True `body-content-type`: this is the `"Content-Type"` header without any charset declaration `charset:` if there is a charset declaration in the `"Content-Type"` header, the value is returned in this key `client-cert`: if the server is configured to capture remote client certificates, and the client supplied a certificate, this key will be populated with the SSLCertificate for the client `close:` set to True if the connection should be closed after responding, False if not (as derived from the request header) `headers-raw`: a hash of raw request headers without any case conversions or other processing `request-uri`: gives the request URI in an HTTP request `socket:` the bind address used to bind the listener (`"socket-info"` provides more detailed information) `socket-info`: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo()) `peer-info`: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo()) `url:` a hash of broken-down URL information (as returned from Qore::parse_url()) `id:` the unique HTTP connection ID `ssl:` True if the request was encrypted with HTTPS, False if not `listener-id`: the HTTP server listener ID (see HttpServer::getListenerInfo()) `user:` the current RBAC username (if any) `root_path:` the root URL path matched if the request was matched by a URL prefix
hdr	incoming header hash; all keys will be converted to lower-case, additionally the following keys will be present: `method:` the HTTP method received (ie `"GET"`, `"POST"`, etc) `path:` the HTTP path given in the request, after processing by Qore::decode_uri_request() `http_version:` the HTTP version number in the request (either `"1.0"` or `"1.1"`)
b	message body, if any

Returns

to accept a dedicated connection, return a hash (ideally an HttpServer::HttpResponseInfo hash) with the following key:

"code": assign to 101 (ie "Switching Protocols"); if this is returned, then the start() method will be called with the Socket object for the new connection
"hdr": (optional) set this key to a hash of extra header information to be returned with the response

or, to handle the request without a dedicated connection, return a hash with the following keys

"code": the HTTP return code (see HttpServer::HttpCodes)
"body": the message body to return in the response
"close": (optional) set this key to True if the connection should be unconditionally closed when the handler returns
"hdr": (optional) set this key to a hash of extra header information to be returned with the response

◆ start()

HttpServer::AbstractHttpSocketHandler::start	(	softstring	lid,
		hash< auto >	cx,
		hash< auto >	hdr,
		Socket	s
	)

called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established

This method should not return until the connection is closed or the stop() method is called

Parameters

lid	the listener ID
cx	call context hash; this hash will have the following keys: `header-info`: a hash of information about the request header with the following keys: `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list `accept-encoding`: a hash where keys are values from any `"Accept-Encoding"` header and the values are True `body-content-type`: this is the `"Content-Type"` header without any charset declaration `charset:` if there is a charset declaration in the `"Content-Type"` header, the value is returned in this key `client-cert`: if the server is configured to capture remote client certificates, and the client supplied a certificate, this key will be populated with the SSLCertificate for the client `close:` set to True if the connection should be closed after responding, False if not (as derived from the request header) `headers-raw`: a hash of raw request headers without any case conversions or other processing `request-uri`: gives the request URI in an HTTP request `socket:` the bind address used to bind the listener (`"socket-info"` provides more detailed information) `socket-info`: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo()) `peer-info`: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo()) `url:` a hash of broken-down URL information (as returned from Qore::parse_url()) `id:` the unique HTTP connection ID `ssl:` True if the request was encrypted with HTTPS, False if not `listener-id`: the HTTP server listener ID (see HttpServer::getListenerInfo()) `user:` the current RBAC username (if any) `root_path:` the root URL path matched if the request was matched by a URL prefix
hdr	a hash of headers in the request
s	the Socket object for the dedicated connection

◆ startImpl()

abstract HttpServer::AbstractHttpSocketHandler::startImpl	(	softstring	lid,
		hash< auto >	cx,
		hash< auto >	hdr,
		Socket	s
	)

privatepure virtual

called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established

This method should not return until the connection is closed or the stop() (and therefore stopImpl()) method is called

Parameters

lid	the listener ID
cx	call context hash; this hash will have the following keys: `socket:` the bind address used to bind the listener (`"socket-info"` provides more detailed information) `socket-info`: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo()) `peer-info`: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo()) `url:` a hash of broken-down URL information (as returned from Qore::parse_url()) `id:` the unique HTTP connection ID `ssl:` True if the request was encrypted with HTTPS, False if not `listener-id`: the HTTP server listener ID (see HttpServer::getListenerInfo()) `user:` the current RBAC username (if any) `root_path:` the root URL path matched if the request was matched by a URL prefix
hdr	a hash of headers in the request
s	the Socket object for the dedicated connection

◆ stop() [1/2]

HttpServer::AbstractHttpSocketHandler::stop ( softstring lid )

called from the HTTP server when the socket should be closed due to an HTTP listener being stopped; the start() method for all connections on the particular listener should return as soon as possible after this method is called

child classes should implement the stopImpl(string) method which is called from this method to implement custom stop actions for particular listeners

Parameters

lid	the listener ID

◆ stop() [2/2]

HttpServer::AbstractHttpSocketHandler::stop ( )

called from the HTTP server when the socket should be closed due to an external request; the start() method should return as soon as possible after this method is called

child classes should implement the stopImpl() method which is called from this method to implement custom stop actions

◆ stopImpl()

HttpServer::AbstractHttpSocketHandler::stopImpl ( string lid )

private

called from the HTTP server when the socket should be closed because the listener is stopping; the start() method for all connections handled by the given listener should return as soon as possible after this method is called

Parameters

lid	the listener ID

Public Member Methods

Private Member Methods

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ constructor()

◆ handleRequest()

◆ start()

◆ startImpl()

◆ stop() [1/2]

◆ stop() [2/2]

◆ stopImpl()