Qore HttpServer Module Reference  0.3.11
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 
224 
231 namespace HttpServer {
233 
241  hash parse_uri_query(string path, bool trans = True);
242 
243 
245 
251  string get_exception_string(hash ex);
252 
253 };
254 
255 // class containing handler info
256 class HttpServer::HandlerInfo {
257 
258 public:
259  public :
260  string name;
261  AbstractHttpRequestHandler obj;
262  string path;
263  bool isregex;
264  // content type hash
265  hash ch;
266  *list shdr;
267 
268 public:
269 
270  constructor(string name, AbstractHttpRequestHandler obj, string path, bool isregex = True, *softlist content, *softlist shdr);
271 
272 
273  bool matchContentType(string ct);
274 
275 
277  int matchRequest(hash hdr, int score);
278 
279 };
280 
281 // class to implement handler-handling (private)
282 class HttpServer::HttpHandlerList {
283 
284 public:
285  public :
286  hash handlers;
287 
288 public:
289 
290 
291 private:
292  static checkSpecialHeaders(reference sh);
293 public:
294 
295 
297  setHandler(string name, string path, bool isregex = True, *softlist content, AbstractHttpRequestHandler obj, *softlist special_headers);
298 
299 
300  // matches a handler to the request
301  *HandlerInfo findHandler(hash hdr, reference score, bool final = False);
302 
303 
304  bool empty();
305 
306 
307  int size();
308 
309 };
310 
311 // class containing dynamic handler info
312 class HttpServer::DynamicHandlerInfo : public HttpServer::HandlerInfo {
313 
314 public:
315  public :
316  Counter counter();
317 
318 public:
319 
320  constructor(string name, AbstractHttpRequestHandler obj, string path, bool isregex = True, *softlist content, *softlist shdr);
321 
322 };
323 
324 // maintains the request count for dynamic handlers (private)
325 class HttpServer::DynamicHandlerHelper {
326 
327 public:
328 private:
329 
330 public:
331 
332  private :
333  Counter c;
334 
335 public:
336 
337  constructor(Counter c);
338 
339 
340  destructor();
341 
342 };
343 
344 // for dynamic handler-handling (private)
345 class HttpServer::DynamicHttpHandlerList : public HttpServer::HttpHandlerList {
346 
347 public:
348  private :
349  RWLock dhl();
350 
351 public:
352 
354  setHandler(string name, string path, bool isregex, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers);
355 
356 
358  removeHandler(string name);
359 
360 
361  *DynamicHandlerInfo findHandler(hash hdr, reference score, reference dhh);
362 
363 };
364 
366 
369 
370 public:
372 
374  bool requiresAuthentication();
375 
376 
378 
380  string getRealm();
381 
382 
384 
390  authenticate(string user, string pass = "");
391 
392 
394 
400  authenticateByIP(string ip, reference user);
401 
402 
403  private hash getAuthHeader();
404 
405 
406  private hash do401(string msg = "Authentication is required to access this server");
407 
408 
410 
419  *hash authenticateRequest(HttpListener listener, hash hdr, reference cx);
420 
421 };
422 
425 
426 public:
428 
434  *hash authenticateRequest(HttpListener listener, hash hdr, reference cx);
435 
436 };
437 
439 
447 
448 public:
449 private:
450 
451 public:
452 
453  private :
458 
459 public:
460 
462 
474  constructor(hash cx);
475 
476 
478 
488 
489 
491 
501  nothing recv(hash v);
502 
503 
505 
508  any send();
509 
510 
512 
522 
524 
534  abstract nothing recvImpl(hash v);
535 
537 
540  abstract any sendImpl();
541 };
542 
544 
553 
554 public:
555 private:
556 
557 public:
558 
559  private :
565  Socket s;
571  any body;
572 
573 public:
574 
576  constructor(HttpListener listener, AbstractHttpRequestHandler handler, Socket s, hash cx, hash hdr, any body);
577 
578 
579  hash handleRequest();
580 
581 
583 
588  private hash sendResponse();
589 
590 
592 
601  private hash getResponseHeaderMessage();
602 
603 
605 
607  private nothing recv(hash v);
608 
609 
611  private any send();
612 
613 
614  private logChunk(bool send, int size);
615 
616 
618 
630 
631 
633 
642  private nothing recvImpl(hash v);
643 
644 
646 
649  private any sendImpl();
650 
651 };
652 
654 
662 
663 public:
664  public :
667 
669  bool decompress = True;
670 
673 
675  bool stream;
676 
679 
680 public:
681 
683 
686  constructor(*AbstractAuthenticator auth, softbool stream = False);
687 
688 
690  nothing persistentClosed();
691 
692 
694  private nothing checkPersistent(hash cx, hash hdr);
695 
696 
698 
721  hash handleRequest(hash cx, hash hdr, *data body);
722 
723 
725  hash handleRequest(HttpListener listener, Socket s, hash cx, hash hdr, *data body);
726 
727 
729  private AbstractStreamRequest getStreamRequestImpl(HttpListener listener, Socket s, hash cx, hash hdr, *data body);
730 
731 
733  static data decodeBody(string ce, binary body, *string enc);
734 
736  static binary encodeBody(string ce, data body);
737 
739  *data getMessageBody(Socket s, hash hdr, *data body, bool decode = True);
740 
741 
743 
750  static *string getLogMessage(hash cx, hash api, reference params, *reference args);
751 
753 
756 
757 
759 
762 
763 
765  static hash makeResponse(int code, string fmt);
766 
768  static hash makeResponse(hash hdr, int code, string fmt);
769 
771  static hash makeResponse(int code, *data body, *hash hdr);
772 
774  static hash make400(string fmt);
775 
777  static hash make400(hash hdr, string fmt);
778 
780  static hash make501(string fmt);
781 
783  static hash make501(hash hdr, string fmt);
784 
786  static hash redirect(hash cx, hash hdr, string path);
787 };
788 
791 
792 public:
793  public :
795  string url_root;
796 
797 public:
798 
800 
803  constructor(string url_root, *AbstractAuthenticator auth);
804 
805 
807  string getRelativePath(string path);
808 
809 };
810 
812 
815 
816 public:
817  private :
819  bool stop = False;
820 
823 
826 
828  Mutex m();
829 
830 public:
831 
833 
836 
837 
839 
853  start(softstring lid, hash cx, hash hdr, Socket s);
854 
855 
857 
861  stop(softstring lid);
862 
863 
865 
867  stop();
868 
869 
871 
897  abstract hash handleRequest(hash cx, hash hdr, *data b);
898 
900 
914  private abstract startImpl(softstring lid, hash cx, hash hdr, Socket s);
915 
917 
919  private stopImpl(string lid);
920 
921 
923  private stopImpl();
924 
925 };
926 
929 
930 public:
931  public :
933  const Version = "0.3.11";
935  const ReadTimeout = 30000; // recvs timeout after 30 seconds
937  const PollTimeout = 5000; // check for exit every 5 seconds while waiting
938 
939  // logging options
940  const LP_LOGPARAMS = 1 << 16;
941  const LP_LEVELMASK = LP_LOGPARAMS - 1;
942 
945 
947  const HttpMethods = (
948  "HEAD": True,
949  "POST": True,
950  "PUT": True,
951  "DELETE": True,
952  "GET": True,
953  "OPTIONS": True,
954  //"TRACE": True,
955  //"CONNECT": True,
956  );
957 
959  const HttpCodes = (
960  // 100s: Informational
961  "100": "Continue",
962  "101": "Switching Protocols",
963 
964  // RFC 2518: WebDAV
965  "102": "Processing",
966 
967  // 200s: Success
968  "200": "OK",
969  "201": "Created",
970  "202": "Accepted",
971  "203": "Non-Authoritative Information",
972  "204": "No Content",
973  "205": "Reset Content",
974  "206": "Partial Content",
975 
976  // 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
977  "207": "Multi-Status",
978 
979  // 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
980  "208": "Already Reported",
981 
982  // RFC 3229
983  "226": "IM Used",
984 
985  // 300s: Redirection
986  "300": "Multiple Choices",
987  "301": "Moved Permanently",
988  "302": "Found",
989  "303": "See Other",
990  "304": "Not Modified",
991  "305": "Use Proxy",
992  //"306": "(Reserved)",
993  "307": "Temporary Redirect",
994 
995  // 400s: Client Errors
996  "400": "Bad Request",
997  "401": "Unauthorized",
998  "402": "Payment Required",
999  "403": "Forbidden",
1000  "404": "Not Found",
1001  "405": "Method Not Allowed",
1002  "406": "Not Acceptable",
1003  "407": "Proxy Authentication Required",
1004  "408": "Request Timeout",
1005  "409": "Conflict",
1006  "410": "Gone",
1007  "411": "Length Required",
1008  "412": "Precondition Failed",
1009  "413": "Request Entity Too Large",
1010  "414": "Request-URI Too Long",
1011  "415": "Unsupported Media Type",
1012  "416": "Requested Range Not Satisfiable",
1013  "417": "Expectation Failed",
1014 
1015  // RFC 2324: http://tools.ietf.org/html/rfc2324
1016  "418": "I'm a teapot",
1017 
1018  // Returned by the Twitter Search and Trends API when the client is being rate limited
1019  "420": "Enhance Yextern Calm",
1020 
1021  // RFC 4918: WebDAV: The request was well-formed but was unable to be followed due to semantic errors
1022  "422": "Unprocessable Entity",
1023 
1024  // RFC 4918: WebDAV: The resource that is being accessed is locked
1025  "423": "Locked",
1026 
1027  // RFC 4918: WebDAV: The request failed due to failure of a previous request (e.g. a PROPPATCH)
1028  "424": "Failed Dependency",
1029 
1030  // Internet draft: Defined in drafts of "WebDAV Advanced Collections Protocol", but not present in "Web Distributed Authoring and Versioning (WebDAV) Ordered Collections Protocol"
1031  "425": "Unordered Collection",
1032 
1033  // RFC 2817: The client should switch to a different protocol such as TLS/1.0
1034  "426": "Upgrade Required",
1035 
1036  // 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."
1037  "428": "Precondition Required",
1038 
1039  // RFC 6585: The user has sent too many requests in a given amount of time. Intended for use with rate limiting schemes
1040  "429": "Too Many Requests",
1041 
1042  // RFC 6585
1043  "431": "Request Header Fields Too Large",
1044 
1045  // 500s: Server Errors
1046  "500": "Internal Server Error",
1047  "501": "Not Implemented",
1048  "502": "Bad Gateway",
1049  "503": "Service Unavailable",
1050  "504": "Gateway Timeout",
1051  "505": "HTTP Version Not Supported",
1052  "509": "Bandwidth Limit Exceeded",
1053 
1054  // RFC 2774: Further extensions to the request are required for the server to fulfill it
1055  "510": "Not Extended",
1056 
1057  // 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)
1058  "511": "Network Authentication Required",
1059  );
1060 
1063  "gzip": "gzip",
1064  "deflate": "deflate",
1065  "bzip2": "bzip2",
1066  "x-gzip": "gzip",
1067  "x-deflate": "deflate",
1068  "x-bzip2": "bzip2",
1069  );
1070 
1073 
1075  const CompressionThreshold = 1024;
1076 
1077 public:
1078 
1080  private :
1081  *code logfunc;
1082  *code errlogfunc;
1083 
1084  // quit server flag
1085  bool exit = False;
1086 
1087  // if True then verbose exception info will be logged
1088  bool debug;
1089 
1090  Sequence seqSessions();
1091  Sequence seqListeners();
1092 
1093  bool stopped = False;
1094 
1095  // permanent handlers; these handlers are never removed
1096  HttpHandlerList handlers();
1097 
1098  // default handler
1099  hash defaultHandler;
1100 
1101  // hash of listeners keyed by listener ID
1102  hash listeners;
1103 
1104  // map of bind addresses to listener IDs
1105  hash smap;
1106 
1107  // map of listener names to listener IDs
1108  hash nmap;
1109 
1110  // listener Gate
1111  Gate lm();
1112 
1113  // running listener counter
1114  Counter c();
1115 
1116  // dynamic handlers
1117  DynamicHttpHandlerList dhandlers();
1118 
1119  // connection thread pool
1120  ThreadPool threadPool(-1, DefaultIdleThreads);
1121 
1122  // other misc response headers
1123  hash hdr;
1124 
1125  // 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
1126  *string override_encoding;
1127 
1128  static string HttpServerString;
1129 
1130 public:
1132 
1134 
1142  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));
1143 
1144 
1146  destructor();
1147 
1148 
1150  static string getHttpServerVersionString();
1151 
1152  setDefaultTextEncoding(string enc);
1153 
1154 
1155  string getDefaultTextEncoding();
1156 
1157 
1159 
1188  final list addListenersWithHandler(string hname, AbstractHttpRequestHandler handler, hash lp, *code logger, *code errorlogger, *code stopc, *string name, int family = AF_UNSPEC);
1189 
1190 
1192 
1208  hash addListener(softstring sock, *string cert_path, *string key_path, *string name, int family = AF_UNSPEC, *string pwd);
1209 
1210 
1212 
1228  softlist addListeners(softstring sock, *string cert_path, *string key_path, *string name, int family = AF_UNSPEC, *string pwd);
1229 
1230 
1232 
1247  list addINETListeners(*string node, softstring service, *string cert_path, *string key_path, *string name, int family = AF_UNSPEC, *string pwd);
1248 
1249 
1251  copy();
1252 
1253 
1255 
1257  hash getListeners();
1258 
1259 
1261 
1278  hash getListenerInfo(softint id);
1279 
1280 
1282 
1299  hash getListenerInfoName(string name);
1300 
1301 
1303  int getListenerCount();
1304 
1305 
1307 
1309  stopNoWait();
1310 
1311 
1313  waitStop();
1314 
1315 
1316  // only called from the listeners - do not call externally
1317  listenerStopped(HttpListener l);
1318 
1319 
1321 
1323  stop();
1324 
1325 
1327  stopListener(softstring bind);
1328 
1329 
1331  stopListenerID(softint id);
1332 
1333 
1335  int getListenerTID(softint id);
1336 
1337 
1340 
1341 
1343  setHandler(string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex = True);
1344 
1345 
1347  setDynamicHandler(string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex = True);
1348 
1349 
1351  setHandler(string name, AbstractUrlHandler obj);
1352 
1353 
1355  setDynamicHandler(string name, AbstractUrlHandler obj);
1356 
1357 
1359  addHandlerToListener(softstring bind, string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex = True);
1360 
1361 
1363  addHandlerToListenerID(softint id, string name, string path, *softlist content_type, AbstractHttpRequestHandler obj, *softlist special_headers, bool isregex = True);
1364 
1365 
1367  addHandlerToListener(softstring bind, string name, AbstractUrlHandler obj);
1368 
1369 
1371  addHandlerToListenerID(softint id, string name, AbstractUrlHandler obj);
1372 
1373 
1375  removeDynamicHandler(string name);
1376 
1377 
1379  log();
1380 
1381 
1383  logError();
1384 
1385 
1387  logArgs(softlist args = ());
1388 
1389 
1391  logErrorArgs(softlist args = ());
1392 
1393 
1395  sendHttpError(HttpListener listener, hash cx, Socket s, int code, string msg, *hash extra_hdrs, *string encoding);
1396 
1397 
1399 
1401  static string getURLFromBind(softstring bind, *string host);
1402 
1404  setDebug(bool dbg = True);
1405 
1406 
1408  bool getDebug();
1409 
1410 
1411  startConnection(code c);
1412 
1413 
1415  static nothing setReplyHeaders(Socket s, hash cx, reference rv);
1416 
1418  // don't reimplement this method; fix/enhance it in the module
1419  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);
1420 
1421 
1422  // don't reimplement this method; fix/enhance it in the module
1423  static final private hash getSSLObjects(string cert_path, *string key_path, *string pwd);
1424 
1425  // don't reimplement this method; fix/enhance it in the module
1426  final private list addINETListenersIntern(*string node, softstring service, *hash sd, *hash lp, *code logger, *code errorlogger, *code stopc, *string name, int family = AF_UNSPEC);
1427 
1428 
1429  // don't reimplement this method; fix/enhance it in the module
1430  final private hash noHandlerError(hash cx, hash hdr, any body);
1431 
1432 
1433  // handles an incoming request - do not call externally; this method is called by the listeners when a request is received
1434  // don't reimplement this method; fix/enhance it in the module
1435  final handleRequest(HttpListener listener, Socket s, reference cx, hash hdr, hash hh, *data body, bool head = False, HttpPersistentHandlerInfo phi);
1436 
1437 
1438  // sends a reply to a request
1439  // don't reimplement this method; fix/enhance it in the module
1440  final sendReply(HttpListener listener, Socket s, AbstractHttpRequestHandler handler, hash rv, reference cx, hash hdr, bool head);
1441 
1443 };
1444 
1445 class HttpServer::HttpPersistentHandlerInfo {
1446 
1447 public:
1448  public :
1449  *DynamicHandlerHelper dhh;
1450  *AbstractHttpRequestHandler handler;
1451 
1452 public:
1453 
1454  destructor();
1455 
1456 
1457  assign(DynamicHandlerHelper dhh, AbstractHttpRequestHandler handler);
1458 
1459 
1460  clear();
1461 
1462 };
1463 
1466 
1467 public:
1468  private :
1469  HttpServer serv;
1470  Sequence ss;
1471  *SSLCertificate cert;
1472  *SSLPrivateKey key;
1473  bool ssl = False;
1474  any socket;
1475  hash socket_info;
1476 
1477  // connection counter
1478  Counter cThreads();
1479  bool exit = False;
1480  bool stopped = False;
1481  int id;
1482 
1483  // socket handler hash
1484  hash shh;
1485 
1486  // mutex
1487  Mutex m();
1488 
1489  // code references to external logging functions
1490  *code logger;
1491  *code errorlogger;
1492 
1493  // stop notification closure
1494  *code stopc;
1495 
1496  string name;
1497 
1498  const PollInterval = 1s;
1499  const ListenQueue = 100;
1500 
1501 public:
1502 
1503  public :
1504  // TID of the background listener thread
1505  int tid;
1506 
1507  // listener-specific handlers
1508  HttpHandlerList handlers();
1509 
1510  // default handler info
1511  *HandlerInfo defaultHandler;
1512 
1513 public:
1514 
1515  // params: server, id, session ID sequence object, socket, rbac obj, [cert, key]
1516  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);
1517 
1518 
1519  addHandlers(hash hi);
1520 
1521 
1522  setDefaultHandler(string name);
1523 
1524 
1525  copy();
1526 
1527 
1528  destructor();
1529 
1530 
1531  string getName();
1532 
1533 
1534  any getAddress();
1535 
1536 
1537  int getID();
1538 
1539 
1540  bool isSecure();
1541 
1542 
1543  hash getInfo();
1544 
1545 
1546  any removeUserThreadContext(string k);
1547 
1548 
1549  addUserThreadContext(hash uctx);
1550 
1551 
1552  stopNoWait();
1553 
1554 
1555  stop();
1556 
1557 
1558  logResponse(hash cx, int code, *data body, *hash hdr);
1559 
1560 
1561  logResponse(hash cx, hash rv);
1562 
1563 
1564  log();
1565 
1566 
1567  logError();
1568 
1569 
1570  private mainThread();
1571 
1572 
1573  // thread for handling communication per connection
1574  private connectionThread(Socket s);
1575 
1576 
1577  bool registerDedicatedSocket(softstring id, AbstractHttpSocketHandler h);
1578 
1579 
1580  removeDedicatedSocket(softstring id, AbstractHttpSocketHandler h);
1581 
1582 };
*hash authenticateRequest(HttpListener listener, hash hdr, reference cx)
primary method called to authenticate each request
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
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:569
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:552
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:661
class providing automatic authentication for all requests
Definition: HttpServer.qm.dox.h:424
*AbstractAuthenticator auth
the optional AbstractAuthenticator for requests to this handler
Definition: HttpServer.qm.dox.h:666
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:935
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:822
*hash ex
if an exception is raised in a callback then the exception hash is saved here
Definition: HttpServer.qm.dox.h:457
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
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'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:678
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:1072
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:947
AbstractHttpRequestHandler handler
the request handler for the request
Definition: HttpServer.qm.dox.h:563
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:669
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:455
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:675
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:446
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:368
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:937
hash cx
the call context variable
Definition: HttpServer.qm.dox.h:567
Socket s
the Socket object for the response
Definition: HttpServer.qm.dox.h:565
private any sendImpl()
abstract callback method for sending chunked data
hash parse_uri_query(string path, bool trans=True)
parses a URI path for a arguments and a method; where the method is the part of the path before the f...
constructor(*AbstractAuthenticator auth)
create the object optionally with the given AbstractAuthenticator
nothing exit(softint rc=0)
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:1075
abstract hash getResponseHeaderMessageImpl()
this method should return the response message description hash
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
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:814
abstract class for HTTP request handlers anchored at a specific URL
Definition: HttpServer.qm.dox.h:790
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
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
const AIFlags
address info flags
Definition: HttpServer.qm.dox.h:944
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:672
copy()
throws an exception; these objects do not support copying
const Version
version of the HttpServer's implementation
Definition: HttpServer.qm.dox.h:933
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:928
authenticate(string user, string pass="")
called to authenticate a user for a connection
the main namespace for the HttpServer module
Definition: HttpServer.qm.dox.h:231
HttpListener listener
the listener servicing the request for logging purposes
Definition: HttpServer.qm.dox.h:561
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:1465
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 ...
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:795
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:959
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:825
any body
any message body given in a non-chunked request; could already be deserialized
Definition: HttpServer.qm.dox.h:571
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:1062
int getListenerTID(softint id)
gets the TID of a listener based on its listener ID