Httpx

General Information

Field	Value
Package Name	httpx
Manufacturer / Vendor	Encode (Tom Christie and contributors)
Software Category	Library
Primary Documentation	Documentation, GitHub, PyPI
Programming Language(s)	Python
License	BSD-3-Clause
Deployed Version(s)	>=0.28.0 (version-locked at 0.28.1)
Most Recent Available Version	0.28.1
Last Review Date	2026-01-27

Overview

httpx is a next-generation HTTP client for Python that provides both synchronous and asynchronous APIs with native support for HTTP/1.1 and HTTP/2 protocols. The library offers a requests-compatible API with modern async/await support, strict timeout handling, connection pooling, and comprehensive type annotations. With 14.9k+ GitHub stars and 100% test coverage, httpx has become the de facto standard for async HTTP communication in the Python ecosystem.

Within the medical device software, httpx serves as the foundational HTTP communication layer for all inter-service communication in the microservices architecture. The library is integrated into the legithp-essentials framework through the AsyncHttpClient wrapper, which provides enterprise-grade HTTP capabilities to all services including the control plane, API gateway, expert orchestrator, and clinical detector applications. Specifically, httpx is used for:

• Asynchronous service-to-service communication: The AsyncHttpClient class wraps httpx.AsyncClient to provide non-blocking HTTP operations between microservices, enabling efficient handling of concurrent requests across the distributed system
• Synchronous clinical detector clients: Clinical sign detection services (hair follicle detector, acneiform detector) use httpx.Client for blocking HTTP calls to specialized ML model endpoints
• Connection pooling and resource management: httpx's Limits configuration enables efficient connection reuse with configurable pool sizes (max 100 connections, 20 keep-alive connections) to prevent resource exhaustion under load
• Distributed tracing support: Correlation IDs are automatically injected into request headers via httpx's header management, enabling request tracing across the entire microservice mesh
• Health monitoring infrastructure: Dedicated health check methods with shorter timeouts (5 seconds) use httpx to monitor service availability and readiness across the system

The library was selected for its async-first design compatible with FastAPI/Starlette, comprehensive timeout handling throughout the request lifecycle, connection pooling capabilities, robust exception hierarchy for granular error handling, and permissive BSD-3-Clause licensing suitable for commercial medical device software.

Functional Requirements

The following functional capabilities of this SOUP are relied upon by the medical device software.

Requirement ID	Description	Source / Reference
FR-001	Execute asynchronous HTTP requests (GET, POST, PUT, PATCH, DELETE)	httpx.AsyncClient methods
FR-002	Execute synchronous HTTP requests for blocking operations	httpx.Client methods
FR-003	Automatic JSON serialization and deserialization of request/response bodies	json parameter, response.json()
FR-004	Connection pooling with configurable limits for connection reuse	httpx.Limits class
FR-005	Configurable timeout handling for connect, read, write, and pool operations	httpx.Timeout class
FR-006	Custom header injection for correlation ID propagation	headers parameter
FR-007	Context manager support for proper resource cleanup	async with, with statements
FR-008	Custom transport injection for testing with mock responses	transport parameter, MockTransport
FR-009	Structured exception hierarchy for granular error handling	HTTPError, TimeoutException, etc.

Performance Requirements

The following performance expectations are relevant to the medical device software.

Requirement ID	Description	Acceptance Criteria
PR-001	HTTP requests shall complete within configured timeout bounds	Requests timeout appropriately; no indefinite blocking
PR-002	Connection pooling shall reduce connection establishment overhead	Reused connections for repeated requests to same host
PR-003	Async operations shall not block the event loop	Non-blocking I/O enabling concurrent request handling
PR-004	Memory usage shall remain stable during sustained request activity	No memory leaks during prolonged operation; connections properly released

Hardware Requirements

The following hardware dependencies or constraints are imposed by this SOUP component.

Requirement ID	Description	Notes / Limitations
HR-001	Network interface for HTTP/HTTPS	Standard TCP/IP networking required
HR-002	x86-64 or ARM64 processor architecture	Pre-built wheels available for common platforms

Software Requirements

The following software dependencies and environmental assumptions are required by this SOUP component.

Requirement ID	Description	Dependency / Version Constraints
SR-001	Python runtime environment	Python >=3.8
SR-002	httpcore for underlying transport layer	Bundled dependency (automatically installed)
SR-003	h11 for HTTP/1.1 protocol implementation	Bundled dependency (automatically installed)
SR-004	certifi for SSL certificate verification	Bundled dependency (automatically installed)
SR-005	idna for internationalized domain name support	Bundled dependency (automatically installed)
SR-006	sniffio for async library detection	Bundled dependency (automatically installed)
SR-007	asyncio event loop for async operations	Python standard library

Known Anomalies Assessment

This section evaluates publicly reported issues, defects, or security vulnerabilities associated with this SOUP component and their relevance to the medical device software.

As of the review date (2026-01-27), no security vulnerabilities have been reported in the National Vulnerability Database (NVD), GitHub Security Advisories, or Snyk vulnerability database for the httpx package. The project maintains a security policy (SECURITY.md) and the maintainers (Encode organization) have a history of responsible security practices across their other projects (Starlette, uvicorn).

The device's usage pattern follows security best practices:

• TLS verification enabled: All HTTPS connections use certificate verification via certifi, ensuring secure communication between services
• Timeout enforcement: Strict timeouts are configured throughout (30 seconds default, 5 seconds for health checks, 120 seconds for ML operations), preventing indefinite resource blocking
• Connection limits: Maximum connection pool sizes are configured to prevent resource exhaustion attacks
• No external URL processing: All HTTP requests are made to internal microservices with pre-configured base URLs; no user-supplied URLs are processed through httpx
• Header injection controls: Only controlled headers (correlation IDs, authentication tokens) are injected; no user-controlled header values
• Error isolation: Custom exception hierarchy wraps httpx exceptions, preventing information leakage in error responses

Risk Control Measures

The following risk control measures are implemented to mitigate potential security and operational risks associated with this SOUP component:

• Version locking via requirements_lock.txt files ensures reproducible deployments across all services
• All inter-service communication uses TLS with certificate verification
• Timeout configuration prevents indefinite blocking
• Connection pooling limits prevent resource exhaustion
• No user-controlled URLs or headers are processed
• Exponential backoff retry logic prevents cascade failures
• Correlation ID propagation enables distributed tracing for security monitoring

Assessment Methodology

The following methodology was used to identify and assess known anomalies:

• Sources consulted:

  • National Vulnerability Database (NVD) search for "httpx"
  • GitHub Security Advisories for the encode/httpx repository
  • Snyk vulnerability database for package security analysis
  • PyPI package security reports
  • httpcore security advisories (as primary dependency)

• Criteria for determining applicability:

  • Vulnerability must affect deployed version (0.28.1)
  • Vulnerability must be exploitable in the device's internal service-to-service communication context
  • Vulnerability must impact the specific features used (AsyncClient, Client, connection pooling, timeout handling)

Signature meaning

The signatures for the approval process of this document can be found in the verified commits at the repository for the QMS. As a reference, the team members who are expected to participate in this document and their roles in the approval process, as defined in Annex I Responsibility Matrix of the GP-001, are:

• Author: Team members involved
• Reviewer: JD-003, JD-004
• Approver: JD-001