All Classes Namespaces Functions Variables Groups Pages
HttpServer::HttpServer Class Reference

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

## Public Member Functions

| constructor (*code logfunc, *code errlogfunc, bool dbg=False, string name=sprintf("Qore-HTTP-Server/%s", HttpServer::Version))
| creates the HttpServer
| destructor ()
| calls stop() and destroys the object
final list | addListenersWithHandler (string hname, AbstractHttpRequestHandler handler, hash lp, *code logger, *code errorlogger, *code stopc, *string name)
| adds a dedicated listener to the server with an explicit/dedicated handler for incoming connections
hash | addListener (softstring sock, *string cert_path, *string key_path, *string name)
| adds a global listener to the server
softlist | addListeners (softstring sock, *string cert_path, *string key_path, *string name)
| adds one or more global listeners according to the bind address
list | addINETListeners (*string node, softstring service, *string cert_path, *string key_path, *string name)
| adds one or more global listeners according to the bind address
| copy ()
| throws an exception; these objects do not support copying
hash | getListeners ()
| returns a hash of listener information
hash | getListenerInfo (softint id)
| returns a hash of information about the listener given the listener ID
hash | getListenerInfoName (string name)
| returns a hash of information about the listener given the listener name or bind ID
int | getListenerCount ()
| returns the number of running HTTP listeners
| stopNoWait ()
| stops all listeners; does not wait for all connections on the listeners to close
| waitStop ()
| waits for all listeners to be stopped; call after calling HttpServer::stopNoWait()
| stop ()
| stops all listeners; only returns when all connections are closed on all listeners
| 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
int | getListenerTID (softint id)
| gets the TID of a listener based on its listener ID
| setDefaultHandler (string name, AbstractHttpRequestHandler obj)
| sets the default request handler when no other handler can be matched
| setHandler (string name, string url, *string content_type, AbstractHttpRequestHandler obj, *softlist special_headers)
| sets a request handler according to the arguments given
| setDynamicHandler (string name, string url, *string content_type, AbstractHttpRequestHandler obj, *softlist special_headers)
| sets a dynamic request handler according to the arguments given
| removeDynamicHandler (string name)
| remove dynamic handler
| log ()
| called to log information to the registered log code
| logError ()
| called to log error information to the registered error log code
| logArgs (list args=())
| calls the log function/closure with the given args
| logErrorArgs (list args=())
| calls the error log function/closure with the given args
| sendHttpError (Socket s, int code, string msg, bool close=False, *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
bool | getDebug ()
| returns the current status of the debug flag

## Static Public Member Functions

static string | getURLFromBind (softstring bind, *string host)
| returns a complete URL from a bind address

## Public Attributes

const | Version = "0.3.6"
| version of the HttpServer's implementation
const | ReadTimeout = 30000
| default read timeout in ms
const | PollTimeout = 5000
| default poll timeout in ms
const | AIFlags = AI_PASSIVE | AI_ADDRCONFIG
| address info flags
const | HttpCodes
| map of HTTP result codes and text messages

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

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

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

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

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

softlist HttpServer::HttpServer::addListeners | ( | softstring | sock,
|  | *string | cert_path,
|  | *string | key_path,
|  | *string | name
| ) |  |

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

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

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

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
  - `bind:` (required) the bind address for the dedicated listener
  - `content_type:` (optional) an optional content type to match; this is more important for handlers on the global listeners
  - `special_headers:` (optional) a string or a list of strings giving special headers that when matched will direct requests to the given handler; this is more important for handlers on the global listeners

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

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

HttpServer::HttpServer::constructor | ( | *code | logfunc,
|  | *code | errlogfunc,
|  | bool | dbg = `False`,
|  | string | name = `sprintf("Qore-HTTP-Server/%s", HttpServer::Version)`
| ) |  |

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)

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

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