Qore HttpServer Module Reference 0.3.7

- Main Page
- Related Pages
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
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)
| 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)
| adds a global listener to the server More...
softlist | addListeners (softstring sock, *string cert_path, *string key_path, *string name, int family=AF_UNSPEC)
| 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 | getURLFromBind (softstring bind, *string host)
| returns a complete URL from a bind address More...

## Public Attributes
const | AIFlags = AI_PASSIVE | AI_ADDRCONFIG
| address info flags
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.7"
| 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`
| ) |  |

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

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`
| ) |  |

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

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`
| ) |  |

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

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 `cert:` (optional) an SSLCertificate object for HTTPS listeners `key:` (optional) an 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