Qore RestHandler Module Reference 1.6.2
Loading...
Searching...
No Matches
RestHandler.qm.dox.h
1// -*- mode: c++; indent-tabs-mode: nil -*-
3
4/* RestHandler.qm Copyright (C) 2013 - 2024 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// minimum qore version
26
27// use new-style
28
29// require type definitions everywhere
30
31// enable all warnings
32
33
34
475namespace RestHandler {
477
485
486public:
487
488
489protected:
491 hash<auto> cx;
492
494 *hash<auto> ex;
495
497 *hash<auto> ah;
498
500 hash<auto> rhdr;
501
504
505public:
506
508
527 constructor(hash<auto> cx, *hash<auto> ah);
528
529
531
541 hash<HttpServer::HttpHandlerResponseInfo> getResponseHeaderMessage();
542
543
545
564 nothing recv(hash<auto> v);
565
566
568
573 auto send();
574
575
578
579
582
583
585 setTimeout(timeout n_timeout_ms);
586
587
590
591
593 streamError(hash<auto> n_ex);
594
595
597
606 abstract hash<auto> getResponseHeaderMessageImpl();
607
609
619 abstract nothing recvImpl(hash<auto> v);
620
622
625 abstract auto sendImpl();
626 };
627
630
631public:
632protected:
634 bool deserialized;
635
636public:
637
640 ;
641
642
645
646
647 // callback method for the response header; this calls @ref RestHandler::AbstractRestStreamRequestHandler::getResponseHeaderMessage() and returns the result
657protected:
658 hash<HttpServer::HttpHandlerResponseInfo> getResponseHeaderMessageImpl();
659public:
660
661
663
673protected:
674 nothing recvImpl(hash<auto> v);
675public:
676
677
679
682protected:
683 auto sendImpl();
684public:
685
686 };
687
690
691public:
693 hash<string, AbstractRestClass> class_hash;
694
696 const RestBasicMethodSet = map {$1: True}, RestHandler::Methods.iterator();
697
698 constructor();
699
700
702 abstract string name();
703
706
707
709
744 *AbstractRestClass subClass(string name, hash<auto> cx, *hash<auto> args);
745
746
748
780 *AbstractRestClass subClassImpl(string name, hash<auto> cx, *hash<auto> args);
781
782
784 hash<HttpServer::HttpHandlerResponseInfo> handleRequest(HttpListenerInterface listener, RestHandler rh, Socket s, *list<string> cl, string mn, hash<auto> cx, *hash<auto> args);
785
786
788protected:
789 hash<HttpServer::HttpHandlerResponseInfo> dispatchStream(HttpListenerInterface listener, RestHandler rh, Socket s, string mn, *hash<auto> ah, hash<auto> cx);
790public:
791
792
794
820protected:
821 hash<HttpServer::HttpHandlerResponseInfo> dispatch(RestHandler rh, string mn, *hash<auto> ah, hash<auto> cx);
822public:
823
824
826
855protected:
856 hash<HttpServer::HttpHandlerResponseInfo> unknownSubClassError(string cls_name, hash<auto> cx, *hash<auto> ah);
857public:
858
859
861
889protected:
890 *hash<string, bool> doGetPossibleSubClasses(hash<auto> cx, *hash<auto> ah);
891public:
892
893 };
894
896
907
908public:
910 const Err501 = ...;
911
912
914 const Methods = ...;
915
916
917protected:
920
921public:
922
924
931 ;
932
933
935
942 constructor(Logger::LoggerInterface logger, *HttpServer::AbstractAuthenticator auth, RestSchemaValidator::AbstractRestSchemaValidator validator = new NullRestSchemaValidator(logger))
943 ;
944
945
947 string name();
948
949
951 setLogger(*Logger::LoggerInterface logger);
952
953
955 *AbstractRestSchemaValidator getRestSchemaValidator();
956
957
959
983 auto handleExternalRequest(string method, string path, *hash<auto> body, hash<auto> cx = {});
984
985
987
1023 hash<HttpResponseInfo> handleRequest(HttpListenerInterface listener, Socket s, hash<auto> cx, hash<auto> hdr, *data b);
1024
1025
1027
1029protected:
1030 *hash<auto> errorResponseHeaders(hash<auto> cx);
1031public:
1032
1033
1035protected:
1036 hash<HttpHandlerResponseInfo> dispatchRequest(HttpListenerInterface listener, Socket s, *list<string> class_list, string method_name, string path, hash<auto> cx, *hash<auto> args);
1037public:
1038
1039
1041
1044protected:
1045 hash<HttpHandlerResponseInfo> returnRestException(hash<ExceptionInfo> ex);
1046public:
1047
1048
1050protected:
1051 checkExceptionSerializable(reference<hash<ExceptionInfo>> ex);
1052public:
1053
1054
1056 hash<auto> get(hash<auto> cx, *hash<auto> ah);
1057
1058
1060 removeRootPath(reference<string> path);
1061
1062
1064 requestDeserializationError(hash<auto> hdr, hash<auto> cx, string body);
1065
1066
1068 responseSerializationError(hash<auto> cx, *hash<auto> aih, hash<auto> rv);
1069
1070
1072
1074 logInfo(string fmt, ...);
1075
1076
1078
1080 logError(string fmt, ...);
1081
1082
1084
1086 logDebug(string fmt, ...);
1087
1088
1090 static hash<HttpHandlerResponseInfo> make200(string fmt, ...);
1091
1093 static hash<HttpHandlerResponseInfo> make200(hash<auto> hdr, string fmt, ...);
1094
1096 static hash<HttpHandlerResponseInfo> make400(string fmt, ...);
1097
1099 static hash<HttpHandlerResponseInfo> make400(hash<auto> hdr, string fmt, ...);
1100
1102 static hash<HttpHandlerResponseInfo> makeResponse(int code, auto body, *hash<auto> hdr);
1103
1105 static hash<HttpHandlerResponseInfo> make500(string fmt, ...);
1106
1108 static hash<HttpHandlerResponseInfo> make500(hash<auto> hdr, string fmt, ...);
1109
1111 static hash<HttpHandlerResponseInfo> make501(string fmt, ...);
1112
1114 static hash<HttpHandlerResponseInfo> make501(hash<auto> hdr, string fmt, ...);
1115 };
1116};
1117
1118// private, unexported namespace
1119namespace Priv {
1120 // dumHttpListenerInterface class
1121class DummyListenerInterface : public HttpListenerInterface {
1122
1123public:
1124 addUserThreadContext(hash<auto> uctx);
1125
1126
1127 auto removeUserThreadContext(*string k);
1128
1129
1130 log(string fmt, ...);
1131
1132
1133 logError(string fmt, ...);
1134
1135 };
1136};
AbstractHttpRequestHandler handler
HttpListenerInterface listener
the base abstract class for REST handler classes
Definition RestHandler.qm.dox.h:689
hash< HttpServer::HttpHandlerResponseInfo > unknownSubClassError(string cls_name, hash< auto > cx, *hash< auto > ah)
returns a 404 Not Found response when a request tries to access an unknown subclass
abstract string name()
this provides the name of the REST class
hash< HttpServer::HttpHandlerResponseInfo > dispatchStream(HttpListenerInterface listener, RestHandler rh, Socket s, string mn, *hash< auto > ah, hash< auto > cx)
this method is called to dispatch streamed requests on the given object
hash< HttpServer::HttpHandlerResponseInfo > handleRequest(HttpListenerInterface listener, RestHandler rh, Socket s, *list< string > cl, string mn, hash< auto > cx, *hash< auto > args)
this method is called by the RestHandler class to match the right object with incoming requests
addClass(AbstractRestClass cls)
adds a REST class to the handler
*AbstractRestClass subClassImpl(string name, hash< auto > cx, *hash< auto > args)
this method will be called to find a sub-class
*hash< string, bool > doGetPossibleSubClasses(hash< auto > cx, *hash< auto > ah)
returns a set of possible subclasses for a particular request
hash< string, AbstractRestClass > class_hash
class hash: name -> AbstractRestClass
Definition RestHandler.qm.dox.h:693
*AbstractRestClass subClass(string name, hash< auto > cx, *hash< auto > args)
this method will be called to find a sub-class
const RestBasicMethodSet
set of REST class method names based on basic HTTP methods
Definition RestHandler.qm.dox.h:696
hash< HttpServer::HttpHandlerResponseInfo > dispatch(RestHandler rh, string mn, *hash< auto > ah, hash< auto > cx)
this method is called to dispatch requests on the given object
the base abstract class for REST stream request handlers
Definition RestHandler.qm.dox.h:484
hash< auto > rhdr
headers to add in the response
Definition RestHandler.qm.dox.h:500
auto send()
this method provides the callback method for sending chunked data by calling sendImpl()
abstract auto sendImpl()
abstract callback method for sending chunked data
hash< auto > cx
call context hash
Definition RestHandler.qm.dox.h:491
nothing recv(hash< auto > v)
this method provides the callback method for receiving chunked data by calling recvImpl()
*int getTimeout()
returns the timeout in milliseconds or NOTHING if no timeout is set
*hash< auto > ah
call argument hash
Definition RestHandler.qm.dox.h:497
hash< HttpServer::HttpHandlerResponseInfo > getResponseHeaderMessage()
this method returns the response message description hash by calling getResponseHeaderMessageImpl()
bool isPersistent()
returns True if the connection is persistent; this method in the base class returns False by default
abstract hash< auto > getResponseHeaderMessageImpl()
this method should return the response message description hash
*int timeout_ms
socket I/O timeout in milliseconds
Definition RestHandler.qm.dox.h:503
setTimeout(timeout n_timeout_ms)
sets the internal socket I/O timeout value in ms
constructor(hash< auto > cx, *hash< auto > ah)
creates the object with the given arguments
streamError(hash< auto > n_ex)
registers stream errors in the send operation with the stream handler if no error is already present
*hash< auto > ex
if an exception is raised in a callback then the exception hash is saved here
Definition RestHandler.qm.dox.h:494
*code getPersistentClosedNotification()
returns a callable value in case a persistent connection is in progress; NOTHING if not; this method ...
abstract nothing recvImpl(hash< auto > v)
abstract callback method for receiving chunked data
auto handleExternalRequest(string method, string path, *hash< auto > body, hash< auto > cx={})
processes REST API calls outside the HTTP server
logError(string fmt,...)
This method is called with error log messages.
responseSerializationError(hash< auto > cx, *hash< auto > aih, hash< auto > rv)
default implementation is empty
static hash< HttpHandlerResponseInfo > make500(hash< auto > hdr, string fmt,...)
creates a hash for an HTTP 500 error response with the response message body as a string
setLogger(*Logger::LoggerInterface logger)
Sets a new logger.
const Methods
supported HTTP methods
Definition RestHandler.qm.dox.h:914
RestSchemaValidator::AbstractRestSchemaValidator validator
REST schema validator.
Definition RestHandler.qm.dox.h:919
removeRootPath(reference< string > path)
default implementation is empty
hash< HttpResponseInfo > handleRequest(HttpListenerInterface listener, Socket s, hash< auto > cx, hash< auto > hdr, *data b)
called by the HTTP server to handle incoming HTTP requests
logInfo(string fmt,...)
This method is called with informational log messages.
hash< HttpHandlerResponseInfo > dispatchRequest(HttpListenerInterface listener, Socket s, *list< string > class_list, string method_name, string path, hash< auto > cx, *hash< auto > args)
Dispatches the request and returns the response.
*AbstractRestSchemaValidator getRestSchemaValidator()
Returns any REST schema validator set for the handler.
static hash< HttpHandlerResponseInfo > make501(string fmt,...)
creates a hash for an HTTP 501 error response with the response message body as a string
checkExceptionSerializable(reference< hash< ExceptionInfo > > ex)
Recursively ensure that exception arguments are serializable.
static hash< HttpHandlerResponseInfo > make500(string fmt,...)
creates a hash for an HTTP 500 error response with the response message body as a string
static hash< HttpHandlerResponseInfo > make400(string fmt,...)
creates a hash for an HTTP 400 error response with the response message body as a string
static hash< HttpHandlerResponseInfo > makeResponse(int code, auto body, *hash< auto > hdr)
creates a hash for an HTTP response with the response code and a literal response message body
logDebug(string fmt,...)
This method is called with debug log messages.
hash< HttpHandlerResponseInfo > returnRestException(hash< ExceptionInfo > ex)
method that determines how exceptions handling REST requests are returned
constructor(Logger::LoggerInterface logger, *HttpServer::AbstractAuthenticator auth, RestSchemaValidator::AbstractRestSchemaValidator validator=new NullRestSchemaValidator(logger))
create the object optionally with the given Logger and authenticator
constructor(*HttpServer::AbstractAuthenticator auth, RestSchemaValidator::AbstractRestSchemaValidator validator=new NullRestSchemaValidator())
create the object optionally with the given HttpServer::AbstractAuthenticator
static hash< HttpHandlerResponseInfo > make501(hash< auto > hdr, string fmt,...)
creates a hash for an HTTP 501 error response with the response message body as a string
string name()
returns the name of the root REST class
*hash< auto > errorResponseHeaders(hash< auto > cx)
Retrieves headers for an error response.
static hash< HttpHandlerResponseInfo > make400(hash< auto > hdr, string fmt,...)
creates a hash for an HTTP 400 error response with the response message body as a string
static hash< HttpHandlerResponseInfo > make200(string fmt,...)
creates a hash for an HTTP 200 OK error response with the response message body as a string
hash< auto > get(hash< auto > cx, *hash< auto > ah)
default get handler for the base handler class
requestDeserializationError(hash< auto > hdr, hash< auto > cx, string body)
default implementation is empty
static hash< HttpHandlerResponseInfo > make200(hash< auto > hdr, string fmt,...)
creates a hash for an HTTP 200 OK error response with the response message body as a string
the base class for handling HTTP chunked requests and responses within the RestHandler infrastructure
Definition RestHandler.qm.dox.h:629
nothing recvImpl(hash< auto > v)
callback method for receiving chunked data; this calls RestHandler::AbstractRestStreamRequestHandler:...
hash< HttpServer::HttpHandlerResponseInfo > getResponseHeaderMessageImpl()
destructor()
destroys the object and updates the request handler about the status of the persistent connection
constructor(RestHandler::AbstractRestStreamRequestHandler n_stream, HttpServer::HttpListenerInterface listener, HttpServer::AbstractHttpRequestHandler handler, Socket s, hash< auto > cx, hash< auto > hdr, auto body)
creates the object with the given attributes
auto sendImpl()
callback method for sending chunked data; this calls RestHandler::AbstractRestStreamRequestHandler::s...
the RestHandler namespace contains all the objects in the RestHandler module
Definition RestHandler.qm.dox.h:475