Vaultx.Transport.HTTPBehaviour behaviour (Vaultx v0.7.0)

View Source

Behaviour definition for HashiCorp Vault HTTP transport implementations.

This behaviour defines the comprehensive interface that HTTP transport implementations must implement for secure, reliable communication with Vault servers. It ensures consistency across different HTTP client implementations and testing scenarios.

Design Requirements

  • Type Safety: All operations use well-defined types
  • Error Handling: Structured error responses with context
  • Security: Support for authentication and SSL/TLS
  • Performance: Efficient request/response handling
  • Testability: Easy mocking and testing support

Implementation Guidelines

HTTP transport implementations should:

  • Handle all standard HTTP methods (GET, POST, PUT, DELETE, PATCH)
  • Support request/response body encoding/decoding
  • Implement proper error handling and classification
  • Provide detailed error context for debugging
  • Support authentication headers and tokens

References

Summary

Callbacks

request(http_method, t, body, headers, options)

Makes an HTTP request to the specified URL.

Callbacks

request(http_method, t, body, headers, options)

@callback request(
  Vaultx.Types.http_method(),
  String.t(),
  Vaultx.Types.body(),
  Vaultx.Types.headers(),
  Vaultx.Types.options()
) :: Vaultx.Types.http_result()

Makes an HTTP request to the specified URL.

Parameters

  • method - HTTP method (:get, :post, :put, :patch, :delete)
  • url - Full URL to make the request to
  • body - Request body (map, string, or nil)
  • headers - List of HTTP headers as tuples
  • opts - Additional options for the request

Returns

  • {:ok, response} - Successful response with status, body, and headers
  • {:error, %Vaultx.Base.Error{}} - Request failed with detailed error

Examples

iex> HTTPClient.request(:get, "https://vault.example.com/v1/sys/health", nil, [], [])
{:ok, %{status: 200, body: %{"initialized" => true}, headers: []}}

iex> HTTPClient.request(:post, "https://vault.example.com/v1/auth/token/create", %{}, [], [])
{:ok, %{status: 200, body: %{"auth" => %{"client_token" => "hvs.123"}}, headers: []}}