Skip to main content

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}