Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sprinfall/webcc
Lightweight C++ HTTP client and server library based on Asio for embedding purpose.
https://github.com/sprinfall/webcc
asio beast boost cplusplus cpp http requests rest webcc webservice
Last synced: 3 months ago
JSON representation
Lightweight C++ HTTP client and server library based on Asio for embedding purpose.
- Host: GitHub
- URL: https://github.com/sprinfall/webcc
- Owner: sprinfall
- License: lgpl-3.0
- Created: 2017-05-26T08:43:48.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-12-11T14:04:49.000Z (11 months ago)
- Last Synced: 2024-05-10T11:33:13.576Z (6 months ago)
- Topics: asio, beast, boost, cplusplus, cpp, http, requests, rest, webcc, webservice
- Language: C++
- Homepage:
- Size: 7.5 MB
- Stars: 265
- Watchers: 16
- Forks: 61
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-http - Webcc - activity/y/sprinfall/webcc) (Programming Languages / C++)
README
# Webcc - C++ HTTP Library
[__中文版 README__](README_zh_CN.md)
Lightweight C++ HTTP __client and server__ library based on [Boost Asio](https://www.boost.org/doc/libs/release/libs/asio/) for __embedding__ purpose.
=> [Build Instructions](doc/Build-Instructions.md) ([__中文版__](doc/Build-Instructions_zh_CN.md))
Git repo: https://github.com/sprinfall/webcc. Please check this one instead of the forked for the latest features.
**Contents**
* [Overview](#overview)
* [Client API](#client-api)
* [A Complete Example](#a-complete-example)
* [Request Builder](#request-builder)
* [HTTPS](#https)
* [Invoking GitHub REST API](#invoking-github-rest-api)
* [Authorization](#authorization)
* [Keep-Alive (Persistent Connection)](#keep-alive)
* [POST Request](#post-request)
* [Downloading Files](#downloading-files)
* [Uploading Files](#uploading-files)
* [Client API and Threads](#client-api-and-threads)
* [Server API](#server-api)
* [A Minimal Server](#a-minimal-server)
* [URL Route](#url-route)
* [Running A Server](#running-a-server)
* [Response Builder](#response-builder)
* [REST Book Server](#rest-book-server)
* [IPv6 Support](#ipv6-support)
* [IPv6 Server](#ipv6-server)
* [IPv6 Client](#ipv6-client)
## Overview
- Cross-platform: Windows, Linux and MacOS
- Easy-to-use client API inspired by Python [requests](https://github.com/psf/requests)
- IPv6 support
- SSL/HTTPS support with OpenSSL
- GZip compression support with Zlib (optional)
- Persistent (Keep-Alive) connections
- Data streaming
- for uploading and downloading large files on client
- for serving and receiving large files on server
- Basic & Token authorization
- Timeout control
- Source code follows [Google C++ Style](https://google.github.io/styleguide/cppguide.html)
- Automation tests and unit tests included
## Client API
### A Complete Example
Let's start from a complete client example:
```cpp
#include
#include "webcc/client_session.h"
#include "webcc/logger.h"
int main() {
// Configure logger to print only to console.
WEBCC_LOG_INIT("", webcc::LOG_CONSOLE);
// Session provides convenient request APIs, stores request configurations
// and manages persistent connenctions.
webcc::ClientSession session;
// Catch exceptions for error handling.
try {
// Send a HTTP GET request.
auto r =
session.Send(webcc::RequestBuilder{}.Get("http://httpbin.org/get")());
// Print the response data.
std::cout << r->data() << std::endl;
} catch (const webcc::Error& error) {
std::cerr << error << std::endl;
}
return 0;
}
```
### Request Builder
As you can see, a helper class named `RequestBuilder` is used to chain the parameters and finally build a request object. Please pay attention to the `()` operator.
URL query parameters can be easily added through `Query()` method:
```cpp
session.Send(webcc::RequestBuilder{}
.Get("http://httpbin.org/get")
.Query("key1", "value1")
.Query("key2", "value2")());
```
Adding additional headers is also easy:
```cpp
session.Send(webcc::RequestBuilder{}
.Get("http://httpbin.org/get")
.Header("Accept", "application/json")());
```
### HTTPS
Accessing HTTPS has no difference from HTTP:
```cpp
session.Send(webcc::RequestBuilder{}.Get("https://httpbin.org/get")());
```
*NOTE: The HTTPS/SSL support requires the build option `WEBCC_ENABLE_SSL` to be enabled.*
### Invoking GitHub REST API
Listing GitHub public events is not a big deal:
```cpp
auto r = session.Send(
webcc::RequestBuilder{}.Get("https://api.github.com/events")());
```
You can then parse `r->data()` to JSON object with your favorite JSON library. My choice for the examples is [jsoncpp](https://github.com/open-source-parsers/jsoncpp). But Webcc itself doesn't understand JSON nor require one. It's up to you to choose the most appropriate JSON library.
`RequestBuilder` provides a lot of functions for you to customize the request. Let's see more examples.
### Authorization
In order to list the followers of an authorized GitHub user, you need either **Basic Authorization**:
```cpp
session.Send(webcc::RequestBuilder{}.
Get("https://api.github.com/user/followers").
AuthBasic(, )
());
```
Or **Token Authorization**:
```cpp
session.Send(webcc::RequestBuilder{}
.Get("https://api.github.com/user/followers")
.AuthToken(token)());
```
### Keep-Alive
Though **Keep-Alive** (i.e., Persistent Connection) is a good feature and enabled by default, you can turn it off:
```cpp
auto r = session.Send(
webcc::RequestBuilder{}.Get("http://httpbin.org/get").KeepAlive(false)());
```
The API for other HTTP requests is no different from GET.
### POST Request
A POST request needs a body which is normally a JSON string for REST API. Let's post a small UTF-8 encoded JSON string:
```cpp
session.Send(webcc::RequestBuilder{}
.Post("http://httpbin.org/post")
.Body("{'name'='Adam', 'age'=20}")
.Json()
.Utf8()());
```
The body of a POST request could be any content other than JSON string.
It could be the binary data of a file. See [Uploading Files](#uploading-files).
It could be a form urlencoded string:
```cpp
webcc::ClientSession session;
session.SetContentType("application/x-www-form-urlencoded", "utf8");
// Use UrlQuery to compose the urlencoded string.
// Don't use RequestBuilder::Query() which is dedicated to GET.
webcc::UrlQuery query;
query.Add("key1", "value1");
query.Add("key2", "value2");
// ...
auto r = session.Send(webcc::RequestBuilder{}
.Post("http://httpbin.org/post")
.Body(query.ToString())());
```
Please see [examples/form_urlencoded_client.cc](examples/form_urlencoded_client.cc) for more details.
### Downloading Files
Webcc has the ability to stream large response data to a file. This is especially useful when downloading files.
```cpp
// stream = true
auto r = session.Send(
webcc::RequestBuilder{}.Get("http://httpbin.org/image/jpeg")(), true);
// Move the streamed file to your destination.
r->file_body()->Move("./wolf.jpeg");
```
### Uploading Files
Streaming is also available for uploading:
```cpp
auto r = session.Send(
webcc::RequestBuilder{}.Post("http://httpbin.org/post").File(path)());
```
The file will not be loaded into the memory all at once, instead, it will be read and sent piece by piece.
Please note that `Content-Length` header will still be set to the true size of the file, this is different from the handling of chunked data (`Transfer-Encoding: chunked`).
### Client API and Threads
A `ClientSession` shouldn't be used by multiple threads to send requests.
The state functions, `Start()`, `Stop()` and `Cancel()`, are thread safe. E.g., you can call `Send()` in thread A and call `Stop()` in thread B. Please see [examples/heartbeat_client](examples/heartbeat_client.cc) for more details.
Example:
```cpp
void ThreadedClient() {
std::vector threads;
for (int i = 0; i < 3; ++i) {
threads.emplace_back([]() {
webcc::ClientSession session;
try {
auto r = session.Send(
webcc::RequestBuilder{}.Get("http://httpbin.org/get")());
std::cout << r->data() << std::endl;
} catch (const webcc::Error&) {
}
});
}
for (auto& t : threads) {
t.join();
}
}
```
## Server API
### A Minimal Server
The following example is a minimal yet complete HTTP server.
Start it, open a browser with `localhost:8080`, you will see `Hello, World!` as response.
```cpp
#include "webcc/logger.h"
#include "webcc/response_builder.h"
#include "webcc/server.h"
class HelloView : public webcc::View {
public:
webcc::ResponsePtr Handle(webcc::RequestPtr request) override {
if (request->method() == "GET") {
return webcc::ResponseBuilder{}.OK().Body("Hello, World!")();
}
return {};
}
};
int main() {
try {
webcc::Server server{ boost::asio::ip::tcp::v4(), 8080 };
server.Route("/", std::make_shared());
server.Run();
} catch (const std::exception&) {
return 1;
}
return 0;
}
```
### URL Route
The `Route()` method routes different URLs to different `views`.
You can route different URLs to the same view:
```cpp
server.Route("/", std::make_shared());
server.Route("/hello", std::make_shared());
```
Or even the same view object:
```cpp
auto view = std::make_shared();
server.Route("/", view);
server.Route("/hello", view);
```
But normally a view only handles a specific URL (see the Book Server example).
The URL could be regular expressions. The Book Server example uses a regex URL to match against book IDs.
Finally, it's always suggested to explicitly specify the HTTP methods allowed for a route:
```cpp
server.Route("/", std::make_shared(), { "GET" });
```
### Running A Server
The last thing about server is `Run()`:
```cpp
void Run(std::size_t workers = 1, std::size_t loops = 1);
```
Workers are threads which will be waken to process the HTTP requests once they arrive. Theoretically, the more `workers` you have, the more concurrency you gain. In practice, you have to take the number of CPU cores into account and allocate a reasonable number for it.
The `loops` means the number of threads running the IO Context of Asio. Normally, one thread is good enough, but it could be more than that.
### Response Builder
The server API provides a helper class `ResponseBuilder` for the views to chain the parameters and finally build a response object. This is exactly the same strategy as `RequestBuilder`.
### REST Book Server
Suppose you want to create a book server and provide the following operations with RESTful API:
- Query books based on some criterias.
- Add a new book.
- Get the detailed information of a book.
- Update the information of a book.
- Delete a book.
The first two operations are implemented by `BookListView` deriving from `webcc::View`:
```cpp
class BookListView : public webcc::View {
public:
webcc::ResponsePtr Handle(webcc::RequestPtr request) override {
if (request->method() == "GET") {
return Get(request);
}
if (request->method() == "POST") {
return Post(request);
}
return {};
}
private:
// Get a list of books based on query parameters.
webcc::ResponsePtr Get(webcc::RequestPtr request);
// Create a new book.
// The new book's data is attached as request data in JSON format.
webcc::ResponsePtr Post(webcc::RequestPtr request);
};
```
Other operations are implemented by `BookDetailView`:
```cpp
class BookDetailView : public webcc::View {
public:
webcc::ResponsePtr Handle(webcc::RequestPtr request) override {
if (request->method() == "GET") {
return Get(request);
}
if (request->method() == "PUT") {
return Put(request);
}
if (request->method() == "DELETE") {
return Delete(request);
}
return {};
}
protected:
// Get the detailed information of a book.
webcc::ResponsePtr Get(webcc::RequestPtr request);
// Update a book.
webcc::ResponsePtr Put(webcc::RequestPtr request);
// Delete a book.
webcc::ResponsePtr Delete(webcc::RequestPtr request);
};
```
The detailed implementation is out of the scope of this README, but here is an example:
```cpp
webcc::ResponsePtr BookDetailView::Get(webcc::RequestPtr request) {
if (request->args().size() != 1) {
// NotFound means the resource specified by the URL cannot be found.
// BadRequest could be another choice.
return webcc::ResponseBuilder{}.NotFound()();
}
const std::string& book_id = request->args()[0];
// Get the book by ID from, e.g., the database.
// ...
if () {
// There's no such book with the given ID.
return webcc::ResponseBuilder{}.NotFound()();
}
// Convert the book to JSON string and set as response data.
return webcc::ResponseBuilder{}.OK().Data().
Json().Utf8()();
}
```
Last step, route URLs to the proper views and run the server:
```cpp
int main(int argc, char* argv[]) {
// ...
try {
webcc::Server server{ boost::asio::ip::tcp::v4(), 8080 };
server.Route("/books",
std::make_shared(),
{ "GET", "POST" });
server.Route(webcc::R("/books/(\\d+)"),
std::make_shared(),
{ "GET", "PUT", "DELETE" });
server.Run();
} catch (const std::exception& e) {
std::cerr << e.what() << std::endl;
return 1;
}
return 0;
```
Please see [examples/book_server](examples/book_server) for more details.
## IPv6 Support
### IPv6 Server
Only need to change the protocol to `boost::asio::ip::tcp::v6()`:
```cpp
webcc::Server server{ boost::asio::ip::tcp::v6(), 8080 };
```
### IPv6 Client
Only need to specify an IPv6 address:
```cpp
session.Send(webcc::RequestBuilder{}.Get("http://[::1]:8080/books")());
```