src/httpserver.h

   1 // Copyright (c) 2015-2016 The Bitcoin Core developers
   2 // Distributed under the MIT software license, see the accompanying
   3 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
   4
   5 #ifndef BITCOIN_HTTPSERVER_H
   6 #define BITCOIN_HTTPSERVER_H
   7
   8 #include <string>
   9 #include <stdint.h>
  10 #include <functional>
  11
  12 static const int DEFAULT_HTTP_THREADS=4;
  13 static const int DEFAULT_HTTP_WORKQUEUE=16;
  14 static const int DEFAULT_HTTP_SERVER_TIMEOUT=30;
  15
  16 struct evhttp_request;
  17 struct event_base;
  18 class CService;
  19 class HTTPRequest;
  20
  21 /** Initialize HTTP server.
  22  * Call this before RegisterHTTPHandler or EventBase().
  23  */
  24 bool InitHTTPServer();
  25 /** Start HTTP server.
  26  * This is separate from InitHTTPServer to give users race-condition-free time
  27  * to register their handlers between InitHTTPServer and StartHTTPServer.
  28  */
  29 bool StartHTTPServer();
  30 /** Interrupt HTTP server threads */
  31 void InterruptHTTPServer();
  32 /** Stop HTTP server */
  33 void StopHTTPServer();
  34
  35 /** Change logging level for libevent. Removes BCLog::LIBEVENT from logCategories if
  36  * libevent doesn't support debug logging.*/
  37 bool UpdateHTTPServerLogging(bool enable);
  38
  39 /** Handler for requests to a certain HTTP path */
  40 typedef std::function<bool(HTTPRequest* req, const std::string &)> HTTPRequestHandler;
  41 /** Register handler for prefix.
  42  * If multiple handlers match a prefix, the first-registered one will
  43  * be invoked.
  44  */
  45 void RegisterHTTPHandler(const std::string &prefix, bool exactMatch, const HTTPRequestHandler &handler);
  46 /** Unregister handler for prefix */
  47 void UnregisterHTTPHandler(const std::string &prefix, bool exactMatch);
  48
  49 /** Return evhttp event base. This can be used by submodules to
  50  * queue timers or custom events.
  51  */
  52 struct event_base* EventBase();
  53
  54 /** In-flight HTTP request.
  55  * Thin C++ wrapper around evhttp_request.
  56  */
  57 class HTTPRequest
  58 {
  59 private:
  60     struct evhttp_request* req;
  61     bool replySent;
  62
  63 public:
  64     HTTPRequest(struct evhttp_request* req);
  65     ~HTTPRequest();
  66
  67     enum RequestMethod {
  68         UNKNOWN,
  69         GET,
  70         POST,
  71         HEAD,
  72         PUT
  73     };
  74
  75     /** Get requested URI.
  76      */
  77     std::string GetURI();
  78
  79     /** Get CService (address:ip) for the origin of the http request.
  80      */
  81     CService GetPeer();
  82
  83     /** Get request method.
  84      */
  85     RequestMethod GetRequestMethod();
  86
  87     /**
  88      * Get the request header specified by hdr, or an empty string.
  89      * Return a pair (isPresent,string).
  90      */
  91     std::pair<bool, std::string> GetHeader(const std::string& hdr);
  92
  93     /**
  94      * Read request body.
  95      *
  96      * @note As this consumes the underlying buffer, call this only once.
  97      * Repeated calls will return an empty string.
  98      */
  99     std::string ReadBody();
 100
 101     /**
 102      * Write output header.
 103      *
 104      * @note call this before calling WriteErrorReply or Reply.
 105      */
 106     void WriteHeader(const std::string& hdr, const std::string& value);
 107
 108     /**
 109      * Write HTTP reply.
 110      * nStatus is the HTTP status code to send.
 111      * strReply is the body of the reply. Keep it empty to send a standard message.
 112      *
 113      * @note Can be called only once. As this will give the request back to the
 114      * main thread, do not call any other HTTPRequest methods after calling this.
 115      */
 116     void WriteReply(int nStatus, const std::string& strReply = "");
 117 };
 118
 119 /** Event handler closure.
 120  */
 121 class HTTPClosure
 122 {
 123 public:
 124     virtual void operator()() = 0;
 125     virtual ~HTTPClosure() {}
 126 };
 127
 128 /** Event class. This can be used either as a cross-thread trigger or as a timer.
 129  */
 130 class HTTPEvent
 131 {
 132 public:
 133     /** Create a new event.
 134      * deleteWhenTriggered deletes this event object after the event is triggered (and the handler called)
 135      * handler is the handler to call when the event is triggered.
 136      */
 137     HTTPEvent(struct event_base* base, bool deleteWhenTriggered, const std::function<void(void)>& handler);
 138     ~HTTPEvent();
 139
 140     /** Trigger the event. If tv is 0, trigger it immediately. Otherwise trigger it after
 141      * the given time has elapsed.
 142      */
 143     void trigger(struct timeval* tv);
 144
 145     bool deleteWhenTriggered;
 146     std::function<void(void)> handler;
 147 private:
 148     struct event* ev;
 149 };
 150
 151 #endif // BITCOIN_HTTPSERVER_H