Skip to main content

Crate connector_pack

Crate connector_pack 

Source
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:

connectorsoperations
a templated host, which does not resolve at allconfluence, docusign, freshdesk, jira, mailchimp, newrelic, okta, salesforce, shopify, supabase, zendesk65
a templated path, on a host that does resolvecontentful, statuspage10

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’s execute directly, so Operation’s own permission_subjects is the only place a host’s egress allow-list is consulted for the inner call. Declaring {subdomain}.zendesk.com there asks that allow-list to match a string no host resolves to. See tool::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. See ConfigStore::get for 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. See RequestPlan.
  • The redaction set is already registered when you reach it through this crate. RequestPlan::redactions documents itself as a requirement — a consumer of connector-resolve alone must register the strings before formatting, logging or dispatching the plan. Operation::build_request_plan keeps the stronger order this crate has always kept: every value is resolved and registered with ctx.redactor before a request exists, so the field is a checkable restatement rather than the only defence. Pass the same ctx on to step 4 and the guarantee travels.
  • Nothing here dispatches for you, and nothing consults http.request’s own network gate. Egress::send calls the tool’s execute directly and therefore bypasses Executor::dispatch, exactly as this crate’s own Operation does. Step 3 is not optional; it is the gate.
  • The transport stays inside the port. Egress::send is the published dispatch seam precisely so Egress::tool can 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_credential login does not go through this path (C-136). Its answer is a credential, and Tool::execute diverts 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 the Tool projection. See Operation::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§

ConfigValue
One connection setting and the policy decision that may activate it.
Configuration
The configuration adapter a host binds when it constructs the pack.
CredentialRef
Where one tenant’s credential for one connector lives.
CredentialReference
A credential a rehearsed call would carry, named rather than resolved.
Credentials
The credential adapter a host binds when it constructs the pack.
DocumentRehearsal
One operation, rehearsed from its canonical document.
DryRun
What an operation would send — the answer a dry run gives.
DryRunTransport
The transport that cannot send.
Egress
The connector’s egress: the tool every projected operation hands its request to.
FileStore
A SecretStore kept in one file.
InstanceId
One of a tenant’s connections to a connector, named by uuid.
MemoryConfig
An in-memory ConfigStore, for a host that already holds its settings and for tests.
MemoryStore
A SecretStore held 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.
PreparedChannelPlan
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 }, exactly http.request’s own input.
RequestPlan
What one call would send, as data.
Secret
A credential value.
SensitiveText
Text that may contain credential material and therefore never reveals itself through Debug.
TenantInstances
The connections one tenant holds to one connector, and which of them an address names.
TenantLayout
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.
NameError
Why an operation id has no dotted tool name.
Slot
Where a configuration variable lands on the request.
StoreError
What a SecretStore can fail with.

Constants§

DEFAULT_SERVICE
The reserved service name CredentialRef::new elides, 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§

ConfigStore
A host’s connection settings, as the pack asks for them.
Layout
How a CredentialRef becomes a path in some store.
SecretStore
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).