Qore HttpServerUtil Module Reference  0.3.11.1
HttpServer::AbstractStreamRequest Class Reference

abstract class for streaming HTTP chunked requests/responses More...

Public Member Functions

 constructor (HttpListenerInterface n_listener, AbstractHttpRequestHandler n_handler, Socket n_s, hash n_cx, hash n_hdr, any n_body)
 creates the object with the given attributes More...
 
private hash getResponseHeaderMessage ()
 this method returns the response message description hash by calling getResponseHeaderMessageImpl() More...
 
private hash getResponseHeaderMessageImpl ()
 this method should return the response message description hash More...
 
hash handleRequest ()
 handles the request
 
private nothing recv (hash v)
 this is the primary callback for receiving chunked data; data will be logged, and then recvImpl() is called More...
 
private nothing recvImpl (hash v)
 callback method for receiving chunked data; the default implementation in this base class does nothing More...
 
private any send ()
 this is the primary callback for sending chunked responses; first sendImpl() is called to get the raw data, and then any chunked data is encoded by this method if required
 
private any sendImpl ()
 callback method for sending chunked data; the default implementation in this base class does nothing and returns nothing More...
 
private hash sendResponse ()
 called to either create the response hash or send a chunked response directly More...
 

Private Attributes

any body
 any message body given in a non-chunked request; could already be deserialized
 
hash cx
 the call context variable
 
AbstractHttpRequestHandler handler
 the request handler for the request
 
hash hdr
 a hash of request headers
 
HttpListenerInterface listener
 an HttpListenerInterface object for the listener serving the request for logging purposes
 
Socket s
 the Socket object for the response
 
timeout timeout_ms = HttpServer::DefaultTimeout
 send and receive timeout
 

Detailed Description

abstract class for streaming HTTP chunked requests/responses

This class is the base class for handling HTTP stream requests; i.e. with chunked data

The calling order is as follows:

  • constructor(): this is called when the request is received
  • recv(): this is called once for each HTTP chunk (if data is sent chunked), and then once with any message trailer. If data is sent non-chunked, then this method is called with the monolithic message body and then again with NOTHING to signify the end of the transfer and to simulate a chunked transfer. The simulation of a chunked transfer or the actual chunked receive with the callbacks is made by the handleRequest() method. Subclasses should re-implement recvImpl() which is called by this method
  • getResponseHeaderMessage(): this is called after the message body has been received to get the response headers and optionally a message body. Subclasses should reimplement getResponseHeaderMessageImpl() which is called by this method
  • send(): this is called if no message body is returned by getResponseHeaderMessage(); each time this method returns data, the data is sent in a response chunk; when this method returns NOTHING, then no more data is sent. Subclasses should re-implement sendImpl() which is called by this method

Member Function Documentation

◆ constructor()

HttpServer::AbstractStreamRequest::constructor ( HttpListenerInterface  n_listener,
AbstractHttpRequestHandler  n_handler,
Socket  n_s,
hash  n_cx,
hash  n_hdr,
any  n_body 
)

creates the object with the given attributes

Parameters
n_listeneran HttpListenerInterface object for the listener serving the request for logging purposes
n_handlerthe handler serving the request
n_sthe Socket for serving the request
n_cxa call context hash
n_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")
n_bodyany message body in the request already received from the incoming socket

◆ getResponseHeaderMessage()

private hash HttpServer::AbstractStreamRequest::getResponseHeaderMessage ( )

this method returns the response message description hash by calling getResponseHeaderMessageImpl()

Returns
a hash with the following keys:
  • "code": the HTTP return code (see HttpServer::HttpCodes)
  • "body": the message body to return in the response; if this key is returned, then the reply is sent immediately; a chunked reply is not made, and send() and sendImpl() are not called
  • "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
this method is called after the message body has been received

◆ getResponseHeaderMessageImpl()

private hash HttpServer::AbstractStreamRequest::getResponseHeaderMessageImpl ( )

this method should return the response message description hash

The default implementation in this class is to return a 501 Not Implemented response; override in subclasses to return a custom response. Omit the "body" key to ensure that a chunked response is sent and the send() and sendImpl() callbacks are called.

Returns
a hash with the following keys:
  • "code": the HTTP return code (see HttpServer::HttpCodes)
  • "body": the message body to return in the response; if this key is returned, then the reply is sent immediately; a chunked reply is not made, and send() and sendImpl() are not called
  • "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
this method is called after the message body has been received

◆ recv()

private nothing HttpServer::AbstractStreamRequest::recv ( hash  v)

this is the primary callback for receiving chunked data; data will be logged, and then recvImpl() is called

content decoding is not possible with chunked data because only the entire message can be decoded

◆ recvImpl()

private nothing HttpServer::AbstractStreamRequest::recvImpl ( hash  v)

callback method for receiving chunked data; the default implementation in this base class does nothing

Parameters
vthe first time this method is called with a hash of the message headers in the "hdr" key, and then with any message body in the "data"; if a chunked HTTP message is received, then this method is called once for each chunk; when the message has been received, then this method is called with a hash representing any trailer data received in a chunked transfer or NOTHING if the data was received in a normal message body or if there was no trailer data in a chunked transfer. The argument to this callback is always a hash; data calls have the following keys:
  • "data": the string or binary data
  • "chunked": True if the data was received with chunked transfer encoding, False if not
Header or trailer data is placed in a hash with the following keys:
  • "hdr": this can be assigned to NOTHING for the trailer hash if the data was not sent chunked or no trailers were included in a chunked message
  • "obj": this is the owning object (so socket parameters can be changed based on headers received, such as, for example, socket character encoding)

◆ sendImpl()

private any HttpServer::AbstractStreamRequest::sendImpl ( )

callback method for sending chunked data; the default implementation in this base class does nothing and returns nothing

Returns
The chunked HTTP data to send; this method must return either a string or a binary value each time it is called to give the chunked data to send; when all data has been sent, then a hash of message trailers can be returned or simply NOTHING which will close the chunked message

◆ sendResponse()

private hash HttpServer::AbstractStreamRequest::sendResponse ( )

called to either create the response hash or send a chunked response directly

This method calls getResponseHeaderMessageImpl() to get the response code, headers and optionally a response message body. If a "Content-Encoding: chunked" header is included, then the response is sent chunked using the send() callback; in this case the "reply_sent" key in the response is set to True. Otherwise, any message body is immediately encoded (if accepted by the requestor).