From cb5a7842c404054fa34ba46e80af4f8585aa0da2 Mon Sep 17 00:00:00 2001 From: Sam Gwilym Date: Fri, 9 Aug 2024 14:49:11 +0100 Subject: [PATCH 1/3] A few more doc fixes --- data-model/src/encoding/error.rs | 2 +- data-model/src/encoding/traits.rs | 8 ++++---- data-model/src/encoding/traits_sync.rs | 8 ++++---- data-model/src/entry.rs | 2 +- data-model/src/grouping/area.rs | 2 +- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/data-model/src/encoding/error.rs b/data-model/src/encoding/error.rs index cec12ce..0807138 100644 --- a/data-model/src/encoding/error.rs +++ b/data-model/src/encoding/error.rs @@ -10,7 +10,7 @@ pub enum DecodeError { Producer(ProducerError), /// The bytes produced by the producer cannot be decoded into anything meaningful. InvalidInput, - /// Tried to use a u64 as a usize when the current target's usize is not big enough. + /// Tried to use a u64 as a usize when the current compilation target’s usize is not big enough. U64DoesNotFitUsize, } diff --git a/data-model/src/encoding/traits.rs b/data-model/src/encoding/traits.rs index 7b47bbf..68edef8 100644 --- a/data-model/src/encoding/traits.rs +++ b/data-model/src/encoding/traits.rs @@ -7,7 +7,7 @@ use ufotofu::local_nb::{BulkConsumer, BulkProducer}; /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait Encodable { - /// A function from the set `Self` to the set of bytestrings. + /// A function which maps the set `Self` to the set of bytestrings in such a way that any value of `Self` must map to exactly *one* bytestring. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encode_s) fn encode( @@ -22,7 +22,7 @@ pub trait Encodable { /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait Decodable { - /// A function from the set of bytestrings to the set of `T`. + /// A function which maps the set of bytestrings to the set of `T` in such a way that any bytestring must map to exactly *one* value of `Self`. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#decode_s) fn decode( @@ -36,7 +36,7 @@ pub trait Decodable { /// A type that can be used to encode `T` to a bytestring *encoded relative to `R`*. /// This can be used to create more compact encodings from which `T` can be derived by anyone with `R`. pub trait RelativeEncodable { - /// A function from the set `Self` to the set of bytestrings *encoded relative to `reference`*. + /// A function which maps the set `(Self, R)` to the set of bytestrings in such a way that any value of `Self` must map to exactly *one* bytestring. fn relative_encode( &self, reference: &R, @@ -49,7 +49,7 @@ pub trait RelativeEncodable { /// A type that can be used to decode `T` from a bytestring *encoded relative to `Self`*. /// This can be used to decode a compact encoding frow which `T` can be derived by anyone with `R`. pub trait RelativeDecodable { - /// A function from the set of bytestrings *encoded relative to `Self`* to the set of `T` in relation to `Self`. + /// A function which maps the set of `(bytestring, R)` to the set of `T` in such a way that any bytestring and reference value must map to exactly *one* value of `Self`. fn relative_decode( reference: &R, producer: &mut Producer, diff --git a/data-model/src/encoding/traits_sync.rs b/data-model/src/encoding/traits_sync.rs index cfd15a1..f60aa35 100644 --- a/data-model/src/encoding/traits_sync.rs +++ b/data-model/src/encoding/traits_sync.rs @@ -5,7 +5,7 @@ use ufotofu::sync::{BulkConsumer, BulkProducer}; /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait Encodable { - /// A function from the set `Self` to the set of bytestrings. + /// A function which maps the set `Self` to the set of bytestrings in such a way that any value of `Self` must map to exactly *one* bytestring. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encode_s) fn encode(&self, consumer: &mut Consumer) -> Result<(), Consumer::Error> @@ -17,7 +17,7 @@ pub trait Encodable { /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait Decodable { - /// A function from the set of bytestrings to the set of `T`. + /// A function which maps the set of bytestrings to the set of `T` in such a way that any bytestring must map to exactly *one* value of `Self`. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#decode_s) fn decode(producer: &mut Producer) -> Result> @@ -29,7 +29,7 @@ pub trait Decodable { /// A type that can be used to encode `T` to a bytestring *encoded relative to `R`*. /// This can be used to create more compact encodings from which `T` can be derived by anyone with `R`. pub trait RelativeEncodable { - /// A function from the set `Self` to the set of bytestrings *encoded relative to `reference`*. + /// A function which maps the set `(Self, R)` to the set of bytestrings in such a way that any value of `Self` must map to exactly *one* bytestring. fn relative_encode( &self, reference: &R, @@ -42,7 +42,7 @@ pub trait RelativeEncodable { /// A type that can be used to decode `T` from a bytestring *encoded relative to `Self`*. /// This can be used to decode a compact encoding frow which `T` can be derived by anyone with `R`. pub trait RelativeDecodable { - /// A function from the set of bytestrings *encoded relative to `Self`* to the set of `T` in relation to `Self`. + /// A function which maps the set of `(bytestring, R)` to the set of `T` in such a way that any bytestring and reference value must map to exactly *one* value of `Self`. fn relative_decode( reference: &R, producer: &mut Producer, diff --git a/data-model/src/entry.rs b/data-model/src/entry.rs index 456b935..6320a5f 100644 --- a/data-model/src/entry.rs +++ b/data-model/src/entry.rs @@ -7,7 +7,7 @@ use crate::{ path::Path, }; -/// A Timestamp is a 64-bit unsigned integer, that is, a natural number between zero (inclusive) and 2^64 - 1 (exclusive). +/// A Timestamp is a 64-bit unsigned integer, that is, a natural number between zero (inclusive) and 2^64 (exclusive). /// Timestamps are to be interpreted as a time in microseconds since the Unix epoch. /// [Definition](https://willowprotocol.org/specs/data-model/index.html#Timestamp). pub type Timestamp = u64; diff --git a/data-model/src/grouping/area.rs b/data-model/src/grouping/area.rs index c300f9f..8761210 100644 --- a/data-model/src/grouping/area.rs +++ b/data-model/src/grouping/area.rs @@ -14,7 +14,7 @@ use super::range::Range; pub enum AreaSubspace { /// A value that signals that an [`Area`] includes Entries with arbitrary subspace_ids. Any, - /// A concrete [`SubspaceId`] + /// A concrete [`SubspaceId`]. Id(S), } From c8785b6b9c8d11215e067b44a889ec23f0263ce0 Mon Sep 17 00:00:00 2001 From: Sam Gwilym Date: Fri, 9 Aug 2024 14:59:11 +0100 Subject: [PATCH 2/3] Update README --- README.md | 45 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index dde9f40..bd71961 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,47 @@ # willow-rs -> Protocols for synchronisable data stores. The best parts? Fine-grained permissions, a keen approach to privacy, destructive edits, and a dainty bandwidth and memory footprint. +> Protocols for synchronisable data stores. The best parts? Fine-grained +> permissions, a keen approach to privacy, destructive edits, and a dainty +> bandwidth and memory footprint. -Eventually, this repo will house Rust implementations of +_Currently_, this repo provides Rust implementations of: -- The [Willow Data Model](https://willowprotocol.org/specs/data-model/index.html#data_model), a mutable eventually-consistent store with improved deletion, -- [Willow Sideloading protocol](https://willowprotocol.org/specs/sideloading/index.html#sideloading), eventually consistent data delivered by any means possible, -- [Meadowcap](https://willowprotocol.org/specs/meadowcap/index.html#meadowcap), a capability system configurable to different social contexts, -- and [Willow General Purpose Sync Protocol](https://willowprotocol.org/specs/sync/index.html#sync), private and efficient synchronisation of Willow stores, +- [Meadowcap](https://willowprotocol.org/specs/meadowcap/index.html#meadowcap), + a capability system adaptable to local needs, +- Everything in the + [Willow Data Model](https://willowprotocol.org/specs/data-model/index.html#data_model) + (parameters, paths, entries, groupings, encodings) _except_ for the + all-important + [store](https://willowprotocol.org/specs/data-model/index.html#store). -probably implemented in that order. +_Eventually_, this repo will house Rust implementations of: -We welcome contributions! If you're looking for contribution ideas, please see the repo's issues, milestones, and projects. +- The aforementioned all-important + [store](https://willowprotocol.org/specs/data-model/index.html#store), +- [Willow Sideloading protocol](https://willowprotocol.org/specs/sideloading/index.html#sideloading), + eventually consistent data delivered by any means possible, +- and + [Willow General Purpose Sync Protocol](https://willowprotocol.org/specs/sync/index.html#sync), + private and efficient synchronisation of Willow stores. + +We welcome contributions! If you're looking for contribution ideas, please see +the repo's issues, milestones, and projects. ## See also - [Willow website](https://willowprotocol.org) -- [willow-js](https://github.com/earthstar-project/willow-js) - TypeScript implementation of Willow Data Model, Sideloading, and General Purpose Sync protocol. -- [meadowcap-js](https://github.com/earthstar-project/meadowcap-js) - TypeScript implementation of Meadowcap +- [willow-js](https://github.com/earthstar-project/willow-js) - TypeScript + implementation of Willow Data Model, Sideloading, and General Purpose Sync + protocol. +- [meadowcap-js](https://github.com/earthstar-project/meadowcap-js) - TypeScript + implementation of Meadowcap --- -This project was funded through the [NGI0 Core](https://nlnet.nl/core) Fund, a fund established by [NLnet](https://nlnet.nl/) with financial support from the European Commission's [Next Generation Internet](https://ngi.eu/) programme, under the aegis of [DG Communications Networks, Content and Technology](https://commission.europa.eu/about-european-commission/departments-and-executive-agencies/communications-networks-content-and-technology_en) under grant agreement No [101092990](https://cordis.europa.eu/project/id/101092990). +This project was funded through the [NGI0 Core](https://nlnet.nl/core) Fund, a +fund established by [NLnet](https://nlnet.nl/) with financial support from the +European Commission's [Next Generation Internet](https://ngi.eu/) programme, +under the aegis of +[DG Communications Networks, Content and Technology](https://commission.europa.eu/about-european-commission/departments-and-executive-agencies/communications-networks-content-and-technology_en) +under grant agreement No +[101092990](https://cordis.europa.eu/project/id/101092990). From b089e6b53223cf5a56f503fafee61eebcde6511a Mon Sep 17 00:00:00 2001 From: Sam Gwilym Date: Sat, 10 Aug 2024 11:00:35 +0100 Subject: [PATCH 3/3] =?UTF-8?q?I=20tried=20so=20hard,=20I=20got=20so=20far?= =?UTF-8?q?,=20but=20in=20the=20end=20it=20doesn=E2=80=99t=20even=20matter?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- data-model/src/encoding/traits.rs | 8 ++++---- data-model/src/encoding/traits_sync.rs | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/data-model/src/encoding/traits.rs b/data-model/src/encoding/traits.rs index 68edef8..f45e7f5 100644 --- a/data-model/src/encoding/traits.rs +++ b/data-model/src/encoding/traits.rs @@ -7,7 +7,7 @@ use ufotofu::local_nb::{BulkConsumer, BulkProducer}; /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait Encodable { - /// A function which maps the set `Self` to the set of bytestrings in such a way that any value of `Self` must map to exactly *one* bytestring. + /// Encode a value to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what). /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encode_s) fn encode( @@ -22,7 +22,7 @@ pub trait Encodable { /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait Decodable { - /// A function which maps the set of bytestrings to the set of `T` in such a way that any bytestring must map to exactly *one* value of `Self`. + /// Decade a value to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what). /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#decode_s) fn decode( @@ -36,7 +36,7 @@ pub trait Decodable { /// A type that can be used to encode `T` to a bytestring *encoded relative to `R`*. /// This can be used to create more compact encodings from which `T` can be derived by anyone with `R`. pub trait RelativeEncodable { - /// A function which maps the set `(Self, R)` to the set of bytestrings in such a way that any value of `Self` must map to exactly *one* bytestring. + /// Encode a value (relative to a reference value) to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what). fn relative_encode( &self, reference: &R, @@ -49,7 +49,7 @@ pub trait RelativeEncodable { /// A type that can be used to decode `T` from a bytestring *encoded relative to `Self`*. /// This can be used to decode a compact encoding frow which `T` can be derived by anyone with `R`. pub trait RelativeDecodable { - /// A function which maps the set of `(bytestring, R)` to the set of `T` in such a way that any bytestring and reference value must map to exactly *one* value of `Self`. + /// Decode a value (relative to a reference value) to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what). fn relative_decode( reference: &R, producer: &mut Producer, diff --git a/data-model/src/encoding/traits_sync.rs b/data-model/src/encoding/traits_sync.rs index f60aa35..6b1ed5b 100644 --- a/data-model/src/encoding/traits_sync.rs +++ b/data-model/src/encoding/traits_sync.rs @@ -5,7 +5,7 @@ use ufotofu::sync::{BulkConsumer, BulkProducer}; /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait Encodable { - /// A function which maps the set `Self` to the set of bytestrings in such a way that any value of `Self` must map to exactly *one* bytestring. + /// Encode a value to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what). /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encode_s) fn encode(&self, consumer: &mut Consumer) -> Result<(), Consumer::Error> @@ -17,7 +17,7 @@ pub trait Encodable { /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait Decodable { - /// A function which maps the set of bytestrings to the set of `T` in such a way that any bytestring must map to exactly *one* value of `Self`. + /// Decode a value to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what). /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#decode_s) fn decode(producer: &mut Producer) -> Result> @@ -29,7 +29,7 @@ pub trait Decodable { /// A type that can be used to encode `T` to a bytestring *encoded relative to `R`*. /// This can be used to create more compact encodings from which `T` can be derived by anyone with `R`. pub trait RelativeEncodable { - /// A function which maps the set `(Self, R)` to the set of bytestrings in such a way that any value of `Self` must map to exactly *one* bytestring. + /// Encode a value (relative to a reference value) to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what). fn relative_encode( &self, reference: &R, @@ -42,7 +42,7 @@ pub trait RelativeEncodable { /// A type that can be used to decode `T` from a bytestring *encoded relative to `Self`*. /// This can be used to decode a compact encoding frow which `T` can be derived by anyone with `R`. pub trait RelativeDecodable { - /// A function which maps the set of `(bytestring, R)` to the set of `T` in such a way that any bytestring and reference value must map to exactly *one* value of `Self`. + /// Decode a value (relative to a reference value) to a bytestring in a specific way that is best described over at [willowprotocol.org](https://willowprotocol.org/specs/encodings/index.html#encodings_what). fn relative_decode( reference: &R, producer: &mut Producer,