Skip to content

v0.5.1

Release v0.5.1: Add HTTP Client Resource for REST API Integrations
@nshkrdotcom nshkrdotcom tagged this 21 Dec 03:45 
This release introduces FlowStone.HTTP.Client, a built-in HTTP client
resource that enables FlowStone pipelines to orchestrate external
services via REST APIs. The client follows FlowStone's Resource pattern
for configuration and lifecycle management.

New Modules:

FlowStone.HTTP.Client implements the FlowStone.Resource behaviour and
provides GET, POST, PUT, PATCH, and DELETE operations with automatic
JSON body handling. The client supports configurable base URLs, request
timeouts, default headers, and pass-through options to the underlying
Req library.

FlowStone.HTTP.Retry provides retry logic with exponential backoff for
transient failures. The module handles 5xx server errors, 429 rate limit
responses with Retry-After header support, and transport errors such as
timeouts and connection refused. Client errors in the 4xx range except
429 are not retried.

Features:

Automatic retry with exponential backoff uses configurable parameters
for max attempts, base delay, max delay, and optional jitter to prevent
thundering herd problems when multiple clients retry simultaneously.

Idempotency key support via the X-Idempotency-Key header enables safe
retries for non-idempotent operations. Servers can use these keys to
deduplicate requests that may be retried due to network issues.

Resource lifecycle methods include setup for client initialization,
teardown for cleanup, and health_check for monitoring integration via
the /health endpoint.

Telemetry Integration:

The client emits standard telemetry events following FlowStone naming
conventions:

  [:flowstone, :http, :request, :start]
  [:flowstone, :http, :request, :stop]
  [:flowstone, :http, :request, :error]

Measurements include system_time, duration, status codes, and error
reasons. Metadata provides method, URL, path, and base_url for all
events, enabling comprehensive observability through StatsD, Prometheus,
OpenTelemetry, or custom handlers.

Documentation:

Added comprehensive design documentation in docs/20251219/http-adapter/
covering the overview, detailed adapter design, configuration reference,
and telemetry reference. The README includes a new HTTP Client Resource
section with usage examples.

Testing:

Added unit tests for FlowStone.HTTP.Client covering setup configuration,
header merging, retry config merging, and struct validation. Added tests
for FlowStone.HTTP.Retry covering success paths, retry conditions for
various status codes and transport errors, exponential backoff timing,
delay capping, and jitter behavior. Added telemetry structure tests to
document expected event metadata and measurements.

Example:

Added examples/http_client_example.exs demonstrating client setup,
configuration options, HTTP operations against JSONPlaceholder API,
idempotency keys, per-request options, pipeline integration patterns,
and resource lifecycle management.

Configuration:

The client accepts the following options:
  base_url    - Required base URL for all requests
  timeout     - Request timeout in milliseconds, default 30000
  headers     - Map of default headers for all requests
  retry       - Map with max_attempts, base_delay_ms, max_delay_ms, jitter
  req_options - Pass-through options to Req library

Compatibility:

This release is fully backwards compatible. All changes are additive.
Requires Elixir 1.14 or later. Uses the existing req dependency.
Assets 2
Loading