Minimal async HTTP/1.1 POST client on asio coroutines. More...

#include <neograph/api.h>
#include <asio/awaitable.hpp>
#include <asio/any_io_executor.hpp>
#include <chrono>
#include <cstddef>
#include <functional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>

Include dependency graph for http_client.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	neograph::async::HttpResponseHead
	Status and headers of a streamed response, reported before its body. More...

struct	neograph::async::HttpStreamResponse
	Metadata returned by async_post_stream after the body has been fully delivered via the callback. More...

struct	neograph::async::RequestOptions
	Per-call knobs. More...

Functions
NEOGRAPH_API asio::awaitable< HttpResponse >	neograph::async::async_get (asio::any_io_executor ex, std::string_view host, std::string_view port, std::string_view path, std::vector< std::pair< std::string, std::string > > headers={}, bool tls=false, RequestOptions opts={})
	Async HTTP(S) GET.

NEOGRAPH_API asio::awaitable< HttpResponse >	neograph::async::async_post (asio::any_io_executor ex, std::string_view host, std::string_view port, std::string_view path, std::string_view body, std::vector< std::pair< std::string, std::string > > headers={}, bool tls=false, RequestOptions opts={})
	Async HTTP(S) POST.

NEOGRAPH_API asio::awaitable< HttpStreamResponse >	neograph::async::async_post_stream (asio::any_io_executor ex, std::string_view host, std::string_view port, std::string_view path, std::string_view body, std::vector< std::pair< std::string, std::string > > headers, bool tls, std::function< void(std::string_view chunk)> on_chunk, RequestOptions opts={})
	Async HTTP(S) POST with chunked, bounded Content-Length, or close-delimited response bodies.

NEOGRAPH_API asio::awaitable< HttpStreamResponse >	neograph::async::async_request_stream (asio::any_io_executor ex, std::string_view method, std::string_view host, std::string_view port, std::string_view target, std::string_view body, std::vector< std::pair< std::string, std::string > > headers, bool tls, std::function< void(const HttpResponseHead &)> on_head, std::function< void(std::string_view chunk)> on_chunk, RequestOptions opts={})
	Async HTTP(S) request of any method (POST, GET, DELETE, ...) with a streamed response.

Detailed Description

Minimal async HTTP/1.1 POST client on asio coroutines.

The one-shot path opens a fresh connection for every exchange and supports TLS, bounded Content-Length/chunked/close-delimited response framing, streaming callbacks, and same-origin redirects. It deliberately leaves authentication policy to callers.

Every call opens a fresh connect → (handshake) → write → read → close cycle. The TLS branch verifies the peer certificate against OpenSSL's default trust store and sets SNI to the requested host.

Definition in file http_client.h.

Function Documentation

◆ async_get()

NEOGRAPH_API asio::awaitable< HttpResponse > neograph::async::async_get	(	asio::any_io_executor	ex,
		std::string_view	host,
		std::string_view	port,
		std::string_view	path,
		std::vector< std::pair< std::string, std::string > >	headers = `{}`,
		bool	tls = `false`,
		RequestOptions	opts = `{}`
	)

Async HTTP(S) GET.

Same shape as async_post but issues a GET request with an empty body and no Content-Length / Content-Type headers — used for resources like the A2A /.well-known/agent-card.json discovery endpoint. Request inputs are copied before the returned awaitable is exposed.

References neograph::async::async_get().

Referenced by neograph::async::async_get().

◆ async_post()

NEOGRAPH_API asio::awaitable< HttpResponse > neograph::async::async_post	(	asio::any_io_executor	ex,
		std::string_view	host,
		std::string_view	port,
		std::string_view	path,
		std::string_view	body,
		std::vector< std::pair< std::string, std::string > >	headers = `{}`,
		bool	tls = `false`,
		RequestOptions	opts = `{}`
	)

Async HTTP(S) POST.

Returns the response body and status on the given executor's thread(s). Throws asio::system_error (or std::system_error wrapping SSL errors) on transport failure — caller decides retry policy.

Parameters

ex	Executor (io_context / strand) where the coroutine runs.
host	Target host (e.g. "127.0.0.1" or "api.anthropic.com"). When `tls` is true this is also used as the SNI value and the name verified against the peer certificate.
port	Port string (e.g. "8080", "443"). Resolver-compatible.
path	Path with leading slash (e.g. "/v1/messages").
body	Raw request body. `Content-Length` is computed from it.
headers	Optional extra headers (name, value) pairs. Callers typically set "Authorization", "Content-Type", "x-api-key" etc.
tls	When true, wrap the socket in asio::ssl::stream, do TLS handshake with SNI=host, and verify the peer certificate against the system trust store.

All request inputs are copied before this function returns, so the returned awaitable does not borrow the caller's strings or header vector.

References neograph::async::async_post().

Referenced by neograph::async::async_post().

◆ async_post_stream()

NEOGRAPH_API asio::awaitable< HttpStreamResponse > neograph::async::async_post_stream	(	asio::any_io_executor	ex,
		std::string_view	host,
		std::string_view	port,
		std::string_view	path,
		std::string_view	body,
		std::vector< std::pair< std::string, std::string > >	headers,
		bool	tls,
		std::function< void(std::string_view chunk)>	on_chunk,
		RequestOptions	opts = `{}`
	)

Async HTTP(S) POST with chunked, bounded Content-Length, or close-delimited response bodies.

Callback data arrives in wire order. A nonempty fixed-length body is delivered once; an empty body emits no callback. The returned HttpStreamResponse carries the HTTP status.

Transport failures throw asio::system_error. Invalid framing, premature EOF, body-limit violations, and already-buffered surplus bytes are rejected. HTTP errors (4xx, 5xx) retain their status and delivered body; the caller decides how to interpret them.

The request uses Connection: close — chunked streams are typically long-lived and sharing a conn afterwards offers little amortization. ConnPool integration is deferred to a later Semester if/when a streaming workload wants it.

The bytes passed to on_chunk are only valid for the duration of the callback invocation; copy them out if you need to retain. The callback object and request inputs are copied before this function returns. Objects referenced by the callback's captures remain caller-owned.

References neograph::async::async_post_stream().

Referenced by neograph::async::async_post_stream().

◆ async_request_stream()

NEOGRAPH_API asio::awaitable< HttpStreamResponse > neograph::async::async_request_stream	(	asio::any_io_executor	ex,
		std::string_view	method,
		std::string_view	host,
		std::string_view	port,
		std::string_view	target,
		std::string_view	body,
		std::vector< std::pair< std::string, std::string > >	headers,
		bool	tls,
		std::function< void(const HttpResponseHead &)>	on_head,
		std::function< void(std::string_view chunk)>	on_chunk,
		RequestOptions	opts = `{}`
	)

Async HTTP(S) request of any method (POST, GET, DELETE, ...) with a streamed response.

on_head runs once with the final status and headers before any body byte, so a caller can choose how to read the body (for example as Server-Sent Events); on_chunk then receives the body as for async_post_stream. A GET sends no body and no Content-Type; other methods send body with its Content-Length. target is the request target, path and query. Redirects are not followed. Transport failures and an expired opts.timeout throw asio::system_error; an HTTP error status is returned with its body delivered.

References neograph::async::async_request_stream().

Referenced by neograph::async::async_request_stream().