Files

T

freemo 5f7bba3e96 feat(client): add server http client

Implement ServerHttpClient with httpx for server communication including:
- Health check endpoint (GET /health)
- Version negotiation (GET /version, POST /version/negotiate)
- Pagination helpers for list endpoints
- Per-request timeout and retry policy with exponential backoff
- Request/response logging with auth header redaction
- TLS verification toggle with warning when disabled
- Server error responses mapped to domain errors (A2aNotAvailableError, etc.)
- Client-specific exceptions (ServerConnectionError, ServerTimeoutError,
  ServerVersionMismatchError)
- Settings fields: server_base_url, server_api_token, server_tls_verify,
  server_request_timeout
- Factory function create_client_from_settings wired to Settings
- httpx added to pyproject.toml dependencies
- Behave scenarios (23 scenarios, 72 steps)
- Robot Framework smoke tests
- ASV benchmark for connection overhead baseline
- Reference documentation at docs/reference/server_client_http.md

ISSUES CLOSED: #335

2026-03-24 20:28:19 +00:00

2.6 KiB

Raw Blame History

Server HTTP Client

The ServerHttpClient provides communication with a remote CleverAgents server instance. It wraps httpx and handles health checks, version negotiation, pagination, retry with exponential backoff, and request/response logging with auth-header redaction.

Configuration

Environment variable	Settings field	Default	Description
`CLEVERAGENTS_SERVER_BASE_URL`	`server_base_url`	`None`	Base URL of the remote server (e.g. `https://server.example.com`)
`CLEVERAGENTS_SERVER_API_TOKEN`	`server_api_token`	`None`	Bearer token for server authentication
`CLEVERAGENTS_SERVER_TLS_VERIFY`	`server_tls_verify`	`True`	Verify TLS certificates; set to `False` only for development
`CLEVERAGENTS_SERVER_REQUEST_TIMEOUT`	`server_request_timeout`	`30.0`	Per-request timeout in seconds

Usage

from cleveragents.client.http_client import create_client_from_settings

client = create_client_from_settings()

# Health check
is_healthy = client.health_check()

# Version negotiation
version = client.get_version()
negotiated = client.negotiate_version("1.0")

# Paginated list endpoint
page = client.list_endpoint("/plans", page=1, per_page=20)
print(page.items, page.has_next)

Connection Errors

Exception	Cause
`ServerConnectionError`	Cannot reach the server, non-retryable HTTP error, or authentication failure
`ServerTimeoutError`	Request exceeded the configured timeout
`ServerVersionMismatchError`	Client and server protocol versions are incompatible
`A2aNotAvailableError`	Server returned 503 Service Unavailable

Retry Policy

Idempotent methods (GET, HEAD, OPTIONS, PUT, DELETE) are automatically retried up to 3 times with exponential backoff on status codes 429, 500, 502, and 504. Non-idempotent methods (POST, PATCH) are never retried automatically.

TLS Verification

When server_tls_verify is set to False a warning is logged at client creation time. This is intended only for local development against self-signed certificates; production deployments must always verify TLS.

Health Check Failure

When health_check() encounters a connection or timeout error it returns False rather than raising. This allows callers to use it as a boolean probe without try/except.

Version Negotiation Failure

negotiate_version() raises ServerVersionMismatchError when the server does not return a negotiated version. The exception includes both the requested client version and the list of versions the server supports.

2.6 KiB Raw Blame History