Qore HttpServer Module Reference  0.3.8
 All Classes Namespaces Functions Variables Groups Pages
HttpServer.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // @file HttpServer.qm HTTP multi-threaded server module definition
3 
4 /* HttpServer.qm Copyright (C) 2012 - 2014 David Nichols
5 
6  Permission is hereby granted, free of charge, to any person obtaining a
7  copy of this software and associated documentation files (the "Software"),
8  to deal in the Software without restriction, including without limitation
9  the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  and/or sell copies of the Software, and to permit persons to whom the
11  Software is furnished to do so, subject to the following conditions:
12 
13  The above copyright notice and this permission notice shall be included in
14  all copies or substantial portions of the Software.
15 
16  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  DEALINGS IN THE SOFTWARE.
23 */
24 
25 // need mime definitions
26 
27 
28 /* Version History: see docs below
29  note that this server suffers from the following limitations, among many others:
30  + not totally HTTP 1.1 compliant although claims to be
31 */
32 
211 
218 namespace HttpServer {
220 
226  hash parse_uri_query(string path);
227 
228 
230 
236  string get_exception_string(hash ex);
237 
238 };
239 
240 // class containing handler info
241 class HttpServer::HandlerInfo {
242 
243 public:
244  public :
245  string name;
246  AbstractHttpRequestHandler obj;
247  string path;
248  bool isregex;
249  // content type hash
250  hash ch;
251  *list shdr;
252 
253 public:
254 
255  constructor(string name, AbstractHttpRequestHandler obj, string path, bool isregex = True, *softlist content, *softlist shdr);
256 
257 
258  bool matchContentType(string ct);
259 
260 
262  int matchRequest(hash hdr, int score);
263 
264 };
265 
266 // class to implement handler-handling (private)
267 class HttpServer::HttpHandlerList {
268 
269 public:
270  public :
271  hash handlers;
272 
273 public:
274 
275 
276 private:
277  static checkSpecialHeaders(reference sh);
278 public:
279 
280 
282  setHandler(string name, string path, bool isregex = True, *softlist content, AbstractHttpRequestHandler obj, *softlist special_headers);
283 
284 
285  // matches a handler to the request
286  *HandlerInfo findHandler(hash hdr, reference score, bool final = False);
287 
288 
289  bool empty();
290 
291 
292  int size();
293 
294 };
295 
296 // class containing dynamic handler info
297 class HttpServer::DynamicHandlerInfo : public HttpServer::HandlerInfo {
298 
299 public:
300  public :
301  Counter counter();
302 
303 public:
304 
305  constructor(string name, AbstractHttpRequestHandler obj, string path, bool isregex = True, *softlist content, *softlist shdr);
306 
307 };
308 
309 // maintains the request count for dynamic handlers (private)
310 class HttpServer::DynamicHandlerHelper {
311 
312 public:
313 private:
314 
315 public:
316 
317  private :
318  Counter c;
319 
320 public:
321 
322  constructor(Counter c);
323 
324 
325  destructor();
326 
327 };
328 
329 // for dynamic handler-handling (private)
330 class HttpServer::DynamicHttpHandlerList : public HttpServer::HttpHandlerList {
331 
332 public:
333  private :
334  RWLock dhl();
335 
336 public:
337 
339  setHandler(string name, string path, bool isregex, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers);
340 
341 
343  removeHandler(string name);
344 
345 
346  *DynamicHandlerInfo findHandler(hash hdr, reference score, reference dhh);
347 
348 };
349 
351 
354 
355 public:
357 
359  bool requiresAuthentication();
360 
361 
363 
365  string getRealm();
366 
367 
369 
375  authenticate(string user, string pass = "");
376 
377 
379 
385  authenticateByIP(string ip, reference user);
386 
387 
388  private hash getAuthHeader();
389 
390 
391  private hash do401(string msg = "Authentication is required to access this server");
392 
393 
395 
404  *hash authenticateRequest(HttpListener listener, hash hdr, reference cx);
405 
406 };
407 
409 
417 
418 public:
419 private:
420 
421 public:
422 
423  private :
428 
429 public:
430 
432 
445 
446 
448 
458 
459 
461 
471  nothing recv(hash v);
472 
473 
475 
478  any send();
479 
480 
482 
492 
494 
504  abstract nothing recvImpl(hash v);
505 
507 
510  abstract any sendImpl();
511 };
512 
514 
523 
524 public:
525 private:
526 
527 public:
528 
529  private :
535  Socket s;
541  any body;
542 
543 public:
544 
547 
548 
549  hash handleRequest();
550 
551 
553 
558  private hash sendResponse();
559 
560 
562 
571  private hash getResponseHeaderMessage();
572 
573 
575 
577  private nothing recv(hash v);
578 
579 
581  private any send();
582 
583 
584  private logChunk(bool send, int size);
585 
586 
588 
600 
601 
603 
612  private nothing recvImpl(hash v);
613 
614 
616 
619  private any sendImpl();
620 
621 };
622 
624 
632 
633 public:
634  public :
637 
639  bool decompress = True;
640 
643 
645  bool stream;
646 
649 
650 public:
651 
653 
657 
658 
660  nothing persistentClosed();
661 
662 
664  private nothing checkPersistent(hash cx, hash hdr);
665 
666 
668 
691  hash handleRequest(hash cx, hash hdr, *data body);
692 
693 
695  hash handleRequest(HttpListener listener, Socket s, hash cx, hash hdr, *data body);
696 
697 
699  private AbstractStreamRequest getStreamRequestImpl(HttpListener listener, Socket s, hash cx, hash hdr, *data body);
700 
701 
703  static data decodeBody(string ce, binary body, *string enc);
704 
706  static binary encodeBody(string ce, data body);
707 
709  *data getMessageBody(Socket s, hash hdr, *data body, bool decode = True);
710 
711 
713 
720  static *string getLogMessage(hash cx, hash api, reference params, *reference args);
721 
723 
726 
727 
729 
732 
733 
735  static hash makeResponse(int code, string fmt);
736 
738  static hash makeResponse(hash hdr, int code, string fmt);
739 
741  static hash makeResponse(int code, *data body, *hash hdr);
742 
744  static hash make400(string fmt);
745 
747  static hash make400(hash hdr, string fmt);
748 
750  static hash make501(string fmt);
751 
753  static hash make501(hash hdr, string fmt);
754 
756  static hash redirect(hash cx, hash hdr, string path);
757 };
758 
761 
762 public:
763  public :
765  string url_root;
766 
767 public:
768 
770 
774 
775 
777  string getRelativePath(string path);
778 
779 };
780 
782 
785 
786 public:
787  private :
789  bool stop = False;
790 
793 
796 
798  Mutex m();
799 
800 public:
801 
803 
806 
807 
809 
823  start(softstring lid, hash cx, hash hdr, Socket s);
824 
825 
827 
831  stop(softstring lid);
832 
833 
835 
837  stop();
838 
839 
841 
867  abstract hash handleRequest(hash cx, hash hdr, *data b);
868 
870 
884  private abstract startImpl(softstring lid, hash cx, hash hdr, Socket s);
885 
887 
889  private stopImpl(string lid);
890 
891 
893  private stopImpl();
894 
895 };
896 
899 
900 public:
901  public :
903  const Version = "0.3.7";
905  const ReadTimeout = 30000; // recvs timeout after 30 seconds
907  const PollTimeout = 5000; // check for exit every 5 seconds while waiting
908 
909  // logging options
910  const LP_LOGPARAMS = 1 << 16;
911  const LP_LEVELMASK = LP_LOGPARAMS - 1;
912 
915 
917  const HttpMethods = (
918  "HEAD": True,
919  "POST": True,
920  "PUT": True,
921  "DELETE": True,
922  "GET": True,
923  "OPTIONS": True,
924  //"TRACE": True,
925  //"CONNECT": True,
926  );
927 
929  const HttpCodes = (
930  // 100s: Informational
931  "100": "Continue",
932  "101": "Switching Protocols",
933 
934  // RFC 2518: WebDAV
935  "102": "Processing",
936 
937  // 200s: Success
938  "200": "OK",
939  "201": "Created",
940  "202": "Accepted",
941  "203": "Non-Authoritative Information",
942  "204": "No Content",
943  "205": "Reset Content",
944  "206": "Partial Content",
945 
946  // RFC 4918: WebDAV: The message body that follows is an XML message and can contain a number of separate response codes, depending on how many sub-requests were made
947  "207": "Multi-Status",
948 
949  // RFC 5842: WebDAV: The members of a DAV binding have already been enumerated in a previous reply to this request, and are not being included again
950  "208": "Already Reported",
951 
952  // RFC 3229
953  "226": "IM Used",
954 
955  // 300s: Redirection
956  "300": "Multiple Choices",
957  "301": "Moved Permanently",
958  "302": "Found",
959  "303": "See Other",
960  "304": "Not Modified",
961  "305": "Use Proxy",
962  //"306": "(Reserved)",
963  "307": "Temporary Redirect",
964 
965  // 400s: Client Errors
966  "400": "Bad Request",
967  "401": "Unauthorized",
968  "402": "Payment Required",
969  "403": "Forbidden",
970  "404": "Not Found",
971  "405": "Method Not Allowed",
972  "406": "Not Acceptable",
973  "407": "Proxy Authentication Required",
974  "408": "Request Timeout",
975  "409": "Conflict",
976  "410": "Gone",
977  "411": "Length Required",
978  "412": "Precondition Failed",
979  "413": "Request Entity Too Large",
980  "414": "Request-URI Too Long",
981  "415": "Unsupported Media Type",
982  "416": "Requested Range Not Satisfiable",
983  "417": "Expectation Failed",
984 
985  // RFC 2324: http://tools.ietf.org/html/rfc2324
986  "418": "I'm a teapot",
987 
988  // Returned by the Twitter Search and Trends API when the client is being rate limited
989  "420": "Enhance Yextern Calm",
990 
991  // RFC 4918: WebDAV: The request was well-formed but was unable to be followed due to semantic errors
992  "422": "Unprocessable Entity",
993 
994  // RFC 4918: WebDAV: The resource that is being accessed is locked
995  "423": "Locked",
996 
997  // RFC 4918: WebDAV: The request failed due to failure of a previous request (e.g. a PROPPATCH)
998  "424": "Failed Dependency",
999 
1000  // Internet draft: Defined in drafts of "WebDAV Advanced Collections Protocol", but not present in "Web Distributed Authoring and Versioning (WebDAV) Ordered Collections Protocol"
1001  "425": "Unordered Collection",
1002 
1003  // RFC 2817: The client should switch to a different protocol such as TLS/1.0
1004  "426": "Upgrade Required",
1005 
1006  // RFC 6585: The origin server requires the request to be conditional. Intended to prevent "the 'lost update' problem, where a client GETs a resource's state, modifies it, and PUTs it back to the server, when meanwhile a third party has modified the state on the server, leading to a conflict."
1007  "428": "Precondition Required",
1008 
1009  // RFC 6585: The user has sent too many requests in a given amount of time. Intended for use with rate limiting schemes
1010  "429": "Too Many Requests",
1011 
1012  // RFC 6585
1013  "431": "Request Header Fields Too Large",
1014 
1015  // 500s: Server Errors
1016  "500": "Internal Server Error",
1017  "501": "Not Implemented",
1018  "502": "Bad Gateway",
1019  "503": "Service Unavailable",
1020  "504": "Gateway Timeout",
1021  "505": "HTTP Version Not Supported",
1022  "509": "Bandwidth Limit Exceeded",
1023 
1024  // RFC 2774: Further extensions to the request are required for the server to fulfill it
1025  "510": "Not Extended",
1026 
1027  // RFC 6585: The client needs to authenticate to gain network access. Intended for use by intercepting proxies used to control access to the network (e.g. "captive portals" used to require agreement to Terms of Service before granting full Internet access via a Wi-Fi hotspot)
1028  "511": "Network Authentication Required",
1029  );
1030 
1033  "gzip": "gzip",
1034  "deflate": "deflate",
1035  "bzip2": "bzip2",
1036  "x-gzip": "gzip",
1037  "x-deflate": "deflate",
1038  "x-bzip2": "bzip2",
1039  );
1040 
1043 
1045  const CompressionThreshold = 1024;
1046 
1047 public:
1048 
1050  private :
1051  *code logfunc;
1052  *code errlogfunc;
1053 
1054  // quit server flag
1055  bool exit = False;
1056 
1057  // if True then verbose exception info will be logged
1058  bool debug;
1059 
1060  Sequence seqSessions();
1061  Sequence seqListeners();
1062 
1063  bool stopped = False;
1064 
1065  // permanent handlers; these handlers are never removed
1066  HttpHandlerList handlers();
1067 
1068  // default handler
1069  hash defaultHandler;
1070 
1071  // hash of listeners keyed by listener ID
1072  hash listeners;
1073 
1074  // map of bind addresses to listener IDs
1075  hash smap;
1076 
1077  // map of listener names to listener IDs
1078  hash nmap;
1079 
1080  // listener Gate
1081  Gate lm();
1082 
1083  // running listener counter
1084  Counter c();
1085 
1086  // dynamic handlers
1087  DynamicHttpHandlerList dhandlers();
1088 
1089  // connection thread pool
1090  ThreadPool threadPool(-1, DefaultIdleThreads);
1091 
1092  // other misc response headers
1093  hash hdr;
1094 
1095  // override message body encoding if none is received from the sender; http://tools.ietf.org/html/rfc2616#section-3.7.1 states that it must be iso-8850-1
1096  *string override_encoding;
1097 
1098  static string HttpServerString;
1099 
1100 public:
1102 
1104 
1112  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));
1113 
1114 
1116  destructor();
1117 
1118 
1120  static string getHttpServerVersionString();
1121 
1122  setDefaultTextEncoding(string enc);
1123 
1124 
1125  string getDefaultTextEncoding();
1126 
1127 
1129 
1157  final list addListenersWithHandler(string hname, AbstractHttpRequestHandler handler, hash lp, *code logger, *code errorlogger, *code stopc, *string name, int family = AF_UNSPEC);
1158 
1159 
1161 
1176  hash addListener(softstring sock, *string cert_path, *string key_path, *string name, int family = AF_UNSPEC);
1177 
1178 
1180 
1195  softlist addListeners(softstring sock, *string cert_path, *string key_path, *string name, int family = AF_UNSPEC);
1196 
1197 
1199 
1213  list addINETListeners(*string node, softstring service, *string cert_path, *string key_path, *string name, int family = AF_UNSPEC);
1214 
1215 
1217  copy();
1218 
1219 
1221 
1223  hash getListeners();
1224 
1225 
1227 
1244  hash getListenerInfo(softint id);
1245 
1246 
1248 
1265  hash getListenerInfoName(string name);
1266 
1267 
1269  int getListenerCount();
1270 
1271 
1273 
1275  stopNoWait();
1276 
1277 
1279  waitStop();
1280 
1281 
1282  // only called from the listeners - do not call externally
1283  listenerStopped(HttpListener l);
1284 
1285 
1287 
1289  stop();
1290 
1291 
1293  stopListener(softstring bind);
1294 
1295 
1297  stopListenerID(softint id);
1298 
1299 
1301  int getListenerTID(softint id);
1302 
1303 
1306 
1307 
1309  setHandler(string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex = True);
1310 
1311 
1313  setDynamicHandler(string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex = True);
1314 
1315 
1317  setHandler(string name, AbstractUrlHandler obj);
1318 
1319 
1321  setDynamicHandler(string name, AbstractUrlHandler obj);
1322 
1323 
1325  addHandlerToListener(softstring bind, string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex = True);
1326 
1327 
1329  addHandlerToListenerID(softint id, string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex = True);
1330 
1331 
1333  addHandlerToListener(softstring bind, string name, AbstractUrlHandler obj);
1334 
1335 
1337  addHandlerToListenerID(softint id, string name, AbstractUrlHandler obj);
1338 
1339 
1341  removeDynamicHandler(string name);
1342 
1343 
1345  log();
1346 
1347 
1349  logError();
1350 
1351 
1353  logArgs(softlist args = ());
1354 
1355 
1357  logErrorArgs(softlist args = ());
1358 
1359 
1361  sendHttpError(HttpListener listener, hash cx, Socket s, int code, string msg, *hash extra_hdrs, *string encoding);
1362 
1363 
1365 
1367  static string getURLFromBind(softstring bind, *string host);
1368 
1370  setDebug(bool dbg = True);
1371 
1372 
1374  bool getDebug();
1375 
1376 
1377  startConnection(code c);
1378 
1379 
1381  static nothing setReplyHeaders(Socket s, hash cx, reference rv);
1382 
1384  // don't reimplement this method; fix/enhance it in the module
1385  final private HttpListener addListenerIntern(*string node, *softstring service, *Qore::SSLCertificate cert, *Qore::SSLPrivateKey key, *hash hi, *code logger, *code errorlogger, *code stopc, *string name, int family = AF_UNSPEC);
1386 
1387 
1388  // don't reimplement this method; fix/enhance it in the module
1389  static final private hash getSSLObjects(string cert_path, *string key_path);
1390 
1391  // don't reimplement this method; fix/enhance it in the module
1392  final private list addINETListenersIntern(*string node, softstring service, *hash sd, *hash lp, *code logger, *code errorlogger, *code stopc, *string name, int family = AF_UNSPEC);
1393 
1394 
1395  // don't reimplement this method; fix/enhance it in the module
1396  final private hash noHandlerError(hash cx, hash hdr, any body);
1397 
1398 
1399  // handles an incoming request - do not call externally; this method is called by the listeners when a request is received
1400  // don't reimplement this method; fix/enhance it in the module
1401  final handleRequest(HttpListener listener, Socket s, reference cx, hash hdr, hash hh, *data body, bool head = False, HttpPersistentHandlerInfo phi);
1402 
1403 
1404  // sends a reply to a request
1405  // don't reimplement this method; fix/enhance it in the module
1406  final sendReply(HttpListener listener, Socket s, AbstractHttpRequestHandler handler, hash rv, hash cx, hash hdr, bool head);
1407 
1409 };
1410 
1411 class HttpServer::HttpPersistentHandlerInfo {
1412 
1413 public:
1414  public :
1415  *DynamicHandlerHelper dhh;
1416  *AbstractHttpRequestHandler handler;
1417 
1418 public:
1419 
1420  destructor();
1421 
1422 
1423  assign(DynamicHandlerHelper dhh, AbstractHttpRequestHandler handler);
1424 
1425 
1426  clear();
1427 
1428 };
1429 
1432 
1433 public:
1434  private :
1435  HttpServer serv;
1436  Sequence ss;
1437  *SSLCertificate cert;
1438  *SSLPrivateKey key;
1439  bool ssl = False;
1440  any socket;
1441  hash socket_info;
1442 
1443  // connection counter
1444  Counter cThreads();
1445  bool exit = False;
1446  bool stopped = False;
1447  int id;
1448 
1449  // socket handler hash
1450  hash shh;
1451 
1452  // mutex
1453  Mutex m();
1454 
1455  // code references to external logging functions
1456  *code logger;
1457  *code errorlogger;
1458 
1459  // stop notification closure
1460  *code stopc;
1461 
1462  string name;
1463 
1464  const PollInterval = 1s;
1465  const ListenQueue = 100;
1466 
1467 public:
1468 
1469  public :
1470  // TID of the background listener thread
1471  int tid;
1472 
1473  // listener-specific handlers
1474  HttpHandlerList handlers();
1475 
1476  // default handler info
1477  *HandlerInfo defaultHandler;
1478 
1479 public:
1480 
1481  // params: server, id, session ID sequence object, socket, rbac obj, [cert, key]
1482  constructor(HttpServer server, int id, Sequence ss, *string node, *softstring service, *Qore::SSLCertificate cert, *Qore::SSLPrivateKey key, *hash hi, *code logger, *code errorlogger, *code stopc, string name, int family = AF_UNSPEC);
1483 
1484 
1485  addHandlers(hash hi);
1486 
1487 
1488  setDefaultHandler(string name);
1489 
1490 
1491  copy();
1492 
1493 
1494  destructor();
1495 
1496 
1497  string getName();
1498 
1499 
1500  any getAddress();
1501 
1502 
1503  int getID();
1504 
1505 
1506  bool isSecure();
1507 
1508 
1509  hash getInfo();
1510 
1511 
1512  any removeUserThreadContext(string k);
1513 
1514 
1515  addUserThreadContext(hash uctx);
1516 
1517 
1518  stopNoWait();
1519 
1520 
1521  stop();
1522 
1523 
1524  logResponse(hash cx, int code, *data body, *hash hdr);
1525 
1526 
1527  logResponse(hash cx, hash rv);
1528 
1529 
1530  log();
1531 
1532 
1533  logError();
1534 
1535 
1536  private mainThread();
1537 
1538 
1539  // thread for handling communication per connection
1540  private connectionThread(Socket s);
1541 
1542 
1543  bool registerDedicatedSocket(softstring id, AbstractHttpSocketHandler h);
1544 
1545 
1546  removeDedicatedSocket(softstring id, AbstractHttpSocketHandler h);
1547 
1548 };
constructor(HttpListener listener, AbstractHttpRequestHandler handler, Socket s, hash cx, hash hdr, any body)
creates the object with the given attributes
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
logArgs(softlist args=())
calls the log function/closure with the given args
any send()
this method provides the callback method for sending chunked data by calling sendImpl() ...
abstract nothing recvImpl(hash v)
abstract callback method for receiving chunked data
const AF_UNSPEC
string sprintf(string fmt,...)
hash getListeners()
returns a hash of listener information
hash hdr
a hash of request headers
Definition: HttpServer.qm.dox.h:539
hash addListener(softstring sock, *string cert_path, *string key_path, *string name, int family=AF_UNSPEC)
adds a global listener to the server
private nothing recvImpl(hash v)
abstract callback method for receiving chunked data
string get_exception_string(hash ex)
returns a multi-line string from the exception hash argument suitable for logging or output on the co...
abstract class for streaming HTTP chunked requests/responses
Definition: HttpServer.qm.dox.h:522
abstract hash handleRequest(hash cx, hash hdr, *data b)
called by the HTTP server to handle incoming HTTP requests
setDebug(bool dbg=True)
turns on or off debugging; when debugging is enabled more verbose error messages are reported ...
string getRealm()
returns the authentication realm as a string
abstract class that all HTTP request handler objects must inherit from
Definition: HttpServer.qm.dox.h:631
*AbstractAuthenticator auth
the optional AbstractAuthenticator for requests to this handler
Definition: HttpServer.qm.dox.h:636
static string getURLFromBind(softstring bind, *string host)
returns a complete URL from a bind address
constructor(hash cx)
creates the object with the given arguments
const ReadTimeout
default read timeout in ms
Definition: HttpServer.qm.dox.h:905
removeDynamicHandler(string name)
remove dynamic handler
hash lh
hash of listener references; this is to stop all connections associated with a particular listener ...
Definition: HttpServer.qm.dox.h:792
*hash ex
if an exception is raised in a callback then the exception hash is saved here
Definition: HttpServer.qm.dox.h:427
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&#39;s id
destructor()
calls stop() and destroys the object
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&#39;s name or bind address
const True
start(softstring lid, hash cx, hash hdr, Socket s)
called from the HTTP server after the handleRequest() method indicates that a dedicated connection sh...
string getRelativePath(string path)
returns the relative path anchored from the url_root if possible; URI query arguments are stripped of...
bool persistent
persistent connection flag
Definition: HttpServer.qm.dox.h:648
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
*data getMessageBody(Socket s, hash hdr, *data body, bool decode=True)
optionally retrieves and post-processes any message body
const DefaultIdleThreads
default number of idle threads to have waiting for new connections (accross all listeners) ...
Definition: HttpServer.qm.dox.h:1042
stopListener(softstring bind)
stops a single listener based on its name or bind address; does not return until all connections on t...
stopListenerID(softint id)
stops a single listener based on its listener ID; does not return until all connections on the listen...
private hash sendResponse()
called to either create the response hash or send a chunked response directly
const HttpMethods
supported HTTP methods
Definition: HttpServer.qm.dox.h:917
AbstractHttpRequestHandler handler
the request handler for the request
Definition: HttpServer.qm.dox.h:533
nothing recv(hash v)
this method provides the callback method for receiving chunked data by calling recvImpl() ...
bool decompress
if POSTed data should be decompressed automatically if there is content-encoding
Definition: HttpServer.qm.dox.h:639
abstract private startImpl(softstring lid, hash cx, hash hdr, Socket s)
called from the HTTP server after the handleRequest() method indicates that a dedicated connection sh...
hash cx
call context hash
Definition: HttpServer.qm.dox.h:425
private hash getResponseHeaderMessageImpl()
this method should return the response message description hash
stop()
stops all listeners; only returns when all connections are closed on all listeners ...
binary binary()
bool stream
if the handler supports streaming requests/responses with chunked data
Definition: HttpServer.qm.dox.h:645
constructor(*AbstractAuthenticator auth, softbool stream=False)
create the object optionally with the given AbstractAuthenticator
constructor(string url_root, *AbstractAuthenticator auth)
creates the object based on the URL root and optional authenticator
Mutex m()
listener reference hash mutex
abstract class for embedded objects serving streaming requests
Definition: HttpServer.qm.dox.h:416
private stopImpl()
called from the HTTP server when the socket should be closed due to an external request; the start() ...
static hash make501(string fmt)
creates a hash for an HTTP 501 error response with the response message body as a string ...
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
const False
bool requiresAuthentication()
called to check if the connection requires authentication
list list(...)
abstract base class for external authentication
Definition: HttpServer.qm.dox.h:353
static hash makeResponse(int code, string fmt)
creates a hash for an HTTP response with the response code and the response message body as a formatt...
static hash make400(string fmt)
creates a hash for an HTTP 400 error response with the response message body as a string ...
hash getListenerInfo(softint id)
returns a hash of information about the listener given the listener ID
restoreThreadLocalData(*hash data)
called after handleRequest() with any data returned from saveThreadData()
private nothing recv(hash v)
this is the primary callback for receiving chunked data; data will be logged, and then recvImpl() is ...
stop()
called from the HTTP server when the socket should be closed due to an external request; the start() ...
const PollTimeout
default poll timeout in ms
Definition: HttpServer.qm.dox.h:907
hash cx
the call context variable
Definition: HttpServer.qm.dox.h:537
Socket s
the Socket object for the response
Definition: HttpServer.qm.dox.h:535
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
private any sendImpl()
abstract callback method for sending chunked data
constructor(*AbstractAuthenticator auth)
create the object optionally with the given AbstractAuthenticator
nothing exit(softint rc=0)
hash parse_uri_query(string path)
parses a URI path for a arguments and a method; where the method is the part of the path before the f...
static binary encodeBody(string ce, data body)
encodes a message body with content-encoding
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 ...
static string getHttpServerVersionString()
returns the HTTP server version string
static *string getLogMessage(hash cx, hash api, reference params, *reference args)
helper method for handling log messages
sendHttpError(HttpListener listener, hash cx, Socket s, int code, string msg, *hash extra_hdrs, *string encoding)
sends an HTTP error message on the socket
stopNoWait()
stops all listeners; does not wait for all connections on the listeners to close
bool getDebug()
returns the current status of the debug flag
private AbstractStreamRequest getStreamRequestImpl(HttpListener listener, Socket s, hash cx, hash hdr, *data body)
returns the AbstractStreamRequest object for handling chunked requests
abstract any sendImpl()
abstract callback method for sending chunked data
const CompressionThreshold
default threadhold for data compressions; transfers smaller than this size will not be compressed ...
Definition: HttpServer.qm.dox.h:1045
abstract hash getResponseHeaderMessageImpl()
this method should return the response message description hash
private any send()
this is the primary callback for sending chunked responses; first sendImpl() is called to get the raw...
abstract class that all HTTP dedicated socket handler objects must inherit from
Definition: HttpServer.qm.dox.h:784
abstract class for HTTP request handlers anchored at a specific URL
Definition: HttpServer.qm.dox.h:760
waitStop()
waits for all listeners to be stopped; call after calling HttpServer::stopNoWait() ...
static data decodeBody(string ce, binary body, *string enc)
decodes a message body with content-encoding
hash handleRequest(hash cx, hash hdr, *data body)
will be called when a request is received that should be directed to the handler
static nothing setReplyHeaders(Socket s, hash cx, reference rv)
helper method to set HTTP response headers
const AIFlags
address info flags
Definition: HttpServer.qm.dox.h:914
private hash getResponseHeaderMessage()
this method returns the response message description hash by calling getResponseHeaderMessageImpl() ...
bool decompress_to_string
if automatically decompressed POSTed data should be converted to a string (if False, then it will be decompressed to a binary)
Definition: HttpServer.qm.dox.h:642
copy()
throws an exception; these objects do not support copying
const Version
version of the HttpServer&#39;s implementation
Definition: HttpServer.qm.dox.h:903
setDefaultHandler(string name, AbstractHttpRequestHandler obj)
sets the default request handler when no other handler can be matched
The HttpServer class implements a multithreaded HTTP server primarily designed for serving RPC-style ...
Definition: HttpServer.qm.dox.h:898
authenticate(string user, string pass="")
called to authenticate a user for a connection
HttpListener listener
the listener servicing the request for logging purposes
Definition: HttpServer.qm.dox.h:531
hash getResponseHeaderMessage()
this method returns the response message description hash by calling getResponseHeaderMessageImpl() ...
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
int getListenerCount()
returns the number of running HTTP listeners
this class implements the listeners for the HttpServer class
Definition: HttpServer.qm.dox.h:1431
log()
called to log information to the registered log code
const VersionString
*hash saveThreadLocalData()
called before handleRequest() any data returned here will be given to restoreThreadLocalData() after ...
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
authenticateByIP(string ip, reference user)
called when the connection requires authentication, but no authentication credentials were supplied...
hash hash(object obj)
string url_root
root part of URL for matching requests
Definition: HttpServer.qm.dox.h:765
const AI_ADDRCONFIG
hash getListenerInfoName(string name)
returns a hash of information about the listener given the listener name or bind ID ...
const HttpCodes
map of HTTP result codes and text messages
Definition: HttpServer.qm.dox.h:929
nothing persistentClosed()
called externally when a persistent connection is closed
const AI_PASSIVE
static hash redirect(hash cx, hash hdr, string path)
generates a redirect hash for the given path
*hash authenticateRequest(HttpListener listener, hash hdr, reference cx)
primary method called to authenticate each request
hash lsh
hash of listener stop flags
Definition: HttpServer.qm.dox.h:795
any body
any message body given in a non-chunked request; could already be deserialized
Definition: HttpServer.qm.dox.h:541
private nothing checkPersistent(hash cx, hash hdr)
this method will throw an exception if a persistent connection cannot be granted
const ContentEncodings
content-encodings supported; this is a hash to simulate a set with O(ln(n)) access times ...
Definition: HttpServer.qm.dox.h:1032
int getListenerTID(softint id)
gets the TID of a listener based on its listener ID