Expand description
The plan-deriving core: a connector’s canonical document in, its HTTP request plan out.
use std::collections::BTreeMap;
let zendesk = connector_resolve::document::provider("zendesk").expect("a shipped connector");
let operation = zendesk.operation("zendesk-ticket-show").expect("a shipped operation");
let base = zendesk.base_url(&operation.service).expect("its service");
let plan = connector_resolve::resolve(
operation,
base,
&serde_json::json!({ "ticket_id": 35436 }),
&BTreeMap::from([("subdomain".to_string(), "acme".to_string())]),
&[],
)?;
assert_eq!(plan.request.method, "GET");
assert_eq!(plan.request.url, "https://acme.zendesk.com/api/v2/tickets/35436");§Engine-free, and that is the point rather than a coincidence
codewandler-connector-pack’s resolve returns flux_core::Result<Arc<dyn Tool>>, which
couples every consumer to one codewandler-flux-* line even when no catalogue content changed
(docs/designs/catalog-artifact.md §3). This crate is the half of that work which has no engine
in it: it links no codewandler-flux-* crate, and
crates/connector-cli/tests/main/engine_free_core.rs::the_plan_deriving_core_links_no_engine_crate
asserts that over the graph cargo resolves — kinds filtered to the edges a consumer links —
rather than over this paragraph.
It also opens no socket, holds no HTTP client and resolves no host. Dispatch is the consumer’s:
connector-pack wraps a plan in a flux Tool, and Exchange wraps one in its own workflows.
§One boundary a consumer must hold
Projecting a plan into a Tool is not composing a request. A consumer wraps and dispatches the plan it was handed; a consumer that edits one has become a second request-composition path, which is the defect this whole design exists to end.
§What is derived here, and what is the caller’s
Derived here: the method, the URL with its structured query, the headers, the body, the
permission subjects, and the set of strings a redactor must hold. Its two data inputs — the
tenant’s resolved endpoint map and the assembled credentials — are produced here too as of
C-557, from bound ports the caller implements: resolve_endpoints over a ConfigPort, and
assemble_credentials over a connector_secrets::SecretStore. The ports say what this
tenant’s value is; the producers apply the enforcement — declared defaults, operator approval,
origin normalisation, mechanism selection, the acquisition axis, the redaction set — on top. A
crate that reached past the ports for a value would be a crate that had opinions about where a
tenant’s secrets live, which is why the ports exist.
The producers are the whole point of the split for a host: they were pub(crate) in the
flux-coupled connector-pack, so no engine-free consumer could produce a plan. connector-pack’s
own Configuration/Credentials producers now delegate here, and the whole-catalogue
differential gate holds the two to one plan.
§The refusals are the safety property
Every Error variant refuses; none repairs. A partly-evaluated request is not a degraded
request — it is a different call, and the vendor at the other end answers it.
Modules§
- auth
- The two axes of authentication: acquisition (what the stored value becomes) and placement (where it goes on the request).
- document
- The canonical document, typed.
Structs§
- Assembly
- The credentials one operation’s chosen mechanism resolves to, and everything to redact.
- Config
Value - One connection setting and the policy decision that may activate it.
- Prepared
Channel Plan - A complete RFC 6455 handshake plan containing no client, socket, resolver or runtime.
- Redaction
- One credential-derived string a consumer must register with its redactor, and the credential it came from.
- Request
- The request:
{ method, url, headers, body }, exactlyhttp.request’s own input. - Request
Plan - What one call would send, as data.
- Sensitive
Text - Text that may contain credential material and therefore never reveals itself through
Debug.
Enums§
- Config
Field - Which non-secret connection value the resolver is asking for.
- Error
- Why a request plan could not be derived from the document.
- Slot
- Where a configuration variable lands on the request.
Constants§
- DEFAULT_
USER_ AGENT - What this software calls itself on the wire (C-223).
Traits§
- Config
Port - A host’s non-secret connection settings, as the endpoint resolver asks for them.
Functions§
- assemble_
credentials - Resolve, assemble and collect the redactions for one operation’s credentials (C-557).
- build_
request - The request
operationmakes when called withparams, overendpoints. - channel_
plan - Compose a generated socket channel from catalogue declarations and bound tenant ports (C-558).
- resolve
- The plan
operationmakes when called withparams, withcredentialsplaced on it. - resolve_
endpoint - Resolve and validate one endpoint value through the same path request construction and a host’s permission fallback both take (C-557).
- resolve_
endpoints - Resolve every endpoint variable
operationnames, or refuse (C-557). - scan_
template - The one brace grammar, shared by every template this crate reads.
- text
- flux-lang’s
lit_text: a string is itself,nullis empty, anything else is compact JSON. - truthy
- flux-lang’s
json_truthy: null/false/0/empty are falsey, and so is the text"false"/"0". - validate_
authority - Whether
authorityis still an authority once a configuration value has been substituted into it. - validate_
header - A value that is an HTTP field value and nothing more (RFC 9110 §5.5).
- validate_
path - A value that stays inside one path segment.
- validate_
query - A value that adds no parameter of its own to the query string.
- validate_
templated_ authority - Validate an authority whose template, rather than a configured value, may state a port.