Skip to main content

Guides · 3 of 6

Build a catalog bundle

A catalog bundle is a deterministic function of its pinned source; building it twice gives the same bytes, and nothing reaches the network.

crates/connectors-catalog/src/pipeline.rs, adapters/catalog/tests/bundle_drift.rs, docs/local-catalog-provider.md

Build a catalog bundle

The catalog provider serves operations from a bundle: a pinned API document compiled into an inventory of operations with the source's SHA-256. connectors-build catalog writes the bundle and an index.json beside it. This guide rebuilds the GitLab bundle into a scratch directory and compares it with the committed one. Run it from the repository root after cargo build --locked -p connectors-build.

Compile the pinned source​

mkdir -p target/try/bundles
target/debug/connectors-build catalog --provider gitlab \
  --source adapters/gitlab/upstream/openapi_v3.yaml \
  --amendments adapters/gitlab/upstream/openapi_v3.amendments.json \
  --directory target/try/bundles --auth-profile gitlab.pat \
  | jq '{provider, source_sha256, openapi, info_version, inventoried, unsupported}'
{
  "provider": "gitlab",
  "source_sha256": "f9e830bd3d2b99c49d60a7713fe1a64f5164418aca24b559287daab075beb530",
  "openapi": "3.0.0",
  "info_version": "19.4",
  "inventoried": 1847,
  "unsupported": 67
}

The command prints a coverage report; jq keeps its summary. --amendments applies the cited corrections the committed GitLab bundle carries (see below); without it the bundle differs from the committed one. All 1,847 operations of the pinned GitLab document are inventoried. The 67 it names as unsupported are array query parameters the source serialises with explode: false; each is sent as the one value a caller gives. The full report lists every reason with the operations it affects.

Confirm it is the committed bundle​

cmp target/try/bundles/gitlab.bundle.json adapters/catalog/generated/bundles/gitlab.bundle.json && echo identical
identical
jq '.entries[] | {provider, operations, unsupported, bundle_sha256}' target/try/bundles/index.json
{
  "provider": "gitlab",
  "operations": 1847,
  "unsupported": 67,
  "bundle_sha256": "79ce6c959045d173c45d206eaf0bfd8dcdf9ba87215df4654ff207733865025c"
}

The repository's own test does the same for every committed bundle and fails when one differs, so a bundle can only change with its source.

Sources that are not OpenAPI​

  • A Google Discovery document is first projected to OpenAPI 3.0.3 with connectors-build discovery; the bundle is then built with --derived-from naming the Discovery document, and the pipeline recomputes the projection and refuses a source that differs from it.
  • A Swagger 2.0 document is projected to OpenAPI 3.1.0 with connectors-build swagger and ingested the same way (since 0.37.0). A construct the projection has no exact row for is refused by its JSON pointer.
  • --amendments applies cited corrections to the pinned source's inventory: an optional query parameter it leaves out, or a path template written in a vendor notation, such as GitLab's (-/) optional segment, resolved without retargeting the operation. The pinned document is unchanged, and the bundle records the amendment file's SHA-256.

A bundle alone exposes nothing. A reviewed selection set under adapters/catalog/providers/<provider>/operations.json names which operations a connector serves, with each one's effect; see The catalog provider.