this class is used to customize and control the behavior of the Qorus HTTP server as it redirects URLs to services More...

Inheritance diagram for OMQ::AbstractServiceHttpHandler:

[legend]

Collaboration diagram for OMQ::AbstractServiceHttpHandler:

[legend]

Public Member Methods
OMQ::ThreadLocalData	otld ()
	thread-local data to add before calling handleRequest()

	constructor (string n_path, softlist< auto > n_content_type, softlist< auto > n_special_headers, HttpServer::AbstractAuthenticator n_auth=new DefaultQorusRBACAuthenticator(), bool n_isregex=True)
	creates the object with the given arguments More...

hash< auto >	getServiceInfo ()
	returns a hash with info about the linked service

	addListener (hash< HttpServer::HttpListenerOptionInfo > opt)
	adds a listener from a bind string in the format: `"address:port"` (ex: `"192.168.20.1:8011"`) More...

	addListener (softstring bind, hash< HttpServer::HttpListenerOptionInfo > opt)
	adds a listener from a bind string in the format: `"address:port"` (ex: `"192.168.20.1:8011"`) More...

	addListener (softstring bind, string cert_path, string key_path, string key_password, hash< HttpServer::HttpListenerOptionInfo > opt)
	adds a listener from a bind string in the format: `"address:port"` (ex: `"192.168.20.1:8011"`) More...

	addListener (softstring bind, Qore::SSLCertificate cert, Qore::SSLPrivateKey key, *hash< HttpServer::HttpListenerOptionInfo > opt)
	adds a listener from a bind string in the format: `"address:port"` (ex: `"192.168.20.1:8011"`) More...

	addListeners (softlist< auto > l)
	adds a list of listeners from hash elements describing the listener More...

final *hash< auto >	saveThreadLocalData ()
	called before handleRequest() More...

final	restoreThreadLocalData (*hash< auto > data)
	called after handleRequest() with any data returned from saveThreadLocalData()

	log (int ll, string fmt)
	logs to the service log file

	setUserIndexInfo (string heading, string title, string url)
	sets heading and title for user HTTP services

	clearUserIndexInfo ()
	clears heading and title into for user HTTP services More...

hash< HttpResponseInfo >	handleRequest (HttpListenerInterface listener, Socket s, hash< auto > cx, hash< auto > hdr, *data body)
	this method ensures that thread-local data is set properly

hash< auto >	handleRequest (hash< auto > cx, hash< auto > hdr, *data body)
	This method calls handleRequestImpl() to service the request. More...

string	getRequestPath (string hpath)
	returns the request path with the common leading part of the URL and also any URI query argument stripped

*hash< auto >	handleRequestImpl (reference< hash< auto > > cx, hash< auto > hdr, *data body)
	This method is called by this class's handleRequest() More...

	setDefaultResource (string name)
	sets the default service file resource to be rendered More...

	setThreadContext (hash< auto > cx)
	Sets the service thread context. More...

Static Public Member Methods
static AbstractServiceStream	getServiceStreamRequestExtern (AbstractServiceHttpHandler hr, Socket s, hash< auto > cx, hash< auto > hdr, *data body)
	for calling the getServiceStreamRequestImpl() externally

static	setServiceThreadContext (hash< auto > cx)
	Sets the service thread context. More...

Public Attributes
string	url
	The path string or regex to match incoming requests.

*softlist< auto >	content_type
	the content-type to check

*softlist< auto >	special_headers
	list of special headers; if a request has any of these HTTP headers, then the requests will match this handler

list< auto >	listeners = ()
	list of listener info; do not write to this list directly More...

code	svcc
	a closure that allows specific Service methods to be called

code	svc_method_call
	a closure that allows any Service methods to be called

*string	utype
	the type/heading for user HTTP services

*string	utitle
	the title for user HTTP services

*string	uurl
	the URL for user HTTP services

bool	isregex
	if the path is a regex or a string

*string	default_resource
	the default resource to serve

hash< auto >	svcinfo
	service info hash

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

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

Detailed Description

this class is used to customize and control the behavior of the Qorus HTTP server as it redirects URLs to services

If any listeners are added to the AbstractServiceHttpHandler object with addListener(), then the URL set in the object is only bound to the new listeners specified in this object.

Otherwise, the URL is bound to all listeners in the system HTTP server. Override the handleRequestImpl() method to handle HTTP requests.

Note: When used in Stateless services, HTTP handlers are identified by a unique ID that is generated from the options used to create the object. To ensure that all stateless services use the same ID, you must ensure that the same options are used in each service's bindHttp() call. Failure to do this, for example my using a randomly-generated root path, will cause runtime errors.

Member Function Documentation

◆ addListener() [1/4]

OMQ::AbstractServiceHttpHandler::addListener ( hash< HttpServer::HttpListenerOptionInfo > opt )

adds a listener from a bind string in the format: "address:port" (ex: "192.168.20.1:8011")

If any listeners are added to the AbstractServiceHttpHandler object, then the URL set in the object is only bound to the new listeners specified in this object

Parameters

opt	HTTP listener parameters

Exceptions

ADDLISTENER-ERROR key_path argument provided, but no certificate provided

Since: Qorus 4.0.3

◆ addListener() [2/4]

OMQ::AbstractServiceHttpHandler::addListener	(	softstring	bind,
		*Qore::SSLCertificate	cert,
		*Qore::SSLPrivateKey	key,
		*hash< HttpServer::HttpListenerOptionInfo >	opt
	)

adds a listener from a bind string in the format: "address:port" (ex: "192.168.20.1:8011")

If any listeners are added to the AbstractServiceHttpHandler object, then the URL set in the object is only bound to the new listeners specified in this object

Parameters

bind	the address:port string or port number to bind the listener to
cert	optional X.509 certificate object
key	optional private key for an X.509 certificate
opt	HTTP listener parameters

Exceptions

ADDLISTENER-ERROR key argument provided, but no certificate provided

◆ addListener() [3/4]

OMQ::AbstractServiceHttpHandler::addListener	(	softstring	bind,
		*string	cert_path,
		*string	key_path,
		*string	key_password,
		*hash< HttpServer::HttpListenerOptionInfo >	opt
	)

adds a listener from a bind string in the format: "address:port" (ex: "192.168.20.1:8011")

If any listeners are added to the AbstractServiceHttpHandler object, then the URL set in the object is only bound to the new listeners specified in this object

Parameters

bind	the address:port string or port number to bind the listener to
cert_path	optional path to an X.509 certificate file
key_path	optional path to a private key file for an X.509 certificate
key_password	optional password to the private key
opt	HTTP listener parameters

Exceptions

ADDLISTENER-ERROR key_path argument provided, but no certificate provided

◆ addListener() [4/4]

OMQ::AbstractServiceHttpHandler::addListener	(	softstring	bind,
		hash< HttpServer::HttpListenerOptionInfo >	opt
	)

adds a listener from a bind string in the format: "address:port" (ex: "192.168.20.1:8011")

If any listeners are added to the AbstractServiceHttpHandler object, then the URL set in the object is only bound to the new listeners specified in this object

Parameters

bind	the address:port string or port number to bind the listener to
opt	HTTP listener parameters

Exceptions

ADDLISTENER-ERROR key_path argument provided, but no certificate provided

Since: Qorus 4.0.3

◆ addListeners()

OMQ::AbstractServiceHttpHandler::addListeners ( softlist< auto > l )

adds a list of listeners from hash elements describing the listener

If any listeners are added to the AbstractServiceHttpHandler object, then the URL set in the object is only bound to the new listeners specified in this object

Parameters

l

list of listeners; each element should be a hash with the following keys:

"bind": (required) a bind string in the format: "address:port" (ex: "192.168.20.1:8011") or an integer port, meaning to bind on all interfaces on that port
"cert_file": (optional) path to an X.509 certificate file (do not include both "cert_file" and "cert")
"cert": (optional) a Qore::SSLCertificate object (do not include both "cert_file" and "cert")
"key_file": (optional) path to a private key file for an X.509 certificate (do not include both "key_file" and "key")
"key": (optional) a Qore::SSLPrivateKey object (do not include both "key_file" and "key")

Exceptions

ADDLISTENERS-ERROR invalid element in argument list

◆ clearUserIndexInfo()

OMQ::AbstractServiceHttpHandler::clearUserIndexInfo ( )

clears heading and title into for user HTTP services

Since: Qorus 4.0

◆ constructor()

OMQ::AbstractServiceHttpHandler::constructor	(	string	n_path,
		*softlist< auto >	n_content_type,
		*softlist< auto >	n_special_headers,
		HttpServer::AbstractAuthenticator	n_auth = `new DefaultQorusRBACAuthenticator()`,
		bool	n_isregex = `True`
	)

creates the object with the given arguments

Parameters

n_path	the regular expression for the path to match on incoming requests (ex `"^my-service(\?\|/\|$)"`); note see the n_isregex parameter to treat this argument as a URL root instead of a regular expression
n_content_type	an optional list of Content-Types to match on incoming requests
n_special_headers	an optional list of special headers to check that will indicate a match with this handler
n_auth	the AbstractAuthenticator for the object; if no argument is passed, then the system RBAC authenticator is used; meaning that Qorus application users are required to connect, and the users must have the OMQ::QR_LOGIN role to connect as well
n_isregex	if True, then the path argument is treated as a regular expression pattern, otherwise it is treated as a literal URL root; it's normally recommended to set this argument to False so that service file resources can be matched and served; this method has the default value True only for backwards compatibility

Example:: class MyHttpHandler inherits OMQ::AbstractServiceHttpHandler {

constructor() : OMQ::AbstractServiceHttpHandler("my-service", "text/tab-separated-values", NOTHING, NOTHING, False) {

}

}

OMQ
main Qorus namespace
Definition: QorusRbacAuth.qm:21

◆ handleRequest()

hash< auto > OMQ::AbstractServiceHttpHandler::handleRequest	(	hash< auto >	cx,
		hash< auto >	hdr,
		*data	body
	)

This method calls handleRequestImpl() to service the request.

If handleRequestImpl() returns NOTHING, then it tries to automatically serve service file resources or serve the default resource if no resource can be matched

Parameters

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 Socket::getSocketInfo() "Socket::getSocketInfo()") `peer-info`: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo() "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()) `ssl:` if the connection with the client is an SSL/TLS connection, then this key will be present and will be True `user:` the current RBAC username (if any)
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_url() `http_version:` the HTTP version number in the request (either `"1.0"` or `"1.1"`)
body	message 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

The following keys are added to the cx argument when calling handleRequestImpl():

resource_path: the relative path without any query arguments and with the URL root stripped off (if the request was matched by the URL root, otherwise this will be the request path with any URI query arguments removed)
url_root: the root URL
isregex: if the url_root string is a regular expression or not (this is always False when this class is used)
hdr: this is added to the cx argument directly from the hdr argument, however it also includes the "params" key which holds the URI query parameters as returned in the params key from HttpServer::parse_uri_query()

To override the logic in this method and handle requests directly, override this method in your subclass.

If handleRequestImpl() returns NOTHING and no resource can be matched and served, then this method returns a 501 error code

◆ handleRequestImpl()

*hash< auto > OMQ::AbstractServiceHttpHandler::handleRequestImpl	(	reference< hash< auto > >	cx,
		hash< auto >	hdr,
		*data	body
	)

This method is called by this class's handleRequest()

This method is called before trying to service the request automatically based on service file resources

If this method returns a value; then the value is used to serve the request directly, otherwise, if it returns NOTHING, Qorus will try to match cx.resource_path with a service file resource and serve it automatically.

Example:: class MyHttpHandler inherits OMQ::AbstractServiceHttpHandler {

constructor() : OMQ::AbstractServiceHttpHandler("my-service", "text/tab-separated-values", NOTHING, NOTHING, False) {

}

*hash<auto> handleRequestImpl(hash<auto> cx, hash<auto> hdr, *data body) {

logDebug("message received: hdr=%y", hdr);

# similate a successful POST, otherwise serve service resources automatically

if (cx.method == "POST")

return {"code": 200, "body": "OK"};

}

}

Parameters

cx	call context hash; this hash will have the following keys: `hdr:` this is a copy of the hdr argument, however it also includes the `"params"` key which holds the URI query parameters as returned in the params key from HttpServer::parse_uri_query(); ex: `hdr.host` will contain the `Host` header from the incoming request `id:` the unique HTTP connection ID `isregex:` if the url_root string is a regular expression or not `listener-id`: the HTTP server listener ID (see HttpServer::getListenerInfo()) `peer-info`: a hash of socket information for the remote socket (as returned by Socket::getPeerInfo()) `resource_path:` the resource path without any query arguments and with the URL root stripped off (if the request was matched by the URL root, otherwise this will be the request path with any URI query arguments removed) `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 Socket::getSocketInfo()) `ssl:` if the connection with the client is an SSL/TLS connection, then this key will be present and will be True `url:` a hash of broken-down URL information (as returned from Qore::parse_url()) `url_root:` the root URL `user:` the current RBAC username (if any)
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_url() `http_version:` the HTTP version number in the request (either `"1.0"` or `"1.1"`) `params:` holds the URI query parameters as returned in the params key from HttpServer::parse_uri_query()
body	message body, if any

Returns

either NOTHING, meaning that Qorus should try to match cx.resource_path with a service file resource and serve it automaticaly, or 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

this method has the following additional keys in the cx hash: resource_path, url_root, and isregex
the default implementation simply returns NOTHING for all requests; reimplement this method in a subclass to provide the required functionality
for remote services running in independent qsvc processes, no non-serializable data types can be added to cx, or the call will fail

◆ saveThreadLocalData()

final *hash< auto > OMQ::AbstractServiceHttpHandler::saveThreadLocalData ( )

called before handleRequest()

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

◆ setDefaultResource()

OMQ::AbstractServiceHttpHandler::setDefaultResource ( string name )

sets the default service file resource to be rendered

The default resource is rendered when the request is not matched to a resource and handleRequestImpl() does not return a response

◆ setServiceThreadContext()

static OMQ::AbstractServiceHttpHandler::setServiceThreadContext ( hash< auto > cx )

static

Sets the service thread context.

This should be called from HTTP I/O threads only; no attempt is made to save and restore the thread-local data on exit

Note: Does not set the thread context correctly; use the non static mnethod setThreadContext() instead

◆ setThreadContext()

OMQ::AbstractServiceHttpHandler::setThreadContext ( hash< auto > cx )

Sets the service thread context.

This should be called from HTTP I/O threads only; no attempt is made to save and restore the thread-local data on exit

Member Data Documentation

◆ listeners

list<auto> OMQ::AbstractServiceHttpHandler::listeners = ()

list of listener info; do not write to this list directly

use AbstractServiceHttpHandler::addListener() instead of writing to this list directly (the internal format may change)

The documentation for this class was generated from the following file:

AbstractServiceHttpHandler.qc

Public Member Methods

Static Public Member Methods

Public Attributes

Private Member Methods

Detailed Description

Member Function Documentation

◆ addListener() [1/4]

◆ addListener() [2/4]

◆ addListener() [3/4]

◆ addListener() [4/4]

◆ addListeners()

◆ clearUserIndexInfo()

◆ constructor()

◆ handleRequest()

◆ handleRequestImpl()

◆ saveThreadLocalData()

◆ setDefaultResource()

◆ setServiceThreadContext()

◆ setThreadContext()

Member Data Documentation

◆ listeners