From 1bbe2bdffcd20aaa392d602e999259912d3933cb Mon Sep 17 00:00:00 2001 From: Sam Gwilym Date: Wed, 11 Sep 2024 13:01:39 +0100 Subject: [PATCH] non-building API sketch --- encoding/src/traits.rs | 68 +++++++++++++++++++++++++++++++++++------- 1 file changed, 58 insertions(+), 10 deletions(-) diff --git a/encoding/src/traits.rs b/encoding/src/traits.rs index 0919713..1134a66 100644 --- a/encoding/src/traits.rs +++ b/encoding/src/traits.rs @@ -3,12 +3,16 @@ use std::future::Future; use crate::error::DecodeError; use ufotofu::local_nb::{BulkConsumer, BulkProducer}; -/// A type that can be encoded to a bytestring, ensuring that any value of `Self` maps to exactly one bytestring. +/// A type which can be asynchronously encoded to bytes consumed by a [`ufotofu::local_nb::BulkConsumer`] /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait Encodable { - /// 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). + /// Encode the value with an [encoding function](https://macromania--channelclosing.deno.dev/specs/encodings/index.html#encoding_function) for the set of `Self`, ensuring that any value of `Self` maps to exactly one bytestring, such that there exists a _decoding_ function such that: /// + /// - for every value `s` in `Self` and every bytestring `b` that starts with `encode_s(s)`, we have `decode_s(b)=s`, and + /// - for every `s` in `Self` and every bytestring b that does not start with `encode_s(s)`, we have `decode_s(b) ≠ s`. + /// + /// The encoded bytestring will be consumed to the provided [`ufotofu::local_nb::BulkConsumer`]. /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encode_s) fn encode( &self, @@ -18,11 +22,16 @@ pub trait Encodable { Consumer: BulkConsumer; } -/// A type that can be decoded from a bytestring, ensuring that every valid encoding maps to exactly one member of `Self`. +/// A type which can be asynchronously decoded from bytes produced by a [`ufotofu::local_nb::BulkProducer`] /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait Decodable { - /// 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). + /// Decode a bytestring created with an [encoding function](https://macromania--channelclosing.deno.dev/specs/encodings/index.html#encoding_function) for the set of `Self`, ensuring that any value of `Self` maps to exactly one bytestring, such that there exists a _decoding_ function (provided by this trait!) such that: + /// + /// - for every value `s` in `Self` and every bytestring `b` that starts with `encode_s(s)`, we have `decode_s(b)=s`, and + /// - for every `s` in `Self` and every bytestring `b` that does not start with `encode_s(s)`, we have `decode_s(b) ≠ s`. + /// + /// Will return an error if the encoding correlates to the **encoding relation** and not the result of the aforementioned encoding function. /// /// [Definition](https://willowprotocol.org/specs/encodings/index.html#decode_s) fn decode( @@ -31,12 +40,31 @@ pub trait Decodable { where Producer: BulkProducer, Self: Sized; + + /// Decode a bytestring belonging to the **encoding relation** on the set of `Self` and the set of bytestrings, such that: + /// + /// - for every `s` in `Self`, there is at least one bytestring in relation with `s`, and + /// - no bytestring in the relation is a prefix of another bytestring in the relation. + /// + /// [Definition](https://willowprotocol.org/specs/encodings/index.html#decode_s) + fn decode_relation( + producer: &mut Producer, + ) -> impl Future>> + where + Producer: BulkProducer, + Self: Sized; } -/// 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`. +/// A type relative to a reference value of type `R` which can be asynchronously encoded to bytes consumed by a [`ufotofu::local_nb::BulkConsumer`] +/// +/// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) +/// +/// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait RelativeEncodable { - /// 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). + /// Encode a pair of `Self` and `R` with the [encoding function](https://macromania--channelclosing.deno.dev/specs/encodings/index.html#encoding_function) for the set of `Self` relative to a value of the set of `R`, ensuring that any pair of `Self` and `R` maps to exactly one bytestring, such that there exists a _decoding_ function such that: + /// + /// - for every pair of `s` in `Self` and `r` in `R`, and every bytestring `b` that starts with `encode_s(s, r)`, we have `decode_s(b, r)=s`, and + /// - for every pair of `s` in `Self` and `r` in `R`, and every bytestring `b` that does not start with `encode_s(s, r)`, we have `decode_s(b, r) ≠ s`. fn relative_encode( &self, reference: &R, @@ -46,10 +74,19 @@ pub trait RelativeEncodable { Consumer: BulkConsumer; } -/// 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`. +/// A type relative to a value of type `R` which can be asynchronously decoded from bytes produced by a [`ufotofu::local_nb::BulkProducer`] +/// +/// [Definition](https://willowprotocol.org/specs/encodings/index.html#encodings_what) pub trait RelativeDecodable { - /// 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). + /// + /// Decode a bytestring created with an [encoding function](https://macromania--channelclosing.deno.dev/specs/encodings/index.html#encoding_function) for the set of `Self` relative to a value of the set of `R`, ensuring that any pair of `Self` and `R` maps to exactly one bytestring, such that there exists a _decoding_ function (provided by this trait!) such that: + /// + /// - for every pair of `s` in `Self` and `r` in `R`, and every bytestring `b` that starts with `encode_s(s, r)`, we have `decode_s(b, r)=s`, and + /// - for every pair of `s` in `Self` and `r` in `R`, and every bytestring `b` that does not start with `encode_s(s, r)`, we have `decode_s(b, r) ≠ s`. + /// + /// Will return an error if the encoding correlates to the **encoding relation** and not the result of the aforementioned encoding function. + /// + /// [Definition](https://willowprotocol.org/specs/encodings/index.html#decode_s) fn relative_decode( reference: &R, producer: &mut Producer, @@ -57,4 +94,15 @@ pub trait RelativeDecodable { where Producer: BulkProducer, Self: Sized; + + /// Decode a bytestring belonging to the **encoding relation** on the set of `Self` relative to a value of the set of `R`, and the set of bytestrings, such that: + /// + /// - for every pair of `s` in `Self` and `r` in `R`, there is at least one bytestring in relation with the pair of `s` and `r`, and + /// - no bytestring in the relation is a prefix of another bytestring in the relation. + fn relative_decode_relation( + producer: &mut Producer, + ) -> impl Future>> + where + Producer: BulkProducer, + Self: Sized; }