Qore HttpServerUtil Module Reference  0.3.12
HttpServerUtil.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
2 // @file HttpServerUtil.qm HTTP server base code
3 
4 /* HttpServerUtil.qm Copyright (C) 2014 - 2017 Qore Technologies, s.r.o.
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 
83 
88 namespace HttpServer {
90  const HttpServerVersion = "0.3.11.1";
91 
93  const HttpServerString = sprintf("Qore-HTTP-Server/%s", HttpServerVersion);
94 
96  const DefaultTimeout = 30s; // recvs timeout after 30 seconds
97 
100 
102  const HttpCodes = (
103  // 100s: Informational
104  "100": "Continue",
105  "101": "Switching Protocols",
106 
107  // RFC 2518: WebDAV
108  "102": "Processing",
109 
110  // 200s: Success
111  "200": "OK",
112  "201": "Created",
113  "202": "Accepted",
114  "203": "Non-Authoritative Information",
115  "204": "No Content",
116  "205": "Reset Content",
117  "206": "Partial Content",
118 
119  // 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
120  "207": "Multi-Status",
121 
122  // 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
123  "208": "Already Reported",
124 
125  // RFC 3229
126  "226": "IM Used",
127 
128  // 300s: Redirection
129  "300": "Multiple Choices",
130  "301": "Moved Permanently",
131  "302": "Found",
132  "303": "See Other",
133  "304": "Not Modified",
134  "305": "Use Proxy",
135  //"306": "(Reserved)",
136  "307": "Temporary Redirect",
137 
138  // 400s: Client Errors
139  "400": "Bad Request",
140  "401": "Unauthorized",
141  "402": "Payment Required",
142  "403": "Forbidden",
143  "404": "Not Found",
144  "405": "Method Not Allowed",
145  "406": "Not Acceptable",
146  "407": "Proxy Authentication Required",
147  "408": "Request Timeout",
148  "409": "Conflict",
149  "410": "Gone",
150  "411": "Length Required",
151  "412": "Precondition Failed",
152  "413": "Request Entity Too Large",
153  "414": "Request-URI Too Long",
154  "415": "Unsupported Media Type",
155  "416": "Requested Range Not Satisfiable",
156  "417": "Expectation Failed",
157 
158  // RFC 2324: http://tools.ietf.org/html/rfc2324
159  "418": "I'm a teapot",
160 
161  // Returned by the Twitter Search and Trends API when the client is being rate limited
162  "420": "Enhance Yextern Calm",
163 
164  // RFC 4918: WebDAV: The request was well-formed but was unable to be followed due to semantic errors
165  "422": "Unprocessable Entity",
166 
167  // RFC 4918: WebDAV: The resource that is being accessed is locked
168  "423": "Locked",
169 
170  // RFC 4918: WebDAV: The request failed due to failure of a previous request (e.g. a PROPPATCH)
171  "424": "Failed Dependency",
172 
173  // Internet draft: Defined in drafts of "WebDAV Advanced Collections Protocol", but not present in "Web Distributed Authoring and Versioning (WebDAV) Ordered Collections Protocol"
174  "425": "Unordered Collection",
175 
176  // RFC 2817: The client should switch to a different protocol such as TLS/1.0
177  "426": "Upgrade Required",
178 
179  // 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."
180  "428": "Precondition Required",
181 
182  // RFC 6585: The user has sent too many requests in a given amount of time. Intended for use with rate limiting schemes
183  "429": "Too Many Requests",
184 
185  // RFC 6585
186  "431": "Request Header Fields Too Large",
187 
188  // 500s: Server Errors
189  "500": "Internal Server Error",
190  "501": "Not Implemented",
191  "502": "Bad Gateway",
192  "503": "Service Unavailable",
193  "504": "Gateway Timeout",
194  "505": "HTTP Version Not Supported",
195  "509": "Bandwidth Limit Exceeded",
196 
197  // RFC 2774: Further extensions to the request are required for the server to fulfill it
198  "510": "Not Extended",
199 
200  // 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)
201  "511": "Network Authentication Required",
202  );
203 
207  const LP_LOGPARAMS = 1 << 16;
209 
213 
215  public struct HttpResponseInfo {
217  int code;
218 
220  *data body;
221 
223  softbool close = False;
224 
227 
230 
232  string log;
233 
235  string errlog;
236  };
237 
239  public struct HttpHandlerResponseInfo {
241  int code;
242 
244  auto body;
245 
247  softbool close = False;
248 
251 
254 
256  string log;
257 
259  string errlog;
260  };
261 
263 
266  string http_get_url_from_bind(softstring bind, *string host);
267 
268 
270 
280  hash<Util::UriQueryInfo> parse_uri_query(string path);
281 
282 
284  nothing http_set_reply_headers(Socket s, hash cx, reference rv, *string server_string);
285 
286 
288 
299  string http_mask_data(string msg);
300 
301 };
302 
305 
306 public:
308 
310  abstract log(string fmt);
311 
313 
315  abstract logError(string fmt);
316 
318 
320  logArgs(*softlist args);
321 
322 
324 
326  logErrorArgs(*softlist args);
327 
328 };
329 
332 
333 public:
335 
337  abstract addUserThreadContext(hash uctx);
338 
340 
342  abstract auto removeUserThreadContext(*string k);
343 };
344 
346 
349 
350 public:
352 
354  bool requiresAuthentication();
355 
356 
358 
360  string getRealm();
361 
362 
364 
370  authenticate(string user, string pass = "");
371 
372 
374 
380  authenticateByIP(string ip, reference<string> user);
381 
382 
383 
384 private:
385  hash getAuthHeader();
386 public:
387 
388 
390 
391 private:
392  hash<HttpResponseInfo> do401(string msg = "Authentication is required to access this server");
393 public:
394 
395 
397 
415  *hash<HttpResponseInfo> authenticateRequest(HttpListenerInterface listener, hash hdr, reference<hash> cx);
416 
417 };
418 
421 
422 public:
424 
439  *hash<HttpResponseInfo> authenticateRequest(HttpListenerInterface listener, hash hdr, reference<hash> cx);
440 
441 };
442 
444 
453 
454 public:
455 private:
456 
457 public:
458 
459  private :
465  Socket s;
471  auto body;
473  timeout timeout_ms = HttpServer::DefaultTimeout;
474 
475 public:
476 
478 
488  constructor(HttpListenerInterface n_listener, AbstractHttpRequestHandler n_handler, Socket n_s, hash n_cx, hash n_hdr, auto n_body);
489 
490 
492  hash<HttpHandlerResponseInfo> handleRequest();
493 
494 
496 
502 private:
503  hash<HttpHandlerResponseInfo> sendResponse();
504 public:
505 
506 
508 
518 private:
519  hash<HttpHandlerResponseInfo> getResponseHeaderMessage();
520 public:
521 
522 
524 
527 private:
528  nothing recv(hash v);
529 public:
530 
531 
533 
534 private:
535  auto send();
536 public:
537 
538 
540 
550 private:
551  logChunk(bool send, int size);
552 public:
553 
554 
556 
568 private:
569  hash<HttpResponseInfo> getResponseHeaderMessageImpl();
570 public:
571 
572 
574 
584 private:
585  nothing recvImpl(hash v);
586 public:
587 
588 
590 
594 private:
595  auto sendImpl();
596 public:
597 
598 };
599 
601 
609 
610 public:
611  public :
614 
616  bool decompress = True;
617 
619  bool decompress_to_string = True;
620 
622  bool stream;
623 
625  timeout timeout_ms = HttpServer::DefaultTimeout;
626 
628  const NotificationThreadKey = "_AHRH_pc";
629 
631  const PersistenceThreadKey = "_AHRH_p";
632 
633 public:
634 
636 
639  constructor(*AbstractAuthenticator n_auth, softbool n_stream = False);
640 
641 
643  bool isPersistent();
644 
645 
647  setPersistent(bool p = True);
648 
649 
651  notifyClosed(*code c);
652 
653 
655 
659  string maskData(string msg);
660 
661 
663  static staticNotificationCleanup();
664 
666  static staticPersistenceCleanup();
667 
669  nothing persistentClosed();
670 
671 
673 
674 private:
675  nothing checkPersistent(hash cx, hash hdr);
676 public:
677 
678 
680 
705  hash<HttpResponseInfo> handleRequest(hash cx, hash hdr, *data body);
706 
707 
709  hash<HttpResponseInfo> handleRequest(HttpListenerInterface listener, Socket s, hash cx, hash hdr, *data body);
710 
711 
713 
714 private:
715  AbstractStreamRequest getStreamRequestImpl(HttpListenerInterface listener, Socket s, hash cx, hash hdr, *data body);
716 public:
717 
718 
720  static data decodeBody(string ce, binary body, *string enc);
721 
723  static binary encodeBody(string ce, data body);
724 
726  *data getMessageBody(Socket s, hash hdr, *data body, bool decode = True);
727 
728 
730 
746  static *string getLogMessage(hash cx, hash api, reference params, *reference<string> args);
747 
749 
751  *hash saveThreadLocalData();
752 
753 
755 
757  restoreThreadLocalData(*hash data);
758 
759 
761  static hash<HttpResponseInfo> makeResponse(int code, string fmt);
762 
764  static hash<HttpResponseInfo> makeResponse(hash hdr, int code, string fmt);
765 
767  static hash<HttpResponseInfo> makeResponse(int code, *data body, *hash hdr);
768 
770  static hash<HttpResponseInfo> make400(string fmt);
771 
773  static hash<HttpResponseInfo> make400(hash hdr, string fmt);
774 
776  static hash<HttpResponseInfo> make501(string fmt);
777 
779  static hash<HttpResponseInfo> make501(hash hdr, string fmt);
780 
782  static hash<HttpResponseInfo> redirect(hash cx, hash hdr, string path);
783 };
784 
787 
788 public:
789  public :
791  string url_root;
792 
793 public:
794 
796 
799  constructor(string n_url_root, *AbstractAuthenticator auth) ;
800 
801 
803  string getRelativePath(string path);
804 
805 };
806 
808 
811 
812 public:
813  private :
815  bool stop = False;
816 
819 
822 
824  Mutex m();
825 
826 public:
827 
829 
831  constructor(*AbstractAuthenticator auth) ;
832 
833 
835 
851  start(softstring lid, hash cx, hash hdr, Socket s);
852 
853 
855 
859  stop(softstring lid);
860 
861 
863 
865  stop();
866 
867 
869 
897  abstract hash handleRequest(hash cx, hash hdr, *data b);
898 
900 
917 private:
918  abstract startImpl(softstring lid, hash cx, hash hdr, Socket s);
919 public:
920 
922 
925 private:
926  stopImpl(string lid);
927 public:
928 
929 
931 
932 private:
933  stopImpl();
934 public:
935 
936 };
softbool close
set this key to True if the connection should be unconditionally closed when the handler returns ...
Definition: HttpServerUtil.qm.dox.h:223
bool reply_sent
this key can be set to True if the reply has already been sent (by a chunked callback for example) ...
Definition: HttpServerUtil.qm.dox.h:229
string sprintf(string fmt,...)
hash hdr
a hash of request headers
Definition: HttpServerUtil.qm.dox.h:469
const ReadTimeout
read timeout in ms
Definition: HttpServerUtil.qm.dox.h:99
const HttpCodes
map of HTTP result codes and text messages
Definition: HttpServerUtil.qm.dox.h:102
abstract class for streaming HTTP chunked requests/responses
Definition: HttpServerUtil.qm.dox.h:452
const LP_LOGPARAMS
bit for logging argument
Definition: HttpServerUtil.qm.dox.h:208
abstract class that all HTTP request handler objects must inherit from
Definition: HttpServerUtil.qm.dox.h:608
class providing automatic authentication for all requests
Definition: HttpServerUtil.qm.dox.h:420
*AbstractAuthenticator auth
the optional AbstractAuthenticator for requests to this handler
Definition: HttpServerUtil.qm.dox.h:613
hash lh
hash of listener references; this is to stop all connections associated with a particular listener ...
Definition: HttpServerUtil.qm.dox.h:818
*hash hdr
set this key to a hash of extra header information to be returned with the response ...
Definition: HttpServerUtil.qm.dox.h:226
const True
this abstract class defines the public interface of the private HttpListener class defined in the Htt...
Definition: HttpServerUtil.qm.dox.h:331
string http_mask_data(string msg)
this function can be used to mask data in log messages
AbstractHttpRequestHandler handler
the request handler for the request
Definition: HttpServerUtil.qm.dox.h:463
string errlog
a string can be returned here which will be logged in the HTTP server&#39;s error log file (if any) ...
Definition: HttpServerUtil.qm.dox.h:235
binary binary()
bool stream
if the handler supports streaming requests/responses with chunked data
Definition: HttpServerUtil.qm.dox.h:622
string errlog
a string can be returned here which will be logged in the HTTP server&#39;s error log file (if any) ...
Definition: HttpServerUtil.qm.dox.h:259
const False
string http_get_url_from_bind(softstring bind, *string host)
returns a complete URL from a bind address
abstract base class for external authentication
Definition: HttpServerUtil.qm.dox.h:348
hash cx
the call context variable
Definition: HttpServerUtil.qm.dox.h:467
Socket s
the Socket object for the response
Definition: HttpServerUtil.qm.dox.h:465
const HttpServerVersion
version of the HttpServer&#39;s implementation
Definition: HttpServerUtil.qm.dox.h:90
*data body
the message body to return in the response; if this key is returned, then the reply is sent immediate...
Definition: HttpServerUtil.qm.dox.h:220
*hash hdr
set this key to a hash of extra header information to be returned with the response ...
Definition: HttpServerUtil.qm.dox.h:250
HttpListenerInterface listener
an HttpListenerInterface object for the listener serving the request for logging purposes ...
Definition: HttpServerUtil.qm.dox.h:461
this abstract class defines the interface for classes that provide logging methods ...
Definition: HttpServerUtil.qm.dox.h:304
auto body
any message body given in a non-chunked request; could already be deserialized
Definition: HttpServerUtil.qm.dox.h:471
int code
the HTTP return code (see HttpServer::HttpCodes for possible values)
Definition: HttpServerUtil.qm.dox.h:241
const DefaultTimeout
default timeout in ms
Definition: HttpServerUtil.qm.dox.h:96
string log
a string can be returned here which will be logged in the HTTP server&#39;s log file (if any) ...
Definition: HttpServerUtil.qm.dox.h:256
int code
the HTTP return code (see HttpServer::HttpCodes for possible values)
Definition: HttpServerUtil.qm.dox.h:217
abstract class that all HTTP dedicated socket handler objects must inherit from
Definition: HttpServerUtil.qm.dox.h:810
abstract class for HTTP request handlers anchored at a specific URL
Definition: HttpServerUtil.qm.dox.h:786
the return value of HTTP handler methods with potentially unserialized message bodies ...
Definition: HttpServerUtil.qm.dox.h:239
hash< Util::UriQueryInfo > 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...
const LP_LEVELMASK
mask for the log level
Definition: HttpServerUtil.qm.dox.h:211
const HttpServerString
default HTTP server string
Definition: HttpServerUtil.qm.dox.h:93
the main namespace for the HttpServer and HttpServerUtil modules
Definition: HttpServerUtil.qm.dox.h:88
the return value of HTTP handler methods where any message body has been serialized for sending over ...
Definition: HttpServerUtil.qm.dox.h:215
nothing http_set_reply_headers(Socket s, hash cx, reference rv, *string server_string)
helper function for setting HTTP response headers
hash hash(object obj)
string url_root
root part of URL for matching requests
Definition: HttpServerUtil.qm.dox.h:791
auto body
the message body to return in the response; for higher-level handlers this can be any data type that ...
Definition: HttpServerUtil.qm.dox.h:244
hash lsh
hash of listener stop flags
Definition: HttpServerUtil.qm.dox.h:821
string log
a string can be returned here which will be logged in the HTTP server&#39;s log file (if any) ...
Definition: HttpServerUtil.qm.dox.h:232