`#[derive(MaxEncodedLen)]` (#8737)

* impl #[derive(MaxEncodedLen)] for structs

* impl #[derive(MaxEncodedLen)] for enums, unions

* break long comments onto multiple lines

* add doc for public item

* add examples to macro documentation

* move MaxEncodedLen macro docs, un-ignore doc-tests

substrate/frame/support/procedural/src/lib.rs

@@ -28,6 +28,7 @@ mod debug_no_bound;
 mod clone_no_bound;
 mod partial_eq_no_bound;
 mod default_no_bound;
+mod max_encoded_len;
 
 pub(crate) use storage::INHERENT_INSTANCE_NAME;
 use proc_macro::TokenStream;
@@ -432,3 +433,9 @@ pub fn crate_to_pallet_version(input: TokenStream) -> TokenStream {
 /// The number of module instances supported by the runtime, starting at index 1,
 /// and up to `NUMBER_OF_INSTANCE`.
 pub(crate) const NUMBER_OF_INSTANCE: u8 = 16;
+
+/// Derive `MaxEncodedLen`.
+#[proc_macro_derive(MaxEncodedLen)]
+pub fn derive_max_encoded_len(input: TokenStream) -> TokenStream {
+	max_encoded_len::derive_max_encoded_len(input)
+}

substrate/frame/support/procedural/src/max_encoded_len.rs

+// This file is part of Substrate.
+
+// Copyright (C) 2021 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use frame_support_procedural_tools::generate_crate_access_2018;
+use quote::{quote, quote_spanned};
+use syn::{
+	Data, DeriveInput, Fields, GenericParam, Generics, TraitBound, Type, TypeParamBound,
+	parse_quote, spanned::Spanned,
+};
+
+/// impl for `#[derive(MaxEncodedLen)]`
+pub fn derive_max_encoded_len(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+	let input: DeriveInput = match syn::parse(input) {
+		Ok(input) => input,
+		Err(e) => return e.to_compile_error().into(),
+	};
+
+	let mel_trait = match max_encoded_len_trait() {
+		Ok(mel_trait) => mel_trait,
+		Err(e) => return e.to_compile_error().into(),
+	};
+
+	let name = &input.ident;
+	let generics = add_trait_bounds(input.generics, mel_trait.clone());
+	let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
+
+	let data_expr = data_length_expr(&input.data);
+
+	quote::quote!(
+		const _: () = {
+			impl #impl_generics #mel_trait for #name #ty_generics #where_clause {
+				fn max_encoded_len() -> usize {
+					#data_expr
+				}
+			}
+		};
+	)
+	.into()
+}
+
+fn max_encoded_len_trait() -> syn::Result<TraitBound> {
+	let frame_support = generate_crate_access_2018("frame-support")?;
+	Ok(parse_quote!(#frame_support::traits::MaxEncodedLen))
+}
+
+// Add a bound `T: MaxEncodedLen` to every type parameter T.
+fn add_trait_bounds(mut generics: Generics, mel_trait: TraitBound) -> Generics {
+	for param in &mut generics.params {
+		if let GenericParam::Type(ref mut type_param) = *param {
+			type_param.bounds.push(TypeParamBound::Trait(mel_trait.clone()));
+		}
+	}
+	generics
+}
+
+/// generate an expression to sum up the max encoded length from several fields
+fn fields_length_expr(fields: &Fields) -> proc_macro2::TokenStream {
+	let type_iter: Box<dyn Iterator<Item = &Type>> = match fields {
+		Fields::Named(ref fields) => Box::new(fields.named.iter().map(|field| &field.ty)),
+		Fields::Unnamed(ref fields) => Box::new(fields.unnamed.iter().map(|field| &field.ty)),
+		Fields::Unit => Box::new(std::iter::empty()),
+	};
+	// expands to an expression like
+	//
+	//   0
+	//     .saturating_add(<type of first field>::max_encoded_len())
+	//     .saturating_add(<type of second field>::max_encoded_len())
+	//
+	// We match the span of each field to the span of the corresponding
+	// `max_encoded_len` call. This way, if one field's type doesn't implement
+	// `MaxEncodedLen`, the compiler's error message will underline which field
+	// caused the issue.
+	let expansion = type_iter.map(|ty| {
+		quote_spanned! {
+			ty.span() => .saturating_add(<#ty>::max_encoded_len())
+		}
+	});
+	quote! {
+		0_usize #( #expansion )*
+	}
+}
+
+// generate an expression to sum up the max encoded length of each field
+fn data_length_expr(data: &Data) -> proc_macro2::TokenStream {
+	match *data {
+		Data::Struct(ref data) => fields_length_expr(&data.fields),
+		Data::Enum(ref data) => {
+			// We need an expression expanded for each variant like
+			//
+			//   0
+			//     .max(<variant expression>)
+			//     .max(<variant expression>)
+			//     .saturating_add(1)
+			//
+			// The 1 derives from the discriminant; see
+			// https://github.com/paritytech/parity-scale-codec/
+			//   blob/f0341dabb01aa9ff0548558abb6dcc5c31c669a1/derive/src/encode.rs#L211-L216
+			//
+			// Each variant expression's sum is computed the way an equivalent struct's would be.
+
+			let expansion = data.variants.iter().map(|variant| {
+				let variant_expression = fields_length_expr(&variant.fields);
+				quote! {
+					.max(#variant_expression)
+				}
+			});
+
+			quote! {
+				0_usize #( #expansion )* .saturating_add(1)
+			}
+		}
+		Data::Union(ref data) => {
+			// https://github.com/paritytech/parity-scale-codec/
+			//   blob/f0341dabb01aa9ff0548558abb6dcc5c31c669a1/derive/src/encode.rs#L290-L293
+			syn::Error::new(data.union_token.span(), "Union types are not supported")
+				.to_compile_error()
+		}
+	}
+}

substrate/frame/support/src/traits.rs

@@ -82,4 +82,32 @@ mod voting;
 pub use voting::{CurrencyToVote, SaturatingCurrencyToVote, U128CurrencyToVote};
 
 mod max_encoded_len;
+// This looks like an overlapping import/export, but it isn't:
+// macros and traits live in distinct namespaces.
 pub use max_encoded_len::MaxEncodedLen;
+/// Derive [`MaxEncodedLen`][max_encoded_len::MaxEncodedLen].
+///
+/// # Examples
+///
+/// ```
+/// # use codec::Encode;
+/// # use frame_support::traits::MaxEncodedLen;
+/// #[derive(Encode, MaxEncodedLen)]
+/// struct TupleStruct(u8, u32);
+///
+/// assert_eq!(TupleStruct::max_encoded_len(), u8::max_encoded_len() + u32::max_encoded_len());
+/// ```
+///
+/// ```
+/// # use codec::Encode;
+/// # use frame_support::traits::MaxEncodedLen;
+/// #[derive(Encode, MaxEncodedLen)]
+/// enum GenericEnum<T> {
+/// 	A,
+/// 	B(T),
+/// }
+///
+/// assert_eq!(GenericEnum::<u8>::max_encoded_len(), u8::max_encoded_len() + u8::max_encoded_len());
+/// assert_eq!(GenericEnum::<u128>::max_encoded_len(), u8::max_encoded_len() + u128::max_encoded_len());
+/// ```
+pub use frame_support_procedural::MaxEncodedLen;

substrate/frame/support/test/tests/max_encoded_len.rs

+// This file is part of Substrate.
+
+// Copyright (C) 2020-2021 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Tests for MaxEncodedLen derive macro
+
+use frame_support::traits::MaxEncodedLen;
+use codec::{Compact, Encode};
+
+// These structs won't even compile if the macro isn't working right.
+
+#[derive(Encode, MaxEncodedLen)]
+struct Primitives {
+	bool: bool,
+	eight: u8,
+}
+
+#[test]
+fn primitives_max_length() {
+	assert_eq!(Primitives::max_encoded_len(), 2);
+}
+
+#[derive(Encode, MaxEncodedLen)]
+struct Composites {
+	fixed_size_array: [u8; 128],
+	tuple: (u128, u128),
+}
+
+#[test]
+fn composites_max_length() {
+	assert_eq!(Composites::max_encoded_len(), 128 + 16 + 16);
+}
+
+#[derive(Encode, MaxEncodedLen)]
+struct Generic<T> {
+	one: T,
+	two: T,
+}
+
+#[test]
+fn generic_max_length() {
+	assert_eq!(Generic::<u8>::max_encoded_len(), u8::max_encoded_len() * 2);
+	assert_eq!(Generic::<u32>::max_encoded_len(), u32::max_encoded_len() * 2);
+}
+
+#[derive(Encode, MaxEncodedLen)]
+struct TwoGenerics<T, U> {
+	t: T,
+	u: U,
+}
+
+#[test]
+fn two_generics_max_length() {
+	assert_eq!(
+		TwoGenerics::<u8, u16>::max_encoded_len(),
+		u8::max_encoded_len() + u16::max_encoded_len()
+	);
+	assert_eq!(
+		TwoGenerics::<Compact<u64>, [u16; 8]>::max_encoded_len(),
+		Compact::<u64>::max_encoded_len() + <[u16; 8]>::max_encoded_len()
+	);
+}
+
+#[derive(Encode, MaxEncodedLen)]
+struct UnitStruct;
+
+#[test]
+fn unit_struct_max_length() {
+	assert_eq!(UnitStruct::max_encoded_len(), 0);
+}
+
+#[derive(Encode, MaxEncodedLen)]
+struct TupleStruct(u8, u32);
+
+#[test]
+fn tuple_struct_max_length() {
+	assert_eq!(TupleStruct::max_encoded_len(), u8::max_encoded_len() + u32::max_encoded_len());
+}
+
+#[derive(Encode, MaxEncodedLen)]
+struct TupleGeneric<T>(T, T);
+
+#[test]
+fn tuple_generic_max_length() {
+	assert_eq!(TupleGeneric::<u8>::max_encoded_len(), u8::max_encoded_len() * 2);
+	assert_eq!(TupleGeneric::<u32>::max_encoded_len(), u32::max_encoded_len() * 2);
+}
+
+#[derive(Encode, MaxEncodedLen)]
+#[allow(unused)]
+enum UnitEnum {
+	A,
+	B,
+}
+
+#[test]
+fn unit_enum_max_length() {
+	assert_eq!(UnitEnum::max_encoded_len(), 1);
+}
+
+#[derive(Encode, MaxEncodedLen)]
+#[allow(unused)]
+enum TupleEnum {
+	A(u32),
+	B,
+}
+
+#[test]
+fn tuple_enum_max_length() {
+	assert_eq!(TupleEnum::max_encoded_len(), 1 + u32::max_encoded_len());
+}
+
+#[derive(Encode, MaxEncodedLen)]
+#[allow(unused)]
+enum StructEnum {
+	A { sixty_four: u64, one_twenty_eight: u128 },
+	B,
+}
+
+#[test]
+fn struct_enum_max_length() {
+	assert_eq!(StructEnum::max_encoded_len(), 1 + u64::max_encoded_len() + u128::max_encoded_len());
+}
+
+// ensure that enums take the max of variant length, not the sum
+#[derive(Encode, MaxEncodedLen)]
+#[allow(unused)]
+enum EnumMaxNotSum {
+	A(u32),
+	B(u32),
+}
+
+#[test]
+fn enum_max_not_sum_max_length() {
+	assert_eq!(EnumMaxNotSum::max_encoded_len(), 1 + u32::max_encoded_len());
+}

substrate/frame/support/test/tests/max_encoded_len_ui.rs

+// This file is part of Substrate.
+
+// Copyright (C) 2020-2021 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#[rustversion::attr(not(stable), ignore)]
+#[test]
+fn derive_no_bound_ui() {
+	// As trybuild is using `cargo check`, we don't need the real WASM binaries.
+	std::env::set_var("SKIP_WASM_BUILD", "1");
+
+	let t = trybuild::TestCases::new();
+	t.compile_fail("tests/max_encoded_len_ui/*.rs");
+}

substrate/frame/support/test/tests/max_encoded_len_ui/not_encode.rs

+use frame_support::traits::MaxEncodedLen;
+
+#[derive(MaxEncodedLen)]
+struct NotEncode;
+
+fn main() {}

substrate/frame/support/test/tests/max_encoded_len_ui/not_encode.stderr

+error[E0277]: the trait bound `NotEncode: WrapperTypeEncode` is not satisfied
+  --> $DIR/not_encode.rs:3:10
+   |
+3  | #[derive(MaxEncodedLen)]
+   |          ^^^^^^^^^^^^^ the trait `WrapperTypeEncode` is not implemented for `NotEncode`
+   |
+  ::: $WORKSPACE/frame/support/src/traits/max_encoded_len.rs
+   |
+   | pub trait MaxEncodedLen: Encode {
+   |                          ------ required by this bound in `MaxEncodedLen`
+   |
+   = note: required because of the requirements on the impl of `frame_support::dispatch::Encode` for `NotEncode`
+   = note: this error originates in a derive macro (in Nightly builds, run with -Z macro-backtrace for more info)

substrate/frame/support/test/tests/max_encoded_len_ui/not_mel.rs

+use codec::Encode;
+use frame_support::traits::MaxEncodedLen;
+
+#[derive(Encode)]
+struct NotMel;
+
+#[derive(Encode, MaxEncodedLen)]
+struct Generic<T> {
+	t: T,
+}
+
+fn main() {
+	let _ = Generic::<NotMel>::max_encoded_len();
+}

substrate/frame/support/test/tests/max_encoded_len_ui/not_mel.stderr

+error[E0599]: the function or associated item `max_encoded_len` exists for struct `Generic<NotMel>`, but its trait bounds were not satisfied
+  --> $DIR/not_mel.rs:13:29
+   |
+5  | struct NotMel;
+   | -------------- doesn't satisfy `NotMel: MaxEncodedLen`
+...
+8  | struct Generic<T> {
+   | -----------------
+   | |
+   | function or associated item `max_encoded_len` not found for this
+   | doesn't satisfy `Generic<NotMel>: MaxEncodedLen`
+...
+13 |     let _ = Generic::<NotMel>::max_encoded_len();
+   |                                ^^^^^^^^^^^^^^^ function or associated item cannot be called on `Generic<NotMel>` due to unsatisfied trait bounds
+   |
+   = note: the following trait bounds were not satisfied:
+           `NotMel: MaxEncodedLen`
+           which is required by `Generic<NotMel>: MaxEncodedLen`
+   = help: items from traits can only be used if the trait is implemented and in scope
+   = note: the following trait defines an item `max_encoded_len`, perhaps you need to implement it:
+           candidate #1: `MaxEncodedLen`

substrate/frame/support/test/tests/max_encoded_len_ui/union.rs

+use codec::Encode;
+use frame_support::traits::MaxEncodedLen;
+
+#[derive(Encode, MaxEncodedLen)]
+union Union {
+	a: u8,
+	b: u16,
+}
+
+fn main() {}

substrate/frame/support/test/tests/max_encoded_len_ui/union.stderr

+error: Union types are not supported
+ --> $DIR/union.rs:5:1
+  |
+5 | union Union {
+  | ^^^^^
+
+error: Union types are not supported.
+ --> $DIR/union.rs:5:1
+  |
+5 | union Union {
+  | ^^^^^

substrate/frame/support/test/tests/max_encoded_len_ui/unsupported_variant.rs

+use codec::Encode;
+use frame_support::traits::MaxEncodedLen;
+
+#[derive(Encode)]
+struct NotMel;
+
+#[derive(Encode, MaxEncodedLen)]
+enum UnsupportedVariant {
+	NotMel(NotMel),
+}
+
+fn main() {}

substrate/frame/support/test/tests/max_encoded_len_ui/unsupported_variant.stderr

+error[E0599]: no function or associated item named `max_encoded_len` found for struct `NotMel` in the current scope
+ --> $DIR/unsupported_variant.rs:9:9
+  |
+5 | struct NotMel;
+  | -------------- function or associated item `max_encoded_len` not found for this
+...
+9 |     NotMel(NotMel),
+  |            ^^^^^^ function or associated item not found in `NotMel`
+  |
+  = help: items from traits can only be used if the trait is implemented and in scope
+  = note: the following trait defines an item `max_encoded_len`, perhaps you need to implement it:
+          candidate #1: `MaxEncodedLen`