Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
by hand). The proof envelope gains no variant; the `verify` feature now
builds `grovedb-private-document-store` (without storage) for the store's
root.
- An opt-in mode that settles storage owner changes:
`BatchApplyOptions::settle_owner_changes` together with
`StorageFlags::update_element_flags_settling_owner_changes` as the flags
callback. An update in place whose new storage flags name a different owner
than the stored flags is accounted as a deletion plus an insertion: every
byte of the old element, key included, counts as removed and is sectioned
to the old owner through its epoch map by `split_removal_bytes`, and every
byte of the new element, key included, counts as added and is charged to
the writer, who keeps the flags they wrote. Without the mode the new owner
took the whole element (and its refund) when the size changed, or paid for
an element that kept naming the old owner when it did not. Updates that
keep the owner, or that have no owner on either side, are unchanged. The
flags callback can now answer an `ElementFlagsUpdate` (`Unchanged`,
`Changed`, `SettleOwnerChange`, new in `grovedb_costs`) in place of a
`bool`; a batch refuses `SettleOwnerChange` unless the option is set, and
on a write that keeps the stored flags (an untrusted `RefreshReference`, or
a tree's root update), which brings no owner of its own, with
`Error::InvalidBatchOperation`. With the option, the average-case and
worst-case batch estimates charge every `InsertOrReplace`, `Replace`,
`Patch` and trusted `RefreshReference` of an element with flags, and the
write of a flagged tree the batch also writes under, at least the bytes its
node adds when inserted. For a backward-references element the worst case
counts the referrers it carries over at its declared capacity, each at the
largest entry registration admits, so a worst-case estimate is never below
a settled apply; the average case counts the typical referrer shape. With
the option off, every cost, estimate, stored element and hash is what it
was before. A batch with the option predicts a same-batch reference's
target as `GROVE_V4` does on every grove version.

### Changed
- **BREAKING**: `BatchApplyOptions` has a new public field,
`settle_owner_changes` (`false` by default), so a struct literal that names
every field without `..Default::default()` must add it.
- **BREAKING**: Merk's just-in-time value update callback (the
`update_tree_value_based_on_costs` argument of
`Merk::apply_with_costs_just_in_time_value_update`, `Merk::apply_unchecked`,
`Merk::apply_unchecked_with_old_value_observer`, `Walker::apply_to`, the
`TreeNode` put functions and the `Walker::put_value*` family) answers
`(ElementFlagsUpdate, Option<ValueDefinedCostType>)` in place of
`(bool, Option<ValueDefinedCostType>)`. GroveDB's own flags callback (in
`apply_batch_with_element_flags_update`,
`apply_partial_batch_with_element_flags_update` and
`estimated_case_operations_for_batch`) takes any answer that converts into
an `ElementFlagsUpdate`, so a callback answering a `bool` compiles as before,
except one that never returns `Ok`, which now has to name its result type
(for example `-> Result<bool, Error>`).
- **BREAKING**: `Query` adds the public `offset: Option<u16>` field for
branch-local committed-count-unit pagination. Exhaustive struct literals
must supply the field or use a default update. Offset-bearing queries use
Expand Down
47 changes: 47 additions & 0 deletions costs/src/storage_cost/transition.rs
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,39 @@ pub enum OperationStorageTransitionType {
OperationNone,
}

/// What a just-in-time flags update decided for an element that an update
/// rewrites in place
///
/// A flags-update callback that only rewrites flags answers `Changed` or
/// `Unchanged`, and a `bool` converts to those. `SettleOwnerChange` also
/// changes how the update is accounted, and a batch only accepts it when its
/// options ask for that.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ElementFlagsUpdate {
/// The new element's flags were left as they were
Unchanged,
/// The new element's flags were rewritten
Changed,
/// The update hands the element to a different owner. It is accounted
/// as the removal of the old element plus the insertion of the new one
/// (an [`OperationStorageTransitionType::OperationReplace`]): every byte
/// of the old element, key included, counts as removed and is sectioned
/// through the old element's flags as a deletion sections it, and every
/// byte of the new element, key included, counts as added. The new
/// element keeps the flags the callback leaves it with.
SettleOwnerChange,
}

impl From<bool> for ElementFlagsUpdate {
fn from(flags_changed: bool) -> Self {
if flags_changed {
ElementFlagsUpdate::Changed
} else {
ElementFlagsUpdate::Unchanged
}
}
}

impl StorageCost {
/// the type of transition that the costs represent
pub fn transition_type(&self) -> OperationStorageTransitionType {
Expand All @@ -79,3 +112,17 @@ impl StorageCost {
}
}
}

#[cfg(test)]
mod tests {
use super::ElementFlagsUpdate;

#[test]
fn a_bool_flags_update_converts_to_changed_or_unchanged() {
assert_eq!(ElementFlagsUpdate::from(true), ElementFlagsUpdate::Changed);
assert_eq!(
ElementFlagsUpdate::from(false),
ElementFlagsUpdate::Unchanged
);
}
}
1 change: 1 addition & 0 deletions docs/crates/auxiliary.md
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,7 @@ These work on raw `ElementFlags` and match the callback signatures GroveDB expec
- **Anything else, or no old flags**: leaves `new_flags` alone and returns `false`.

It always merges with `MergingOwnersStrategy::UseTheirs`. When `old_flags` is `Some`, both the old and the new bytes must decode to flags, or it returns `RemovingFlagsError`.
- `StorageFlags::update_element_flags_settling_owner_changes(cost, old_flags, new_flags) -> Result<ElementFlagsUpdate, StorageFlagsError>` answers `ElementFlagsUpdate::SettleOwnerChange` for an update in place (bigger, smaller or same size) whose old and new flags both name an owner and the owners differ, and leaves `new_flags` as written. Every other update gets what `update_element_flags` gives it, as `Changed` or `Unchanged`. A batch accepts the settling answer only with `BatchApplyOptions::settle_owner_changes` set, and then accounts the update as a deletion plus an insertion: the old element's key and value bytes are removed and sectioned to the old owner by `split_removal_bytes`, and the new element's key and value bytes are added.
- `StorageFlags::split_removal_bytes(flags: &mut ElementFlags, removed_key_bytes, removed_value_bytes)` decodes the flags and calls `split_storage_removed_bytes`. It returns `BasicStorageRemoval` for both parts if the element has no flags.

Other helpers include:
Expand Down
Loading
Loading