connector_pack/lib.rs
1//! The connector Tool pack: this repository's connectors, as flux tools.
2//!
3//! ```no_run
4//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
5//! # use std::sync::Arc;
6//! # use connector_pack::{Configuration, Credentials, Egress, MemoryConfig, SecretStore};
7//! # use flux_runtime::{Tool, ToolRegistry};
8//! # let configured_http_request_tool: Arc<dyn Tool> = flux_runtime::tool_fn(
9//! # flux_spec::ToolSpec { name: "http.request".into(), description: String::new(),
10//! # input_schema: serde_json::json!({}), output_schema: None, effects: Vec::new(),
11//! # risk: flux_spec::Risk::Medium, idempotency: flux_spec::Idempotency::NonIdempotent,
12//! # access: Vec::new(), group: None },
13//! # |params| async move { Ok(params) });
14//! # let host_secret_store: Arc<dyn SecretStore> =
15//! # Arc::new(connector_pack::MemoryStore::new());
16//! // flux's own `http.request`, already configured by the host — in a host that uses flux-web,
17//! // `Arc::new(flux_web::http::HttpRequestTool::new(&options))`.
18//! let http = Egress::new(configured_http_request_tool);
19//! // Where this tenant's credentials live. Bound here, never looked up globally.
20//! let credentials = Credentials::new(host_secret_store, "9f3a4b2c")?;
21//! // And this tenant's non-secret connection settings — the `{subdomain}` in Zendesk's base URL.
22//! // Without it `zendesk.ticket.show` refuses rather than calling a host that does not resolve.
23//! let configuration = Configuration::new(
24//! // `default` is zendesk's only service; a multi-service connector names the one it means.
25//! Arc::new(
26//! MemoryConfig::new().with_endpoint("9f3a4b2c", "zendesk", "default", "subdomain", "acme"),
27//! ),
28//! "9f3a4b2c",
29//! )?;
30//!
31//! let mut registry = ToolRegistry::new();
32//! connector_pack::pack(&["zendesk"], http, credentials, configuration)(&mut registry)?;
33//!
34//! assert!(registry.get("zendesk.ticket.show").is_some());
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! or, from a host that uses flux's SDK, the same values straight into the builder:
40//!
41//! ```ignore
42//! let http = Egress::new(Arc::new(flux_web::http::HttpRequestTool::new(&web_options)));
43//! let credentials = Credentials::new(Arc::new(VaultStore::new(&vault)?), &tenant)?;
44//! let configuration = Configuration::new(Arc::new(settings_for(&tenant)), &tenant)?;
45//! let client = flux_sdk::Client::builder()
46//! .try_register_pack(
47//! connector_pack::pack(&["zendesk", "slack"], http, credentials, configuration),
48//! )
49//! .build()?;
50//! ```
51//!
52//! # Why a Tool pack, and not more `.flux`
53//!
54//! `connectors/<provider>.flux` keeps shipping and keeps being the human-readable contract. This is
55//! an **additional** surface, and it exists because of a naming asymmetry that no amount of
56//! composite Flux can get around: a **dotted name is not a legal Flux declaration**, which is why
57//! this repository emits `zendesk-ticket-show`, and **every flux tool is dotted** — `http.request`,
58//! `op.register`, `skill.load`. flux's reference flow calls `zendesk.ticket.show`. It was written
59//! against a tool surface, and only a tool surface can spell it. See [`dotted_name`].
60//!
61//! The safety argument is the stronger one. As a composite, an operation inherits whatever gating
62//! `http.request` happens to get. As a Tool, each operation is gated **individually** by flux's
63//! permission and approval envelope, at the risk level the connector author declared — a capability
64//! the composite path cannot have.
65//!
66//! # This crate still ships no runtime
67//!
68//! It links flux's runtime types and constructs none of it. `vision.md`'s non-goal stands: *this
69//! repo compiles; flux executes.* A host builds the registry, binds the ports and runs the loop;
70//! [`pack`] hands it declarations. The compiler crates — `connector-spec`, `connector-flux`,
71//! `connector-cli` — link none of this, and `connector-catalog` stays dependency-free.
72//!
73//! # flux keeps every byte of egress
74//!
75//! `Tool::execute` derives `{ method, url, headers, body }` — through
76//! [`connector_resolve`](connector_resolve), from the canonical document's request template (C-538)
77//! — and hands it to flux's own `http.request`, passing the **same** `ctx`. This crate opens no socket, holds no HTTP client and
78//! resolves no host: the transport is a constructor argument, so a host supplies the instance it has
79//! already configured with its SSRF guard, its private-network grant and its audit sink.
80//!
81//! Since C-145 that delegation is written down as [`Transport`], with [`Egress`] as its live arm
82//! and [`DryRunTransport`] as the arm that **cannot** send — a zero-sized type, so the claim is a
83//! property of the type rather than a flag a caller can forget. [`Operation::dry_run`] is the
84//! surface a host asks "what request would this make?" through, and it answers *before* a
85//! credential is resolved rather than after, so what it reports carries credential references and
86//! never values. See [`crate::dry_run`].
87//!
88//! That delegation calls `http.request`'s `execute` directly, which **bypasses
89//! `Executor::dispatch`** — so `http.request`'s own `permission_subjects` and `intents` are never
90//! consulted for the inner call. Both have default trait implementations returning empty, so a Tool
91//! that omitted them would compile, register, execute, reach the vendor, and never have the host's
92//! network policy consulted. [`Operation`] declares both itself and `tests/network_gate.rs` holds
93//! every shipped operation to it.
94//!
95//! # The credential never reaches a surface
96//!
97//! A credential is resolved here, assembled here — the `Bearer ` prefix, the basic-auth base64, the
98//! query placement — and placed on a request here, which is what dissolves the `$auth` blocker:
99//! flux's whole-value `{"$secret"}` marker never has to grow any of those capabilities. See
100//! [`crate::auth`] for the three axes and [`Credentials`] for the port.
101//!
102//! The order is the safety property. Every value is registered with `ctx.redactor` **before the
103//! request is constructed** — and before any fallible step that follows resolution — so a failure
104//! between construction and dispatch cannot surface it. `flux-web`'s `http.rs:248` is the precedent,
105//! and `tests/credentials.rs` holds it against all four surfaces `Executor::dispatch` scrubs.
106//!
107//! Registration is *checked*, not assumed, and that is the correction C-152 made. flux's
108//! `Redactor::add_secret` silently ignores a value under six trimmed characters, so a short
109//! credential was registered successfully and redacted nowhere, while this paragraph said otherwise.
110//! A value the redactor does not end up holding is now [`Error::UnredactableCredential`] and **is not
111//! sent** — the guarantee holds for every credential that travels, because one it cannot cover does
112//! not travel. See `docs/designs/connector-tool-pack.md` for why refusing beat documenting the
113//! threshold.
114//!
115//! # What is not here yet
116//!
117//! **Not a gap any more: every connector can be addressed.** What used to stand here was that only
118//! two connectors could be, and C-92 left it behind. A credential's address is
119//! `tenants/<tenant>/<authority>/<credential>`, and **all 53 shipped connectors** declare an
120//! `authority` (C-37); the "only two — `slack` and `fly`" this note once recorded was true of a
121//! nineteen-connector fleet. A connector that declared none would still
122//! refuse with [`Error::NoCredentialAddress`] rather than send an unauthenticated request —
123//! fail-closed, with a diagnostic naming the missing fact instead of a vendor's `401` — and
124//! `freshdesk`, which deliberately declares no *credential*, still refuses that way.
125//!
126//! **The response is a record, and this pack still shapes nothing** (C-403). What stood here was
127//! that `http.request` returned one flat string (`HTTP {status}\n{headers}\n{body}`), returned
128//! whole, and that the paragraph expired on a flux-web bump. This is that bump: from flux-web
129//! **0.43.0** the canonical `ToolResult.content` is the record `{status, headers, body}` — JSON
130//! encoded, `body` parsed when the response is a JSON object or array — and the flat block is the
131//! model-facing `view`. A caller reads `$resp.body.data.id` instead of searching a block.
132//!
133//! **The "returned whole" half did not change and is not going to.** This pack delegates to the
134//! transport the host bound and hands back what it produced, so the shape is flux-web's to decide
135//! and a consumer's to read. That is also why the change is worth a paragraph rather than a line:
136//! nothing in this crate's types moved, so a host that parsed the old block compiles against the
137//! new record and quietly reads the wrong thing.
138//!
139//! # Configuration resolves through a bound port (C-193)
140//!
141//! What used to stand here was the note that a templated base URL reached the wire verbatim. It
142//! does not any more. **Thirteen** of the 53 shipped connectors declare a `base_url` carrying a
143//! `{placeholder}` — at connector level or on one of their services — covering **75 of 299
144//! operations**, which is exactly the catalogue's `unbound-base-url-template` issue count:
145//!
146//! | | connectors | operations |
147//! |---|---|---|
148//! | a templated **host**, which does not resolve at all | `confluence`, `docusign`, `freshdesk`, `jira`, `mailchimp`, `newrelic`, `okta`, `salesforce`, `shopify`, `supabase`, `zendesk` | 65 |
149//! | a templated **path**, on a host that does resolve | `contentful`, `statuspage` | 10 |
150//!
151//! Both rows matter and only the first is obvious. `https://api.statuspage.io/v1/pages/{page_id}`
152//! reaches a real server and asks it for a page called `{page_id}`, which is a `404` that reads like
153//! a missing record rather than a connector nobody configured.
154//!
155//! A tenant's values reach them through [`Configuration`], the second bound port, on the same terms
156//! as [`Credentials`]: handed in at construction, never a global, and never the process
157//! environment. Note that `freshdesk` and `okta` both name their variable `domain` — the port is
158//! keyed by connector as well as by variable, so the two are different values rather than a
159//! collision.
160//!
161//! **And by service** (C-197), which is the same collision one level down and the one that was
162//! live. `contentful` declares `delivery_space_id` and `management_space_id`, both binding
163//! `endpoint.space_id`, under two services that reach two different hosts. Keyed by connector alone
164//! they were one slot, so a management write went to whichever space the delivery reads had been
165//! configured with — a `200` from a real server rather than a refusal. The key is now
166//! `(tenant, provider, service, kind, name)`; see [`ConfigStore::get`].
167//!
168//! Two consequences worth stating, because both are the kind that look like they work:
169//!
170//! - **Substitution is total or refused.** One unbound variable is [`Error::MissingConfig`], naming
171//! the tenant, the connector and the field — never a request to a host with a brace in it.
172//! - **The permission subject is the substituted host.** The pack calls `http.request`'s `execute`
173//! directly, so [`Operation`]'s own `permission_subjects` is the only place a host's egress
174//! allow-list is consulted for the inner call. Declaring `{subdomain}.zendesk.com` there asks that
175//! allow-list to match a string no host resolves to. See [`tool::Operation::subjects`].
176//! - **And the port is read once, not once per call** (C-198). The two bullets above are two
177//! *separate* calls into the host's [`ConfigStore`], so a store with interior mutability could
178//! answer the gate with one host and the request with another — through the one gate there is.
179//! Every value an operation can ask for is therefore resolved when the operation is projected, and
180//! the projected operation holds no handle to the store. See [`ConfigStore::get`] for the
181//! requirement that still binds a host across *several* operations.
182//!
183//! **And the variables are *declared* now, not inferred** (C-538). What stood here was that this
184//! crate reads a connector's endpoint variables off each operation's own emitted Flux, by scanning
185//! string literals for braces — the honest answer while nothing published them. The canonical
186//! document publishes them: `"endpoint": {"subdomain": ["host"]}` names the variable *and* the
187//! position it lands in, so [`Operation::endpoint_variables`], [`Operation::endpoint_slots`] and
188//! [`Operation::caller_path_parameters`] are read rather than derived, and a connector whose braces
189//! are the vendor's own syntax is no longer a shape this crate has to classify at all.
190//!
191//! What this still does *not* do is publish the whole configuration surface — the labels, help text
192//! and `binds` targets that let a product render "connect your Zendesk". That is C-87.
193//!
194//! # The consumer contract: obtaining a plan and dispatching it yourself (C-553)
195//!
196//! **Read this before writing a `Tool` projection of your own.** It is the contract Exchange's
197//! `X-156` adopts and the one upstream `C-541`'s wrapper retirement keys on: when this crate's
198//! `Tool`-returning [`resolve`] is no longer called from any consumer path, the wrapper retires and
199//! what remains is exactly the four calls below.
200//!
201//! ```no_run
202//! # async fn consumer(
203//! # entry: &'static catalog::Operation,
204//! # http: connector_pack::Egress,
205//! # credentials: connector_pack::Credentials,
206//! # configuration: connector_pack::Configuration,
207//! # ctx: &flux_runtime::ToolContext,
208//! # params: &serde_json::Value,
209//! # ) -> Result<flux_runtime::ToolResult, Box<dyn std::error::Error>> {
210//! // 1. Project the operation onto the ports this host bound.
211//! let operation = connector_pack::Operation::project(entry, http.clone(), credentials, configuration)?;
212//!
213//! // 2. Ask for the whole plan — request, permission subjects, redaction set.
214//! let plan = operation.build_request_plan(ctx, params).await?;
215//!
216//! // 3. Judge the call with the host's own network policy, on the subjects the plan names.
217//! // They are the URL *before* any credential was placed, so they are safe to quote in an
218//! // approval prompt, a policy rule and an evidence record.
219//! for subject in &plan.permission_subjects {
220//! # let _ = subject;
221//! // host_policy.admit(subject)?;
222//! }
223//!
224//! // 4. Hand the request back to the bound transport. `Egress::tool()` is never needed.
225//! let result = http.send(ctx, plan.request).await?;
226//! # Ok(result)
227//! # }
228//! ```
229//!
230//! Four properties of that sequence are load-bearing, and each is a way a consumer could get the
231//! same four lines wrong:
232//!
233//! - **Project the plan; never compose one.** A consumer that reads `plan.request`'s parts and
234//! rebuilds a request from them has become the second request-composition path this family
235//! already rejected. Carry it across whole. See [`RequestPlan`].
236//! - **The redaction set is already registered when you reach it through this crate.**
237//! [`RequestPlan::redactions`] documents itself as a *requirement* — a consumer of
238//! `connector-resolve` alone must register the strings before formatting, logging or dispatching
239//! the plan. [`Operation::build_request_plan`] keeps the stronger order this crate has always
240//! kept: every value is resolved and registered with `ctx.redactor` **before a request exists**,
241//! so the field is a checkable restatement rather than the only defence. Pass the same `ctx` on
242//! to step 4 and the guarantee travels.
243//! - **Nothing here dispatches for you, and nothing consults `http.request`'s own network gate.**
244//! [`Egress::send`] calls the tool's `execute` directly and therefore bypasses
245//! `Executor::dispatch`, exactly as this crate's own [`Operation`] does. Step 3 is not optional;
246//! it is the gate.
247//! - **The transport stays inside the port.** [`Egress::send`] is the published dispatch seam
248//! precisely so [`Egress::tool`] can be refused outright by a consumer that does not want a second
249//! request path — which is the rule Exchange enforces in every one of its files.
250//! - **A `produces_credential` login does not go through this path** (C-136). Its answer is a
251//! credential, and [`Tool::execute`] diverts that answer into the bound store rather than
252//! returning it; the plan path derives a request and dispatches it, applying no diversion, so it
253//! would hand the caller the vendor's token in the clear. No shipped connector mints today, but
254//! this is permanent API — such an operation must go through the [`Tool`] projection. See
255//! [`Operation::build_request_plan`], "the one operation shape the plan path does *not* serve".
256//!
257//! What is *not* published, deliberately: `Credentials::resolve` and `Configuration::snapshot`, the
258//! two ingredients X-156 offered as an alternative to the plan. Handing those out would put the
259//! **ordering** between them — registration before construction, endpoint resolution before
260//! substitution — in the consumer's hands, and Decision 0022's "enforcement topology unchanged" is
261//! the invariant that ordering *is*. See [`Operation::build_request_plan`] for the four steps it
262//! applies and `docs/designs/catalog-artifact.md` §3 for the written decision.
263
264mod auth;
265mod channel;
266mod config;
267mod credentials;
268mod document_rehearsal;
269mod dry_run;
270mod mint;
271mod name;
272mod rehearsal;
273mod request;
274mod spec;
275mod tool;
276
277pub use channel::{channel_plan, PreparedChannelPlan, SensitiveText};
278pub use config::{ConfigStore, ConfigValue, Configuration, Field, MemoryConfig};
279pub use credentials::{Credentials, DEFAULT_SERVICE};
280pub use dry_run::{CredentialReference, DryRun, DryRunTransport, Transport};
281pub use name::{dotted_name, NameError};
282// **Two rehearsals, side by side, deliberately** (C-538). `Rehearsal` reads the emitted Flux;
283// `DocumentRehearsal` reads the canonical document, with the same observable semantics. Both are
284// exported until Exchange's settings and connection-verification call sites migrate (C-539), and
285// `tests/main/catalogue_differential.rs` requires them to agree for every operation in the catalogue
286// until C-540 deletes the first.
287pub use document_rehearsal::DocumentRehearsal;
288pub use rehearsal::Rehearsal;
289// **The request and the identity moved to `connector-resolve`** (C-538) and are re-exported here
290// unchanged, so a consumer's `use connector_pack::Request` keeps resolving. They moved because the
291// plan is the unit the differential gate compares, and a comparison between two structurally
292// identical types would be a comparison of two copies rather than of two derivations.
293//
294// **`RequestPlan` joins them** (C-553), as the return type of [`Operation::build_request_plan`]. It
295// is the same type `connector_resolve::resolve` produces — re-exported rather than wrapped, because
296// a `connector_pack::RequestPlan` that merely looked like one would be the second plan vocabulary a
297// consumer has to reconcile. `SensitiveText`, its redaction set's element type, is already
298// re-exported above through [`channel`].
299pub use connector_resolve::{Request, RequestPlan, Slot, DEFAULT_USER_AGENT};
300pub use spec::{is_exposed, project};
301pub use tool::{Egress, Operation};
302
303// The credential vocabulary, re-exported rather than redefined — the same posture
304// `connector-secrets` takes towards `connector-spec`'s addressing. A host binding this pack's
305// credential port should not have to name three crates to spell one address.
306pub use connector_secrets::{
307 CredentialRef, FileStore, InstanceId, Layout, MemoryStore, Secret, SecretStore, StoreError,
308 TenantInstances, TenantLayout,
309};
310
311use catalog::ProviderKey;
312use flux_runtime::{Tool, ToolRegistry};
313use std::sync::Arc;
314
315/// Why a pack could not be installed.
316///
317/// Every variant refuses; none repairs. A pack that installed *most* of a provider would leave a
318/// host holding a connector that resolves some of its operations and silently not others.
319#[derive(Debug, thiserror::Error)]
320pub enum Error {
321 /// The pack named a connector this catalogue does not carry.
322 ///
323 /// Reported rather than skipped: registering nothing and returning success is how a host ends
324 /// up with a client that cannot call anything and no diagnostic saying why. A typo in a
325 /// provider name is the overwhelmingly likely cause.
326 #[error(
327 "no connector named `{provider}` is in this catalogue — `catalog::providers()` lists the \
328 {available} this build carries"
329 )]
330 UnknownProvider {
331 /// The name that was asked for.
332 provider: String,
333 /// How many connectors the catalogue does carry.
334 available: usize,
335 },
336
337 /// The provider carries no channel under the requested name.
338 #[error("connector `{provider}` declares no channel binding `{binding}`")]
339 UnknownChannel { provider: String, binding: String },
340
341 /// A non-socket binding cannot be composed as a WebSocket handshake.
342 #[error("connector `{provider}` binding `{binding}` is not a socket channel")]
343 NotSocketChannel { provider: String, binding: String },
344
345 /// A vendor-specific socket has no generic RFC 6455 connect declaration.
346 #[error("connector `{provider}` binding `{binding}` is vendor-specific and has no generic connect plan")]
347 VendorSocketChannel { provider: String, binding: String },
348
349 /// The operation's id has no dotted tool name. See [`NameError`].
350 #[error("`{operation}` cannot be projected onto a flux tool name: {source}")]
351 Name {
352 /// The operation id.
353 operation: String,
354 /// Which end of the seam refused it.
355 #[source]
356 source: NameError,
357 },
358
359 /// The Flux embedded for an operation does not parse.
360 ///
361 /// Unreachable for a catalogue this repository generated —
362 /// `crates/catalog/tests/embedded_operations.rs` parses every rendering on its own as a
363 /// standing gate. It is reported as the corrupt-input case it would be rather than unwrapped,
364 /// because the alternative is a panic inside a host's registration call.
365 #[error("the Flux embedded for `{operation}` does not parse: {message}")]
366 Unparsable {
367 /// The operation id.
368 operation: String,
369 /// What flux-lang said.
370 message: String,
371 },
372
373 /// A catalogue rendering is exactly one `op` declaration, and this one is not.
374 #[error(
375 "the Flux embedded for `{operation}` declares {found} operations; one catalogue rendering \
376 is exactly one declaration"
377 )]
378 NotOneOperation {
379 /// The operation id.
380 operation: String,
381 /// How many declarations were found.
382 found: usize,
383 },
384
385 /// The projected spec is one flux itself will not register.
386 ///
387 /// flux pairs `effects` with `access`: a declared effect with no host capability that could
388 /// carry it is refused by `authority_requirements_from_declaration`, and therefore by
389 /// `try_register_from`. Unreachable for a declaration this repository emits — every generated
390 /// op declares `read` or `write` before `network`, which pairs with network access — and
391 /// reported here rather than left to surface at a host's startup with only the tool name to go
392 /// on.
393 ///
394 /// The refusal is deliberate. Satisfying flux by claiming an access kind the connector does not
395 /// have would register a tool that looks gated and is not.
396 #[error("`{operation}` projects onto a spec flux will not register: {message}")]
397 Unregistrable {
398 /// The operation id.
399 operation: String,
400 /// What flux's authority checker said.
401 message: String,
402 },
403
404 /// A rendering declaring a different operation than the entry it is filed under.
405 ///
406 /// Left alone this would register a tool under a name derived from one id carrying a contract
407 /// taken from another — the two halves of an operation coming apart with nothing to notice it.
408 #[error(
409 "the entry for `{operation}` embeds a declaration of `{declared}`; the catalogue's index \
410 and its renderings disagree"
411 )]
412 Mismatched {
413 /// The operation id the entry is filed under.
414 operation: String,
415 /// The operation the embedded Flux actually declares.
416 declared: String,
417 },
418
419 /// An entry naming no host, which therefore cannot be network-gated.
420 ///
421 /// [`Operation::permission_subjects`](flux_runtime::Tool::permission_subjects) falls back to
422 /// the declared hosts when a request cannot be built, so an entry with none would answer
423 /// *empty* exactly when the answer matters most — and empty is the default the trait hands out
424 /// for free, indistinguishable from a considered answer at every other layer. Unreachable for a
425 /// catalogue this repository generated: `http_hosts` derives from a service's `base_url`
426 /// (C-10), which is mandatory.
427 #[error(
428 "`{operation}` declares no host, so no permission subject could name where it goes; a \
429 connector that cannot be network-gated does not install"
430 )]
431 NoDeclaredHost {
432 /// The operation id.
433 operation: String,
434 },
435
436 /// A call that omitted a parameter the operation declares.
437 ///
438 /// Refused rather than defaulted, because the failure it prevents is silent: an absent path
439 /// parameter leaves its `{placeholder}` verbatim in the URL (flux's interpolator does not drop
440 /// an unbound name), and the vendor answers that request. This is the same contract flux's own
441 /// composite dispatch applies — every declared parameter is required, and an *optional* one is
442 /// a parameter a caller may pass `null` for.
443 #[error("`{operation}` was called without `{parameter}`, which it declares")]
444 MissingParameter {
445 /// The operation id.
446 operation: String,
447 /// The parameter that was not supplied.
448 parameter: String,
449 },
450
451 /// A caller-supplied path parameter that would leave its reviewed URL segment (C-478).
452 ///
453 /// Unlike [`UnsafeConfig`](Self::UnsafeConfig), this value arrives with an operation call and
454 /// is addressed by the operation parameter name. It is refused while the request environment is
455 /// being bound, before authentication or the transport sees a request.
456 #[error(
457 "`{operation}` cannot place caller parameter `{parameter}` in one path segment: {reason}; \
458 the request was not sent"
459 )]
460 UnsafePathParameter {
461 /// The operation id.
462 operation: String,
463 /// The caller-visible parameter the emitted Flux places in the path.
464 parameter: String,
465 /// Why its value would escape or reshape one segment.
466 reason: String,
467 },
468
469 /// An operation whose emitted body this pack cannot evaluate into a request.
470 ///
471 /// The refusal is the point. `connector-flux` emits one closed shape and
472 /// [`crate::request`](crate) models exactly it; a body that grew a node beyond that — a quirk
473 /// compiled into control flow (C-12), a `retry` — must fail here, because the alternative is a
474 /// request assembled from *part* of an operation and sent anyway. A partly-evaluated request is
475 /// not a degraded request, it is a different call, and the vendor answers it.
476 #[error("`{operation}` cannot be built into a request: {message}")]
477 Unbuildable {
478 /// The operation id.
479 operation: String,
480 /// What the evaluator refused.
481 message: String,
482 },
483
484 /// A tenant id that cannot be part of an address.
485 ///
486 /// Refused when the port is bound rather than at the first call: a tenant id is untrusted input
487 /// that ends up in a store path, and the cautionary precedent is close to home — action-proxy
488 /// puts two client-supplied headers straight into a Vault path with no validation at all.
489 #[error("`{tenant}` cannot address a tenant's credentials: {reason}")]
490 Tenant {
491 /// The tenant id that was refused.
492 tenant: String,
493 /// `connector_address::credential::validate_tenant`'s own explanation.
494 reason: String,
495 },
496
497 /// A connection instance is not the canonical UUID C-406's address requires.
498 #[error("`{instance}` cannot address a connection instance: {reason}")]
499 Instance {
500 /// The instance spelling that was refused.
501 instance: String,
502 /// `connector_address::credential::validate_instance`'s explanation.
503 reason: String,
504 },
505
506 /// **No credential is stored where the operation's credential lives.**
507 ///
508 /// The request is not sent. That is the whole point of the variant: an unauthenticated call is
509 /// a fail-closed `401`, and a host treating `401` as retryable will loop against the vendor
510 /// forever without ever being told what is actually missing.
511 #[error(
512 "`{operation}` needs a credential and none is stored at `{path}` — the request was not \
513 sent ({alternatives} address(es) tried)"
514 )]
515 MissingCredential {
516 /// The operation id.
517 operation: String,
518 /// The path the store looked at, **as the store's own layout renders it** — the place an
519 /// operator has to go and put the value.
520 path: String,
521 /// How many alternative mechanisms were tried before giving up.
522 alternatives: usize,
523 },
524
525 /// The secret store answered, and not with a value.
526 ///
527 /// Kept apart from [`MissingCredential`](Self::MissingCredential) deliberately: "unreachable"
528 /// and "not configured" want opposite responses, and collapsing them is the gap C-91's error
529 /// type exists to close. `StoreError` never carries a value, so this is safe to log.
530 #[error("`{operation}` could not resolve `{credential}`: {source}")]
531 CredentialStore {
532 /// The operation id.
533 operation: String,
534 /// The credential that could not be resolved.
535 credential: String,
536 /// What the store said.
537 #[source]
538 source: connector_secrets::StoreError,
539 },
540
541 /// The connector declares no `authority`, so its credential has no address.
542 ///
543 /// C-37's `pid` is the second segment of every credential path, and a connector without one
544 /// cannot say *where* its secrets live — so there is nothing to look up. Refused rather than
545 /// defaulted: any invented authority would render a plausible path pointing at a value nobody
546 /// ever stored, and the resulting `NotFound` would send an operator to the wrong place.
547 #[error(
548 "`{operation}` needs `{credential}`, but connector `{provider}` declares no `authority`, so \
549 no credential address renders for it (C-37); the request was not sent"
550 )]
551 NoCredentialAddress {
552 /// The operation id.
553 operation: String,
554 /// The connector that declares no authority.
555 provider: String,
556 /// The credential that therefore cannot be addressed.
557 credential: String,
558 },
559
560 /// The address components do not compose into a valid [`CredentialRef`].
561 ///
562 /// Unreachable for a catalogue this repository generated — every component is validated at the
563 /// loader — and reported as the corrupt-input case it would be rather than unwrapped.
564 #[error("`{operation}` cannot address `{credential}`: {reason}")]
565 CredentialAddress {
566 /// The operation id.
567 operation: String,
568 /// The credential in question.
569 credential: String,
570 /// `CredentialRef::new`'s own explanation.
571 reason: String,
572 },
573
574 /// An operation requiring a credential its connector does not declare.
575 ///
576 /// The loader refuses this, so it is a disagreement between the catalogue's operation table and
577 /// its credential table rather than an authoring error — the same class of drift
578 /// [`Mismatched`](Self::Mismatched) covers for renderings.
579 #[error(
580 "`{operation}` requires `{credential}`, which connector `{provider}` does not declare; the \
581 catalogue's operations and its credentials disagree"
582 )]
583 UndeclaredCredential {
584 /// The operation id.
585 operation: String,
586 /// The credential named by the operation.
587 credential: String,
588 /// The connector that does not declare it.
589 provider: String,
590 },
591
592 /// An operation authenticating with a **signing** secret.
593 ///
594 /// Every other credential answers "where does this go on the way out"; a webhook signing secret
595 /// has no answer, because it never goes out — it verifies bytes that arrived. Placing one on a
596 /// request would hand the vendor the value that authenticates *their* calls inbound. The loader
597 /// already refuses it (`AGENTS.md`'s authentication contract); this is the second lock.
598 #[error(
599 "`{operation}` authenticates with `{credential}`, which is an inbound signing secret \
600 and never leaves"
601 )]
602 InboundCredential {
603 /// The operation id.
604 operation: String,
605 /// The signing credential.
606 credential: String,
607 },
608
609 /// A credential whose header the operation's own emitted Flux already sets.
610 ///
611 /// Refused rather than overwritten: a silent replacement would send a request that neither the
612 /// module nor the pack describes, and the two surfaces would still look identical in isolation.
613 #[error(
614 "`{operation}` would place `{credential}` in `{header}`, which its own module already sets"
615 )]
616 CredentialCollision {
617 /// The operation id.
618 operation: String,
619 /// The credential that could not be placed.
620 credential: String,
621 /// The header, as the module spells it.
622 header: String,
623 },
624
625 /// A Basic credential whose **non-secret** user half is not configured.
626 ///
627 /// The user half is config — an email address, an account name — so it resolves through
628 /// [`Configuration`] rather than from the secret store. Refused rather than composed as
629 /// `base64(":<secret>")`, which is a header the vendor answers with a `401` that says nothing
630 /// about what is missing.
631 ///
632 /// It is a distinct variant from [`MissingConfig`](Self::MissingConfig), which it wraps, purely
633 /// so the refusal can also quote the connector's `user_env` — the name the vendor's own
634 /// documentation gives this value, and the fastest way for an operator to recognise it.
635 #[error(
636 "`{operation}` needs the non-secret user half of `{credential}` for tenant `{tenant}`, and \
637 the bound configuration supplies none (elsewhere this value is called `{env}`); the \
638 request was not sent"
639 )]
640 MissingCredentialConfig {
641 /// The operation id.
642 operation: String,
643 /// The credential whose user half is missing.
644 credential: String,
645 /// The tenant it was looked up for.
646 tenant: String,
647 /// What the same value is called in the vendor's documentation and in flux's `AuthMethod`.
648 env: String,
649 },
650
651 /// **A connection setting the tenant has not supplied**, so the request cannot be composed.
652 ///
653 /// The refusal that closes C-193. A `base_url` such as `https://{subdomain}.zendesk.com` is not
654 /// a URL until a tenant's value fills it, and there is no safe partial answer: substituting what
655 /// is available and sending the rest would produce a request to a *different* host, which the
656 /// vendor at that host answers. This is the same rule [`Unbuildable`](Self::Unbuildable) states
657 /// for a partly-evaluated body, applied to the part of the URL a tenant owns.
658 ///
659 /// `field` is spelled in the design's `binds` vocabulary — `endpoint.subdomain`,
660 /// `username.zendesk.api_token` — so the diagnostic names the same thing a connector's
661 /// configuration surface will when C-87 publishes it.
662 ///
663 /// **It names the service too** (C-197), because `binds` alone does not identify a field. Two
664 /// services of one connector may bind the same target and want different values — `contentful`
665 /// declares `delivery_space_id` and `management_space_id`, both `endpoint.space_id` — so a
666 /// refusal quoting only the connector and the target sends an operator to a field they have two
667 /// of.
668 ///
669 /// No value is quoted, only the address of the missing one. A connection setting is not a
670 /// secret, but it is a customer's, and the same care [`UnredactableCredential`] takes applies.
671 #[error(
672 "`{operation}` needs `{field}` of service `{service}` of connector `{provider}` for tenant \
673 `{tenant}`, and the bound configuration supplies none, so no URL composes; the request \
674 was not sent"
675 )]
676 MissingConfig {
677 /// The operation id.
678 operation: String,
679 /// The connector whose configuration is incomplete.
680 provider: String,
681 /// The connector's service the value was looked up under — `default` for a connector with a
682 /// single API surface.
683 service: String,
684 /// The tenant the value was looked up for.
685 tenant: String,
686 /// The missing field, as `binds` spells it.
687 field: String,
688 },
689
690 /// A connection-level value whose declaration requires deployment/operator approval has not
691 /// been approved. The value itself is intentionally absent from this diagnostic.
692 #[error(
693 "`{operation}` cannot activate configuration field `{field}` of service `{service}` of \
694 connector `{provider}` until deployment/operator policy approves and pins it; the request \
695 was not sent"
696 )]
697 UnapprovedConfig {
698 operation: Box<str>,
699 provider: Box<str>,
700 service: Box<str>,
701 field: Box<str>,
702 },
703
704 /// A configured origin did not satisfy the declared HTTPS-origin grammar. The value is never
705 /// quoted into the refusal, logs or evidence.
706 #[error(
707 "`{operation}` cannot activate origin field `{field}` of service `{service}` of connector \
708 `{provider}`: {reason}; the request was not sent"
709 )]
710 UnsafeOrigin {
711 operation: Box<str>,
712 provider: Box<str>,
713 service: Box<str>,
714 field: Box<str>,
715 reason: Box<str>,
716 },
717
718 /// **A configuration value that would reshape the request it is substituted into** (C-214).
719 ///
720 /// The guard `connector-spec` has had since C-187 — `Position::validate_value` — has two call
721 /// sites, both in the loader, and both run against a `ConfigField::example` or a pinned
722 /// parameter *name*. Nothing ran against the value a tenant actually supplies, because this
723 /// repository never sees one: it arrives through [`ConfigStore`], at the host, at request time.
724 /// So the guard existed and did not guard, and this is the refusal that closes it, raised at the
725 /// one point where a value and the request it shapes are both in hand.
726 ///
727 /// The severe case is `position: "host"`, and it predates the pin surface. A path or query value
728 /// cannot move the origin — substitution lands after the authority is fixed in the `base`
729 /// literal — but nine shipped connectors template the host itself, and there a `subdomain` of
730 /// `acme.zendesk.com@evil.example` resolves to `evil.example.zendesk.com`, because the `@` makes
731 /// everything before it userinfo. That is a request to a host the operator never named, carrying
732 /// that operator's own token, past an egress gate that was shown a `zendesk.com` subject.
733 ///
734 /// The value is operator-supplied rather than attacker-supplied, so this is a
735 /// paste-the-wrong-thing hazard rather than a classic injection — and it is refused rather than
736 /// repaired for the reason every refusal here is: the alternative is a *different, valid*
737 /// request, which the vendor at the other end answers.
738 ///
739 /// The refusal quotes the value, as [`UnresolvedEndpoint`](Self::UnresolvedEndpoint) already
740 /// quotes a URL composed from one. A connection setting is not a secret, and the value is
741 /// precisely what an operator has to see in order to fix what they pasted.
742 #[error(
743 "`{operation}` cannot substitute the configured `{variable}` into the {position} of its \
744 request: {reason}; the request was not sent"
745 )]
746 UnsafeConfig {
747 /// The operation id.
748 operation: String,
749 /// The configuration variable whose value was refused, as the connector's own Flux spells
750 /// the placeholder — `subdomain`, `zone_id`, `teamId`.
751 variable: String,
752 /// Where the value would have landed: `host`, `path segment`, `query parameter` or
753 /// `header`.
754 position: &'static str,
755 /// What is wrong with the value.
756 reason: String,
757 },
758
759 /// A finished URL still naming a configuration variable.
760 ///
761 /// Every variable had a value, so no *literal* can have carried a placeholder through — this is
762 /// reachable only when a caller passes a parameter whose own text spells one, and interpolating
763 /// it puts the brace back. Refused rather than sent: a request whose URL names a variable
764 /// nobody resolved is not a request to the host the gate was shown.
765 #[error(
766 "`{operation}` built the URL `{url}`, which still names the configuration variable \
767 `{variable}`; a parameter value put it there, and the request was not sent"
768 )]
769 UnresolvedEndpoint {
770 /// The operation id.
771 operation: String,
772 /// The variable still named in the URL.
773 variable: String,
774 /// The URL as it was built. Unauthenticated — no credential has been placed on it yet.
775 url: String,
776 },
777
778 /// Two ports bound to two different tenants.
779 ///
780 /// [`Credentials`] and [`Configuration`] each carry the tenant they answer for, and nothing in
781 /// the types stops a host from pairing them wrongly. The result of that mistake is specific:
782 /// one tenant's credential sent to another tenant's host, an authenticated request to the wrong
783 /// customer's server. Refused at install, where every other misconfiguration of a port is.
784 #[error(
785 "`{operation}` was given credentials for tenant `{credentials}` and configuration for \
786 tenant `{configuration}`; one connector serves one tenant"
787 )]
788 TenantMismatch {
789 /// The operation id.
790 operation: String,
791 /// The tenant the credential port answers for.
792 credentials: String,
793 /// The tenant the configuration port answers for.
794 configuration: String,
795 },
796
797 /// The credential and configuration ports selected different connection instances.
798 #[error(
799 "`{operation}` was given credentials for instance {credentials:?} and configuration for \
800 instance {configuration:?}; one operation serves one connection"
801 )]
802 InstanceMismatch {
803 /// The operation being projected.
804 operation: String,
805 /// The credential port's UUID, if any.
806 credentials: Option<String>,
807 /// The configuration port's UUID, if any.
808 configuration: Option<String>,
809 },
810
811 /// **A credential the host's redactor will not hold, and therefore will not travel.**
812 ///
813 /// flux's `Redactor::add_secret` silently ignores a value under six characters once trimmed
814 /// (`codewandler-flux-secret-1.0.1/src/lib.rs:195-201`) — refusing to over-redact a common word
815 /// is the right trade for flux, and it means registration can *succeed* while protecting
816 /// nothing. A credential that short would then travel unredacted through all four surfaces
817 /// `Executor::dispatch` scrubs, with every line of code above it reading as though it were
818 /// protected.
819 ///
820 /// Refused rather than sent, which is C-152's recorded decision (see
821 /// `docs/designs/connector-tool-pack.md`): a credential the host cannot keep off a surface is
822 /// one it should not put on the wire, and a five-character API token is a misconfiguration long
823 /// before it is a credential. The alternative considered was to state the threshold wherever the
824 /// guarantee is stated and accept it; the design says why this one won.
825 ///
826 /// The refusal names the address so an operator can go and replace the value, and it names
827 /// neither the value nor its length — a length is a fingerprint, which is the same care
828 /// `connector_secrets::Secret`'s `Debug` takes.
829 #[error(
830 "`{operation}` resolved `{credential}` for tenant `{tenant}` under `{authority}`, and the \
831 host's redactor will not hold a value that short, so it could not be kept off a surface; \
832 the request was not sent"
833 )]
834 UnredactableCredential {
835 /// The operation id.
836 operation: String,
837 /// The credential that could not be protected.
838 credential: String,
839 /// The tenant whose credential it is — the address, minus the value.
840 tenant: String,
841 /// The provider's reverse-DNS authority, the second segment of that address.
842 authority: String,
843 },
844
845 /// A mechanism naming no credentials at all.
846 ///
847 /// It would authenticate nothing while looking satisfied, which is the one failure shape that
848 /// resembles success. The loader refuses a degenerate empty mechanism; this is the second lock.
849 #[error(
850 "`{operation}` offers a mechanism that names no credentials, so it authenticates nothing"
851 )]
852 EmptyMechanism {
853 /// The operation id.
854 operation: String,
855 },
856
857 /// **A credential-producing call that produced none** — C-136, and the failure path the whole
858 /// story turns on.
859 ///
860 /// Raised whenever the secret cannot be taken out of the vendor's answer: the transport failed,
861 /// the answer is not JSON, the declared location resolves to nothing, or it resolves to
862 /// something that is not a non-empty string. One variant for all four, because telling them
863 /// apart for a caller would mean describing the body — and the body of a login is where the
864 /// credential is.
865 ///
866 /// **It carries no bytes of that answer.** At most the HTTP status, which is a small structured
867 /// fact rather than vendor text, and which is the one thing an operator actually acts on. That
868 /// is the deliberate cost the story pays: an operation whose success is a credential cannot
869 /// quote its own failure, because the two are the same document read at different times. See
870 /// [`crate::mint`].
871 #[error(
872 "`{operation}` was called to mint `{credential}` and no credential was minted; the \
873 vendor's answer is withheld, because an operation of this shape cannot quote its own \
874 response without risking the value it exists to divert{}",
875 status.map_or_else(String::new, |status| format!(" (HTTP {status})"))
876 )]
877 CredentialNotMinted {
878 /// The operation id.
879 operation: String,
880 /// The credential it was called to mint.
881 credential: String,
882 /// The vendor's HTTP status, when the transport's answer carried one.
883 status: Option<u64>,
884 },
885}
886
887impl From<Error> for flux_core::Error {
888 fn from(error: Error) -> Self {
889 flux_core::Error::Config(error.to_string())
890 }
891}
892
893/// **The plan-deriving core's refusals, as this crate's** (C-538).
894///
895/// Every variant maps onto the identically-named one above, carrying the same fields and rendering
896/// the same sentence. It is a mapping rather than a re-export because the acceptance requires each
897/// `connector_pack::Error` variant to keep its **name and its trigger** — a host matches on them —
898/// while `connector_resolve` must stay engine-free, and this enum's `Name` variant carries a
899/// [`NameError`] derived from `flux_lang`'s identifier predicates.
900///
901/// The duplication that buys is seven sentences, and it is pinned rather than trusted:
902/// [`tests::the_mapped_refusals_render_the_same_sentence`] renders both sides of every arm and
903/// requires the strings to be equal, so a reworded refusal in either crate fails in the same run.
904///
905/// The match is **exhaustive on purpose**: a variant added to the core has to be given a home here
906/// rather than arriving as a catch-all that erases which refusal happened.
907impl From<connector_resolve::Error> for Error {
908 fn from(error: connector_resolve::Error) -> Self {
909 use connector_resolve::Error as Refused;
910 match error {
911 Refused::MissingParameter {
912 operation,
913 parameter,
914 } => Error::MissingParameter {
915 operation,
916 parameter,
917 },
918 Refused::UnsafePathParameter {
919 operation,
920 parameter,
921 reason,
922 } => Error::UnsafePathParameter {
923 operation,
924 parameter,
925 reason,
926 },
927 Refused::Unbuildable { operation, message } => {
928 Error::Unbuildable { operation, message }
929 }
930 Refused::UnsafeConfig {
931 operation,
932 variable,
933 position,
934 reason,
935 } => Error::UnsafeConfig {
936 operation,
937 variable,
938 position,
939 reason,
940 },
941 Refused::UnresolvedEndpoint {
942 operation,
943 variable,
944 url,
945 } => Error::UnresolvedEndpoint {
946 operation,
947 variable,
948 url,
949 },
950 Refused::CredentialCollision {
951 operation,
952 credential,
953 header,
954 } => Error::CredentialCollision {
955 operation,
956 credential,
957 header,
958 },
959 Refused::InboundCredential {
960 operation,
961 credential,
962 } => Error::InboundCredential {
963 operation,
964 credential,
965 },
966 // The producers' refusals (C-557), each onto the identically-named and identically-worded
967 // one above. `Box<str>`-fielded variants take the core's `String` through `.into()`.
968 Refused::MissingConfig {
969 operation,
970 provider,
971 service,
972 tenant,
973 field,
974 } => Error::MissingConfig {
975 operation,
976 provider,
977 service,
978 tenant,
979 field,
980 },
981 Refused::UnapprovedConfig {
982 operation,
983 provider,
984 service,
985 field,
986 } => Error::UnapprovedConfig {
987 operation: operation.into(),
988 provider: provider.into(),
989 service: service.into(),
990 field: field.into(),
991 },
992 Refused::UnsafeOrigin {
993 operation,
994 provider,
995 service,
996 field,
997 reason,
998 } => Error::UnsafeOrigin {
999 operation: operation.into(),
1000 provider: provider.into(),
1001 service: service.into(),
1002 field: field.into(),
1003 reason: reason.into(),
1004 },
1005 Refused::MissingCredential {
1006 operation,
1007 path,
1008 alternatives,
1009 } => Error::MissingCredential {
1010 operation,
1011 path,
1012 alternatives,
1013 },
1014 Refused::CredentialStore {
1015 operation,
1016 credential,
1017 source,
1018 } => Error::CredentialStore {
1019 operation,
1020 credential,
1021 source,
1022 },
1023 Refused::NoCredentialAddress {
1024 operation,
1025 provider,
1026 credential,
1027 } => Error::NoCredentialAddress {
1028 operation,
1029 provider,
1030 credential,
1031 },
1032 Refused::CredentialAddress {
1033 operation,
1034 credential,
1035 reason,
1036 } => Error::CredentialAddress {
1037 operation,
1038 credential,
1039 reason,
1040 },
1041 Refused::UndeclaredCredential {
1042 operation,
1043 credential,
1044 provider,
1045 } => Error::UndeclaredCredential {
1046 operation,
1047 credential,
1048 provider,
1049 },
1050 Refused::MissingCredentialConfig {
1051 operation,
1052 credential,
1053 tenant,
1054 env,
1055 } => Error::MissingCredentialConfig {
1056 operation,
1057 credential,
1058 tenant,
1059 env,
1060 },
1061 Refused::EmptyMechanism { operation } => Error::EmptyMechanism { operation },
1062 // The channel-handshake producer's refusals (C-558), each onto the identically-named and
1063 // identically-worded one above.
1064 Refused::NotSocketChannel { provider, binding } => {
1065 Error::NotSocketChannel { provider, binding }
1066 }
1067 Refused::VendorSocketChannel { provider, binding } => {
1068 Error::VendorSocketChannel { provider, binding }
1069 }
1070 }
1071 }
1072}
1073
1074/// **The pack.** Install every **exposed** operation of each named provider into a host's registry.
1075///
1076/// This is the **model-facing** seam, and the word `exposed` is the whole of C-413: an operation
1077/// declaring `expose = false` is deliberately withheld here, so a host handing this registry to a
1078/// model advertises only what the connector meant to advertise. It is still callable — by name,
1079/// through [`resolve`], under the identical admission checks. A caller that needs *any* declared
1080/// operation wants `resolve`; a caller assembling a model's toolset wants this.
1081///
1082/// The returned value is `FnOnce(&mut ToolRegistry) -> flux_core::Result<()>` — exactly what
1083/// `flux_sdk::ClientBuilder::try_register_pack` takes, and equally callable against a bare
1084/// [`ToolRegistry`]. There is deliberately no `flux-sdk` dependency here: the SDK is the host's
1085/// choice, not this crate's, and a pack that required it could not be used by a host that
1086/// assembles its registry directly.
1087///
1088/// Each provider installs under **its own source label** (`connector-pack:<provider>`) through
1089/// [`ToolRegistry::try_register_all_from`], which is atomic: if any of a provider's operations is
1090/// invalid or collides with something already registered, none of that provider lands and flux's
1091/// own duplicate diagnostic names both contributors. A host composing this pack with its own
1092/// built-ins gets that diagnostic instead of a silent override.
1093///
1094/// The provider names are copied at call time, so the returned closure is independent of the slice
1095/// it was built from.
1096///
1097/// # The transport is an argument
1098///
1099/// Every operation this pack installs delegates its egress to the one [`Egress`] handed in here.
1100/// Taking it rather than constructing it is what lets a host supply the tool it has already
1101/// configured — its egress allow-list, its private-network grant, its audit sink. Constructing one
1102/// here would silently give connectors a *different* network policy from the rest of the host. See
1103/// [`Egress`] for what a substitute must honour, and for the one thing its type cannot enforce.
1104///
1105/// # So is the credential port, and it is not optional
1106///
1107/// [`Credentials`] is the other bound port, and it is a required argument rather than an
1108/// `Option`. A pack that could be built without one would let a host install connectors that send
1109/// every request unauthenticated — a fail-closed `401` from the vendor, but one a host treating
1110/// `401` as retryable will loop on forever. Requiring it makes "I forgot to bind a store" a
1111/// compile error instead of a production symptom.
1112///
1113/// # And so is the configuration port, for the same reason
1114///
1115/// [`Configuration`] is required on identical terms. A pack built without one could install
1116/// `zendesk` and send every request to `https://{subdomain}.zendesk.com` — which is not a
1117/// fail-closed anything, it is a DNS failure several layers away from the fact that nobody was ever
1118/// asked for a subdomain. It is separately required rather than folded into [`Credentials`] because
1119/// the two hold different kinds of value: one is a secret with a redaction guarantee, the other is
1120/// not, and a single port would have to pretend one of those is true of both.
1121///
1122/// Both ports name the tenant they answer for, and [`Operation::project`] refuses a pack whose two
1123/// tenants disagree ([`Error::TenantMismatch`]).
1124///
1125/// # Errors
1126///
1127/// The closure returns an error when a named provider is not in the catalogue, when an operation
1128/// cannot be projected, or when flux refuses the registration. Nothing is installed for a provider
1129/// whose install failed; providers listed before it are already in, because a partially-composed
1130/// registry is the caller's to discard.
1131pub fn pack(
1132 providers: &[&str],
1133 http: Egress,
1134 credentials: Credentials,
1135 configuration: Configuration,
1136) -> impl FnOnce(&mut ToolRegistry) -> flux_core::Result<()> {
1137 let requested: Vec<String> = providers.iter().map(|name| (*name).to_string()).collect();
1138
1139 move |registry: &mut ToolRegistry| {
1140 for provider in &requested {
1141 install(registry, provider, &http, &credentials, &configuration)?;
1142 }
1143 Ok(())
1144 }
1145}
1146
1147/// Install one provider's operations under one source label.
1148fn install(
1149 registry: &mut ToolRegistry,
1150 provider: &str,
1151 http: &Egress,
1152 credentials: &Credentials,
1153 configuration: &Configuration,
1154) -> flux_core::Result<()> {
1155 let entry =
1156 catalog::provider(ProviderKey::id(provider)).ok_or_else(|| Error::UnknownProvider {
1157 provider: provider.to_owned(),
1158 available: catalog::providers().len(),
1159 })?;
1160
1161 // **The one place an operation stops being a tool** (C-413). `expose` separates two claims the
1162 // emitter used to fuse: that an operation exists and can be called, and that it reaches a model
1163 // as a tool. Everything else about an unexposed operation is unchanged — it is in this `entry`,
1164 // in the manifest, in `catalog.json`, and `Operation::project` still builds it into something
1165 // `build_request` and `Rehearsal` drive.
1166 //
1167 // **A caller that names an unexposed operation still runs it — through `resolve`, not through
1168 // here.** That separation is load-bearing and not obvious: a `ToolRegistry` is both the
1169 // advertisement surface (`specs`, which a host hands a model) and the resolution surface
1170 // (`get`, which an execute route reads), so filtering it withholds the *call* as a side effect
1171 // of withholding the *tool*. `resolve` is the caller-facing seam precisely so that this filter
1172 // can stay strictly about what a model is offered.
1173 //
1174 // Filtered here rather than inside `Operation::project` for the same reason: projection is what
1175 // makes an operation callable, so refusing there would withhold the call along with the tool.
1176 let mut tools: Vec<Arc<dyn Tool>> = Vec::new();
1177 for operation in entry.operations {
1178 if !document_of(operation.id)?.expose {
1179 continue;
1180 }
1181 tools.push(Arc::new(Operation::project(
1182 operation,
1183 http.clone(),
1184 credentials.clone(),
1185 configuration.clone(),
1186 )?) as Arc<dyn Tool>);
1187 }
1188
1189 registry.try_register_all_from(source_label(entry.id), tools)
1190}
1191
1192/// **This operation's canonical document** — the request template every derivation now reads.
1193///
1194/// The pack's input used to be the Flux the catalogue embeds; since C-538 it is the reviewed
1195/// document `catalog/<provider>.catalog.json`, served from the pack `catalog-reader` embeds. The
1196/// lookup is by operation id, because the reader indexes it that way and the provider is one of the
1197/// facts the record carries.
1198///
1199/// # Errors
1200///
1201/// [`Error::Unbuildable`] naming the operation. Unreachable for a build this repository produced —
1202/// `crates/connector-cli/tests/catalog_pack.rs` holds the pack to being derived from the same
1203/// documents the catalogue is, in the same build — and reported as the corrupt-input case it would
1204/// be rather than unwrapped, because the alternative is a panic inside a host's registration call.
1205pub(crate) fn document_of(
1206 operation: &str,
1207) -> Result<&'static connector_resolve::document::Operation, Error> {
1208 connector_resolve::document::operation(operation).ok_or_else(|| Error::Unbuildable {
1209 operation: operation.to_owned(),
1210 message: "the embedded catalogue carries no canonical document for it, so no request \
1211 template could be read"
1212 .to_owned(),
1213 })
1214}
1215
1216/// The service base URL `operation` composes its request against, as its provider's document states
1217/// it — the template, before this tenant's connection settings are substituted into it.
1218///
1219/// # Errors
1220///
1221/// [`Error::Unbuildable`], for the same corrupt-input reason [`document_of`] reports one.
1222pub(crate) fn base_url_of(operation: &catalog::Operation) -> Result<&'static str, Error> {
1223 connector_resolve::document::provider(operation.provider)
1224 .and_then(|document| document.base_url(operation.service))
1225 .ok_or_else(|| Error::Unbuildable {
1226 operation: operation.id.to_owned(),
1227 message: format!(
1228 "its provider's canonical document declares no service `{}`, so no base URL \
1229 composes",
1230 operation.service
1231 ),
1232 })
1233}
1234
1235/// The auditable label a provider's operations are registered under.
1236///
1237/// Per-provider rather than one label for the whole pack, so a duplicate diagnostic names the
1238/// connector that contributed the colliding operation rather than "the connector pack".
1239fn source_label(provider: &str) -> String {
1240 format!("connector-pack:{provider}")
1241}
1242
1243/// **One operation, resolved for execution — exposed or not** (C-413).
1244///
1245/// This is the *caller-facing* seam, and [`pack`] is the *model-facing* one. The distinction is the
1246/// whole of C-413 and the two must not be served by one function:
1247///
1248/// - [`pack`] installs what a host **advertises**. It withholds unexposed operations, because
1249/// `expose = false` means exactly "do not offer this to a model".
1250/// - `resolve` answers a caller that **names** an operation. It withholds nothing, because
1251/// "unexposed" says a model is not offered the operation — never that nobody may run it.
1252///
1253/// Collapsing them is the mistake this function exists to prevent, and it is an easy one: a
1254/// `ToolRegistry` serves both roles at once, since [`ToolRegistry::specs`] is what a host advertises
1255/// to a model and [`ToolRegistry::get`] is what an execute route resolves through. Filtering the
1256/// registry therefore withholds the *call* as a side effect of withholding the *tool*, which would
1257/// leave a full-coverage connector with several hundred operations that are catalogued, documented,
1258/// manifest-listed — and unreachable. That is not the feature; it is the feature inverted.
1259///
1260/// # Why it still goes through a registry
1261///
1262/// Registering a single tool and reading it straight back looks like ceremony, and is not.
1263/// [`ToolRegistry::try_register_all_from`] applies flux's own admission checks — a non-empty name,
1264/// and an authority contract validated against the tool's real
1265/// [`permission_subjects`](Tool::permission_subjects) rather than against an empty set — and those
1266/// are the checks a packed tool passes before a host can call it. An execute path that skipped them
1267/// would run operations under weaker admission than the ones a model can reach, which is precisely
1268/// the wrong way round.
1269///
1270/// # Errors
1271///
1272/// Whatever [`Operation::project`] refuses, plus flux's refusal if the projected tool is one it will
1273/// not admit.
1274pub fn resolve(
1275 operation: &'static catalog::Operation,
1276 http: Egress,
1277 credentials: Credentials,
1278 configuration: Configuration,
1279) -> flux_core::Result<Arc<dyn Tool>> {
1280 let tool = Arc::new(Operation::project(
1281 operation,
1282 http,
1283 credentials,
1284 configuration,
1285 )?) as Arc<dyn Tool>;
1286 let name = tool.spec().name.clone();
1287
1288 let mut registry = ToolRegistry::new();
1289 registry.try_register_all_from(source_label(operation.provider), vec![tool])?;
1290
1291 registry.get(&name).ok_or_else(|| {
1292 Error::Unregistrable {
1293 operation: operation.id.to_owned(),
1294 message: format!("`{name}` registered and did not resolve"),
1295 }
1296 .into()
1297 })
1298}
1299
1300#[cfg(test)]
1301pub(crate) mod tests {
1302 use super::*;
1303
1304 /// A bound credential port over an **empty** store.
1305 ///
1306 /// Every test in this crate that does not itself care about credentials wants exactly this: the
1307 /// port is bound, because the pack requires one, and it holds nothing, because a test asserting
1308 /// a *request shape* must not depend on a value being present. The tests that do care live in
1309 /// `tests/credentials.rs` and put a sentinel in a store of their own.
1310 pub(crate) fn empty_credentials() -> Credentials {
1311 Credentials::new(Arc::new(connector_secrets::MemoryStore::new()), TEST_TENANT)
1312 .expect("a valid tenant id")
1313 }
1314
1315 /// The tenant both ports below answer for. One constant, because [`Operation::project`] refuses
1316 /// a pair that disagrees — which is the point of that refusal.
1317 pub(crate) const TEST_TENANT: &str = "t-connector-pack";
1318
1319 /// The value every endpoint variable is bound to. One spelling for all of them, so that
1320 /// `zendesk-ticket-show`'s expected URL is the readable `https://acme.zendesk.com/…` that
1321 /// `tool.rs` asserts, and every other templated connector composes without a per-connector
1322 /// table nobody would maintain.
1323 const TEST_ENDPOINT_VALUE: &str = "acme";
1324
1325 /// The value every Basic user half is bound to — an account identifier, which is what this half
1326 /// of the join actually is.
1327 const TEST_USERNAME_VALUE: &str = "ops@acme.test";
1328
1329 /// A bound configuration port carrying **every** endpoint variable and Basic user half the
1330 /// shipped catalogue declares, **derived from the catalogue** rather than listed.
1331 ///
1332 /// Tests in this crate assert request shapes, and a request shape is only assertable once the
1333 /// URL composes. Supplying the values here rather than per test is what keeps
1334 /// `zendesk-ticket-show`'s expected URL a readable string instead of a template.
1335 ///
1336 /// The Basic user halves are here for the same reason: they are configuration now (C-193), not
1337 /// an environment variable a test could set.
1338 ///
1339 /// **It used to be a hand-written list whose doc said "every templated connector's", and it had
1340 /// already gone stale** — okta's `domain` and statuspage's `page_id` shipped after it was
1341 /// written and were never added, so the claim was false for two of the nine templated
1342 /// connectors. Deriving it makes the claim true by construction, and it is the same discovery
1343 /// `tests/endpoint_configuration.rs` and `tests/network_gate.rs` already do: the variables come
1344 /// off each operation's own emitted Flux, and the user halves off each connector's declared
1345 /// credentials.
1346 ///
1347 /// Built once. Parsing every shipped operation's Flux is cheap but not free, and this is called
1348 /// by every test in the crate that needs a port bound at all.
1349 pub(crate) fn test_configuration() -> Configuration {
1350 static VALUES: std::sync::OnceLock<MemoryConfig> = std::sync::OnceLock::new();
1351
1352 let values = VALUES.get_or_init(|| {
1353 let mut values = MemoryConfig::new();
1354 for provider in catalog::providers() {
1355 // Walked per **operation**, so every value lands under the service that operation
1356 // reads it from (C-197). A connector's credentials are declared once, at connector
1357 // level, but the configuration field supplying a Basic user half is declared under
1358 // a service like every other — so the user halves are bound per service too, and
1359 // repeating an insert for a service already covered is free.
1360 for operation in provider.operations {
1361 for credential in provider.auth {
1362 if matches!(credential.acquire, catalog::Acquisition::BasicJoin { .. }) {
1363 values = values.with_username(
1364 TEST_TENANT,
1365 provider.id,
1366 operation.service,
1367 credential.name,
1368 TEST_USERNAME_VALUE,
1369 );
1370 }
1371 }
1372 let declaration = spec::declaration_of(operation.id, operation.flux)
1373 .unwrap_or_else(|error| panic!("`{}`: {error}", operation.id));
1374 for variable in request::endpoint_variables(&declaration) {
1375 let binding = format!("endpoint.{variable}");
1376 if provider.config.iter().any(|field| {
1377 field.service == operation.service
1378 && field.binds == binding
1379 && field.format == "origin"
1380 }) {
1381 // Origin declarations carry their reviewed default. Leaving this slot
1382 // absent exercises that zero-configuration path and avoids inventing a
1383 // custom origin without an operator approval.
1384 continue;
1385 }
1386 values = values.with_endpoint(
1387 TEST_TENANT,
1388 provider.id,
1389 operation.service,
1390 &variable,
1391 TEST_ENDPOINT_VALUE,
1392 );
1393 }
1394 }
1395 }
1396 values
1397 });
1398
1399 Configuration::new(Arc::new(values.clone()), TEST_TENANT).expect("a valid tenant id")
1400 }
1401
1402 /// **The guard on the derivation.** A helper claiming completeness has to be checked against the
1403 /// thing it claims to cover, or it is the same hand-written list with extra steps. The two
1404 /// connectors named are the ones the previous list had missed.
1405 #[test]
1406 fn the_test_configuration_covers_every_templated_connector() {
1407 let configuration = test_configuration();
1408
1409 let mut templated = 0usize;
1410 for entry in catalog::operations() {
1411 let operation = Operation::project(
1412 entry,
1413 recording_http(),
1414 empty_credentials(),
1415 configuration.clone(),
1416 )
1417 .unwrap_or_else(|error| panic!("`{}`: {error}", entry.id));
1418 if operation.endpoint_variables().is_empty() {
1419 continue;
1420 }
1421 templated += 1;
1422 // `endpoints()` is resolved before any parameter is read, so an uncovered variable
1423 // surfaces here as `MissingConfig` rather than hiding behind the `MissingParameter`
1424 // this deliberately empty argument object also earns.
1425 if let Err(error) = operation.build_request(&serde_json::json!({})) {
1426 assert!(
1427 !matches!(error, Error::MissingConfig { .. }),
1428 "the derived configuration does not cover `{}`: {error}",
1429 entry.id
1430 );
1431 }
1432 }
1433
1434 assert!(
1435 templated > 0,
1436 "no shipped operation declares a configuration variable, so this asserted nothing"
1437 );
1438 for (provider, variable) in [("okta", "domain"), ("statuspage", "page_id")] {
1439 assert!(
1440 catalog::operations_of(ProviderKey::id(provider))
1441 .iter()
1442 .any(|entry| {
1443 let declaration = spec::declaration_of(entry.id, entry.flux)
1444 .expect("a shipped rendering parses");
1445 request::endpoint_variables(&declaration)
1446 .iter()
1447 .any(|found| found == variable)
1448 }),
1449 "`{provider}` no longer declares `{variable}`, so this guard names the wrong case"
1450 );
1451 }
1452 }
1453
1454 /// A stand-in for flux's `http.request`, for tests that need a transport but not a socket.
1455 ///
1456 /// A real [`flux_runtime::ToolContext`] needs a `flux_system::System` over a real workspace
1457 /// root, which unit tests in this crate do not build — so what they assert is
1458 /// [`Operation::build_request`], the request *before* it is sent, which is where the two
1459 /// mistakes that matter live. `execute` is driven end to end from `tests/credentials.rs`, where
1460 /// the `flux-system` dev-dependency makes a real context available.
1461 pub(crate) fn recording_http() -> Egress {
1462 Egress::new(flux_runtime::tool_fn(
1463 flux_spec::ToolSpec {
1464 name: "http.request".into(),
1465 description: "a stand-in that echoes the request it was handed".into(),
1466 input_schema: serde_json::json!({"type": "object"}),
1467 output_schema: None,
1468 effects: vec![flux_spec::Effect::Network],
1469 risk: flux_spec::Risk::Medium,
1470 idempotency: flux_spec::Idempotency::NonIdempotent,
1471 access: vec![flux_spec::AccessKind::Network],
1472 group: None,
1473 },
1474 |params| async move { Ok(params) },
1475 ))
1476 }
1477
1478 /// **The two spellings of seven refusals render one sentence.**
1479 ///
1480 /// [`From<connector_resolve::Error>`](Error) maps each of the plan-deriving core's variants onto
1481 /// the identically-named one here, and the two crates each carry their own `#[error(…)]` text.
1482 /// That duplication is deliberate — see the impl's own documentation — and it is the kind that
1483 /// rots silently, because nothing *fails* when one side is reworded: a host just starts reading
1484 /// a different sentence depending on which crate raised the refusal.
1485 ///
1486 /// So both sides are rendered here, over field values chosen to appear in every interpolation
1487 /// slot, and required to be equal. A variant added to the core makes the match in `From` a
1488 /// compile error; a variant *reworded* in either makes this test red.
1489 #[test]
1490 fn the_mapped_refusals_render_the_same_sentence() {
1491 use connector_resolve::Error as Refused;
1492
1493 let operation = || "acme-thing-list".to_owned();
1494 let refusals = [
1495 Refused::MissingParameter {
1496 operation: operation(),
1497 parameter: "thing_id".to_owned(),
1498 },
1499 Refused::UnsafePathParameter {
1500 operation: operation(),
1501 parameter: "thing_id".to_owned(),
1502 reason: "it contains a slash".to_owned(),
1503 },
1504 Refused::Unbuildable {
1505 operation: operation(),
1506 message: "its template says something else".to_owned(),
1507 },
1508 Refused::UnsafeConfig {
1509 operation: operation(),
1510 variable: "subdomain".to_owned(),
1511 position: "host",
1512 reason: "it contains an at sign".to_owned(),
1513 },
1514 Refused::UnresolvedEndpoint {
1515 operation: operation(),
1516 variable: "subdomain".to_owned(),
1517 url: "https://{subdomain}.acme.test/things".to_owned(),
1518 },
1519 Refused::CredentialCollision {
1520 operation: operation(),
1521 credential: "acme.token".to_owned(),
1522 header: "Authorization".to_owned(),
1523 },
1524 Refused::InboundCredential {
1525 operation: operation(),
1526 credential: "acme.signing_secret".to_owned(),
1527 },
1528 // The producers' refusals (C-557).
1529 Refused::MissingConfig {
1530 operation: operation(),
1531 provider: "acme".to_owned(),
1532 service: "default".to_owned(),
1533 tenant: "t-1".to_owned(),
1534 field: "endpoint.subdomain".to_owned(),
1535 },
1536 Refused::UnapprovedConfig {
1537 operation: operation(),
1538 provider: "acme".to_owned(),
1539 service: "default".to_owned(),
1540 field: "origin".to_owned(),
1541 },
1542 Refused::UnsafeOrigin {
1543 operation: operation(),
1544 provider: "acme".to_owned(),
1545 service: "default".to_owned(),
1546 field: "origin".to_owned(),
1547 reason: "it is not https".to_owned(),
1548 },
1549 Refused::MissingCredential {
1550 operation: operation(),
1551 path: "tenants/t-1/com.acme.api/token".to_owned(),
1552 alternatives: 2,
1553 },
1554 Refused::CredentialStore {
1555 operation: operation(),
1556 credential: "acme.token".to_owned(),
1557 source: connector_secrets::StoreError::Unreachable {
1558 path: "tenants/t-1/com.acme.api/token".to_owned(),
1559 reason: "connection refused".to_owned(),
1560 },
1561 },
1562 Refused::NoCredentialAddress {
1563 operation: operation(),
1564 provider: "acme".to_owned(),
1565 credential: "acme.token".to_owned(),
1566 },
1567 Refused::CredentialAddress {
1568 operation: operation(),
1569 credential: "acme.token".to_owned(),
1570 reason: "authority: not a reverse-DNS name".to_owned(),
1571 },
1572 Refused::UndeclaredCredential {
1573 operation: operation(),
1574 credential: "acme.token".to_owned(),
1575 provider: "acme".to_owned(),
1576 },
1577 Refused::MissingCredentialConfig {
1578 operation: operation(),
1579 credential: "acme.token".to_owned(),
1580 tenant: "t-1".to_owned(),
1581 env: "ACME_USER".to_owned(),
1582 },
1583 Refused::EmptyMechanism {
1584 operation: operation(),
1585 },
1586 // The channel-handshake producer's refusals (C-558).
1587 Refused::NotSocketChannel {
1588 provider: "acme".to_owned(),
1589 binding: "events".to_owned(),
1590 },
1591 Refused::VendorSocketChannel {
1592 provider: "acme".to_owned(),
1593 binding: "socket".to_owned(),
1594 },
1595 ];
1596
1597 for refusal in refusals {
1598 let core = refusal.to_string();
1599 let mapped = Error::from(refusal).to_string();
1600 assert_eq!(
1601 core, mapped,
1602 "the plan-deriving core and this crate word one refusal differently"
1603 );
1604 }
1605 }
1606
1607 #[test]
1608 fn a_providers_operations_are_labelled_with_the_provider() {
1609 let mut registry = ToolRegistry::new();
1610 pack(
1611 &["zendesk"],
1612 recording_http(),
1613 empty_credentials(),
1614 test_configuration(),
1615 )(&mut registry)
1616 .expect("zendesk installs");
1617
1618 assert_eq!(
1619 registry.source("zendesk.ticket.show"),
1620 Some("connector-pack:zendesk")
1621 );
1622 }
1623
1624 /// The closure must not borrow the slice it was built from, or a host could not build a pack
1625 /// from a temporary and hand it to a builder.
1626 #[test]
1627 fn the_pack_outlives_the_names_it_was_built_from() {
1628 let install = {
1629 let names = vec!["zendesk"];
1630 pack(
1631 &names,
1632 recording_http(),
1633 empty_credentials(),
1634 test_configuration(),
1635 )
1636 };
1637
1638 let mut registry = ToolRegistry::new();
1639 install(&mut registry).expect("zendesk installs");
1640 assert!(registry.get("zendesk.ticket.show").is_some());
1641 }
1642
1643 /// Two providers, one registry, one call — the shape the design's example uses.
1644 #[test]
1645 fn several_providers_install_together() {
1646 let mut registry = ToolRegistry::new();
1647 pack(
1648 &["zendesk", "slack"],
1649 recording_http(),
1650 empty_credentials(),
1651 test_configuration(),
1652 )(&mut registry)
1653 .expect("both install");
1654
1655 assert!(registry.get("zendesk.ticket.show").is_some());
1656 assert!(registry.get("slack.chat.post.message").is_some());
1657 assert_eq!(
1658 registry.source("slack.chat.post.message"),
1659 Some("connector-pack:slack")
1660 );
1661 }
1662
1663 #[test]
1664 fn an_unknown_provider_names_itself() {
1665 let mut registry = ToolRegistry::new();
1666 // See `connector-catalog`'s note on negative sentinels: `salesforce` used to sit here and
1667 // stopped being unknown the moment C-163 shipped it.
1668 const NO_SUCH_PROVIDER: &str = "no-such-vendor";
1669
1670 let error = pack(
1671 &[NO_SUCH_PROVIDER],
1672 recording_http(),
1673 empty_credentials(),
1674 test_configuration(),
1675 )(&mut registry)
1676 .expect_err("no such connector");
1677
1678 assert!(error.to_string().contains(NO_SUCH_PROVIDER), "{error}");
1679 assert!(registry.names().is_empty());
1680 }
1681
1682 /// **One transport for the whole pack.** Every operation delegates to the instance the host
1683 /// supplied, so a host that configured one egress policy does not find connectors quietly using
1684 /// another.
1685 #[test]
1686 fn every_operation_delegates_to_the_transport_the_host_supplied() {
1687 let http = recording_http();
1688 let entries = catalog::operations_of(ProviderKey::id("zendesk"));
1689 assert!(!entries.is_empty(), "zendesk carries operations");
1690
1691 for entry in entries {
1692 let operation = Operation::project(
1693 entry,
1694 http.clone(),
1695 empty_credentials(),
1696 test_configuration(),
1697 )
1698 .expect("the entry projects");
1699 assert!(
1700 Arc::ptr_eq(http.tool(), operation.egress().tool()),
1701 "`{}` holds a transport the host did not supply",
1702 entry.id
1703 );
1704 }
1705 }
1706}