Connector Proxy¶

A connector-proxy is an optional application that can be deployed alongside (or separately from) the frontend and backend. Please see Connector Proxy in 5 mins.

graph TD subgraph ConnectorProxy[Connector Proxy Application] direction TB ConnectorA ConnectorB end subgraph ConnectorA[Connector A] direction TB CommandA1[Command C] CommandA2[Command D] end subgraph ConnectorB[Connector B] direction TB CommandB1[Command E] CommandB2[Command F] end

Connector proxies are containers for connectors. In this repository, connectors are Python libraries that are included in connector proxy codebases, and some proxies embed connector logic directly (see the async-http example below). Our connector-proxy-demo includes a few connectors, including connector-aws, connector-http, connector-slack, and connector-smtp. Connector-http can be used for many API interactions, but you can also write your own connectors.

The connector proxy protocol defines discovery, execution, response envelopes, errors, and asynchronous callbacks. This page describes the architecture and the async HTTP example.

async-http Example¶

The async-http example demonstrates a simple and explicit connector proxy pattern:

A command discovery endpoint that returns available commands and parameter schemas
A set of execution routes, one per command
A consistent response envelope for results, with a versioned contract

Implementation notes:

Built with Falcon ASGI (falcon.asgi.App)
Uses httpx.AsyncClient for outbound requests (timeout=None in the sample)
Uses orjson for JSON parsing
Enables CORS (cors_enable=True)

Important: This implementation is intentionally minimal (for example, error handling is marked TODO) and should be hardened before production use. See Security & Production Hardening.

Running async-http with Docker Compose¶

Example compose service:

services:
  connector-proxy-async-http:
    build:
      context: connector-proxies/async-http
      dockerfile: Dockerfile
    environment:
      HOST: "0.0.0.0"
      PORT: "${CONNECTOR_PROXY_ASYNC_HTTP_PORT:-8200}"
      XDG_CACHE_HOME: "/app/.cache"
    ports:
      - "${CONNECTOR_PROXY_ASYNC_HTTP_PORT:-8200}:${CONNECTOR_PROXY_ASYNC_HTTP_PORT:-8200}/tcp"

Start the service:

docker compose up --build

By default, the port published is:

http://localhost:8200 (when CONNECTOR_PROXY_ASYNC_HTTP_PORT is not set)

API: Command Discovery¶

`GET /v1/commands`¶

The protocol reference defines the discovery response. The async-http example exposes these commands:

http/DeleteRequest
http/GetRequest
http/HeadRequest
http/PatchRequest
http/PostRequest
http/PutRequest

API: Command Execution¶

The async-http example exposes these execution routes:

POST /v1/do/http/DeleteRequest
POST /v1/do/http/GetRequest
POST /v1/do/http/HeadRequest
POST /v1/do/http/PatchRequest
POST /v1/do/http/PostRequest
POST /v1/do/http/PutRequest

Each route accepts JSON, makes an outbound request with httpx.AsyncClient.request(...), and returns the version 2 response envelope.

Parameters (`/v1/commands`)¶

The async-http discovery response advertises these parameters.

Common parameters (all commands)¶

url (required, string) — Target URL
headers (optional, any/object) — Request headers

Optional basic authentication (supported)¶

basic_auth_username (optional, string)
basic_auth_password (optional, string)

GET / HEAD commands¶

params (optional, any/object) — Query string parameters

DELETE / PATCH / POST / PUT commands¶

data (optional, any/object) — request body.
body_format (optional, string) — how to send data; defaults to json. Supported values are json, form, raw, and none.
include_response_headers (optional, boolean) — when true, include upstream response headers in command_response.headers.

Note: In this example, DeleteRequest is advertised with data (not params) in the command schema.

The embedded Arena HTTP connector also supports body_format and include_response_headers on its standard write commands.

Request and Response Examples¶

See Connector Proxy API Examples for HTTP command requests, response parsing, errors, and long-running task callbacks.

Error Handling Notes¶

The async-http example is intentionally minimal:

error is included but may not be populated in all cases
the HTTP client is configured with timeout=None

For production use, implement:

consistent error objects in error
exception handling for upstream failures and parsing errors
timeouts and retry policies appropriate for your environment

API Key Authentication¶

See the protocol’s transport security section for API-key behavior and Configure a Connector Proxy for deployment configuration.