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
ConfigChoicesset, and the text a renderer shows for it. - Config
Choices - One configuration field that permits a closed set of values, and the set — C-225.
- Config
Field - 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. - OAuth
Redirect - The loopback redirect an
authorization_codelogin binds. Mirrorsconnector_spec::OAuthRedirect. - Operation
- One operation: its Flux source, and what a caller needs in order to decide whether to use it.
- Operation
Key - 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.
- Provider
Key - How a caller names one provider.
- Selector
- One selector into an inbound envelope.
- Socket
Connect - 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.
- Auth
Hazard - A named weakness in how a credential is obtained (C-440). Mirrors
connector_spec::AuthHazard. - Channel
Transport - How an event reaches a connector binding.
- Credential
Requirement - 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.
- OAuth
Grant - One token grant an
OAuth2credential allows. Mirrorsconnector_spec::OAuthGrant. - Operation
Direction - 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.