connector_address/lib.rs
1//! The address vocabulary: how a provider, a service, an operation and a tenant's credential are
2//! **named**.
3//!
4//! ```text
5//! pid com.amazonaws the provider
6//! gid com.amazonaws/s3:2006-03-01 one service of it, versioned
7//! oip com.amazonaws/s3:2006-03-01#object-get one operation
8//! credential tenants/<tenant>/com.zendesk.api/api_token where a tenant's secret lives
9//! ```
10//!
11//! [`address`] owns the first three and [`credential`] the fourth; they share one grammar, one
12//! reserved [`DEFAULT_SERVICE`] and one elision rule, which is why they are one crate.
13//!
14//! [`origin`] owns one more name of the same kind: **which server** a connection reaches, when the
15//! vendor is self-managed and the connector cannot know it in advance. It is here for the reason the
16//! rest of this crate is here — the compiler validates a declared origin, the runtime pack composes
17//! a request and a permission subject from a supplied one, and Exchange persists and approves a
18//! proposal, so a copy of the grammar in each of them is three programs that can disagree about
19//! which destination was approved (C-523).
20//!
21//! # Why this is its own crate
22//!
23//! It used to be two modules of `connector-spec`, and that crate is the **compiler**: the connector
24//! IR, provider TOML and OpenAPI ingest, validation and the lockfile writer. `connector-secrets` —
25//! a published host library — re-exports [`CredentialRef`] and the rest, because a consumer should
26//! never have to name two crates to spell one address. The publish closure is *derived* from the
27//! manifests, so that one re-export dragged the whole compiler onto crates.io, permanently, to make
28//! a few hundred lines of vocabulary resolve (C-407).
29//!
30//! An address vocabulary is a reasonable thing to have in a published API. A compiler is not. So the
31//! vocabulary moved down here and the edge **inverted**: `connector-spec` is now a *consumer* of
32//! this crate — [`Connector::gid_of`][gid_of] and [`credential_ref_for`][credential_ref_for] derive
33//! addresses from a loaded connector — and it re-exports every name below, so
34//! `connector_spec::address` and `connector_spec::credential` are unchanged for anything that
35//! already spelled them that way.
36//!
37//! [gid_of]: https://docs.rs/codewandler-connector-spec/latest/connector_spec/struct.Connector.html
38//! [credential_ref_for]: https://docs.rs/codewandler-connector-spec/latest/connector_spec/struct.Connector.html
39//!
40//! # What it does not do
41//!
42//! It holds no secret, opens no socket and reads no file. An address is a **name**; resolving one to
43//! a secret is `connector-secrets`' job, and producing one from a provider definition is
44//! `connector-spec`'s. This crate only says which names are well-formed and how they render — which
45//! is exactly why it can be validated, round-tripped, and depended on by both sides.
46//!
47//! [`HttpsOrigin`] is the one name a *tenant* supplies rather than a provider file, and it does not
48//! widen that boundary: it is normalized text, it stores nothing, and it says nothing about whether
49//! deployment policy has approved the destination it names — that state stays with the host.
50//!
51//! ```
52//! use connector_address::{CredentialRef, Gid, Layout, TenantLayout};
53//!
54//! let gid = Gid::parse("com.amazonaws/s3:2006-03-01")?;
55//! assert_eq!(gid.service, "s3");
56//!
57//! let reference = CredentialRef::new("9f3a4b2c", "com.zendesk.api", "support", "api_token")
58//! .expect("a valid address");
59//! assert_eq!(
60//! TenantLayout.render(&reference),
61//! "tenants/9f3a4b2c/com.zendesk.api/support/api_token"
62//! );
63//! # Ok::<(), connector_address::Error>(())
64//! ```
65
66pub mod address;
67pub mod credential;
68pub mod origin;
69
70pub use address::{Gid, Oip, Pid};
71pub use credential::{
72 CredentialRef, CredentialScope, InstanceId, Layout, TenantInstances, TenantLayout,
73};
74pub use origin::{HttpsOrigin, OriginRefusal};
75
76/// The name of the implicit service every operation belongs to unless it names another.
77///
78/// **Reserved.** No `[[services]]` entry may declare it (`connector-spec`'s provider loader refuses
79/// one), because it is the name of the service that exists without being declared — a declaration
80/// of it would be a second, contradictable definition. It is also **elided from every rendered
81/// address** ([`Gid`], [`CredentialRef`]): `default` is an internal name for "this provider has one
82/// API surface", and an address is a promise that would have to be broken the day the provider grows
83/// a second one.
84///
85/// It lives here rather than in the IR because the elision is an *address* rule: both grammars in
86/// this crate are written against it, and a copy on either side of the crate boundary is a copy that
87/// can drift.
88pub const DEFAULT_SERVICE: &str = "default";
89
90/// An address is not well-formed.
91///
92/// One variant, because there is one failure: a string that does not spell an address. The text and
93/// the reason are carried separately so a caller can echo the offending input back verbatim — an
94/// address a user typed is worth quoting exactly as they typed it.
95///
96/// Only the *parsing* direction produces this. Every validator in this crate returns a plain reason
97/// string instead, so `connector-spec`'s provider loader can fold the reason into its own
98/// all-problems-at-once report rather than unwrapping an error to get at it.
99#[derive(Debug, thiserror::Error)]
100pub enum Error {
101 /// A global address (pid, gid or oip) is not well-formed — see [`address`].
102 #[error("`{address}` is not a valid address: {reason}")]
103 InvalidAddress {
104 /// The address as it was given.
105 address: String,
106 /// Why it is not one.
107 reason: String,
108 },
109}
110
111/// The crate's result alias.
112pub type Result<T> = std::result::Result<T, Error>;