Qore HttpServerUtil Module Reference  0.3.11.1
HttpServer::AbstractHttpSocketHandler Class Referenceabstract

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

Inheritance diagram for HttpServer::AbstractHttpSocketHandler:

Public Member Functions

 constructor (*AbstractAuthenticator auth)
 create the object optionally with the given AbstractAuthenticator More...
 
abstract hash handleRequest (hash cx, hash hdr, *data b)
 called by the HTTP server to handle incoming HTTP requests More...
 
 start (softstring lid, hash cx, hash hdr, Socket s)
 called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established More...
 
abstract private startImpl (softstring lid, hash cx, hash 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...
 
private 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...
 
private 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
 
- Public Member Functions inherited from HttpServer::AbstractHttpRequestHandler
private nothing checkPersistent (hash cx, hash hdr)
 this method will throw an exception if a persistent connection cannot be granted
 
 constructor (*AbstractAuthenticator n_auth, softbool n_stream=False)
 create the object optionally with the given AbstractAuthenticator More...
 
*data getMessageBody (Socket s, hash hdr, *data body, bool decode=True)
 optionally retrieves and post-processes any message body
 
private AbstractStreamRequest getStreamRequestImpl (HttpListenerInterface listener, Socket s, hash cx, hash hdr, *data body)
 returns the AbstractStreamRequest object for handling chunked requests
 
hash handleRequest (hash cx, hash hdr, *data body)
 will be called when a request is received that should be directed to the handler More...
 
hash handleRequest (HttpListenerInterface listener, Socket s, hash cx, hash hdr, *data body)
 top-level request handling method
 
bool isPersistent ()
 returns True if the current connection is persistent, False if not
 
 notifyClosed (*code c)
 calls the argument when the persistent connection is closed
 
nothing persistentClosed ()
 called externally when a persistent connection is closed
 
 restoreThreadLocalData (*hash data)
 called after handleRequest() with any data returned from saveThreadData() More...
 
*hash 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 Functions

Mutex m ()
 listener reference hash mutex
 

Private Attributes

hash lh
 hash of listener references; this is to stop all connections associated with a particular listener
 
hash lsh
 hash of listener stop flags
 
bool stop = False
 stop listener flag
 

Additional Inherited Members

- Static Public Member Functions inherited from HttpServer::AbstractHttpRequestHandler
static data decodeBody (string ce, binary body, *string enc)
 decodes a message body with content-encoding
 
static binary encodeBody (string ce, data body)
 encodes a message body with content-encoding
 
static *string getLogMessage (hash cx, hash api, reference params, *reference args)
 helper method for handling log messages More...
 
static hash make400 (string fmt)
 creates a hash for an HTTP 400 error response with the response message body as a string
 
static hash make400 (hash hdr, string fmt)
 creates a hash for an HTTP 400 error response with the response message body as a string
 
static hash make501 (string fmt)
 creates a hash for an HTTP 501 error response with the response message body as a string
 
static hash make501 (hash hdr, string fmt)
 creates a hash for an HTTP 501 error response with the response message body as a string
 
static hash 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 makeResponse (hash 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 makeResponse (int code, *data body, *hash hdr)
 creates a hash for an HTTP response with the response code and a literal response message body
 
static hash redirect (hash cx, hash hdr, string path)
 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
auththe 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  cx,
hash  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
cxcall 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
  • 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
hdrincoming 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")
bmessage body, if any
Returns
to accept a dedicated connection, return a 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  cx,
hash  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
lidthe listener ID
cxcall 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
  • 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
hdra hash of headers in the request
sthe Socket object for the dedicated connection

◆ startImpl()

abstract private HttpServer::AbstractHttpSocketHandler::startImpl ( softstring  lid,
hash  cx,
hash  hdr,
Socket  s 
)
pure 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
lidthe listener ID
cxcall 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
  • 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
hdra hash of headers in the request
sthe 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
lidthe 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()

private HttpServer::AbstractHttpSocketHandler::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

Parameters
lidthe listener ID