Skip to main content

Crate connector_resolve

Crate connector_resolve 

Source
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.
ConfigValue
One connection setting and the policy decision that may activate it.
PreparedChannelPlan
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 }, exactly http.request’s own input.
RequestPlan
What one call would send, as data.
SensitiveText
Text that may contain credential material and therefore never reveals itself through Debug.

Enums§

ConfigField
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§

ConfigPort
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 operation makes when called with params, over endpoints.
channel_plan
Compose a generated socket channel from catalogue declarations and bound tenant ports (C-558).
resolve
The plan operation makes when called with params, with credentials placed 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 operation names, 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, null is 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 authority is 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.