Expand description
The connector Tool pack: this repository’s connectors, as flux tools.
// flux's own `http.request`, already configured by the host — in a host that uses flux-web,
// `Arc::new(flux_web::http::HttpRequestTool::new(&options))`.
let http = Egress::new(configured_http_request_tool);
// Where this tenant's credentials live. Bound here, never looked up globally.
let credentials = Credentials::new(host_secret_store, "9f3a4b2c")?;
// And this tenant's non-secret connection settings — the `{subdomain}` in Zendesk's base URL.
// Without it `zendesk.ticket.show` refuses rather than calling a host that does not resolve.
let configuration = Configuration::new(
// `default` is zendesk's only service; a multi-service connector names the one it means.
Arc::new(
MemoryConfig::new().with_endpoint("9f3a4b2c", "zendesk", "default", "subdomain", "acme"),
),
"9f3a4b2c",
)?;
let mut registry = ToolRegistry::new();
connector_pack::pack(&["zendesk"], http, credentials, configuration)(&mut registry)?;
assert!(registry.get("zendesk.ticket.show").is_some());or, from a host that uses flux’s SDK, the same values straight into the builder:
let http = Egress::new(Arc::new(flux_web::http::HttpRequestTool::new(&web_options)));
let credentials = Credentials::new(Arc::new(VaultStore::new(&vault)?), &tenant)?;
let configuration = Configuration::new(Arc::new(settings_for(&tenant)), &tenant)?;
let client = flux_sdk::Client::builder()
.try_register_pack(
connector_pack::pack(&["zendesk", "slack"], http, credentials, configuration),
)
.build()?;§Why a Tool pack, and not more .flux
connectors/<provider>.flux keeps shipping and keeps being the human-readable contract. This is
an additional surface, and it exists because of a naming asymmetry that no amount of
composite Flux can get around: a dotted name is not a legal Flux declaration, which is why
this repository emits zendesk-ticket-show, and every flux tool is dotted — http.request,
op.register, skill.load. flux’s reference flow calls zendesk.ticket.show. It was written
against a tool surface, and only a tool surface can spell it. See dotted_name.
The safety argument is the stronger one. As a composite, an operation inherits whatever gating
http.request happens to get. As a Tool, each operation is gated individually by flux’s
permission and approval envelope, at the risk level the connector author declared — a capability
the composite path cannot have.
§This crate still ships no runtime
It links flux’s runtime types and constructs none of it. vision.md’s non-goal stands: this
repo compiles; flux executes. A host builds the registry, binds the ports and runs the loop;
pack hands it declarations. The compiler crates — connector-spec, connector-flux,
connector-cli — link none of this, and connector-catalog stays dependency-free.
§flux keeps every byte of egress
Tool::execute derives { method, url, headers, body } — through
connector_resolve, from the canonical document’s request template (C-538)
— and hands it to flux’s own http.request, passing the same ctx. This crate opens no socket, holds no HTTP client and
resolves no host: the transport is a constructor argument, so a host supplies the instance it has
already configured with its SSRF guard, its private-network grant and its audit sink.
Since C-145 that delegation is written down as Transport, with Egress as its live arm
and DryRunTransport as the arm that cannot send — a zero-sized type, so the claim is a
property of the type rather than a flag a caller can forget. Operation::dry_run is the
surface a host asks “what request would this make?” through, and it answers before a
credential is resolved rather than after, so what it reports carries credential references and
never values. See [crate::dry_run].
That delegation calls http.request’s execute directly, which bypasses
Executor::dispatch — so http.request’s own permission_subjects and intents are never
consulted for the inner call. Both have default trait implementations returning empty, so a Tool
that omitted them would compile, register, execute, reach the vendor, and never have the host’s
network policy consulted. Operation declares both itself and tests/network_gate.rs holds
every shipped operation to it.
§The credential never reaches a surface
A credential is resolved here, assembled here — the Bearer prefix, the basic-auth base64, the
query placement — and placed on a request here, which is what dissolves the $auth blocker:
flux’s whole-value {"$secret"} marker never has to grow any of those capabilities. See
[crate::auth] for the three axes and Credentials for the port.
The order is the safety property. Every value is registered with ctx.redactor before the
request is constructed — and before any fallible step that follows resolution — so a failure
between construction and dispatch cannot surface it. flux-web’s http.rs:248 is the precedent,
and tests/credentials.rs holds it against all four surfaces Executor::dispatch scrubs.
Registration is checked, not assumed, and that is the correction C-152 made. flux’s
Redactor::add_secret silently ignores a value under six trimmed characters, so a short
credential was registered successfully and redacted nowhere, while this paragraph said otherwise.
A value the redactor does not end up holding is now Error::UnredactableCredential and is not
sent — the guarantee holds for every credential that travels, because one it cannot cover does
not travel. See docs/designs/connector-tool-pack.md for why refusing beat documenting the
threshold.
§What is not here yet
Not a gap any more: every connector can be addressed. What used to stand here was that only
two connectors could be, and C-92 left it behind. A credential’s address is
tenants/<tenant>/<authority>/<credential>, and all 53 shipped connectors declare an
authority (C-37); the “only two — slack and fly” this note once recorded was true of a
nineteen-connector fleet. A connector that declared none would still
refuse with Error::NoCredentialAddress rather than send an unauthenticated request —
fail-closed, with a diagnostic naming the missing fact instead of a vendor’s 401 — and
freshdesk, which deliberately declares no credential, still refuses that way.
The response is a record, and this pack still shapes nothing (C-403). What stood here was
that http.request returned one flat string (HTTP {status}\n{headers}\n{body}), returned
whole, and that the paragraph expired on a flux-web bump. This is that bump: from flux-web
0.43.0 the canonical ToolResult.content is the record {status, headers, body} — JSON
encoded, body parsed when the response is a JSON object or array — and the flat block is the
model-facing view. A caller reads $resp.body.data.id instead of searching a block.
The “returned whole” half did not change and is not going to. This pack delegates to the transport the host bound and hands back what it produced, so the shape is flux-web’s to decide and a consumer’s to read. That is also why the change is worth a paragraph rather than a line: nothing in this crate’s types moved, so a host that parsed the old block compiles against the new record and quietly reads the wrong thing.
§Configuration resolves through a bound port (C-193)
What used to stand here was the note that a templated base URL reached the wire verbatim. It
does not any more. Thirteen of the 53 shipped connectors declare a base_url carrying a
{placeholder} — at connector level or on one of their services — covering 75 of 299
operations, which is exactly the catalogue’s unbound-base-url-template issue count:
| connectors | operations | |
|---|---|---|
| a templated host, which does not resolve at all | confluence, docusign, freshdesk, jira, mailchimp, newrelic, okta, salesforce, shopify, supabase, zendesk | 65 |
| a templated path, on a host that does resolve | contentful, statuspage | 10 |
Both rows matter and only the first is obvious. https://api.statuspage.io/v1/pages/{page_id}
reaches a real server and asks it for a page called {page_id}, which is a 404 that reads like
a missing record rather than a connector nobody configured.
A tenant’s values reach them through Configuration, the second bound port, on the same terms
as Credentials: handed in at construction, never a global, and never the process
environment. Note that freshdesk and okta both name their variable domain — the port is
keyed by connector as well as by variable, so the two are different values rather than a
collision.
And by service (C-197), which is the same collision one level down and the one that was
live. contentful declares delivery_space_id and management_space_id, both binding
endpoint.space_id, under two services that reach two different hosts. Keyed by connector alone
they were one slot, so a management write went to whichever space the delivery reads had been
configured with — a 200 from a real server rather than a refusal. The key is now
(tenant, provider, service, kind, name); see ConfigStore::get.
Two consequences worth stating, because both are the kind that look like they work:
- Substitution is total or refused. One unbound variable is
Error::MissingConfig, naming the tenant, the connector and the field — never a request to a host with a brace in it. - The permission subject is the substituted host. The pack calls
http.request’sexecutedirectly, soOperation’s ownpermission_subjectsis the only place a host’s egress allow-list is consulted for the inner call. Declaring{subdomain}.zendesk.comthere asks that allow-list to match a string no host resolves to. Seetool::Operation::subjects. - And the port is read once, not once per call (C-198). The two bullets above are two
separate calls into the host’s
ConfigStore, so a store with interior mutability could answer the gate with one host and the request with another — through the one gate there is. Every value an operation can ask for is therefore resolved when the operation is projected, and the projected operation holds no handle to the store. SeeConfigStore::getfor the requirement that still binds a host across several operations.
And the variables are declared now, not inferred (C-538). What stood here was that this
crate reads a connector’s endpoint variables off each operation’s own emitted Flux, by scanning
string literals for braces — the honest answer while nothing published them. The canonical
document publishes them: "endpoint": {"subdomain": ["host"]} names the variable and the
position it lands in, so Operation::endpoint_variables, Operation::endpoint_slots and
Operation::caller_path_parameters are read rather than derived, and a connector whose braces
are the vendor’s own syntax is no longer a shape this crate has to classify at all.
What this still does not do is publish the whole configuration surface — the labels, help text
and binds targets that let a product render “connect your Zendesk”. That is C-87.
§The consumer contract: obtaining a plan and dispatching it yourself (C-553)
Read this before writing a Tool projection of your own. It is the contract Exchange’s
X-156 adopts and the one upstream C-541’s wrapper retirement keys on: when this crate’s
Tool-returning resolve is no longer called from any consumer path, the wrapper retires and
what remains is exactly the four calls below.
// 1. Project the operation onto the ports this host bound.
let operation = connector_pack::Operation::project(entry, http.clone(), credentials, configuration)?;
// 2. Ask for the whole plan — request, permission subjects, redaction set.
let plan = operation.build_request_plan(ctx, params).await?;
// 3. Judge the call with the host's own network policy, on the subjects the plan names.
// They are the URL *before* any credential was placed, so they are safe to quote in an
// approval prompt, a policy rule and an evidence record.
for subject in &plan.permission_subjects {
// host_policy.admit(subject)?;
}
// 4. Hand the request back to the bound transport. `Egress::tool()` is never needed.
let result = http.send(ctx, plan.request).await?;Four properties of that sequence are load-bearing, and each is a way a consumer could get the same four lines wrong:
- Project the plan; never compose one. A consumer that reads
plan.request’s parts and rebuilds a request from them has become the second request-composition path this family already rejected. Carry it across whole. SeeRequestPlan. - The redaction set is already registered when you reach it through this crate.
RequestPlan::redactionsdocuments itself as a requirement — a consumer ofconnector-resolvealone must register the strings before formatting, logging or dispatching the plan.Operation::build_request_plankeeps the stronger order this crate has always kept: every value is resolved and registered withctx.redactorbefore a request exists, so the field is a checkable restatement rather than the only defence. Pass the samectxon to step 4 and the guarantee travels. - Nothing here dispatches for you, and nothing consults
http.request’s own network gate.Egress::sendcalls the tool’sexecutedirectly and therefore bypassesExecutor::dispatch, exactly as this crate’s ownOperationdoes. Step 3 is not optional; it is the gate. - The transport stays inside the port.
Egress::sendis the published dispatch seam precisely soEgress::toolcan be refused outright by a consumer that does not want a second request path — which is the rule Exchange enforces in every one of its files. - A
produces_credentiallogin does not go through this path (C-136). Its answer is a credential, andTool::executediverts that answer into the bound store rather than returning it; the plan path derives a request and dispatches it, applying no diversion, so it would hand the caller the vendor’s token in the clear. No shipped connector mints today, but this is permanent API — such an operation must go through theToolprojection. SeeOperation::build_request_plan, “the one operation shape the plan path does not serve”.
What is not published, deliberately: Credentials::resolve and Configuration::snapshot, the
two ingredients X-156 offered as an alternative to the plan. Handing those out would put the
ordering between them — registration before construction, endpoint resolution before
substitution — in the consumer’s hands, and Decision 0022’s “enforcement topology unchanged” is
the invariant that ordering is. See Operation::build_request_plan for the four steps it
applies and docs/designs/catalog-artifact.md §3 for the written decision.
Structs§
- Config
Value - One connection setting and the policy decision that may activate it.
- Configuration
- The configuration adapter a host binds when it constructs the pack.
- Credential
Ref - Where one tenant’s credential for one connector lives.
- Credential
Reference - A credential a rehearsed call would carry, named rather than resolved.
- Credentials
- The credential adapter a host binds when it constructs the pack.
- Document
Rehearsal - One operation, rehearsed from its canonical document.
- DryRun
- What an operation would send — the answer a dry run gives.
- DryRun
Transport - The transport that cannot send.
- Egress
- The connector’s egress: the tool every projected operation hands its request to.
- File
Store - A
SecretStorekept in one file. - Instance
Id - One of a tenant’s connections to a connector, named by uuid.
- Memory
Config - An in-memory
ConfigStore, for a host that already holds its settings and for tests. - Memory
Store - A
SecretStoreheld in memory. - Operation
- A projected operation: its catalogue entry, the spec a host resolves it by, the declaration its request is built from, and the transport it delegates to.
- Prepared
Channel Plan - A complete RFC 6455 handshake plan containing no client, socket, resolver or runtime.
- Rehearsal
- One operation, rehearsed from its emitted Flux.
- Request
- The request:
{ method, url, headers, body }, exactlyhttp.request’s own input. - Request
Plan - What one call would send, as data.
- Secret
- A credential value.
- Sensitive
Text - Text that may contain credential material and therefore never reveals itself through
Debug. - Tenant
Instances - The connections one tenant holds to one connector, and which of them an address names.
- Tenant
Layout - The default layout:
tenants/<tenant>/<authority>/<service>/<credential>.
Enums§
- Error
- Why a pack could not be installed.
- Field
- Which non-secret value is being asked for.
- Name
Error - Why an operation id has no dotted tool name.
- Slot
- Where a configuration variable lands on the request.
- Store
Error - What a
SecretStorecan fail with.
Constants§
- DEFAULT_
SERVICE - The reserved service name
CredentialRef::newelides, spelled here because a credential is declared at provider level and therefore always addresses it. - DEFAULT_
USER_ AGENT - What this software calls itself on the wire (C-223).
Traits§
- Config
Store - A host’s connection settings, as the pack asks for them.
- Layout
- How a
CredentialRefbecomes a path in some store. - Secret
Store - A place a tenant’s credentials are kept.
- Transport
- Where a built request goes.
Functions§
- channel_
plan - Compose a generated socket channel from catalogue declarations and bound tenant ports.
- dotted_
name - Project an operation id onto the dotted name flux resolves a tool by.
- is_
exposed - Whether this catalogue operation reaches a model as an LLM tool (C-413).
- pack
- The pack. Install every exposed operation of each named provider into a host’s registry.
- project
- Project one catalogue operation onto the spec a host registers it by.
- resolve
- One operation, resolved for execution — exposed or not (C-413).