Skip to content

Commit d8aeadb

Browse files
committed
docs(stack-encrypt): rewrite the order index docs in plain language
The docs that explain why an order index refuses bytes now use short sentences with one idea each. They say that an operator accepts a type, where they said that an operator is answered over a type. The note on the Index error lists what each index accepts.
1 parent 8ed21a6 commit d8aeadb

7 files changed

Lines changed: 88 additions & 66 deletions

File tree

‎languages/golang/stashgen/emit.go‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -802,14 +802,15 @@ func planQueries(f *genFile) error {
802802
return nil
803803
}
804804

805-
// verifiable refuses a probabilistic query on an index-only field: the
806-
// query's rows are checked by decrypting them with Verify, and an
807-
// index-only field stores no ciphertext, so Verify could never pass and
808-
// every real match would be thrown away.
805+
// verifiable refuses a probabilistic query on a field that only stores an
806+
// index. The caller checks the rows of such a query by decrypting them
807+
// with Verify. A field that only stores an index has no ciphertext, so
808+
// Verify would never pass. The caller would discard every real match.
809809
//
810-
// Every index the engine admits on a field answers an operator there, so
811-
// no index is stored that a generated method cannot query. The engine
812-
// refuses the one that would be: an order index on bytes.
810+
// The engine only accepts an index on a field if one of the index's
811+
// operators accepts the field's type. A generated method can therefore
812+
// query every stored index. The engine refuses the one index that no
813+
// method could query: an order index on bytes.
813814
func verifiable(g *genField) error {
814815
if g.Verb != VerbIndex {
815816
return nil

‎languages/golang/stashgen/enginetest/enginetest.go‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -200,9 +200,9 @@ func (e Static) operators(ctx context.Context, d stashgen.Declaration) (map[stri
200200
// equality index, matches through a match index, and the orderings through
201201
// the one order index the field declares (ORE, block ORE or OPE; check
202202
// refused a field with two); each only where the index applies to the type
203-
// (indexApplies). There is no second list of the types the orderings are
204-
// answered over: an index that applies answers its operators, as in the
205-
// engine.
203+
// (indexApplies). As in the engine, there is no second list of the types
204+
// that the orderings accept. If an index applies to a type, each of the
205+
// index's operators accepts that type.
206206
func answeredBy(operator string, t stashgen.GoType, indexes []stashgen.IndexName) (stashgen.IndexName, bool) {
207207
declared := func(want stashgen.IndexName) bool {
208208
for _, idx := range indexes {
@@ -251,8 +251,8 @@ func eightBit(t stashgen.GoType) bool {
251251
// match over text alone, ORE and OPE over integers of 16 bits and wider,
252252
// floats, text, decimals, dates and timestamps. Not over a boolean or an
253253
// 8-bit integer, whose order term would reveal which rows are true, or
254-
// each row's rank among 256 values. Not over bytes, which no ordering
255-
// operator is answered over: the term would be stored and never queried.
254+
// each row's rank among 256 values. Not over bytes: no ordering operator
255+
// accepts bytes, so no query could use the stored term.
256256
// The JSON index is not in the engine yet.
257257
func indexApplies(name stashgen.IndexName, t stashgen.GoType) error {
258258
switch name {

‎packages/stack-encrypt/src/dynamic/kind.rs‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -62,13 +62,14 @@ use crate::target::IndexSpec;
6262
/// values. A composite (`array`, `object`) has no term. Only the index's
6363
/// kind matters: a match index's options do not change what it applies to.
6464
///
65-
/// Bytes are the one kind an index is refused though the scheme defines
66-
/// its term. [`IndexSpec::defines`] takes bytes for an order index, but no
67-
/// ordering operator is answered over bytes, so a plan that declared one
68-
/// would store a term anyone can compare and no query can use. A plan
69-
/// admits an index only over a kind one of the index's operators answers,
70-
/// as the typed path's `Index` bound on [`op::Ordered`](crate::op::Ordered)
71-
/// does.
65+
/// A plan refuses an order index on bytes, although the scheme defines an
66+
/// order term for bytes. [`IndexSpec::defines`] accepts bytes for an order
67+
/// index. No ordering operator accepts bytes, so no query could use the
68+
/// stored term. Anyone who reads the rows could still compare the terms.
69+
///
70+
/// A plan therefore accepts an index on a kind only if one of the
71+
/// index's operators accepts that kind. The typed interface has the same
72+
/// rule: an order index needs [`op::Ordered`](crate::op::Ordered).
7273
///
7374
/// ```
7475
/// use stack_encrypt::dynamic::{admits, ValueKind};

‎packages/stack-encrypt/src/op/mod.rs‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -572,14 +572,19 @@ impl<S: 'static> Input<Pair> for (S, S) {
572572
/// timestamps by the microsecond, so instants within one microsecond tie;
573573
/// and decimals by value, so `1.5` ties `1.50`.
574574
///
575-
/// It is also the bound on the order indexes ([`Ore`], [`Ope`],
576-
/// [`OreBlock`]), their terms as
577-
/// targets, and the low-level operations they are built from
578-
/// ([`target::ore`](crate::target::ore) and the others). So an index admits
579-
/// exactly the types its operators answer. Bytes have an order term
580-
/// ([`Orderable`]) but are not `Ordered`: an order index on bytes would
581-
/// store a term that reveals the order of the rows and answers no query,
582-
/// so it does not compile.
575+
/// `Ordered` is also the bound on these:
576+
///
577+
/// - the order indexes: [`Ore`], [`Ope`], and [`OreBlock`]
578+
/// - the terms of those indexes, when a term is a target
579+
/// - the low-level operations that the indexes use, such as
580+
/// [`target::ore`](crate::target::ore)
581+
///
582+
/// An order index therefore accepts exactly the types that the ordering
583+
/// operators accept.
584+
///
585+
/// Bytes have an order term ([`Orderable`]). Bytes are not `Ordered`, so
586+
/// an order index on bytes does not compile. The stored term would reveal
587+
/// the order of the rows. No query could use that term.
583588
///
584589
/// Sealed: a type joins only when the order its terms compare in is the
585590
/// one its operators promise, so a type whose terms could order otherwise

‎packages/stack-encrypt/src/sem/mod.rs‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1359,17 +1359,23 @@ where
13591359
/// its value by ownership (the visitor carries it), so pass a `String` or
13601360
/// a `Vec<u8>`.
13611361
///
1362-
/// This trait says only which types have an order term. An order index
1363-
/// ([`Ore`](crate::Ore), [`Ope`](crate::Ope), [`OreBlock`](crate::OreBlock))
1364-
/// asks for more: [`op::Ordered`](crate::op::Ordered), the types an
1365-
/// ordering operator is answered over. `Vec<u8>` is `Orderable` and not
1366-
/// `Ordered`. The keyset's [`ore_term`](KeysetCipher::ore_term),
1367-
/// [`ope_term`](KeysetCipher::ope_term) and
1368-
/// [`ore_block_term`](KeysetCipher::ore_block_term) derive a term of bytes,
1369-
/// but no plan, record or target can store one: it would reveal the order
1370-
/// of the rows and answer no query. A record that only opens can still
1371-
/// name `Encrypted<OreTerm<Vec<u8>>>`, so rows stored before this rule stay
1372-
/// readable.
1362+
/// `Orderable` only lists the types that have an order term. An order
1363+
/// index ([`Ore`](crate::Ore), [`Ope`](crate::Ope), or
1364+
/// [`OreBlock`](crate::OreBlock)) needs
1365+
/// [`op::Ordered`](crate::op::Ordered). `Ordered` lists the types that
1366+
/// the ordering operators accept.
1367+
///
1368+
/// `Vec<u8>` is `Orderable`, without being `Ordered`:
1369+
///
1370+
/// - The keyset methods [`ore_term`](KeysetCipher::ore_term),
1371+
/// [`ope_term`](KeysetCipher::ope_term), and
1372+
/// [`ore_block_term`](KeysetCipher::ore_block_term) derive an order
1373+
/// term of bytes.
1374+
/// - No plan, record, or target can store that term. A stored term would
1375+
/// reveal the order of the rows. No query could use that term.
1376+
/// - A record that only decrypts can still name
1377+
/// `Encrypted<OreTerm<Vec<u8>>>`. You can therefore still read rows
1378+
/// that were stored before this rule.
13731379
///
13741380
/// A `bool`, a `u8` and an `i8` have no target. An order term over a
13751381
/// domain that small tells anyone holding the column too much: with two

‎packages/stack-encrypt/src/target/index.rs‎

Lines changed: 24 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -188,13 +188,15 @@ impl fmt::Display for IndexSpec {
188188

189189
/// An operation that derives one search term of `S`.
190190
///
191-
/// Implemented for exactly the plaintexts the index answers a query over,
192-
/// which is what makes an inapplicable index a compile error: there is no
193-
/// `Index<u32>` for [`Match`](struct@Match), because match is defined over
194-
/// text. An order index ([`Ore`], [`Ope`], [`OreBlock`]) is implemented for
195-
/// the types an ordering operator is answered over
196-
/// ([`op::Ordered`](crate::op::Ordered)). Its scheme can also order bytes,
197-
/// but no ordering operator is answered over bytes, so there is no
191+
/// An index implements `Index<S>` only for the plaintext types `S` that
192+
/// its operators accept. An index on any other type does not compile. For
193+
/// example, there is no `Index<u32>` for [`Match`](struct@Match), because
194+
/// a match query needs text.
195+
///
196+
/// An order index ([`Ore`], [`Ope`], or [`OreBlock`]) implements
197+
/// `Index<S>` for the types that the ordering operators accept
198+
/// ([`op::Ordered`](crate::op::Ordered)). The order scheme can also order
199+
/// bytes. No ordering operator accepts bytes, so there is no
198200
/// `Index<Vec<u8>>` for [`Ore`].
199201
///
200202
/// An index does not seal anything. [`indexed`] puts a ciphertext beside the
@@ -206,7 +208,7 @@ impl fmt::Display for IndexSpec {
206208
#[diagnostic::on_unimplemented(
207209
message = "`{Self}` is not an index of `{S}`",
208210
label = "this index is not defined over `{S}`",
209-
note = "an index applies only to the plaintexts it answers a query over: `Match` takes text, `Equality` takes the types its scheme encodes, and `Ore`, `Ope` and `OreBlock` take the types `op::Ordered` lists"
211+
note = "`Match` accepts text; `Equality` accepts the types its scheme encodes; `Ore`, `Ope` and `OreBlock` accept the types that implement `op::Ordered`"
210212
)]
211213
pub trait Index<S> {
212214
/// The term this index derives.
@@ -231,14 +233,17 @@ pub trait Index<S> {
231233
pub struct Equality;
232234

233235
/// The order-revealing index: a CLLW ORE ciphertext of the value, under a
234-
/// key derived from the field's context. Defined for every `S` an ordering
235-
/// operator is answered over ([`op::Ordered`](crate::op::Ordered)): the
236-
/// integers of 16 bits and wider, the floats, text, dates, timestamps and
237-
/// decimals.
236+
/// key derived from the field's context.
237+
///
238+
/// `Ore` accepts every type `S` that the ordering operators accept
239+
/// ([`op::Ordered`](crate::op::Ordered)): the integers of 16 bits and
240+
/// wider, the floats, text, dates, timestamps, and decimals.
241+
///
242+
/// `Ore` does not accept bytes. The scheme can order a `Vec<u8>`, but no
243+
/// ordering operator accepts bytes.
238244
///
239-
/// Not for bytes. The scheme can order a `Vec<u8>`, but no ordering
240-
/// operator is answered over bytes, so a stored term would reveal the order
241-
/// of the rows and answer no query. An order index on bytes does not
245+
/// A stored term of bytes would reveal the order of the rows. No query
246+
/// could use that term. An order index on bytes therefore does not
242247
/// compile:
243248
///
244249
/// ```compile_fail
@@ -373,10 +378,10 @@ impl<S: AsRef<str>, O: MatchConfig + 'static> Index<S> for Match<O> {
373378
}
374379
}
375380

376-
// Each order index is declared over `Ordered`, the trait its operators
377-
// need, and not over `Orderable`, which also covers bytes. An index stores
378-
// a term that reveals the order of the rows, so it is declared only for a
379-
// type an ordering operator is answered over.
381+
// Each order index needs `Ordered`, the trait that the ordering operators
382+
// need. `Orderable` is wider: it also covers bytes. An index stores a term
383+
// that reveals the order of the rows, so an index only accepts a type
384+
// that an ordering operator accepts.
380385
impl<S> Index<S> for Ore
381386
where
382387
S: crate::op::Ordered,

‎packages/stack-encrypt/src/target/operations.rs‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1040,15 +1040,19 @@ term_operation!(
10401040
term_operation!(
10411041
/// The order-revealing term of `S` under the context the tree hands it.
10421042
///
1043-
/// `S` is a type an ordering operator is answered over
1044-
/// ([`op::Ordered`](crate::op::Ordered)), as for the [`Ore`](super::Ore)
1045-
/// index. An index or a target of another crate is built from this
1046-
/// operation, so it takes no type that the index refuses. Bytes have an
1047-
/// order term but no ordering operator, so a term stored for them would
1048-
/// reveal the order of the rows and answer no query. The keyset's
1049-
/// [`ore_term`](crate::KeysetCipher::ore_term) still derives one term of
1050-
/// bytes, for tests of the term itself; it is not a description, so no
1051-
/// plan or target can be built from it.
1043+
/// `S` must be a type that the ordering operators accept
1044+
/// ([`op::Ordered`](crate::op::Ordered)). The [`Ore`](super::Ore)
1045+
/// index has the same bound. Another crate can build an index or a
1046+
/// target from this operation, so the operation accepts no type that
1047+
/// the index refuses.
1048+
///
1049+
/// Bytes have an order term, but no ordering operator accepts bytes.
1050+
/// A stored term of bytes would reveal the order of the rows. No
1051+
/// query could use that term.
1052+
///
1053+
/// The keyset method [`ore_term`](crate::KeysetCipher::ore_term) still
1054+
/// derives an order term of bytes, for tests of the term. That method
1055+
/// does not return a description, so no plan or target can use it.
10521056
ore, crate::sem::OreTerm<S>, consume, [],
10531057
[S: crate::op::Ordered]
10541058
);

0 commit comments

Comments
 (0)