Vix Requests

vix::requests is a lightweight HTTP client module for Vix.cpp.

It provides a Python requests-like API for C++:

#include<vix/requests/requests.hpp>
#include<iostream>intmain()
{
auto response = vix::requests::get("https://example.com/");
response.raise_for_status();
std::cout << response.status_code() << "\n";
std::cout << response.text() << "\n";
}

Status

Version: 1.2.1

This module is designed for Vix.cpp v2.7.0.

Current transport support:

Protocol	Status
HTTP	Supported
HTTPS	Supported with OpenSSL TLS

HTTPS is implemented with OpenSSL TLS. TLS verification is enabled by default and can be disabled per request with:

options.verify_tls = false;

This is useful for local development, self-signed certificates, or test fixtures.

The module does not use curl, libcurl, shell commands, popen, or temporary files.

Features

• Simple free functions:

  • get
  • post
  • put
  • patch
  • del
  • head
  • request

• Client API

• Session API

• Headers with case-insensitive lookup

• Query params with URL encoding

• Raw body

• JSON body

• Form URL encoded body

• Binary body

• Basic auth

• Redirect handling

• Redirect loop detection

• Configurable max redirects

• Timeouts

• Response parsing

• Content-Length

• Transfer-Encoding: chunked

• Connection-close body

• raise_for_status()

• OpenSSL for HTTPS

• No curl

• No shell command execution

Quick start

#include<vix/requests/requests.hpp>
#include<iostream>intmain()
{
try
{
constauto response =
vix::requests::get("https://example.com/");
std::cout << response.status_code() << "\n";
std::cout << response.reason() << "\n";
std::cout << response.text() << "\n";
response.raise_for_status();
return0;
}
catch (const vix::requests::RequestException &error)
{
std::cerr << "request error: " << error.what() << "\n";
return1;
}
}

Run it with Vix:

vix run examples/simple_get.cpp

GET with params and headers

#include<vix/requests/requests.hpp>
#include<chrono>
#include<iostream>intmain()
{
vix::requests::RequestOptions options;
options.headers.set("Accept", "application/json");
options.params.set("page", "1");
options.params.set("q", "vix requests");
options.timeout = std::chrono::seconds(10);
constauto response =
vix::requests::get(
"http://example.com/search",
options);
std::cout << response.status_code() << "\n";
std::cout << response.text() << "\n";
}

Run it:

vix run examples/get_params.cpp

POST JSON

#include<vix/requests/requests.hpp>
#include<iostream>intmain()
{
vix::requests::RequestOptions options;
options.headers.set("Accept", "application/json");
constauto response =
vix::requests::post(
"http://127.0.0.1:8080/api/items",
vix::requests::json_body(R"({"name":"Vix"})"),
options);
std::cout << response.status_code() << "\n";
std::cout << response.text() << "\n";
}

Run it:

vix run examples/post_json.cpp

POST form

#include<vix/requests/requests.hpp>
#include<iostream>intmain()
{
constauto response =
vix::requests::post(
"http://127.0.0.1:8080/login",
vix::requests::form_body({
{"username", "gaspard"},
{"project", "Vix Requests"}}));
std::cout << response.status_code() << "\n";
std::cout << response.text() << "\n";
}

Run it:

vix run examples/post_form.cpp

Session

Use Session when multiple requests should share headers, params, auth, timeout, and cookies.

#include<vix/requests/requests.hpp>
#include<chrono>
#include<iostream>intmain()
{
vix::requests::Session session;
session.headers().set("User-Agent", "vix-requests-example/1.0.0");
session.headers().set("Accept", "application/json");
session.params().set("token", "demo-token");
session.timeout() = std::chrono::seconds(10);
constauto profile =
session.get("http://127.0.0.1:8080/api/profile");
profile.raise_for_status();
std::cout << profile.text() << "\n";
constauto created =
session.post(
"http://127.0.0.1:8080/api/items",
vix::requests::form_body({
{"name", "Gaspard"},
{"project", "Vix Requests"}}));
created.raise_for_status();
std::cout << created.text() << "\n";
}

Run it:

vix run examples/session.cpp

Error handling

#include<vix/requests/requests.hpp>
#include<iostream>intmain()
{
try
{
auto response =
vix::requests::get("http://example.com/missing");
response.raise_for_status();
}
catch (const vix::requests::InvalidUrlException &error)
{
std::cerr << "invalid URL: " << error.what() << "\n";
}
catch (const vix::requests::UnsupportedProtocolException &error)
{
std::cerr << "unsupported protocol: " << error.what() << "\n";
}
catch (const vix::requests::TimeoutException &error)
{
std::cerr << "timeout: " << error.what() << "\n";
}
catch (const vix::requests::ConnectionException &error)
{
std::cerr << "connection error: " << error.what() << "\n";
}
catch (const vix::requests::TooManyRedirectsException &error)
{
std::cerr << "redirect error: " << error.what() << "\n";
}
catch (const vix::requests::HttpException &error)
{
std::cerr << "HTTP error: "
<< error.status_code()
<< ""
<< error.reason()
<< "\n";
}
catch (const vix::requests::RequestException &error)
{
std::cerr << "request error: " << error.what() << "\n";
}
}

Run it:

vix run examples/error_handling.cpp

Public API

Main include:

#include<vix/requests/requests.hpp>

Main namespace:

namespacevix::requests

Important public types:

vix::requests::Client
vix::requests::Session
vix::requests::Request
vix::requests::Response
vix::requests::RequestOptions
vix::requests::Headers
vix::requests::Params
vix::requests::Body
vix::requests::Timeout
vix::requests::Url

Request options

vix::requests::RequestOptions options;
options.headers.set("Accept", "application/json");
options.params.set("page", "1");
options.timeout = std::chrono::seconds(10);
options.follow_redirects = true;
options.max_redirects = 10;
options.verify_tls = true;
options.set_basic_auth("username", "password");
options.set_user_agent("my-client/1.0");

Response API

response.status_code();
response.reason();
response.url();
response.headers();
response.header("Content-Type");
response.content_type();
response.content_length();
response.location();
response.text();
response.body();
response.bytes();
response.size();
response.empty();
response.ok();
response.is_redirect();
response.is_error();
response.raise_for_status();
response.elapsed();

Build with Vix

Build the module:

vix build

Build in release mode:

vix build --preset release

Build all targets, including tests and examples:

vix build --build-target all

Clean and rebuild:

vix build --clean

Show detailed Vix output:

vix build -v

Show raw CMake/Ninja output when debugging:

vix build --cmake-verbose

Build options

You can pass CMake options after --.

Build with tests enabled:

vix build --build-target all -- -DVIX_REQUESTS_BUILD_TESTS=ON

Build with examples enabled:

vix build --build-target all -- -DVIX_REQUESTS_BUILD_EXAMPLES=ON

Build with tests and examples enabled:

vix build --build-target all -- \
-DVIX_REQUESTS_BUILD_TESTS=ON \
-DVIX_REQUESTS_BUILD_EXAMPLES=ON

Release build with LTO:

vix build --preset release -- \
-DVIX_REQUESTS_ENABLE_LTO=ON

Tests

Build all targets first:

vix build --build-target all

Run all tests:

vix tests

Run tests with detailed Vix output:

vix tests -v

Run one test:

vix tests --test http_client_test

Short form:

vix tests -R http_client_test

Run the integration tests:

vix tests -R '^(http_client_test|redirect_test|timeout_test)$'

Run tests in release mode:

vix build --preset release --build-target all
vix tests --preset release

List available tests:

vix tests --list

Show raw internal runner output:

vix tests --raw

Test files

Unit tests:

tests/unit/url_test.cpp
tests/unit/headers_test.cpp
tests/unit/params_test.cpp
tests/unit/body_test.cpp
tests/unit/response_parser_test.cpp
tests/unit/serializer_test.cpp
tests/unit/session_test.cpp
tests/unit/errors_test.cpp

Integration tests:

tests/integration/http_client_test.cpp
tests/integration/redirect_test.cpp
tests/integration/timeout_test.cpp

Tests do not require external internet access.

Integration tests use a local loopback HTTP server.

Examples

examples/simple_get.cpp
examples/get_params.cpp
examples/post_json.cpp
examples/post_form.cpp
examples/session.cpp
examples/error_handling.cpp

Run examples with Vix:

vix run examples/simple_get.cpp
vix run examples/get_params.cpp
vix run examples/post_json.cpp
vix run examples/post_form.cpp
vix run examples/session.cpp
vix run examples/error_handling.cpp

CMake target

When using the module from CMake directly:

target_link_libraries(my_appPRIVATEvix::requests)

CMake options

Option	Default	Description
VIX_REQUESTS_BUILD_TESTS	ON	Build tests in standalone mode
VIX_REQUESTS_BUILD_EXAMPLES	ON	Build examples in standalone mode
VIX_REQUESTS_ENABLE_LTO	OFF	Enable LTO in release builds
VIX_REQUESTS_INSTALL	ON	Enable standalone install/package rules

Inside the Vix umbrella build, tests, examples, and standalone install rules are disabled by default unless explicitly enabled.

Design

The module is organized as a real Vix module:

include/vix/requests/
requests.hpp
Client.hpp
Session.hpp
Request.hpp
Response.hpp
RequestOptions.hpp
Headers.hpp
Params.hpp
Method.hpp
Url.hpp
Body.hpp
Error.hpp
Timeout.hpp
Version.hpp
include/vix/requests/transport/
Transport.hpp
src/
Client.cpp
Session.cpp
Request.cpp
Response.cpp
RequestOptions.cpp
Headers.cpp
Params.cpp
Method.cpp
Url.cpp
Body.cpp
Error.cpp
Timeout.cpp
Version.cpp
src/http/
HttpParser.hpp
HttpParser.cpp
HttpSerializer.hpp
HttpSerializer.cpp
RedirectPolicy.hpp
RedirectPolicy.cpp
CookieJar.hpp
CookieJar.cpp
src/transport/
Socket.hpp
Socket.cpp
Resolver.hpp
Resolver.cpp
TcpTransport.hpp
TcpTransport.cpp
TransportFactory.hpp
TransportFactory.cpp
src/detail/
Base64.hpp
Base64.cpp
UrlEncode.hpp
UrlEncode.cpp
CaseInsensitive.hpp
CaseInsensitive.cpp

Current limitations

• HTTPS is implemented with OpenSSL and supports SNI plus hostname verification by default.
• The current transport uses POSIX sockets.
• Windows transport is not implemented yet.
• No gzip or deflate decompression is advertised or faked.
• HTTP proxy support is not implemented yet.
• Connection reuse is prepared by design, but the current transport opens one connection per request.

Recommended development workflow

vix build
vix tests

Before committing:

vix build --build-target all
vix tests

Before release:

vix build --preset release --build-target all
vix tests --preset release

License

MIT