HTTP Connector Configuration Reference
The HTTP Connector is configured in bondy.conf using keys prefixed with http_connector.services.<service_name>. Each service defines an upstream HTTP/REST API and the WAMP procedures that map to its endpoints.
INFO
If no http_connector.services.* keys are present, the HTTP Connector subsystem starts but remains idle with no resource overhead.
Service Settings
The upstream service base URL. All procedure paths are appended to this URL. Supports {{var}} interpolation from auth variables.
Path prefix to strip from incoming request paths.
The authentication module to use. The only supported value is generic, which provides declarative OAuth2 and API key authentication.
Deadline for a whole call to a procedure of this service, measured from its start and including every retry. Each attempt gets only the time left before the deadline. The connector skips a retry whose backoff wait would end past the deadline. A call that reaches the deadline without an upstream response fails with bondy.error.gateway_timeout (status 504).
Number of retry attempts on transport failures, using jittered exponential backoff. After an HTTP response, the connector retries only a 401 or 403, once, with a fresh token. It never retries while the service's pool is down.
Whether Bondy verifies the upstream service's TLS certificate when base_url uses https. With verify_peer, Bondy checks the certificate against the trust store managed by the certificate manager. With verify_none, Bondy skips verification for this service only: the connection is still encrypted, but the upstream is not authenticated. Use verify_none only for development or testing.
The setting applies to the service's connection pool, so it covers every procedure mapped to the service.
Connection Pool
Each service gets a dedicated HTTP connection pool.
Maximum number of connections in the pool.
Timeout for acquiring a connection from the pool.
TCP connection timeout. On a call to a procedure, the connector replaces it with the time left before the service's timeout.
How long idle connections are kept in the pool.
Timeout for receiving a response from the upstream. On a call to a procedure, the connector replaces it with the time left before the service's timeout.
Whether to follow HTTP redirects.
Maximum number of redirects to follow (when enabled).
Liveness Probe
While a service's pool is up, a self-rearming periodic probe checks the upstream and raises an alarm if it starts failing — catching a degrading service before a live WAMP call fails against it. This is separate from the one-shot startup/recovery health check (used while the pool is already down), which always runs regardless of this setting.
Enables the periodic up-state liveness probe for this service.
The path probed on the service's endpoint. The default / probes the bare base_url, identical to the startup health check.
The HTTP method used for the probe.
How often the probe runs while the pool is up.
Connect/receive timeout for a single probe request.
Consecutive probe failures required before the pool is marked down and the service-down alarm is raised. Guards against flapping on a single transient blip. A probe succeeds on any HTTP response, whatever its status, and fails when the request itself fails. While the pool is down, calls to the service fail at once with wamp.error.unavailable (status 503).
Consecutive successful probes required, once a service recovers, before the service-down alarm is cleared. The pool itself is marked up (and starts serving calls again) fail-open on the very first successful probe regardless of this setting — only alarm clearing is gated, so a flapping upstream doesn't flap the page while still resuming traffic as soon as it's reachable.
Alarms
After failure_threshold consecutive failures, Bondy raises an OTP alarm with id {http_connector_service_down, ServiceName}. It's counted by the existing bondy_alarms / bondy_alarm_active{alarm_id} Prometheus metrics and appears in the bundled Grafana dashboard's active-alarms panel — no separate exposition needed.
Auth: Token Acquisition
Configure how the connector acquires authentication tokens for the upstream service.
HTTP method for the token request.
Token endpoint URL. Supports {{var}} interpolation.
How to encode the token request body:
form— URL-encoded form (application/x-www-form-urlencoded)json— JSON (application/json)none— No body
A key-value pair in the token request body. Supports {{var}} interpolation. Define one line per key.
A custom header on the token request. Supports {{var}} interpolation.
Dot-separated JSON path to the token in the response (e.g. access_token or data.token).
Dot-separated JSON path to the error message in the response.
Dot-separated JSON path to the token TTL (in seconds) in the response.
HTTP Basic authentication username for the token request. Supports {{var}} interpolation.
HTTP Basic authentication password for the token request. Supports {{var}} interpolation.
Auth: Token Placement
Configure how the acquired token is applied to upstream requests.
Where to place the token on upstream requests.
The header name or query parameter name.
Format template for the token value. Use {{token}} as a placeholder. For example, Bearer {{token}} produces the header Authorization: Bearer <token>. Unset, the connector sends the raw token.
Auth: Variable Bindings
Define variables for {{var}} interpolation in all auth-related fields.
A named variable binding. The variable name is the $var portion of the key. Referenced as {{var}} in auth URLs, headers, body values, and basic auth credentials.
Auth: Token Cache
Default token TTL when the token response does not include an expires_in value.
How long before token expiry the connector starts a background refresh. Set to 0 to disable preemptive refresh: the connector then fetches a new token synchronously on the first request after expiry.
Auth: External Secrets
Resolve credentials from an external secrets provider at startup. Resolved values override static auth variables.
The secrets provider. The only supported value is aws_sm (AWS Secrets Manager).
The secret identifier — an ARN or secret name.
The AWS region where the secret is stored.
The JSON field name in the secret to extract for this variable.
Transform to apply to the extracted value:
none— Use the raw valuebasic_username— Decode aBasic base64(user:pass)value and extract the usernamebasic_password— Decode aBasic base64(user:pass)value and extract the password
Procedure Mappings
Map WAMP procedure URIs to upstream HTTP endpoints. Each procedure is identified by a short name ($proc) used only as a configuration key.
The WAMP procedure URI to register (e.g. com.billing.get_invoice). Required.
The Bondy realm to register the procedure in. Required.
The HTTP method for the upstream request.
The URL path template. Use {{var}} placeholders for path variables filled from the call kwargs.
Complete Example
## ---------------------------------------------------------------
## Service: billing
## ---------------------------------------------------------------
http_connector.services.billing.base_url = https://billing.example.com/api
http_connector.services.billing.timeout = 15s
http_connector.services.billing.retries = 2
## Connection pool
http_connector.services.billing.pool.size = 25
http_connector.services.billing.pool.checkout_timeout = 5s
http_connector.services.billing.pool.connect_timeout = 8s
## Liveness probe
http_connector.services.billing.liveness.enabled = on
http_connector.services.billing.liveness.path = /
http_connector.services.billing.liveness.method = head
http_connector.services.billing.liveness.interval = 30s
http_connector.services.billing.liveness.timeout = 5s
http_connector.services.billing.liveness.failure_threshold = 3
http_connector.services.billing.liveness.success_threshold = 1
## Auth: token acquisition (OAuth2 client credentials)
http_connector.services.billing.auth.fetch.method = post
http_connector.services.billing.auth.fetch.url = https://idp.example.com/token
http_connector.services.billing.auth.fetch.body_encoding = form
http_connector.services.billing.auth.fetch.body.grant_type = client_credentials
http_connector.services.billing.auth.fetch.body.client_id = {{client_id}}
http_connector.services.billing.auth.fetch.body.client_secret = {{client_secret}}
http_connector.services.billing.auth.fetch.token_path = access_token
http_connector.services.billing.auth.fetch.expires_in_path = expires_in
## Auth: token placement
http_connector.services.billing.auth.apply.placement = header
http_connector.services.billing.auth.apply.name = Authorization
http_connector.services.billing.auth.apply.format = Bearer {{token}}
## Auth: variable bindings
http_connector.services.billing.auth.vars.client_id = my-app
http_connector.services.billing.auth.vars.client_secret = s3cret
## Auth: token cache
http_connector.services.billing.auth.cache.default_ttl = 1h
http_connector.services.billing.auth.cache.refresh_margin = 2m
## WAMP procedure mappings
http_connector.services.billing.procedures.get_invoice.uri = com.billing.get_invoice
http_connector.services.billing.procedures.get_invoice.realm = com.example.myrealm
http_connector.services.billing.procedures.get_invoice.method = get
http_connector.services.billing.procedures.get_invoice.path = /invoices/{{id}}
http_connector.services.billing.procedures.create_invoice.uri = com.billing.create_invoice
http_connector.services.billing.procedures.create_invoice.realm = com.example.myrealm
http_connector.services.billing.procedures.create_invoice.method = post
http_connector.services.billing.procedures.create_invoice.path = /invoices
http_connector.services.billing.procedures.update_invoice.uri = com.billing.update_invoice
http_connector.services.billing.procedures.update_invoice.realm = com.example.myrealm
http_connector.services.billing.procedures.update_invoice.method = patch
http_connector.services.billing.procedures.update_invoice.path = /invoices/{{id}}
http_connector.services.billing.procedures.delete_invoice.uri = com.billing.delete_invoice
http_connector.services.billing.procedures.delete_invoice.realm = com.example.myrealm
http_connector.services.billing.procedures.delete_invoice.method = delete
http_connector.services.billing.procedures.delete_invoice.path = /invoices/{{id}}