1
/* Copyright (c) 2013-2017 the Civetweb developers
2
 * Copyright (c) 2013 No Face Press, LLC
3
 *
4
 * License http://opensource.org/licenses/mit-license.php MIT License
5
 */
6

7
#ifndef _CIVETWEB_SERVER_H_
8
#define _CIVETWEB_SERVER_H_
9
#ifdef __cplusplus
10

11
#include "civetweb.h"
12
#include <map>
13
#include <stdexcept>
14
#include <string>
15
#include <vector>
16

17
// forward declaration
18
class CivetServer;
19

20
/**
21
 * Exception class for thrown exceptions within the CivetHandler object.
22
 */
23
class CIVETWEB_API CivetException : public std::runtime_error
24
{
25
  public:
26
	CivetException(const std::string &msg) : std::runtime_error(msg)
27
	{
28
	}
29
};
30

31
/**
32
 * Basic interface for a URI request handler.  Handlers implementations
33
 * must be reentrant.
34
 */
35
class CIVETWEB_API CivetHandler
36
{
37
  public:
38
	/**
39
	 * Destructor
40
	 */
41
	virtual ~CivetHandler()
42
	{
43
	}
44

45
	/**
46
	 * Callback method for GET request.
47
	 *
48
	 * @param server - the calling server
49
	 * @param conn - the connection information
50
	 * @returns true if implemented, false otherwise
51
	 */
52
	virtual bool handleGet(CivetServer *server, struct mg_connection *conn);
53

54
	/**
55
	 * Callback method for POST request.
56
	 *
57
	 * @param server - the calling server
58
	 * @param conn - the connection information
59
	 * @returns true if implemented, false otherwise
60
	 */
61
	virtual bool handlePost(CivetServer *server, struct mg_connection *conn);
62

63
	/**
64
	 * Callback method for HEAD request.
65
	 *
66
	 * @param server - the calling server
67
	 * @param conn - the connection information
68
	 * @returns true if implemented, false otherwise
69
	 */
70
	virtual bool handleHead(CivetServer *server, struct mg_connection *conn);
71

72
	/**
73
	 * Callback method for PUT request.
74
	 *
75
	 * @param server - the calling server
76
	 * @param conn - the connection information
77
	 * @returns true if implemented, false otherwise
78
	 */
79
	virtual bool handlePut(CivetServer *server, struct mg_connection *conn);
80

81
	/**
82
	 * Callback method for DELETE request.
83
	 *
84
	 * @param server - the calling server
85
	 * @param conn - the connection information
86
	 * @returns true if implemented, false otherwise
87
	 */
88
	virtual bool handleDelete(CivetServer *server, struct mg_connection *conn);
89

90
	/**
91
	 * Callback method for OPTIONS request.
92
	 *
93
	 * @param server - the calling server
94
	 * @param conn - the connection information
95
	 * @returns true if implemented, false otherwise
96
	 */
97
	virtual bool handleOptions(CivetServer *server, struct mg_connection *conn);
98

99
	/**
100
	 * Callback method for PATCH request.
101
	 *
102
	 * @param server - the calling server
103
	 * @param conn - the connection information
104
	 * @returns true if implemented, false otherwise
105
	 */
106
	virtual bool handlePatch(CivetServer *server, struct mg_connection *conn);
107
};
108

109
/**
110
 * Basic interface for a URI authorization handler.  Handler implementations
111
 * must be reentrant.
112
 */
113
class CIVETWEB_API CivetAuthHandler
114
{
115
  public:
116
	/**
117
	 * Destructor
118
	 */
119
	virtual ~CivetAuthHandler()
120
	{
121
	}
122

123
	/**
124
	 * Callback method for authorization requests. It is up the this handler
125
	 * to generate 401 responses if authorization fails.
126
	 *
127
	 * @param server - the calling server
128
	 * @param conn - the connection information
129
	 * @returns true if authorization succeeded, false otherwise
130
	 */
131
	virtual bool authorize(CivetServer *server, struct mg_connection *conn) = 0;
132
};
133

134
/**
135
 * Basic interface for a websocket handler.  Handlers implementations
136
 * must be reentrant.
137
 */
138
class CIVETWEB_API CivetWebSocketHandler
139
{
140
  public:
141
	/**
142
	 * Destructor
143
	 */
144
	virtual ~CivetWebSocketHandler()
145
	{
146
	}
147

148
	/**
149
	 * Callback method for when the client intends to establish a websocket
150
	 *connection, before websocket handshake.
151
	 *
152
	 * @param server - the calling server
153
	 * @param conn - the connection information
154
	 * @returns true to keep socket open, false to close it
155
	 */
156
	virtual bool handleConnection(CivetServer *server,
157
	                              const struct mg_connection *conn);
158

159
	/**
160
	 * Callback method for when websocket handshake is successfully completed,
161
	 *and connection is ready for data exchange.
162
	 *
163
	 * @param server - the calling server
164
	 * @param conn - the connection information
165
	 */
166
	virtual void handleReadyState(CivetServer *server,
167
	                              struct mg_connection *conn);
168

169
	/**
170
	 * Callback method for when a data frame has been received from the client.
171
	 *
172
	 * @param server - the calling server
173
	 * @param conn - the connection information
174
	 * @bits: first byte of the websocket frame, see websocket RFC at
175
	 *http://tools.ietf.org/html/rfc6455, section 5.2
176
	 * @data, data_len: payload, with mask (if any) already applied.
177
	 * @returns true to keep socket open, false to close it
178
	 */
179
	virtual bool handleData(CivetServer *server,
180
	                        struct mg_connection *conn,
181
	                        int bits,
182
	                        char *data,
183
	                        size_t data_len);
184

185
	/**
186
	 * Callback method for when the connection is closed.
187
	 *
188
	 * @param server - the calling server
189
	 * @param conn - the connection information
190
	 */
191
	virtual void handleClose(CivetServer *server,
192
	                         const struct mg_connection *conn);
193
};
194

195
/**
196
 * CivetCallbacks
197
 *
198
 * wrapper for mg_callbacks
199
 */
200
struct CIVETWEB_API CivetCallbacks : public mg_callbacks {
201
	CivetCallbacks();
202
};
203

204
/**
205
 * CivetServer
206
 *
207
 * Basic class for embedded web server.  This has an URL mapping built-in.
208
 */
209
class CIVETWEB_API CivetServer
210
{
211
  public:
212
	/**
213
	 * Constructor
214
	 *
215
	 * This automatically starts the sever.
216
	 * It is good practice to call getContext() after this in case there
217
	 * were errors starting the server.
218
	 *
219
	 * Note: CivetServer should not be used as a static instance in a Windows
220
	 * DLL, since the constructor creates threads and the destructor joins
221
	 * them again (creating/joining threads should not be done in static
222
	 * constructors).
223
	 *
224
	 * @param options - the web server options.
225
	 * @param callbacks - optional web server callback methods.
226
	 *
227
	 * @throws CivetException
228
	 */
229
	CivetServer(const char **options,
230
	            const struct CivetCallbacks *callbacks = 0,
231
	            const void *UserContext = 0);
232
	CivetServer(std::vector<std::string> options,
233
	            const struct CivetCallbacks *callbacks = 0,
234
	            const void *UserContext = 0);
235

236
	/**
237
	 * Destructor
238
	 */
239
	virtual ~CivetServer();
240

241
	/**
242
	 * close()
243
	 *
244
	 * Stops server and frees resources.
245
	 */
246
	void close();
247

248
	/**
249
	 * getContext()
250
	 *
251
	 * @return the context or 0 if not running.
252
	 */
253
	const struct mg_context *
254
	getContext() const
255
	{
256
		return context;
257
	}
258

259
	/**
260
	 * addHandler(const std::string &, CivetHandler *)
261
	 *
262
	 * Adds a URI handler.  If there is existing URI handler, it will
263
	 * be replaced with this one.
264
	 *
265
	 * URI's are ordered and prefix (REST) URI's are supported.
266
	 *
267
	 *  @param uri - URI to match.
268
	 *  @param handler - handler instance to use.
269
	 */
270
	void addHandler(const std::string &uri, CivetHandler *handler);
271

272
	void
273
	addHandler(const std::string &uri, CivetHandler &handler)
274
	{
275
		addHandler(uri, &handler);
276
	}
277

278
	/**
279
	 * addWebSocketHandler
280
	 *
281
	 * Adds a WebSocket handler for a specific URI.  If there is existing URI
282
	 *handler, it will
283
	 * be replaced with this one.
284
	 *
285
	 * URI's are ordered and prefix (REST) URI's are supported.
286
	 *
287
	 *  @param uri - URI to match.
288
	 *  @param handler - handler instance to use.
289
	 */
290
	void addWebSocketHandler(const std::string &uri,
291
	                         CivetWebSocketHandler *handler);
292

293
	void
294
	addWebSocketHandler(const std::string &uri, CivetWebSocketHandler &handler)
295
	{
296
		addWebSocketHandler(uri, &handler);
297
	}
298

299
	/**
300
	 * removeHandler(const std::string &)
301
	 *
302
	 * Removes a handler.
303
	 *
304
	 * @param uri - the exact URL used in addHandler().
305
	 */
306
	void removeHandler(const std::string &uri);
307

308
	/**
309
	 * removeWebSocketHandler(const std::string &)
310
	 *
311
	 * Removes a web socket handler.
312
	 *
313
	 * @param uri - the exact URL used in addWebSocketHandler().
314
	 */
315
	void removeWebSocketHandler(const std::string &uri);
316

317
	/**
318
	 * addAuthHandler(const std::string &, CivetAuthHandler *)
319
	 *
320
	 * Adds a URI authorization handler.  If there is existing URI authorization
321
	 * handler, it will be replaced with this one.
322
	 *
323
	 * URI's are ordered and prefix (REST) URI's are supported.
324
	 *
325
	 * @param uri - URI to match.
326
	 * @param handler - authorization handler instance to use.
327
	 */
328
	void addAuthHandler(const std::string &uri, CivetAuthHandler *handler);
329

330
	void
331
	addAuthHandler(const std::string &uri, CivetAuthHandler &handler)
332
	{
333
		addAuthHandler(uri, &handler);
334
	}
335

336
	/**
337
	 * removeAuthHandler(const std::string &)
338
	 *
339
	 * Removes an authorization handler.
340
	 *
341
	 * @param uri - the exact URL used in addAuthHandler().
342
	 */
343
	void removeAuthHandler(const std::string &uri);
344

345
	/**
346
	 * getListeningPorts()
347
	 *
348
	 * Returns a list of ports that are listening
349
	 *
350
	 * @return A vector of ports
351
	 */
352

353
	std::vector<int> getListeningPorts();
354

355
	/**
356
	 * getCookie(struct mg_connection *conn, const std::string &cookieName,
357
	 *std::string &cookieValue)
358
	 *
359
	 * Puts the cookie value string that matches the cookie name in the
360
	 *cookieValue destinaton string.
361
	 *
362
	 * @param conn - the connection information
363
	 * @param cookieName - cookie name to get the value from
364
	 * @param cookieValue - cookie value is returned using thiis reference
365
	 * @returns the size of the cookie value string read.
366
	 */
367
	static int getCookie(struct mg_connection *conn,
368
	                     const std::string &cookieName,
369
	                     std::string &cookieValue);
370

371
	/**
372
	 * getHeader(struct mg_connection *conn, const std::string &headerName)
373
	 * @param conn - the connection information
374
	 * @param headerName - header name to get the value from
375
	 * @returns a char array which contains the header value as string
376
	 */
377
	static const char *getHeader(struct mg_connection *conn,
378
	                             const std::string &headerName);
379

380
	/**
381
	 * getParam(struct mg_connection *conn, const char *, std::string &, size_t)
382
	 *
383
	 * Returns a query which contained in the supplied buffer.  The
384
	 * occurrence value is a zero-based index of a particular key name.  This
385
	 * should not be confused with the index over all of the keys.  Note that
386
	 *this
387
	 * function assumes that parameters are sent as text in http query string
388
	 * format, which is the default for web forms. This function will work for
389
	 * html forms with method="GET" and method="POST" attributes. In other
390
	 *cases,
391
	 * you may use a getParam version that directly takes the data instead of
392
	 *the
393
	 * connection as a first argument.
394
	 *
395
	 * @param conn - parameters are read from the data sent through this
396
	 *connection
397
	 * @param name - the key to search for
398
	 * @param dst - the destination string
399
	 * @param occurrence - the occurrence of the selected name in the query (0
400
	 *based).
401
	 * @return true if key was found
402
	 */
403
	static bool getParam(struct mg_connection *conn,
404
	                     const char *name,
405
	                     std::string &dst,
406
	                     size_t occurrence = 0);
407

408
	/**
409
	 * getParam(const std::string &, const char *, std::string &, size_t)
410
	 *
411
	 * Returns a query parameter contained in the supplied buffer.  The
412
	 * occurrence value is a zero-based index of a particular key name.  This
413
	 * should not be confused with the index over all of the keys.
414
	 *
415
	 * @param data - the query string (text)
416
	 * @param name - the key to search for
417
	 * @param dst - the destination string
418
	 * @param occurrence - the occurrence of the selected name in the query (0
419
	 *based).
420
	 * @return true if key was found
421
	 */
422
	static bool
423
	getParam(const std::string &data,
424
	         const char *name,
425
	         std::string &dst,
426
	         size_t occurrence = 0)
427
	{
428
		return getParam(data.c_str(), data.length(), name, dst, occurrence);
429
	}
430

431
	/**
432
	 * getParam(const char *, size_t, const char *, std::string &, size_t)
433
	 *
434
	 * Returns a query parameter contained in the supplied buffer.  The
435
	 * occurrence value is a zero-based index of a particular key name.  This
436
	 * should not be confused with the index over all of the keys.
437
	 *
438
	 * @param data the - query string (text)
439
	 * @param data_len - length of the query string
440
	 * @param name - the key to search for
441
	 * @param dst - the destination string
442
	 * @param occurrence - the occurrence of the selected name in the query (0
443
	 *based).
444
	 * @return true if key was found
445
	 */
446
	static bool getParam(const char *data,
447
	                     size_t data_len,
448
	                     const char *name,
449
	                     std::string &dst,
450
	                     size_t occurrence = 0);
451

452
	/**
453
	 * getPostData(struct mg_connection *)
454
	 *
455
	 * Returns response body from a request made as POST. Since the
456
	 * connections map is protected, it can't be directly accessed.
457
	 * This uses string to store post data to handle big posts.
458
	 *
459
	 * @param conn - connection from which post data will be read
460
	 * @return Post data (empty if not available).
461
	 */
462
	static std::string getPostData(struct mg_connection *conn);
463

464
	/**
465
	 * urlDecode(const std::string &, std::string &, bool)
466
	 *
467
	 * @param src - string to be decoded
468
	 * @param dst - destination string
469
	 * @param is_form_url_encoded - true if form url encoded
470
	 *       form-url-encoded data differs from URI encoding in a way that it
471
	 *       uses '+' as character for space, see RFC 1866 section 8.2.1
472
	 *       http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt
473
	 */
474
	static void
475
	urlDecode(const std::string &src,
476
	          std::string &dst,
477
	          bool is_form_url_encoded = true)
478
	{
479
		urlDecode(src.c_str(), src.length(), dst, is_form_url_encoded);
480
	}
481

482
	/**
483
	 * urlDecode(const char *, size_t, std::string &, bool)
484
	 *
485
	 * @param src - buffer to be decoded
486
	 * @param src_len - length of buffer to be decoded
487
	 * @param dst - destination string
488
	 * @param is_form_url_encoded - true if form url encoded
489
	 *       form-url-encoded data differs from URI encoding in a way that it
490
	 *       uses '+' as character for space, see RFC 1866 section 8.2.1
491
	 *       http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt
492
	 */
493
	static void urlDecode(const char *src,
494
	                      size_t src_len,
495
	                      std::string &dst,
496
	                      bool is_form_url_encoded = true);
497

498
	/**
499
	 * urlDecode(const char *, std::string &, bool)
500
	 *
501
	 * @param src - buffer to be decoded (0 terminated)
502
	 * @param dst - destination string
503
	 * @param is_form_url_encoded true - if form url encoded
504
	 *       form-url-encoded data differs from URI encoding in a way that it
505
	 *       uses '+' as character for space, see RFC 1866 section 8.2.1
506
	 *       http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt
507
	 */
508
	static void urlDecode(const char *src,
509
	                      std::string &dst,
510
	                      bool is_form_url_encoded = true);
511

512
	/**
513
	 * urlEncode(const std::string &, std::string &, bool)
514
	 *
515
	 * @param src - buffer to be encoded
516
	 * @param dst - destination string
517
	 * @param append - true if string should not be cleared before encoding.
518
	 */
519
	static void
520
	urlEncode(const std::string &src, std::string &dst, bool append = false)
521
	{
522
		urlEncode(src.c_str(), src.length(), dst, append);
523
	}
524

525
	/**
526
	 * urlEncode(const char *, size_t, std::string &, bool)
527
	 *
528
	 * @param src - buffer to be encoded (0 terminated)
529
	 * @param dst - destination string
530
	 * @param append - true if string should not be cleared before encoding.
531
	 */
532
	static void
533
	urlEncode(const char *src, std::string &dst, bool append = false);
534

535
	/**
536
	 * urlEncode(const char *, size_t, std::string &, bool)
537
	 *
538
	 * @param src - buffer to be encoded
539
	 * @param src_len - length of buffer to be decoded
540
	 * @param dst - destination string
541
	 * @param append - true if string should not be cleared before encoding.
542
	 */
543
	static void urlEncode(const char *src,
544
	                      size_t src_len,
545
	                      std::string &dst,
546
	                      bool append = false);
547

548
	// generic user context which can be set/read,
549
	// the server does nothing with this apart from keep it.
550
	const void *
551
	getUserContext() const
552
	{
553
		return UserContext;
554
	}
555

556
  protected:
557
	class CivetConnection
558
	{
559
	  public:
560
		char *postData;
561
		unsigned long postDataLen;
562

563
		CivetConnection();
564
		~CivetConnection();
565
	};
566

567
	struct mg_context *context;
568
	std::map<struct mg_connection *, class CivetConnection> connections;
569

570
	// generic user context which can be set/read,
571
	// the server does nothing with this apart from keep it.
572
	const void *UserContext;
573

574
  private:
575
	/**
576
	 * requestHandler(struct mg_connection *, void *cbdata)
577
	 *
578
	 * Handles the incoming request.
579
	 *
580
	 * @param conn - the connection information
581
	 * @param cbdata - pointer to the CivetHandler instance.
582
	 * @returns 0 if implemented, false otherwise
583
	 */
584
	static int requestHandler(struct mg_connection *conn, void *cbdata);
585

586
	static int webSocketConnectionHandler(const struct mg_connection *conn,
587
	                                      void *cbdata);
588
	static void webSocketReadyHandler(struct mg_connection *conn, void *cbdata);
589
	static int webSocketDataHandler(struct mg_connection *conn,
590
	                                int bits,
591
	                                char *data,
592
	                                size_t data_len,
593
	                                void *cbdata);
594
	static void webSocketCloseHandler(const struct mg_connection *conn,
595
	                                  void *cbdata);
596
	/**
597
	 * authHandler(struct mg_connection *, void *cbdata)
598
	 *
599
	 * Handles the authorization requests.
600
	 *
601
	 * @param conn - the connection information
602
	 * @param cbdata - pointer to the CivetAuthHandler instance.
603
	 * @returns 1 if authorized, 0 otherwise
604
	 */
605
	static int authHandler(struct mg_connection *conn, void *cbdata);
606

607
	/**
608
	 * closeHandler(struct mg_connection *)
609
	 *
610
	 * Handles closing a request (internal handler)
611
	 *
612
	 * @param conn - the connection information
613
	 */
614
	static void closeHandler(const struct mg_connection *conn);
615

616
	/**
617
	 * Stores the user provided close handler
618
	 */
619
	void (*userCloseHandler)(const struct mg_connection *conn);
620
};
621

622
#endif /*  __cplusplus */
623
#endif /* _CIVETWEB_SERVER_H_ */
624

625