Skip to main content

connector_resolve/
lib.rs

1//! **The plan-deriving core**: a connector's canonical document in, its HTTP request plan out.
2//!
3//! ```no_run
4//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
5//! use std::collections::BTreeMap;
6//!
7//! let zendesk = connector_resolve::document::provider("zendesk").expect("a shipped connector");
8//! let operation = zendesk.operation("zendesk-ticket-show").expect("a shipped operation");
9//! let base = zendesk.base_url(&operation.service).expect("its service");
10//!
11//! let plan = connector_resolve::resolve(
12//!     operation,
13//!     base,
14//!     &serde_json::json!({ "ticket_id": 35436 }),
15//!     &BTreeMap::from([("subdomain".to_string(), "acme".to_string())]),
16//!     &[],
17//! )?;
18//!
19//! assert_eq!(plan.request.method, "GET");
20//! assert_eq!(plan.request.url, "https://acme.zendesk.com/api/v2/tickets/35436");
21//! # Ok(())
22//! # }
23//! ```
24//!
25//! # Engine-free, and that is the point rather than a coincidence
26//!
27//! `codewandler-connector-pack`'s `resolve` returns `flux_core::Result<Arc<dyn Tool>>`, which
28//! couples every consumer to one `codewandler-flux-*` line even when no catalogue content changed
29//! (`docs/designs/catalog-artifact.md` §3). This crate is the half of that work which has no engine
30//! in it: it links no `codewandler-flux-*` crate, and
31//! `crates/connector-cli/tests/main/engine_free_core.rs::the_plan_deriving_core_links_no_engine_crate`
32//! asserts that over the graph cargo resolves — kinds filtered to the edges a *consumer* links —
33//! rather than over this paragraph.
34//!
35//! It also opens no socket, holds no HTTP client and resolves no host. Dispatch is the consumer's:
36//! `connector-pack` wraps a plan in a flux `Tool`, and Exchange wraps one in its own workflows.
37//!
38//! # One boundary a consumer must hold
39//!
40//! **Projecting a plan into a Tool is not composing a request.** A consumer wraps and dispatches
41//! the plan it was handed; a consumer that *edits* one has become a second request-composition
42//! path, which is the defect this whole design exists to end.
43//!
44//! # What is derived here, and what is the caller's
45//!
46//! Derived here: the method, the URL with its structured query, the headers, the body, the
47//! permission subjects, and the set of strings a redactor must hold. Its two data inputs — the
48//! tenant's resolved endpoint map and the assembled credentials — are **produced here too** as of
49//! C-557, from bound ports the caller implements: [`resolve_endpoints`] over a [`ConfigPort`], and
50//! [`assemble_credentials`] over a [`connector_secrets::SecretStore`]. The ports say *what this
51//! tenant's value is*; the producers apply the enforcement — declared defaults, operator approval,
52//! origin normalisation, mechanism selection, the acquisition axis, the redaction set — on top. A
53//! crate that reached past the ports for a value would be a crate that had opinions about where a
54//! tenant's secrets live, which is why the ports exist.
55//!
56//! The producers are the whole point of the split for a host: they were `pub(crate)` in the
57//! flux-coupled `connector-pack`, so no engine-free consumer could produce a plan. `connector-pack`'s
58//! own `Configuration`/`Credentials` producers now delegate here, and the whole-catalogue
59//! differential gate holds the two to one plan.
60//!
61//! # The refusals are the safety property
62//!
63//! Every [`Error`] variant refuses; none repairs. A partly-evaluated request is not a degraded
64//! request — it is a different call, and the vendor at the other end answers it.
65
66#![deny(missing_docs)]
67
68pub mod auth;
69mod channel;
70mod config;
71mod credentials;
72pub mod document;
73mod endpoints;
74mod error;
75mod plan;
76mod request;
77mod resolve;
78mod slot;
79mod template;
80
81pub use channel::{channel_plan, PreparedChannelPlan};
82pub use config::{ConfigField, ConfigPort, ConfigValue};
83pub use credentials::{assemble_credentials, Assembly, Redaction};
84pub use endpoints::{resolve_endpoint, resolve_endpoints};
85pub use error::Error;
86pub use plan::{RequestPlan, SensitiveText};
87pub use request::{Request, DEFAULT_USER_AGENT};
88pub use resolve::{build_request, resolve};
89pub use slot::{
90    validate_authority, validate_header, validate_path, validate_query,
91    validate_templated_authority, Slot,
92};
93pub use template::{scan_template, text, truthy};