Connector image HTTP contract

Exact HTTP surface of the Ads Sync connector images, the metadata verification consumers must do, and the build inputs that produce the images.

Every Ads Sync connector image runs one Python HTTP wrapper, airbyte-source-server.py, in front of a pinned Airbyte connector. A Qualified Run talks to that wrapper over HTTP; it never runs the connector command directly. This page is the wrapper contract for wrapper version ads-sync-wrapper-v0.5.

The build inputs live in the Ads Sync Reference Deployment at packages/ads-sync/deploy/images/. Consumers build the images themselves; the project publishes Dockerfiles, not built images.

images

The pins equal supportedImageVersions in @patronage/ads-sync. Each Dockerfile also sets AIRBYTE_CONNECTOR_IMAGE to the same reference; /metadata reports it as connectorImage. Dockerfile.gsc.access-token is a build variant of Dockerfile.gsc; Dockerfile.postgres.preprovisioned is a build variant of Dockerfile.postgres. Each variant declares # ads-sync-build-variant-of: <reference>. Hosted Loop and Alchemy build those siblings because Alchemy’s external-Dockerfile path cannot pass --build-arg. The reference files keep the build arguments for one-off builds.

build command

IMAGE_REGISTRY=registry.example.com/ads-sync bash build-images.sh --push

Run build-images.sh with bash from packages/ads-sync/deploy/images/; the public tree does not preserve the executable bit. Without --push it loads the images into the local Docker daemon. IMAGE_TAG defaults to 0.3.0 and IMAGE_PLATFORM to linux/amd64. IMAGES defaults to google-ads gsc meta postgres. The hosted variants are gsc-access-token (Dockerfile.gsc.access-token) and postgres-preprovisioned (Dockerfile.postgres.preprovisioned); they take no mode arguments.

exact-match build steps

Each patch script requires the pinned upstream text to match exactly once. On any drift it exits non-zero and the image build fails. The defaults are the single-tenant mode: the operator owns the Google refresh token, and the destination writer role has database-level CREATE so Airbyte owns schema DDL. Hosted Loop builds Dockerfile.gsc.access-token and Dockerfile.postgres.preprovisioned instead of passing those arguments. PlanetScale destination configs omit ssl_mode and set jdbc_url_params to sslmode=verify-full&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory, so the connector cannot replace certificate and hostname verification with its weaker require mode.

wrapper environment

endpoints

The wrapper listens on port 8080 on all interfaces (0.0.0.0). Control responses are JSON; artifact routes stream NDJSON or text.

network posture

The wrapper has no authentication on any route. Under Cloudflare Containers the port is reachable only through the Durable Object binding, and that network isolation is the only access control. Destination sessions run a write with a caller-supplied config, and /network-check opens a TCP connection to a caller-supplied host on an allowlisted port. Do not expose the container port on a host or a shared network. When you run an image outside Cloudflare Containers (for example under docker run for provider admission), bind the port to loopback only. Explicit session deletion removes the artifact spool and any credential-bearing config or catalog files, including a destination session deleted before its messages endpoint is called.

Any POST body must be a JSON object; a missing, non-JSON, or non-object body returns 400 { "error": ... }.

/metadata

{
  "buildOptions": "postgres_schema_mode=airbyte_owned",
  "connectorImage": "airbyte/destination-postgres:3.0.13@sha256:0b310bd46ba0e006757ea3dc1d3b8ef8e3bcf51c3a96f5460a836653b5ac4f4c",
  "service": "airbyte-postgres-destination",
  "status": "ok",
  "wrapperVersion": "ads-sync-wrapper-v0.5"
}

buildOptions is an empty string on images without build modes.

artifact receipt

/read-sessions and the destination messages endpoint return a small receipt. Artifact bodies never appear in JSON:

{
  "args": ["read", "--config", "<config>", "--catalog", "<config>"],
  "exitCode": 0,
  "sessionId": "source-123",
  "stderrLength": 1234,
  "stderrSha256": "…",
  "stdoutLength": 56789,
  "stdoutSha256": "…",
  "success": true
}

args redacts every temporary JSON path as <config>. The status is 200 when the connector exits 0 and 502 otherwise. The wrapper drains stdout and stderr concurrently into bounded files on ephemeral container disk, hashing and counting bytes as it goes. The Qualified Run then streams those files into R2, redacting diagnostic lines and computing the durable manifest without assembling the artifact in Worker memory.

The wrapper writes each request object to a temporary file for the connector process. It enters the cleanup block before the first write, so a failed later write (for example, disk full while writing the catalog) still deletes the config file that holds the credential.

When the connector exceeds the wall-clock budget the wrapper returns 504 { "args": [...], "error": "Connector timed out" }. The wrapper starts the connector with a 30-second inner margin (60 seconds for a destination write) so the connector process ends before the HTTP budget does.

The connector always gets at least 30 seconds inside the budget. When AIRBYTE_READ_TIMEOUT_SECONDS or AIRBYTE_WRITE_TIMEOUT_SECONDS is smaller than the inner margin plus that floor (60 seconds for a source read, 90 for a destination write), the wrapper does not start the connector. It returns 500 { "args": [...], "error": "Connector timeout budget is too small", "minimumTimeoutSeconds": <n>, "timeoutSeconds": <configured> }. This is an image configuration error, not a run result.

source sessions

config and catalog must be objects; state is optional and passed through as --state. The wrapper runs the read, deletes credential-bearing input files, and returns a receipt. The caller streams stdout and stderr from the session routes, then deletes the session. A repeated live sessionId returns 409.

destination sessions

Create the session with config and catalog, then stream newline-delimited Airbyte messages to its /messages endpoint. An exact length is required before the connector starts: x-airbyte-content-length, or Content-Length when that header is still present. Cloudflare may strip Content-Length from a streamed container fetch; the Qualified Run seam therefore sends both. Transfer-Encoding: chunked is accepted when it is the only transfer encoding, and the decoded body must equal the declared length. The wrapper spools the request to bounded ephemeral disk and supplies that file as connector stdin. The receipt also reports inputLength and inputSha256; the caller verifies both against the stream it sent before accepting the write. State commit remains the caller’s decision after a successful write.

/network-check

host must be a non-empty hostname string and port an integer in the AIRBYTE_NETWORK_CHECK_PORTS allowlist; other values return 400. The wrapper opens one TCP connection with a 10-second timeout and does not send data or credentials.

{
  "connected": true,
  "trustStore": {
    "destinationOptionsPresent": true,
    "keytoolReadable": true,
    "path": "/app/java-cacerts",
    "readable": true
  }
}

trustStore is null on images without AIRBYTE_JAVA_TRUST_STORE. A failed connection returns 502 { "connected": false, "errorType": "<Python exception class>" }, for example TimeoutError (timeout on the older Python in the pinned destination image) or ConnectionRefusedError. Use it as an image-level readiness probe for the destination: it proves the container can reach the Postgres host and that the pinned JVM trust store is readable before a /write spends the connector budget.

metadata verification

Before the first connector call of every Qualified Run, the consumer must:

1. GET /metadata.
2. Compare connectorImage with supportedImageVersions[provider] (or supportedImageVersions.destination) as an exact string, digest included.
3. Compare wrapperVersion with the exact string ads-sync-wrapper-v0.5.
4. Fail the run on any mismatch. Do not retry a mismatch; a responding wrapper with the wrong image or version is a deployment error, not a transient condition.

Prefix, tag-only, or semver-range comparisons are not the contract. The pins are what the tests in packages/ads-sync/deploy/images/images.test.ts and the Qualified Run seam assert.

cold-start retry

A newly started Cloudflare Container can answer /metadata with a transient platform error, or refuse the connection, before the wrapper process listens. The Qualified Run seam performs a bounded, unavailable-only retry:

• retry only when the request did not reach a healthy wrapper: connection failure, or any 5xx response (the body is not inspected on a 5xx);
• never retry a 200 whose fields mismatch, and never retry a 4xx;
• stop after the bounded attempt budget and fail the run.

The retry is seam behavior. A consumer that calls the wrapper directly must implement the same rule; the wrapper itself has no retry.

versioning

WRAPPER_VERSION in airbyte-source-server.py changes whenever this contract changes. Consumers pin the exact string; the seam and the internal Paitronage app pin ads-sync-wrapper-v0.5. Adding an endpoint, changing a response field, or changing an error status is a version bump.