RPC Gateway Configuration Reference
The RPC Gateway is configured in bondy.conf using keys prefixed with rpc_gateway.services.<service_name>. Each service defines an upstream HTTP/REST API and the WAMP procedures that map to its endpoints.
INFO
If no rpc_gateway.services.* keys are present, the RPC Gateway 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 interpolation from auth variables.
Path prefix to strip from incoming request paths.
The authentication module to use. Currently only generic is supported, which provides declarative OAuth2 and API key authentication.
Upstream HTTP request timeout.
Number of retry attempts on connection failures, using exponential backoff.
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.
How long idle connections are kept in the pool.
Timeout for receiving a response from the upstream.
Whether to follow HTTP redirects.
Maximum number of redirects to follow (when enabled).
Auth: Token Acquisition
Configure how the gateway acquires authentication tokens for the upstream service.
HTTP method for the token request.
Token endpoint URL. Supports 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 interpolation. Define one line per key.
A custom header on the token request. Supports 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 interpolation.
HTTP Basic authentication password for the token request. Supports 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 as a placeholder. For example, Bearer produces the header Authorization: Bearer <token>.
Auth: Variable Bindings
Define variables for interpolation in all auth-related fields.
A named variable binding. The variable name is the $var portion of the key. Referenced as 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 many seconds before token expiry to trigger a background refresh. Set to 0 to disable preemptive refresh.
Auth: External Secrets
Resolve credentials from an external secrets provider at startup. Resolved values override static auth variables.
The secrets provider. Currently only aws_sm (AWS Secrets Manager) is supported.
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 placeholders for path variables filled from the call kwargs.
Complete Example
## ---------------------------------------------------------------
## Service: billing
## ---------------------------------------------------------------
rpc_gateway.services.billing.base_url = https://billing.example.com/api
rpc_gateway.services.billing.timeout = 15s
rpc_gateway.services.billing.retries = 2
## Connection pool
rpc_gateway.services.billing.pool.size = 25
rpc_gateway.services.billing.pool.checkout_timeout = 5s
rpc_gateway.services.billing.pool.connect_timeout = 8s
## Auth: token acquisition (OAuth2 client credentials)
rpc_gateway.services.billing.auth.fetch.method = post
rpc_gateway.services.billing.auth.fetch.url = https://idp.example.com/token
rpc_gateway.services.billing.auth.fetch.body_encoding = form
rpc_gateway.services.billing.auth.fetch.body.grant_type = client_credentials
rpc_gateway.services.billing.auth.fetch.body.client_id = {{client_id}}
rpc_gateway.services.billing.auth.fetch.body.client_secret = {{client_secret}}
rpc_gateway.services.billing.auth.fetch.token_path = access_token
rpc_gateway.services.billing.auth.fetch.expires_in_path = expires_in
## Auth: token placement
rpc_gateway.services.billing.auth.apply.placement = header
rpc_gateway.services.billing.auth.apply.name = Authorization
rpc_gateway.services.billing.auth.apply.format = Bearer {{token}}
## Auth: variable bindings
rpc_gateway.services.billing.auth.vars.client_id = my-app
rpc_gateway.services.billing.auth.vars.client_secret = s3cret
## Auth: token cache
rpc_gateway.services.billing.auth.cache.default_ttl = 1h
rpc_gateway.services.billing.auth.cache.refresh_margin = 2m
## WAMP procedure mappings
rpc_gateway.services.billing.procedures.get_invoice.uri = com.billing.get_invoice
rpc_gateway.services.billing.procedures.get_invoice.realm = com.example.myrealm
rpc_gateway.services.billing.procedures.get_invoice.method = get
rpc_gateway.services.billing.procedures.get_invoice.path = /invoices/{{id}}
rpc_gateway.services.billing.procedures.create_invoice.uri = com.billing.create_invoice
rpc_gateway.services.billing.procedures.create_invoice.realm = com.example.myrealm
rpc_gateway.services.billing.procedures.create_invoice.method = post
rpc_gateway.services.billing.procedures.create_invoice.path = /invoices
rpc_gateway.services.billing.procedures.update_invoice.uri = com.billing.update_invoice
rpc_gateway.services.billing.procedures.update_invoice.realm = com.example.myrealm
rpc_gateway.services.billing.procedures.update_invoice.method = patch
rpc_gateway.services.billing.procedures.update_invoice.path = /invoices/{{id}}
rpc_gateway.services.billing.procedures.delete_invoice.uri = com.billing.delete_invoice
rpc_gateway.services.billing.procedures.delete_invoice.realm = com.example.myrealm
rpc_gateway.services.billing.procedures.delete_invoice.method = delete
rpc_gateway.services.billing.procedures.delete_invoice.path = /invoices/{{id}}