Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: 28 days ago
JSON representation

Lightweight C++ HTTP client and server library based on Asio for embedding purpose.

Awesome Lists containing this project

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")());
```