Qore HttpServerUtil Module Reference  0.9.11
HttpServer::AbstractHttpRequestHandler Class Reference

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

Inheritance diagram for HttpServer::AbstractHttpRequestHandler:

Public Member Methods

 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< HttpResponseInfohandleExpectHeader (hash< auto > cx, hash< auto > hdr)
 Called if the request contains an "Expect: 100-continue" header. More...
 
hash< HttpResponseInfohandleRequest (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< HttpResponseInfohandleRequest (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
 

Static Public Member Methods

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< HttpResponseInfomake200 (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< HttpResponseInfomake200 (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< HttpResponseInfomake200 (InputStream chunked_body)
 creates a hash for an HTTP 200 OK error response with the response message body from an input stream
 
static hash< HttpResponseInfomake200 (string fmt)
 creates a hash for an HTTP 200 OK error response with the response message body as a string
 
static hash< HttpResponseInfomake400 (hash< auto > hdr, string fmt)
 creates a hash for an HTTP 400 error response with the response message body as a string
 
static hash< HttpResponseInfomake400 (string fmt)
 creates a hash for an HTTP 400 error response with the response message body as a string
 
static hash< HttpResponseInfomake500 (hash< auto > hdr, string fmt)
 creates a hash for an HTTP 500 error response with the response message body as a string
 
static hash< HttpResponseInfomake500 (string fmt)
 creates a hash for an HTTP 500 error response with the response message body as a string
 
static hash< HttpResponseInfomake501 (hash< auto > hdr, string fmt)
 creates a hash for an HTTP 501 error response with the response message body as a string
 
static hash< HttpResponseInfomake501 (string fmt)
 creates a hash for an HTTP 501 error response with the response message body as a string
 
static hash< HttpResponseInfomakeResponse (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< HttpResponseInfomakeResponse (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< HttpResponseInfomakeResponse (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< HttpResponseInfomakeResponse (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< HttpResponseInforedirect (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

*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
 

Private Member Methods

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
 

Detailed Description

abstract class that all HTTP request handler objects must inherit from

Reimplement handleRequest() in subclasses

For handlers supporting chunked data (both for receiving and sending), set stream to True in the constructor() method and implement getStreamRequestImpl() to return the HTTP stream request handler.

See also
AbstractStreamRequest for information about HTTP stream request handlers

Member Function Documentation

◆ constructor()

HttpServer::AbstractHttpRequestHandler::constructor ( *AbstractAuthenticator  n_auth,
softbool  n_stream = False 
)

create the object optionally with the given AbstractAuthenticator

Parameters
n_auththe authentication object to use to authenticate connections (see AbstractAuthenticator); if no AbstractAuthenticator object is passed, then by default no authentication will be required
n_streamif True then stream (i.e. HTTP chunked) requests and responses are handled and getStreamRequestImpl() will be used to return a valid AbstractStreamRequest object to handle requests

◆ getLogMessage()

static *string HttpServer::AbstractHttpRequestHandler::getLogMessage ( hash< auto >  cx,
hash  api,
reference  params,
*reference< string args 
)
static

helper method for handling log messages

Parameters
cxthe 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
apithe API description hash
paramsa reference to the call parameters; the call context hash will be added as the first argument
argsan optional reference to a string describing the arguments
Returns
a string if the message should be logged, otherwise NOTHING

◆ handleExpectHeader()

hash<HttpResponseInfo> HttpServer::AbstractHttpRequestHandler::handleExpectHeader ( hash< auto >  cx,
hash< auto >  hdr 
)

Called if the request contains an "Expect: 100-continue" header.

Parameters
cxcall 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
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")
Returns
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
Note
the default implementation simply returns a 100 Continue response for all requests; reimplement this method in a subclass to provide the required functionality

◆ handleRequest()

hash<HttpResponseInfo> HttpServer::AbstractHttpRequestHandler::handleRequest ( hash< auto >  cx,
hash< auto >  hdr,
*data  body 
)

will be called when a request is received that should be directed to the handler

Parameters
cxcall 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
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")
bodymessage body, if any
Returns
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
Note
the default implementation simply returns a 501 error code for all requests; reimplement this method in a subclass to provide the required functionality

◆ makeResponse()

static hash<HttpResponseInfo> HttpServer::AbstractHttpRequestHandler::makeResponse ( int  code,
*InputStream  chunked_body,
*hash< auto >  hdr 
)
static

creates a hash for an HTTP response with the response code and a response message body from an input stream

Since
HttpServerUtil 0.9.4

◆ maskData()

string HttpServer::AbstractHttpRequestHandler::maskData ( string  msg)

this method can be used to mask data in debug messages

Parameters
msgthe log message to be subjected to masking
Returns
a string with sensitive information masked

◆ restoreThreadLocalData()

HttpServer::AbstractHttpRequestHandler::restoreThreadLocalData ( *hash< auto >  data)

called after handleRequest() with any data returned from saveThreadData()

Note
the default implementation does nothing

◆ saveThreadLocalData()

*hash<auto> HttpServer::AbstractHttpRequestHandler::saveThreadLocalData ( )

called before handleRequest() any data returned here will be given to restoreThreadLocalData() after the handleRequest() call

Note
the default implementation does nothing