Skip to content

Commit 914417d

Browse files
committed
docs(eql-bindings): rewrite the shared resolver docs in plain language
The docs for EqlTargets and its two conversions, and the module docs of the Go guest's resolver, now use short sentences that name who does what. They say Stack Encrypt where they said the engine.
1 parent 4cd9647 commit 914417d

2 files changed

Lines changed: 67 additions & 47 deletions

File tree

‎languages/golang/encrypt/guest/src/targets.rs‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,19 @@
33
//! target fields through. The two names below are cfg-dependent, so they
44
//! are code spans, not links: a doc build of either feature set resolves.
55
//!
6-
//! Two builds of this crate, one resolver each (ADR-0007, amended
7-
//! 2026-10-06). With the `eql` feature, [`Resolver`] is `eql-bindings`'
8-
//! own resolver (`eql_bindings::encryption::EqlTargets`): `se_targets`
9-
//! lists every EQL type the catalog has, and a plan field naming a
10-
//! producible one (`TextEq`) is run through that type's own plan, in the
11-
//! same ZeroKMS request as the rest of the record. Without it,
12-
//! [`Resolver`] is the engine's `NoTargets`
13-
//! (`stack_encrypt::dynamic::NoTargets`): `se_targets` lists nothing, and
14-
//! a plan that names a target is refused when it is parsed — at
15-
//! `se_plan_check`, before any value crosses.
6+
//! This crate has two builds. Each build has one resolver (ADR-0007,
7+
//! amended 2026-10-06).
8+
//!
9+
//! - With the `eql` feature, [`Resolver`] is the resolver from
10+
//! `eql-bindings`, `eql_bindings::encryption::EqlTargets`. `se_targets`
11+
//! lists every EQL type in the catalog. A plan field can name any type
12+
//! that the build can produce, such as `TextEq`. The build encrypts that
13+
//! field with the type's own plan, in the same ZeroKMS request as the
14+
//! rest of the record.
15+
//! - Without the feature, [`Resolver`] is `NoTargets` from Stack Encrypt,
16+
//! `stack_encrypt::dynamic::NoTargets`. `se_targets` lists nothing.
17+
//! `se_plan_check` refuses a plan that names a type when it parses the
18+
//! plan, before the guest receives any value.
1619
//!
1720
//! The Go module embeds both: `encrypt` the build without EQL types,
1821
//! `encrypt/eql` the build with them, registered on import, so a program

‎packages/eql/crates/eql-bindings/src/encryption/resolver.rs‎

Lines changed: 54 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,29 @@
1-
//! The EQL types as Stack Encrypt's resolver: [`EqlTargets`], and the two
2-
//! conversions it is built from. The module is private, so the type's own
3-
//! documentation is what a reader sees.
1+
//! [`EqlTargets`] gives the EQL types to Stack Encrypt. This module also
2+
//! has the two conversions that `EqlTargets` uses.
3+
//!
4+
//! This module is private. Readers of the published docs only read the
5+
//! documentation on `EqlTargets`.
46
57
use stack_encrypt::dynamic::{self, TargetDescriptor, TargetOptions, TargetResolver, ValueFrame};
68
use stack_encrypt::target::IndexSpec;
79
use stack_encrypt::{KeysetCipher, Label, Pending, StackCipher};
810

911
use super::targets::{self, decrypt, encrypt_with, query, Target, TargetError};
1012

11-
/// Every EQL type this crate defines, as Stack Encrypt's resolver.
13+
/// Gives Stack Encrypt every EQL type that this crate defines.
1214
///
13-
/// Stack Encrypt's dynamic interface runs a plan that arrives as data. A
14-
/// field of that plan may name an EQL type, such as `"TextEq"`. Stack
15-
/// Encrypt does not depend on this crate, so a program gives it the EQL
16-
/// types through a [`TargetResolver`]. `EqlTargets` is that resolver. It
17-
/// holds every type in [`targets`](super::targets::targets), and runs a
18-
/// named type through [`encrypt_with`], [`decrypt`] and [`query`].
15+
/// The dynamic interface of Stack Encrypt runs a plan that arrives as
16+
/// data. A field of that plan can name an EQL type, such as `"TextEq"`.
17+
/// Stack Encrypt does not depend on this crate, so your program passes the
18+
/// EQL types to Stack Encrypt through a [`TargetResolver`]. `EqlTargets`
19+
/// is that resolver.
1920
///
20-
/// Pass `&EqlTargets` wherever the dynamic interface takes a resolver, such
21-
/// as `stack_encrypt::dynamic::record::plan_with`.
21+
/// `EqlTargets` lists every type in [`targets`](super::targets::targets).
22+
/// For a type that a plan names, `EqlTargets` calls [`encrypt_with`],
23+
/// [`decrypt`], or [`query`].
24+
///
25+
/// Pass `&EqlTargets` wherever the dynamic interface accepts a resolver,
26+
/// such as `stack_encrypt::dynamic::record::plan_with`.
2227
///
2328
/// ```
2429
/// use eql_bindings::encryption::EqlTargets;
@@ -30,9 +35,9 @@ use super::targets::{self, decrypt, encrypt_with, query, Target, TargetError};
3035
/// # Ok::<(), stack_encrypt::dynamic::TargetError>(())
3136
/// ```
3237
///
33-
/// The resolver sees a type's name and a field's label. It never sees the
34-
/// field's name, so a refusal leaves the field name empty and the engine
35-
/// fills it in.
38+
/// Stack Encrypt passes the resolver a type's name and a field's label,
39+
/// and never the field's name. An error from the resolver therefore has
40+
/// an empty field name, and Stack Encrypt adds the name.
3641
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
3742
pub struct EqlTargets;
3843

@@ -77,17 +82,17 @@ impl TargetResolver for EqlTargets {
7782
}
7883
}
7984

80-
/// A row of the target table as the engine's descriptor. The two have one
81-
/// wire format.
85+
/// Converts a row of the target table to the descriptor that Stack
86+
/// Encrypt uses. The row and the descriptor have the same wire format.
8287
///
83-
/// The descriptor also carries what the engine needs and the wire does
84-
/// not:
88+
/// The descriptor also contains two things that Stack Encrypt needs and
89+
/// the wire format leaves out:
8590
///
86-
/// - the match options, for a type with a match index. The engine answers
87-
/// `matches` through the type only when it knows them;
88-
/// - the three query domains of a type that stores a JSON document. An
89-
/// ordering at a path binds as the leaf operand, `element_match` as the
90-
/// elements operand, and `match` as the predicate operand.
91+
/// - The match options, for a type with a match index. Stack Encrypt runs
92+
/// `matches` through the type only when the descriptor has them.
93+
/// - The three query domains, for a type that stores a JSON document. An
94+
/// ordering at a path uses the leaf domain. `element_match` uses the
95+
/// elements domain. `match` uses the predicate domain.
9196
impl From<&Target> for TargetDescriptor {
9297
fn from(target: &Target) -> Self {
9398
let mut descriptor = TargetDescriptor::new(
@@ -118,14 +123,19 @@ impl From<&Target> for TargetDescriptor {
118123
}
119124
}
120125

121-
/// A refusal of this crate as the engine's. The field name is left empty:
122-
/// the engine fills it in, since the resolver never sees it.
126+
/// Converts an error of this crate to the error type of Stack Encrypt.
127+
///
128+
/// The field name is left empty. Stack Encrypt adds the name, because the
129+
/// resolver never receives it.
130+
///
131+
/// No variant contains any byte of a plaintext or of a stored value:
123132
///
124-
/// No variant carries a byte of a plaintext or of a stored value. A value
125-
/// that is not a JSON document keeps the engine's code for what was wrong.
126-
/// A stored value that does not parse keeps the parser's kind and position
127-
/// and not its message, because `serde_json` quotes the input it refused,
128-
/// and that input is stored ciphertext.
133+
/// - For a value that is not a JSON document, the error keeps the code
134+
/// that Stack Encrypt gave for the fault.
135+
/// - For a stored value that does not parse, the error keeps the kind and
136+
/// position that the parser reported, and drops the parser's message.
137+
/// `serde_json` quotes the input it refused in that message, and the
138+
/// input is stored ciphertext.
129139
impl From<TargetError> for dynamic::TargetError {
130140
fn from(error: TargetError) -> Self {
131141
match error {
@@ -162,12 +172,19 @@ impl From<TargetError> for dynamic::TargetError {
162172
target: target.to_owned(),
163173
reason: stack_encrypt::diagnostic::describe_json_error(&source),
164174
},
165-
// The engine refuses each of these before it calls the
166-
// resolver: it derives a document's queries itself, asks a query
167-
// only through an index the type carries, and refuses options on
168-
// a type with no JSON index when it builds the plan. Reaching
169-
// one is the engine's failure, not the caller's input. Each is
170-
// named, so a variant added later must be placed by hand.
175+
// Stack Encrypt refuses each of these before it calls the
176+
// resolver:
177+
//
178+
// - Stack Encrypt derives the queries of a document itself.
179+
// - Stack Encrypt only asks for a query through an index that
180+
// the type has.
181+
// - Stack Encrypt refuses options on a type with no JSON index
182+
// when it builds the plan.
183+
//
184+
// If the resolver returns one of these, the fault is in Stack
185+
// Encrypt, not in the caller's input. The match names each
186+
// variant, so that a variant added later does not compile
187+
// until someone decides where it goes.
171188
error @ (TargetError::DocumentQuery { .. }
172189
| TargetError::NoIndex { .. }
173190
| TargetError::Options { .. }) => Self::Other(Box::new(error)),

0 commit comments

Comments
 (0)