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
57use stack_encrypt:: dynamic:: { self , TargetDescriptor , TargetOptions , TargetResolver , ValueFrame } ;
68use stack_encrypt:: target:: IndexSpec ;
79use stack_encrypt:: { KeysetCipher , Label , Pending , StackCipher } ;
810
911use 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 ) ]
3742pub 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 .
9196impl 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.
129139impl 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