HttpServer::HttpServer Class Reference

The HttpServer class implements a multithreaded HTTP server primarily designed for serving RPC-style services. More...

Public Member Functions
	addHandlerToListener (softstring bind, string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex=True)
	adds a request handler to a listener given the listener's name or bind address
	addHandlerToListener (softstring bind, string name, AbstractUrlHandler obj)
	adds a request handler to a listener given the listener's name or bind address
	addHandlerToListenerID (softint id, string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex=True)
	adds a request handler to a listener given the listener's id
	addHandlerToListenerID (softint id, string name, AbstractUrlHandler obj)
	adds a request handler to a listener given the listener's id
list	addINETListeners (*string node, softstring service, *string cert_path, *string key_path, *string name, int family=AF_UNSPEC, *string pwd)
	adds one or more global listeners according to the bind address More...
hash	addListener (softstring sock, *string cert_path, *string key_path, *string name, int family=AF_UNSPEC, *string pwd)
	adds a global listener to the server More...
softlist	addListeners (softstring sock, *string cert_path, *string key_path, *string name, int family=AF_UNSPEC, *string pwd)
	adds one or more global listeners according to the bind address More...
final list	addListenersWithHandler (string hname, AbstractHttpRequestHandler handler, hash lp, *code logger, *code errorlogger, *code stopc, *string name, int family=AF_UNSPEC)
	adds a dedicated listener to the server with an explicit/dedicated handler for incoming connections More...
	constructor (*code logfunc, *code errlogfunc, bool dbg=False, string name=sprintf("Qore-HTTP-Server/%s", HttpServer::Version), hash hdr=("X-Powered-By":"Qore/"+Qore::VersionString))
	creates the HttpServer More...
	copy ()
	throws an exception; these objects do not support copying
	destructor ()
	calls stop() and destroys the object
bool	getDebug ()
	returns the current status of the debug flag
int	getListenerCount ()
	returns the number of running HTTP listeners
hash	getListenerInfo (softint id)
	returns a hash of information about the listener given the listener ID More...
hash	getListenerInfoName (string name)
	returns a hash of information about the listener given the listener name or bind ID More...
hash	getListeners ()
	returns a hash of listener information More...
int	getListenerTID (softint id)
	gets the TID of a listener based on its listener ID
	log ()
	called to log information to the registered log code
	logArgs (softlist args=())
	calls the log function/closure with the given args
	logError ()
	called to log error information to the registered error log code
	logErrorArgs (softlist args=())
	calls the error log function/closure with the given args
	removeDynamicHandler (string name)
	remove dynamic handler
	sendHttpError (HttpListener listener, hash cx, Socket s, int code, string msg, *hash extra_hdrs, *string encoding)
	sends an HTTP error message on the socket
	setDebug (bool dbg=True)
	turns on or off debugging; when debugging is enabled more verbose error messages are reported
	setDefaultHandler (string name, AbstractHttpRequestHandler obj)
	sets the default request handler when no other handler can be matched
	setDynamicHandler (string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex=True)
	sets a dynamic request handler according to the arguments given
	setDynamicHandler (string name, AbstractUrlHandler obj)
	sets a dynamic request handler according to the arguments given
	setHandler (string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex=True)
	sets a request handler according to the arguments given
	setHandler (string name, AbstractUrlHandler obj)
	sets a request handler according to the arguments given
	stop ()
	stops all listeners; only returns when all connections are closed on all listeners More...
	stopListener (softstring bind)
	stops a single listener based on its name or bind address; does not return until all connections on the listener have closed
	stopListenerID (softint id)
	stops a single listener based on its listener ID; does not return until all connections on the listener have closed
	stopNoWait ()
	stops all listeners; does not wait for all connections on the listeners to close More...
	waitStop ()
	waits for all listeners to be stopped; call after calling HttpServer::stopNoWait()

Static Public Member Functions
static string	getHttpServerVersionString ()
	returns the HTTP server version string
static string	getURLFromBind (softstring bind, *string host)
	returns a complete URL from a bind address More...
static nothing	setReplyHeaders (Socket s, hash cx, reference rv)
	helper method to set HTTP response headers

Public Attributes
const	AIFlags = AI_PASSIVE | AI_ADDRCONFIG
	address info flags
const	CompressionThreshold = 1024
	default threadhold for data compressions; transfers smaller than this size will not be compressed
const	ContentEncodings
	content-encodings supported; this is a hash to simulate a set with O(ln(n)) access times
const	DefaultIdleThreads = 10
	default number of idle threads to have waiting for new connections (accross all listeners)
const	HttpCodes
	map of HTTP result codes and text messages
const	HttpMethods
	supported HTTP methods
const	PollTimeout = 5000
	default poll timeout in ms
const	ReadTimeout = 30000
	default read timeout in ms
const	Version = "0.3.11"
	version of the HttpServer's implementation

Detailed Description

The HttpServer class implements a multithreaded HTTP server primarily designed for serving RPC-style services.

Member Function Documentation

list HttpServer::HttpServer::addINETListeners	(	*string	node,
		softstring	service,
		*string	cert_path,
		*string	key_path,
		*string	name,
		int	family = AF_UNSPEC,
		*string	pwd
	)

adds one or more global listeners according to the bind address

Parameters

node	the bind address for the listener; if not given then the listener will be bound on all interfaces
service	a service name (which will be lookup up to derive a port number) or port number to bind on
cert_path	an optional path to an X509 certificate for HTTPS listeners
key_path	an optional path to a private key file for an X509 certificate for HTTPS listeners
name	an optional name fo the listener
family	one of the following network family constants: AF_INET: for binding an IPv4 socket AF_INET6: for binding an IPv6 socket AF_UNSPEC: for binding a socket with any available address family
pwd	an optional password for the private key file (PEM format only)

Returns

a list of listener info hashes; see the return value of HttpServer::getListenerInfo() for the description of each hash element in the list returned by this method

Exceptions

HTTPSERVER-ADDLISTENER-ERROR

duplicate bind address

hash HttpServer::HttpServer::addListener	(	softstring	sock,
		*string	cert_path,
		*string	key_path,
		*string	name,
		int	family = AF_UNSPEC,
		*string	pwd
	)

adds a global listener to the server

Parameters

sock	the bind address for the listener
cert_path	an optional path to an X509 certificate for HTTPS listeners
key_path	an optional path to a private key file for an X509 certificate for HTTPS listeners
name	an optional name for the listener; the actual listener name will have the listener id appended to it and will be returned in the "name" key in each hash element in the return value for each listener started
family	one of the following network family constants: AF_INET: for binding an IPv4 socket AF_INET6: for binding an IPv6 socket AF_UNSPEC: for binding a socket with any available address family
pwd	an optional password for the private key file (PEM format only)

Returns

a listener info hash; see the return value of HttpServer::getListenerInfo() for the description of the hash returned by this method

Exceptions

HTTPSERVER-ADDLISTENER-ERROR

duplicate bind address

Note

if sock begins with a "/" character then it is assumed to be a UNIX socket path and the family argument is ignored

softlist HttpServer::HttpServer::addListeners	(	softstring	sock,
		*string	cert_path,
		*string	key_path,
		*string	name,
		int	family = AF_UNSPEC,
		*string	pwd
	)

adds one or more global listeners according to the bind address

Parameters

sock	the bind address for the listener
cert_path	an optional path to an X509 certificate for HTTPS listeners
key_path	an optional path to a private key file for an X509 certificate for HTTPS listeners
name	an optional name for the listener; the actual listener name will have the listener id appended to it and will be returned in the "name" key in each hash element in the return value for each listener started
family	one of the following network family constants: AF_INET: for binding an IPv4 socket AF_INET6: for binding an IPv6 socket AF_UNSPEC: for binding a socket with any available address family
pwd	an optional password for the private key file (PEM format only)

Returns

a list of listener info hashes; see the return value of HttpServer::getListenerInfo() for the description of each hash element in the list returned by this method

Exceptions

HTTPSERVER-ADDLISTENER-ERROR

duplicate bind address

Note

if sock begins with a "/" character then it is assumed to be a UNIX socket path and the family argument is ignored

final list HttpServer::HttpServer::addListenersWithHandler	(	string	hname,
		AbstractHttpRequestHandler	handler,
		hash	lp,
		*code	logger,
		*code	errorlogger,
		*code	stopc,
		*string	name,
		int	family = AF_UNSPEC
	)

adds a dedicated listener to the server with an explicit/dedicated handler for incoming connections

Parameters

hname	the name of the handler
handler	the AbstractHttpRequestHandler object that will handle incoming connections
lp	a hash with the following keys: cert_path: (optional) a path to an X509 certificate for HTTPS listeners key_path: (optional) a path to a private key file for an X509 certificate for HTTPS listeners key_password: (optional) an optional string giving the password for the private key (PEM format only) cert: (optional) a Qore::SSLCertificate object for HTTPS listeners key: (optional) a Qore::SSLPrivateKey object for HTTPS listeners url: (required) the path for matching incoming requests (use "/" for dedicated listeners); this is more important for handlers on the global listeners; this is a regular expression unless isregex is False isregex: (optional) a boolean value determining if the url (= path value) is a regular expression or a simple string; if this key is not present, then url is assumed to the a regular expression bind: (required) the bind address for the dedicated listener; this can be a port number or an address (or hostname) and a port number separated by a colon (ex: "192.168.20.4:8021") content_type: (optional) an optional string or list of string content types to match special_headers: (optional) a string or a list of strings giving special headers that when matched will direct requests to the given handler
logger	an optional closure or call reference that will be called with logging information; if this is not set, then the logger set in the HttpServer::constructor() will be used instead
errorlogger	an optional closure or call reference that will be called with error information; if this is not set, then the error logger set in the HttpServer::constructor() will be used instead
stopc	an optional closure or call reference that will be called immediately after the listener is stopped
name	an optional name for the listener; the actual listener name will have the listener id appended to it and will be returned in the "name" key in each hash element in the return value for each listener started
family	one of the following network family constants: AF_INET: for binding an IPv4 socket AF_INET6: for binding an IPv6 socket AF_UNSPEC: for binding a socket with any available address family

Returns

a list of listener info hashes; see the return value of HttpServer::getListenerInfo() for the description of each hash element in the list returned by this method

Exceptions

SETHANDLER-ERROR	HTTP request handler already exists with the given name; non-string entry in special_header list
HTTPSERVER-ADDLISTENER-ERROR	missing or invalid "bind" or "url" entry in the lp argument; duplicate bind address

Note

if bind begins with a "/" character then it is assumed to be a UNIX socket path and the family argument is ignored

HttpServer::HttpServer::constructor	(	*code	logfunc,
		*code	errlogfunc,
		bool	dbg = False,
		string	name = sprintf("Qore-HTTP-Server/%s", HttpServer::Version),
		hash	hdr = ("X-Powered-By":"Qore/"+Qore::VersionString)
	)

creates the HttpServer

call addListener() to add and start listeners

Parameters

logfunc	an optional closure or call reference that will be called with logging information
errlogfunc	an optional closure or call reference that will be called with error information
dbg	if this parameter is set to True, then additional information will be logged when errors occur
name	the name of the HTTP server as returned in the Server header (should be formatted according to RFC 2616 section 3.8 http://tools.ietf.org/html/rfc2616#section-3.8)
hdr	a hash of headers to return in every response by default; to clear the default send an empty hash as the argument here

hash HttpServer::HttpServer::getListenerInfo

(

softint

id

)

returns a hash of information about the listener given the listener ID

Parameters

id	the listener ID

Returns

a hash of listener information with the following keys:

• name: the listener name
• hostname: the listening interface name if available (ex: "localhost"; note that this key is not present when retrieving information about UNIX sockets)
• hostname_desc: a descriptive string giving the hostname and the address family if the hostname is available (ex: "ipv6[localhost]"; note that this key is not present when retrieving information about UNIX sockets)
• address: a string giving the address (ex: "::ffff:0.0.0.0")
• address_desc: a descriptive string giving the address and the address family (ex: "ipv6[::ffff:0.0.0.0]")
• port: an integer port number if available (note that this key is not present when retrieving information about UNIX sockets)
• family: the network address family (see Network Address Family Constants)
• familystr: a string describing the network address family (ex: "ipv4")
• proto: the protocol used; either "http" or "https" for secure listeners
• id: the listener ID
• bind: the bind specification used

Exceptions

HTTP-SERVER-ERROR

invalid listener ID

hash HttpServer::HttpServer::getListenerInfoName

(

string

name

)

returns a hash of information about the listener given the listener name or bind ID

Parameters

name	the listener name or bind ID

Returns

a hash of listener information with the following keys:

• name: the listener name
• hostname: the listening interface name if available (ex: "localhost"; note that this key is not present when retrieving information about UNIX sockets)
• hostname_desc: a descriptive string giving the hostname and the address family if the hostname is available (ex: "ipv6[localhost]"; note that this key is not present when retrieving information about UNIX sockets)
• address: a string giving the address (ex: "::ffff:0.0.0.0")
• address_desc: a descriptive string giving the address and the address family (ex: "ipv6[::ffff:0.0.0.0]")
• port: an integer port number if available (note that this key is not present when retrieving information about UNIX sockets)
• family: the network address family (see Network Address Family Constants)
• familystr: a string describing the network address family (ex: "ipv4")
• proto: the protocol used; either "http" or "https" for secure listeners
• id: the listener ID
• bind: the bind specification used

Exceptions

HTTP-SERVER-ERROR

invalid listener name or bind ID

hash HttpServer::HttpServer::getListeners

(

)

returns a hash of listener information

Returns

a hash of listener info hashes keyed by listener ID; see the return value of HttpServer::getListenerInfo() for the description of each hash value

static string HttpServer::HttpServer::getURLFromBind ( softstring  bind, *string  host  )

static

returns a complete URL from a bind address

if for any reason there is a path in the bind address, it will be ignored

HttpServer::HttpServer::stop

(

)

stops all listeners; only returns when all connections are closed on all listeners

do not call stop() after calling stopNoWait(); it can cause a deadlock

HttpServer::HttpServer::stopNoWait

(

)

stops all listeners; does not wait for all connections on the listeners to close

do not call stop() after calling stopNoWait(); it can cause a deadlock