src/httpserver.h

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