Skip to content

Commit bbdf033

Browse files
authored
Update README.md (#277)
fixed little typos and syntax highlighting has been added
1 parent acc3e6a commit bbdf033

File tree

1 file changed

+40
-25
lines changed

1 file changed

+40
-25
lines changed

README.md

Lines changed: 40 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ Here are listed the libhttpserver specific options (the canonical configure opti
120120

121121
## Getting Started
122122
The most basic example of creating a server and handling a requests for the path `/hello`:
123-
123+
```cpp
124124
#include <httpserver.hpp>
125125

126126
using namespace httpserver;
@@ -141,7 +141,7 @@ The most basic example of creating a server and handling a requests for the path
141141
142142
return 0;
143143
}
144-
144+
```
145145
To test the above example, you could run the following command from a terminal:
146146

147147
curl -XGET -v http://localhost:8080/hello
@@ -166,9 +166,9 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
166166

167167
## Create and work with a webserver
168168
As you can see from the example above, creating a webserver with standard configuration is quite simple:
169-
169+
```cpp
170170
webserver ws = create_webserver(8080);
171-
171+
```
172172
The `create_webserver` class is a supporting _builder_ class that eases the building of a webserver through chained syntax.
173173

174174
### Basic Startup Options
@@ -214,6 +214,7 @@ In all these 3 cases libhttpserver would provide a standard HTTP response to the
214214
* _.internal_error_resource(**const shared_ptr<http_response>(&ast;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.
215215

216216
#### Example of custom errors:
217+
```cpp
217218
#include <httpserver.hpp>
218219

219220
using namespace httpserver;
@@ -246,7 +247,7 @@ In all these 3 cases libhttpserver would provide a standard HTTP response to the
246247

247248
return 0;
248249
}
249-
250+
```
250251
To test the above example, you can run the following command from a terminal:
251252
252253
curl -XGET -v http://localhost:8080/hello
@@ -262,6 +263,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
262263
* _.log_error(**void(&ast;log_error_ptr)(const std::string&)** functor):_ Specifies a function used to log errors generating from the server.
263264
264265
#### Example of custom logging callback
266+
```cpp
265267
#include <httpserver.hpp>
266268
#include <iostream>
267269
@@ -288,7 +290,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
288290
289291
return 0;
290292
}
291-
293+
```
292294
To test the above example, you can run the following command from a terminal:
293295

294296
curl -XGET -v http://localhost:8080/hello
@@ -312,6 +314,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
312314
* _.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.
313315

314316
#### Minimal example using HTTPS
317+
```cpp
315318
#include <httpserver.hpp>
316319

317320
using namespace httpserver;
@@ -335,7 +338,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
335338

336339
return 0;
337340
}
338-
341+
```
339342
To test the above example, you can run the following command from a terminal:
340343

341344
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
355358
* _.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.
356359

357360
### Examples of chaining syntax to create a webserver
358-
361+
```cpp
359362
webserver ws = create_webserver(8080)
360-
.no_ssl()
361-
.no_ipv6()
363+
.no_ssl()
364+
.no_ipv6()
362365
.no_debug()
363366
.no_pedantic()
364367
.no_basic_auth()
@@ -367,12 +370,14 @@ You should calculate the value of NC_SIZE based on the number of connections per
367370
.no_regex_checking()
368371
.no_ban_system()
369372
.no_post_process();
373+
```
370374
##
375+
```cpp
371376
webserver ws = create_webserver(8080)
372377
.use_ssl()
373378
.https_mem_key("key.pem")
374379
.https_mem_cert("cert.pem");
375-
380+
```
376381
### Starting and stopping a webserver
377382
Once a webserver is created, you can manage its execution through the following methods on the `webserver` class:
378383
* _**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
397402
* _**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`.
398403

399404
#### Example of implementation of render methods
405+
```cpp
400406
#include <httpserver.hpp>
401407

402408
using namespace httpserver;
@@ -421,7 +427,7 @@ Given this, the `http_resource` class contains the following extensible methods
421427

422428
return 0;
423429
}
424-
430+
```
425431
To test the above example, you can run the following commands from a terminal:
426432
* `curl -XGET -v http://localhost:8080/hello`: will return `GET: Hello, World!`.
427433
* `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
436442
* _**void** http_resource::disallow_all():_ Marks all HTTP methods as not allowed.
437443
438444
#### Example of methods allowed/disallowed
445+
```cpp
439446
#include <httpserver.hpp>
440447
441448
using namespace httpserver;
@@ -458,7 +465,7 @@ The base `http_resource` class has a set of methods that can be used to allow an
458465
459466
return 0;
460467
}
461-
468+
```
462469
To test the above example, you can run the following command from a terminal:
463470

464471
curl -XGET -v http://localhost:8080/hello
@@ -482,7 +489,7 @@ There are essentially four ways to specify an endpoint string:
482489
* **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}`.
483490
* **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""`
484491
* 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
486493
#include <httpserver.hpp>
487494

488495
using namespace httpserver;
@@ -526,7 +533,7 @@ There are essentially four ways to specify an endpoint string:
526533

527534
return 0;
528535
}
529-
536+
```
530537
To test the above example, you can run the following commands from a terminal:
531538

532539
* `curl -XGET -v http://localhost:8080/hello`: will return the `Hello, World!` message.
@@ -582,6 +589,7 @@ Details on the `http::file_info` structure.
582589
* _**const std::string** get_transfer_encoding() **const**:_ Returns the transfer encoding of the file uploaded through the HTTP request.
583590

584591
#### Example of handler reading arguments from a request
592+
```cpp
585593
#include <httpserver.hpp>
586594

587595
using namespace httpserver;
@@ -602,7 +610,7 @@ Details on the `http::file_info` structure.
602610

603611
return 0;
604612
}
605-
613+
```
606614
To test the above example, you can run the following command from a terminal:
607615

608616
curl -XGET -v "http://localhost:8080/hello?name=John"
@@ -634,6 +642,7 @@ The `http_response` class offers an additional set of methods to "decorate" your
634642
* _**void** shoutCAST():_ Mark the response as a `shoutCAST` one.
635643

636644
### Example of response setting headers
645+
```cpp
637646
#include <httpserver.hpp>
638647

639648
using namespace httpserver;
@@ -656,7 +665,7 @@ The `http_response` class offers an additional set of methods to "decorate" your
656665

657666
return 0;
658667
}
659-
668+
```
660669
To test the above example, you could run the following command from a terminal:
661670

662671
curl -XGET -v "http://localhost:8080/hello"
@@ -691,6 +700,7 @@ Examples of valid IPs include:
691700
* `"::ffff:192.0.*.*"`: ranges of IPV4 IPs nested into IPV6.
692701

693702
#### Example of IP Whitelisting/Blacklisting
703+
```cpp
694704
#include <httpserver.hpp>
695705

696706
using namespace httpserver;
@@ -714,7 +724,7 @@ Examples of valid IPs include:
714724

715725
return 0;
716726
}
717-
727+
```
718728
To test the above example, you could run the following command from a terminal:
719729

720730
curl -XGET -v "http://localhost:8080/hello"
@@ -733,6 +743,7 @@ Digest authentication uses a one-way authentication method based on MD5 hash alg
733743
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.
734744

735745
### Using Basic Authentication
746+
```cpp
736747
#include <httpserver.hpp>
737748

738749
using namespace httpserver;
@@ -756,7 +767,7 @@ Client certificate authentication uses a X.509 certificate from the client. This
756767

757768
return 0;
758769
}
759-
770+
```
760771
To test the above example, you can run the following command from a terminal:
761772

762773
curl -XGET -v -u myuser:mypass "http://localhost:8080/hello"
@@ -766,6 +777,7 @@ You will receive back the user and password you passed in input. Try to pass the
766777
You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/basic_authentication.cpp).
767778

768779
### Using Digest Authentication
780+
```cpp
769781
#include <httpserver.hpp>
770782

771783
#define MY_OPAQUE "11733b200778ce33060f31c9af70a870ba96ddd4"
@@ -797,25 +809,26 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
797809

798810
return 0;
799811
}
800-
812+
```
801813
To test the above example, you can run the following command from a terminal:
802814

803815
curl -XGET -v --digest --user myuser:mypass localhost:8080/hello
804816

805-
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.
806818

807819
You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/digest_authentication.cpp).
808820

809821
[Back to TOC](#table-of-contents)
810822

811823
## 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).
813825

814826
[Back to TOC](#table-of-contents)
815827

816828
## Other Examples
817829

818830
#### Example of returning a response from a file
831+
```cpp
819832
#include <httpserver.hpp>
820833

821834
using namespace httpserver;
@@ -836,14 +849,15 @@ libhttpserver provides a set of constants to help you develop your HTTP server.
836849

837850
return 0;
838851
}
839-
852+
```
840853
To test the above example, you can run the following command from a terminal:
841854

842855
curl -XGET -v localhost:8080/hello
843856

844857
You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/minimal_file_response.cpp).
845858

846859
#### Example of a deferred response through callback
860+
```cpp
847861
#include <httpserver.hpp>
848862

849863
using namespace httpserver;
@@ -878,14 +892,15 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
878892

879893
return 0;
880894
}
881-
895+
```
882896
To test the above example, you can run the following command from a terminal:
883897
884898
curl -XGET -v localhost:8080/hello
885899
886900
You can also check this example on [github](https://github.com/etr/libhttpserver/blob/master/examples/minimal_deferred.cpp).
887901
888902
#### Example of a deferred response through callback (passing additional data along)
903+
```cpp
889904
#include <atomic>
890905
#include <httpserver.hpp>
891906
@@ -935,7 +950,7 @@ You can also check this example on [github](https://github.com/etr/libhttpserver
935950
936951
return 0;
937952
}
938-
953+
```
939954
To test the above example, you can run the following command from a terminal:
940955

941956
curl -XGET -v localhost:8080/hello

0 commit comments

Comments
 (0)