Skip to main content

Crate catalog

Crate catalog 

Source
Expand description

Every generated connector operation, embedded at compile time.

This is flux-connectors made consumable with cargo add instead of by copying artifacts into ~/.flux/flows. Adding the crate is getting the catalog: every operation’s Flux source and the metadata a caller needs to decide whether to run it are &'static data baked into the binary by include_str! and a generated table. There is no filesystem lookup, no parsing and no initialization; the one dependency is reader — the embedded catalog pack, itself dependency-free (C-537).

It stays inside the charter (AGENTS.md): a library that hands out text, not a runtime. Nothing here executes an operation or touches the network — flux does that, from the module it loads.

use catalog::{OperationKey, ProviderKey, Risk};

let show = catalog::operation(OperationKey::id("zendesk-ticket-show")).unwrap();
assert_eq!(show.risk, Risk::Low);
assert!(show.flux.starts_with("op zendesk-ticket-show("));

// "every operation in this provider" is one call.
let zendesk = catalog::operations_of(ProviderKey::id("zendesk"));
assert!(zendesk.iter().all(|operation| operation.provider == "zendesk"));

§What is generated and what is not

flux-connectors build writes three kinds of file into this crate, all committed and reviewed like every other generated artifact in the repository. Nothing here is hand-written.

  • ops/<provider>/<operation>.flux — one rendering per operation, byte for byte the same text the provider’s module carries for it;
  • src/generated/<provider>.rs — the table that embeds those renderings alongside their metadata;
  • src/generated.rs — [generated], the index naming every provider’s module.

The first two are per provider, so flux-connectors build --provider zendesk regenerates exactly what it compiled. The index is not: it names every provider at once, so it is written by a full build only and a scoped run leaves the committed file untouched rather than rendering an index that drops the providers the run never looked at. web/public/catalog.json follows the same rule for the same reason.

It was hand-written until C-104 on exactly that reasoning, and the cost was structural: two lines per provider, appended by hand, made this the one file every provider story touched — so any two provider stories conflicted and connectors shipped one at a time. tests/embedded_operations.rs still holds the list against providers/, which is now a staleness check on a committed artifact rather than a reminder to add a line.

crates/connector-cli/tests/catalog_artifacts.rs is what makes the embedded data a checked artifact: it recomputes everything here from providers/*.toml and compares byte for byte, so a stale catalog — which still compiles and still answers every query — fails the build.

§The per-provider module is still what ships

connectors/<provider>.flux is unchanged in role: it is the artifact flux loads from ~/.flux/flows, and it declares every one of that provider’s operations. The renderings here are additional — the catalog’s unit, not a substitute for the module — and each one is a substring of it (tests/embedded_operations.rs pins that).

§Addressing, and what C-37 changes

Operations are keyed today by Operation::id, the declarable Flux symbol (zendesk-ticket-show). C-37 introduces a global address — an oip such as com.zendesk.api/support/tickets:v2#show — and the key types here exist so that lands additively: OperationKey and ProviderKey are opaque, constructed only through named constructors, so C-37 adds OperationKey::oip and ProviderKey::pid and no signature in this crate moves. There is deliberately no From<&str> for either: a bare string cannot say whether it is a symbol or an address, and guessing is exactly the ambiguity two identifiers exist to avoid.

§The embedded pack, and what this crate is becoming (C-537)

Decision 0022 (C-535) makes the compile destination a catalog artifact: one canonical JSON document per provider (C-536), compiled into one versioned, digest-carrying pack. This crate is the shim over that pack — it embeds it through reader and re-exports the reader whole, so every consumer of the catalogue already holds the document form of every operation:

let show = catalog::reader::operation("zendesk-ticket-show").unwrap();
assert_eq!(show.provider(), "zendesk");
assert!(show.record().contains("\"id\": \"zendesk-ticket-show\""));

The &'static tables beneath the API above remain generated Rust for now, because this API promises what the documents deliberately no longer carry — Operation::flux, the emitted Flux text the documents replaced with a request template — and connector-pack still parses it. They reduce to the pack when C-540 retires the emitter; the deferral and its reasons are recorded in docs/designs/catalog-artifact.md §2. Nothing in this crate’s public API moved to make room for the pack: the re-export is additive, which is what “no breaking change” means here, and tests/consumer_api.rs compiles the whole promised surface to hold that line.

Re-exports§

pub use catalog_reader as reader;

Structs§

Channel
One generated channel binding. Verification/reply/setup remain available in the manifest and public catalogue; this embedded shape carries every fact the zero-I/O socket planner and generic event router require.
Choice
One permitted value of a ConfigChoices set, and the text a renderer shows for it.
ConfigChoices
One configuration field that permits a closed set of values, and the set — C-225.
ConfigField
One complete configuration field, with no stored value.
Credential
One credential a connector declares: what it is called, where its value is kept, and how it reaches the wire.
Event
One event declaration, including the local/wire identity split.
OAuth2
How a host obtains an OAuth2-backed credential. Mirrors connector_spec::OAuth2Spec.
OAuthRedirect
The loopback redirect an authorization_code login binds. Mirrors connector_spec::OAuthRedirect.
Operation
One operation: its Flux source, and what a caller needs in order to decide whether to use it.
OperationKey
How a caller names one operation.
Pair
One string pair in a generated declaration (query, header or payload mapping).
Provider
One connector, and every operation the catalog carries for it.
ProviderKey
How a caller names one provider.
Selector
One selector into an inbound envelope.
SocketConnect
The generic RFC 6455 handshake facts for one socket binding.

Enums§

Acquisition
How stored material becomes the value that is placed — the acquisition axis.
Approval
Extra authorization required before a supplied configuration value becomes active.
AuthHazard
A named weakness in how a credential is obtained (C-440). Mirrors connector_spec::AuthHazard.
ChannelTransport
How an event reaches a connector binding.
CredentialRequirement
Why an operation names the credentials it does — and, when it names none, which of the two opposite reasons that is (C-235).
Idempotency
Whether repeating an operation is safe, in flux’s own vocabulary.
OAuthGrant
One token grant an OAuth2 credential allows. Mirrors connector_spec::OAuthGrant.
OperationDirection
The connector-authored vendor-state direction of an operation.
Placement
Where a credential goes on the way out — the placement axis of docs/designs/unified-auth.md.
Risk
How much damage an operation can do, in flux’s own vocabulary.
Runtime
How a connector executes — flux’s runtime axis, as the catalogue publishes it (C-405).
Subject
Whose authority a credential carries when it is used (C-528). Mirrors connector_spec::Subject.

Functions§

operation
The lookup. One operation by key, with its Flux source and its metadata.
operations
Every operation in the catalog, provider by provider.
operations_of
Every operation in one provider — the listing that makes a provider addressable rather than merely nameable.
provider
One provider, by key.
providers
Every provider in the catalog, ordered by Provider::id.