Loading...
Searching...
No Matches
HttpServer Namespace Reference

the main namespace for the HttpServer and HttpServerUtil modules More...

## Classes

class | AbstractAuthenticator
| abstract base class for external authentication More...
class | AbstractHttpRequestHandler
| abstract class that all HTTP request handler objects must inherit from More...
class | AbstractHttpSocketHandler
| abstract class that all HTTP dedicated socket handler objects must inherit from More...
class | AbstractHttpSocketHandlerInterface
| Abstract class for HTTP handlers for handling protocol switching. More...
class | AbstractLogger
| this abstract class defines the interface for classes that provide logging methods More...
class | AbstractStreamRequest
| abstract class for streaming HTTP chunked requests/responses More...
class | AbstractUrlHandler
| abstract class for HTTP request handlers anchored at a specific URL More...
struct | HttpHandlerConfigInfo
| hash providing HTTP handler configuration info More...
struct | HttpHandlerResponseInfo
| the return value of HTTP handler methods with potentially unserialized message bodies More...
class | HttpListenerInterface
| this abstract class defines the public interface of the private HttpListener class defined in the HttpServer module More...
struct | HttpListenerOptionInfo
| options for new listeners More...
struct | HttpResponseInfo
| the return value of HTTP handler methods where any message body has been serialized for sending over the HTTP socket More...
class | PermissiveAuthenticator
| class providing automatic authentication for all requests More...

## Functions

hash< HttpListenerOptionInfo > | http_get_listener_options (*string node, *softstring service, *string cert_loc, *string key_loc, *string key_password)
| returns a listener option info hash from flat arguments
hash< HttpListenerOptionInfo > | http_get_listener_options_from_bind (*softstring bind, *string cert_loc, *string key_loc, *string key_password)
| returns a listener option info hash from flat arguments
hash< HttpListenerOptionInfo > | http_get_listener_options_from_bind (*softstring bind, hash< auto > listener_params, hash< HttpListenerOptionInfo > opts=< HttpListenerOptionInfo >{})
| returns a listener option info hash from flat arguments
hash< HttpCertInfo > | http_get_ssl_objects (hash< auto > listener_params)
| converts a hash to HTTP certificate info if possible
hash< HttpCertInfo > | http_get_ssl_objects (string cert_loc, *string key_loc, *string pwd)
| converts a hash to HTTP certificate info if possible
string | http_get_url_from_bind (softstring bind, *string host)
| returns a complete URL from a bind address
string | http_mask_data (string msg)
| this function can be used to mask data in log messages
nothing | http_set_reply_headers (Socket s, hash< auto > cx, reference< auto > rv, *string server_string)
| helper function for setting HTTP response headers
hash< Util::UriQueryInfo > | parse_uri_query (string path)
| parses a URI path for a arguments and a method

## Variables

const | DefaultTimeout = 30s
| default timeout in ms
const | HttpCodes
| map of HTTP result codes and text messages
const | HttpServerString = sprintf("Qore-HTTP-Server/%s", HttpServerVersion)
| default HTTP server string
const | HttpServerVersion = "1.1"
| version of the HttpServer's implementation
const | LP_LEVELMASK = LP_LOGPARAMS - 1
| mask for the log level
const | LP_LOGPARAMS = 1 << 16
const | MaxSslFileLen = 1024 * 1024
| maximum X.509 and private key file length
const | ReadTimeout = DefaultTimeout
| read timeout in ms

## Detailed Description

the main namespace for the HttpServer and HttpServerUtil modules

To use this module, use `"%requires HttpServerUtil"` in your code.

All the public symbols in the module are defined in this namespace

## Function Documentation

## http_get_listener_options()

hash< HttpListenerOptionInfo > HttpServer::http_get_listener_options | ( | *string | node,
|  | *softstring | service,
|  | *string | cert_loc,
|  | *string | key_loc,
|  | *string | key_password
| ) |  |

returns a listener option info hash from flat arguments

Parameters

  node | the node name or address (at least one of either node or service must be provided to make a bind)
  service | the service port (at least one of either node or service must be provided to make a bind)
  cert_loc | the location of an X.509 certificate file (this is actually a file location; supports schemes for file locations; ex: file:///path/to/file; if no scheme is present, defaults to `file://`)
  key_loc | the location of a private key file; if not present, then the certificate is assumed to also have the private key in it (this is actually a file location; supports schemes for file locations; ex: file:///path/to/file; if no scheme is present, defaults to `file://`)
  key_password | the password to the private key, if any

Returns
  a listener option info hash

## http_get_listener_options_from_bind() [1/2]

hash< HttpListenerOptionInfo > HttpServer::http_get_listener_options_from_bind | ( | *softstring | bind,
|  | *string | cert_loc,
|  | *string | key_loc,
|  | *string | key_password
| ) |  |

returns a listener option info hash from flat arguments

Parameters

  bind | a bind address as host:port or just port or a filepath for a UNIX domain socket
  cert_loc | the location of an X.509 certificate file (this is actually a file location; supports schemes for file locations; ex: file:///path/to/file; if no scheme is present, defaults to `file://`)
  key_loc | the location of a private key file; if not present, then the certificate is assumed to also have the private key in it (this is actually a file location; supports schemes for file locations; ex: file:///path/to/file; if no scheme is present, defaults to `file://`)
  key_password | the password to the private key, if any

Returns
  a listener option info hash

## http_get_listener_options_from_bind() [2/2]

hash< HttpListenerOptionInfo > HttpServer::http_get_listener_options_from_bind | ( | *softstring | bind,
|  | hash< auto > | listener_params,
|  | hash< HttpListenerOptionInfo > | opts = `<HttpListenerOptionInfo>{}`
| ) |  |

returns a listener option info hash from flat arguments

Parameters

  bind | a bind address as host:port or just port or a filepath for a UNIX domain socket
  listener_params | parameters for the listener; processed by http_get_ssl_objects()
  opts | listener options

Returns
  a listener option info hash

## http_get_ssl_objects() [1/2]

hash< HttpCertInfo > HttpServer::http_get_ssl_objects | ( | hash< auto > | listener_params | ) |

converts a hash to HTTP certificate info if possible

Parameters

  listener_params

  can have the following keys:
  - `cert_path:` the location of an X.509 certificate file (this is actually a file location; supports schemes for file locations; ex: file:///path/to/file; if no scheme is present, defaults to `file://`)
  - `key_path:` the location of a private key file; if not present, then the certificate is assumed to also have the private key in it (this is actually a file location; supports schemes for file locations; ex: file:///path/to/file; if no scheme is present, defaults to `file://`)
  - `key_password:` the password to the private key file

Returns
  an HttpCertInfo hash

## http_get_ssl_objects() [2/2]

hash< HttpCertInfo > HttpServer::http_get_ssl_objects | ( | string | cert_loc,
|  | *string | key_loc,
|  | *string | pwd
| ) |  |

converts a hash to HTTP certificate info if possible

Parameters

  cert_loc | the location of an X.509 certificate file (this is actually a file location; supports schemes for file locations; ex: file:///path/to/file; if no scheme is present, defaults to `file://`)
  key_loc | the location of a private key file; if not present, then the certificate is assumed to also have the private key in it (this is actually a file location; supports schemes for file locations; ex: file:///path/to/file; if no scheme is present, defaults to `file://`)
  pwd | the password to the private key file

Returns
  an HttpCertInfo hash

## http_get_url_from_bind()

string HttpServer::http_get_url_from_bind | ( | softstring | bind,
|  | *string | host
| ) |  |

returns a complete URL from a bind address

Parameters

  bind | the bind address; if for any reason there is a path in the bind address, it will be ignored
  host | the hostname to use in case the bind string is only a port number; if none is passed or the value passed is equal to the return value of Qore::gethostname(), then `"localhost"` is used

## http_mask_data()

string HttpServer::http_mask_data | ( | string | msg | ) |

this function can be used to mask data in log messages

Example:
  string msg = http_mask_data(msg);
  HttpServer::http_mask_data
  string http_mask_data(string msg)
  this function can be used to mask data in log messages

Parameters

  msg | a log message with potentially sensitive data; expected to be a string of serialized data

Returns
  a string with sensitive data removed; currently the function masks data after `'pass'`, `'password'`, `'sensitive'`, and `'sensitive_data''` followed by a colon, an equals sign, and optionally whitespace

Note
  this algorithm can have false positives and also can miss sensitive data

## parse_uri_query()

hash< Util::UriQueryInfo > HttpServer::parse_uri_query | ( | string | path | ) |

parses a URI path for a arguments and a method

Parameters

  path | the URI path to parse; where the method is the part of the path before the first `"?"` character, and arguments are after

Returns
  a Util::UriQueryInfo hash

Since
  - 0.3.11 the params key value is always returned as a hash
  - 0.3.12 the actual implementation is in Util::parse_uri_query()

Note
  provided by Util::parse_uri_query()

## Variable Documentation

## MaxSslFileLen

const HttpServer::MaxSslFileLen = 1024 * 1024

maximum X.509 and private key file length

there is no real maximum size for these files, however an upper limit is used here to ensure that huge files are not used for the SSL cert and key files which could cause a crash or memory problems; currently set to 1M which is orders of magnitude higher than any real files currently in existence