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>

int main()
{
  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>

int main()
{
  try
  {
    const auto 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();

    return 0;
  }
  catch (const vix::requests::RequestException &error)
  {
    std::cerr << "request error: " << error.what() << "\n";
    return 1;
  }
}

Run it with Vix:

vix run examples/simple_get.cpp

GET with params and headers

#include <vix/requests/requests.hpp>

#include <chrono>
#include <iostream>

int main()
{
  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);

  const auto 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>

int main()
{
  vix::requests::RequestOptions options;
  options.headers.set("Accept", "application/json");

  const auto 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>

int main()
{
  const auto 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>

int main()
{
  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);

  const auto profile =
      session.get("http://127.0.0.1:8080/api/profile");

  profile.raise_for_status();

  std::cout << profile.text() << "\n";

  const auto 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>

int main()
{
  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:

namespace vix::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_app PRIVATE vix::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

GeezerVison

Latest commit

History

Folders and files

Repository files navigation

Vix Requests

Status

Features

Quick start

GET with params and headers

POST JSON

POST form

Session

Error handling

Public API

Request options

Response API

Build with Vix

Build options

Tests

Test files

Examples

CMake target

CMake options

Design

Current limitations

Recommended development workflow

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages