Error taxonomy for async HTTP — retryable vs permanent. More...

#include <asio/error.hpp>
#include <asio/ssl/error.hpp>
#include <openssl/err.h>
#include <openssl/ssl.h>
#include <cerrno>
#include <exception>
#include <stdexcept>
#include <string>
#include <system_error>

Include dependency graph for http_errors.h:

Classes
struct	neograph::async::HttpError
	Structured exception. More...

Enumerations
enum class	neograph::async::HttpErrorKind { ConnectRefused , ConnectTimeout , DnsTemporary , ReadTimeout , WriteTimeout , PeerReset , PeerEofEarly , TlsHandshakeReset , ServerError , TooManyRequests , DnsPermanent , TlsVerifyFailed , ProtocolError , RequestTooLarge , PayloadInvalid , Unknown }

Functions
HttpErrorKind	neograph::async::classify_asio_error (const asio::error_code &ec) noexcept
	Classify an asio error_code — the kind returned inside asio::system_error::code() from any connect/read/write/handshake op.

constexpr HttpErrorKind	neograph::async::classify_http_status (int status) noexcept
	Classify an HTTP status code on its own.

constexpr bool	neograph::async::is_retryable (HttpErrorKind k) noexcept
	True if transparent retry on a different connection may succeed.

Detailed Description

Error taxonomy for async HTTP — retryable vs permanent.

Stage 3 / Semester 1.3 — classifies the error_codes that surface from asio::system_error (and OpenSSL) during async HTTP work into a small enum, plus a single is_retryable() predicate. Higher layers (Provider, MCPClient, future Engine retry) use this instead of each reinventing "which errno means try again".

Scope bounds:

This header defines the taxonomy and classifiers. It does not change async_post / ConnPool behavior — those still throw asio::system_error / std::runtime_error verbatim, so callers that already catch std::exception are unaffected. Wrapping internal throws in HttpError is deferred to Semester 2 when Provider layers want structured retry.
The classifier is a pure, header-friendly function: safe to call from any thread, any context, under error unwinding.

Definition in file http_errors.h.

Enumeration Type Documentation

◆ HttpErrorKind

enum class neograph::async::HttpErrorKind

strong

Enumerator
ConnectRefused	TCP RST on connect — server down / booting.
ConnectTimeout	connect() didn't ACK within budget.
DnsTemporary	EAI_AGAIN equivalent — try again later.
ReadTimeout	no bytes within deadline (1.5 territory).
WriteTimeout	send buffer full too long (1.5 territory).
PeerReset	ECONNRESET / EPIPE mid-exchange.
PeerEofEarly	EOF before the response was complete.
TlsHandshakeReset	Any SSL error except verify failure — overloaded server or flaky link, worth retry.
ServerError	HTTP 500-599 from classify_http_status.
TooManyRequests	HTTP 429 — caller should honor Retry-After.
DnsPermanent	NXDOMAIN.
TlsVerifyFailed	Cert chain / hostname mismatch. Never retry.
ProtocolError	Malformed HTTP, unsupported encoding.
RequestTooLarge	HTTP 413.
PayloadInvalid	HTTP 4xx other than 429 / 413.
Unknown	Code we haven't classified. Default = don't retry (safer than unbounded retries on a misbehaving wire).