You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+40-25Lines changed: 40 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -120,7 +120,7 @@ Here are listed the libhttpserver specific options (the canonical configure opti
120
120
121
121
## Getting Started
122
122
The most basic example of creating a server and handling a requests for the path `/hello`:
123
-
123
+
```cpp
124
124
#include<httpserver.hpp>
125
125
126
126
usingnamespacehttpserver;
@@ -141,7 +141,7 @@ The most basic example of creating a server and handling a requests for the path
141
141
142
142
return 0;
143
143
}
144
-
144
+
```
145
145
To test the above example, you could run the following command from a terminal:
146
146
147
147
curl -XGET -v http://localhost:8080/hello
@@ -166,9 +166,9 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
166
166
167
167
## Create and work with a webserver
168
168
As you can see from the example above, creating a webserver with standard configuration is quite simple:
169
-
169
+
```cpp
170
170
webserver ws = create_webserver(8080);
171
-
171
+
```
172
172
The `create_webserver` class is a supporting _builder_ class that eases the building of a webserver through chained syntax.
173
173
174
174
### Basic Startup Options
@@ -214,6 +214,7 @@ In all these 3 cases libhttpserver would provide a standard HTTP response to the
214
214
*_.internal_error_resource(**const shared_ptr<http_response>(*render_ptr)(const http_request&)** resource):_ Specifies a function to handle a request that is causing an uncaught exception during its execution. **REMEMBER:** is this callback is causing an exception itself, the standard default response from libhttpserver will be reported to the HTTP client.
215
215
216
216
#### Example of custom errors:
217
+
```cpp
217
218
#include<httpserver.hpp>
218
219
219
220
usingnamespacehttpserver;
@@ -246,7 +247,7 @@ In all these 3 cases libhttpserver would provide a standard HTTP response to the
246
247
247
248
return 0;
248
249
}
249
-
250
+
```
250
251
To test the above example, you can run the following command from a terminal:
251
252
252
253
curl -XGET -v http://localhost:8080/hello
@@ -262,6 +263,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
262
263
* _.log_error(**void(*log_error_ptr)(const std::string&)** functor):_ Specifies a function used to log errors generating from the server.
263
264
264
265
#### Example of custom logging callback
266
+
```cpp
265
267
#include <httpserver.hpp>
266
268
#include <iostream>
267
269
@@ -288,7 +290,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
288
290
289
291
return 0;
290
292
}
291
-
293
+
```
292
294
To test the above example, you can run the following command from a terminal:
293
295
294
296
curl -XGET -v http://localhost:8080/hello
@@ -312,6 +314,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
312
314
*_.https_priorities(**const std::string&** priority_string):_ SSL/TLS protocol version and ciphers. Must be followed by a string specifying the SSL/TLS protocol versions and ciphers that are acceptable for the application. The string is passed unchanged to gnutls_priority_init. If this option is not specified, `"NORMAL"` is used.
313
315
314
316
#### Minimal example using HTTPS
317
+
```cpp
315
318
#include<httpserver.hpp>
316
319
317
320
usingnamespacehttpserver;
@@ -335,7 +338,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
335
338
336
339
return 0;
337
340
}
338
-
341
+
```
339
342
To test the above example, you can run the following command from a terminal:
340
343
341
344
curl -XGET -v -k 'https://localhost:8080/hello'
@@ -355,10 +358,10 @@ You should calculate the value of NC_SIZE based on the number of connections per
355
358
*_.digest_auth_random(**const std::string&** nonce_seed):_ Digest Authentication nonce’s seed. For security, you SHOULD provide a fresh random nonce when actually using Digest Authentication with libhttpserver in production.
356
359
357
360
### Examples of chaining syntax to create a webserver
358
-
361
+
```cpp
359
362
webserver ws = create_webserver(8080)
360
-
.no_ssl()
361
-
.no_ipv6()
363
+
.no_ssl()
364
+
.no_ipv6()
362
365
.no_debug()
363
366
.no_pedantic()
364
367
.no_basic_auth()
@@ -367,12 +370,14 @@ You should calculate the value of NC_SIZE based on the number of connections per
367
370
.no_regex_checking()
368
371
.no_ban_system()
369
372
.no_post_process();
373
+
```
370
374
##
375
+
```cpp
371
376
webserver ws = create_webserver(8080)
372
377
.use_ssl()
373
378
.https_mem_key("key.pem")
374
379
.https_mem_cert("cert.pem");
375
-
380
+
```
376
381
### Starting and stopping a webserver
377
382
Once a webserver is created, you can manage its execution through the following methods on the `webserver` class:
378
383
*_**void** webserver::start(**bool** blocking):_ Allows to start a server. If the `blocking` flag is passed as `true`, it will block the execution of the current thread until a call to stop on the same webserver object is performed.
@@ -397,6 +402,7 @@ Given this, the `http_resource` class contains the following extensible methods
397
402
*_**const std::shared_ptr<http_response>** http_resource::render(**const http_request&** req):_ Invoked as a backup method if the matching method is not implemented. It can be used whenever you want all the invocations on a URL to activate the same behavior regardless of the HTTP method requested. The default implementation of the `render` method returns an empty response with a `404`.
398
403
399
404
#### Example of implementation of render methods
405
+
```cpp
400
406
#include<httpserver.hpp>
401
407
402
408
usingnamespacehttpserver;
@@ -421,7 +427,7 @@ Given this, the `http_resource` class contains the following extensible methods
421
427
422
428
return 0;
423
429
}
424
-
430
+
```
425
431
To test the above example, you can run the following commands from a terminal:
426
432
* `curl -XGET -v http://localhost:8080/hello`: will return `GET: Hello, World!`.
427
433
* `curl -XPOST -v http://localhost:8080/hello`: will return `OTHER: Hello, World!`. You can try requesting other methods beside `POST` to verify how the same message will be returned.
@@ -436,6 +442,7 @@ The base `http_resource` class has a set of methods that can be used to allow an
436
442
* _**void** http_resource::disallow_all():_ Marks all HTTP methods as not allowed.
437
443
438
444
#### Example of methods allowed/disallowed
445
+
```cpp
439
446
#include <httpserver.hpp>
440
447
441
448
using namespace httpserver;
@@ -458,7 +465,7 @@ The base `http_resource` class has a set of methods that can be used to allow an
458
465
459
466
return 0;
460
467
}
461
-
468
+
```
462
469
To test the above example, you can run the following command from a terminal:
463
470
464
471
curl -XGET -v http://localhost:8080/hello
@@ -482,7 +489,7 @@ There are essentially four ways to specify an endpoint string:
482
489
***A parametrized path. (e.g. `"/path/to/resource/with/{arg1}/{arg2}/in/url"`)**. In this case, the webserver will match the argument with any value passed. In addition to this, the arguments will be passed to the resource as part of the arguments (readable from the `http_request::get_arg` method - see [here](#parsing-requests)). For example, if passing `"/path/to/resource/with/{arg1}/{arg2}/in/url"` will match any request on URL with any value in place of `{arg1}` and `{arg2}`.
483
490
***A parametrized path with custom parameters.** This is the same of a normal parametrized path, but allows to specify a regular expression for the argument (e.g. `"/path/to/resource/with/{arg1|[0-9]+}/{arg2|[a-z]+}/in/url"`. In this case, the webserver will match the arguments with any value passed that satisfies the regex. In addition to this, as above, the arguments will be passed to the resource as part of the arguments (readable from the `http_request::get_arg` method - see [here](#parsing-requests)). For example, if passing `"/path/to/resource/with/{arg1|[0-9]+}/{arg2|[a-z]+}/in/url"` will match requests on URLs like `"/path/to/resource/with/10/AA/in/url"` but not like `""/path/to/resource/with/BB/10/in/url""`
484
491
* Any of the above marked as `family`. Will match any request on URLs having path that is prefixed by the path passed. For example, if family is set to `true` and endpoint is set to `"/path"`, the webserver will route to the resource not only the requests against `"/path"` but also everything in its nested path `"/path/on/the/previous/one"`.
485
-
492
+
```cpp
486
493
#include<httpserver.hpp>
487
494
488
495
usingnamespacehttpserver;
@@ -526,7 +533,7 @@ There are essentially four ways to specify an endpoint string:
526
533
527
534
return 0;
528
535
}
529
-
536
+
```
530
537
To test the above example, you can run the following commands from a terminal:
531
538
532
539
*`curl -XGET -v http://localhost:8080/hello`: will return the `Hello, World!` message.
@@ -582,6 +589,7 @@ Details on the `http::file_info` structure.
582
589
*_**const std::string** get_transfer_encoding() **const**:_ Returns the transfer encoding of the file uploaded through the HTTP request.
583
590
584
591
#### Example of handler reading arguments from a request
592
+
```cpp
585
593
#include<httpserver.hpp>
586
594
587
595
usingnamespacehttpserver;
@@ -602,7 +610,7 @@ Details on the `http::file_info` structure.
602
610
603
611
return 0;
604
612
}
605
-
613
+
```
606
614
To test the above example, you can run the following command from a terminal:
@@ -634,6 +642,7 @@ The `http_response` class offers an additional set of methods to "decorate" your
634
642
*_**void** shoutCAST():_ Mark the response as a `shoutCAST` one.
635
643
636
644
### Example of response setting headers
645
+
```cpp
637
646
#include<httpserver.hpp>
638
647
639
648
usingnamespacehttpserver;
@@ -656,7 +665,7 @@ The `http_response` class offers an additional set of methods to "decorate" your
656
665
657
666
return 0;
658
667
}
659
-
668
+
```
660
669
To test the above example, you could run the following command from a terminal:
661
670
662
671
curl -XGET -v "http://localhost:8080/hello"
@@ -691,6 +700,7 @@ Examples of valid IPs include:
691
700
*`"::ffff:192.0.*.*"`: ranges of IPV4 IPs nested into IPV6.
692
701
693
702
#### Example of IP Whitelisting/Blacklisting
703
+
```cpp
694
704
#include<httpserver.hpp>
695
705
696
706
usingnamespacehttpserver;
@@ -714,7 +724,7 @@ Examples of valid IPs include:
714
724
715
725
return 0;
716
726
}
717
-
727
+
```
718
728
To test the above example, you could run the following command from a terminal:
719
729
720
730
curl -XGET -v "http://localhost:8080/hello"
@@ -733,6 +743,7 @@ Digest authentication uses a one-way authentication method based on MD5 hash alg
733
743
Client certificate authentication uses a X.509 certificate from the client. This is the strongest authentication mechanism but it requires the use of HTTPS. Client certificate authentication can be used simultaneously with Basic or Digest Authentication in order to provide a two levels authentication (like for instance separate machine and user authentication). You can enable/disable support for Certificate authentication through the `use_ssl` and `no_ssl` methods of the `create_webserver` class.
734
744
735
745
### Using Basic Authentication
746
+
```cpp
736
747
#include<httpserver.hpp>
737
748
738
749
usingnamespacehttpserver;
@@ -756,7 +767,7 @@ Client certificate authentication uses a X.509 certificate from the client. This
756
767
757
768
return 0;
758
769
}
759
-
770
+
```
760
771
To test the above example, you can run the following command from a terminal:
You will receive a `SUCCESS` in response (observe the response message from the server in detail and you'll see the full interaction). Try to pass the wrong credentials or send a request without `digest` active to see the failure.
817
+
You will receive a `SUCCESS` in response (observe the response message from the server in detail and you'll see the full interaction). Try to pass the wrong credentials or send a request without `digest` active to see the failure.
806
818
807
819
You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/digest_authentication.cpp).
808
820
809
821
[Back to TOC](#table-of-contents)
810
822
811
823
## HTTP Utils
812
-
libhttpserver provides a set of constants to help you develop your HTTP server. It would be redudant to list them here; so, please, consult the list directly [here](https://github.com/etr/libhttpserver/blob/master/src/httpserver/http_utils.hpp).
824
+
libhttpserver provides a set of constants to help you develop your HTTP server. It would be redundant to list them here; so, please, consult the list directly [here](https://github.com/etr/libhttpserver/blob/master/src/httpserver/http_utils.hpp).
813
825
814
826
[Back to TOC](#table-of-contents)
815
827
816
828
## Other Examples
817
829
818
830
#### Example of returning a response from a file
831
+
```cpp
819
832
#include<httpserver.hpp>
820
833
821
834
usingnamespacehttpserver;
@@ -836,14 +849,15 @@ libhttpserver provides a set of constants to help you develop your HTTP server.
836
849
837
850
return 0;
838
851
}
839
-
852
+
```
840
853
To test the above example, you can run the following command from a terminal:
841
854
842
855
curl -XGET -v localhost:8080/hello
843
856
844
857
You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/minimal_file_response.cpp).
845
858
846
859
#### Example of a deferred response through callback
860
+
```cpp
847
861
#include<httpserver.hpp>
848
862
849
863
usingnamespacehttpserver;
@@ -878,14 +892,15 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
878
892
879
893
return 0;
880
894
}
881
-
895
+
```
882
896
To test the above example, you can run the following command from a terminal:
883
897
884
898
curl -XGET -v localhost:8080/hello
885
899
886
900
You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/minimal_deferred.cpp).
887
901
888
902
#### Example of a deferred response through callback (passing additional data along)
903
+
```cpp
889
904
#include <atomic>
890
905
#include <httpserver.hpp>
891
906
@@ -935,7 +950,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
935
950
936
951
return 0;
937
952
}
938
-
953
+
```
939
954
To test the above example, you can run the following command from a terminal:
0 commit comments