diff --git a/rust/wheels-macros/src/fixed_offset_layout.rs b/rust/wheels-macros/src/fixed_offset_layout.rs index 9df4e06..c65d1c8 100644 --- a/rust/wheels-macros/src/fixed_offset_layout.rs +++ b/rust/wheels-macros/src/fixed_offset_layout.rs @@ -13,7 +13,7 @@ use syn::{ const FIELD_ATTRIBUTES: &[&str] = &["capacity", "extendable", "flexible"]; const LAYOUT_NAME: &str = "fixed_offset_layout"; const UNSUPPORTED_FIELD_MESSAGE: &str = - "fixed_offset_layout fields must be bool, Pubkey, integer primitives, or fixed-size arrays"; + "fixed_offset_layout fields must be bool, Pubkey, integer primitives, fixed-size arrays, or a final Option containing a supported layout"; const INTEGER_FIELD_MESSAGE: &str = "field must be an integer primitive"; const MAX_LEN_WIDTH: usize = 8; @@ -200,11 +200,24 @@ pub(crate) fn expand_fixed_offset_layout( } } ComptimeOptionalLen::Option { value_size } => { - let value_size = usize_lit(*value_size); quote! { Ok(Self::MIN_DATA_LEN + self.#trailing_variable_field.as_ref().map(|_| 1 + #value_size).unwrap_or(0)) } } + ComptimeOptionalLen::NestedLayoutOption { ty } => quote! { + match &self.#trailing_variable_field { + Some(value) => { + let value_len = ::wheels::layout::Encodable::encoded_len(value)?; + if !(<#ty as ::wheels::layout::LayoutBounds>::MIN_DATA_LEN + ..=<#ty as ::wheels::layout::LayoutBounds>::MAX_DATA_LEN) + .contains(&value_len) { + return Err(::wheels::DataLayoutError::InvalidDataLength); + } + Ok(Self::MIN_DATA_LEN + 1 + value_len) + } + None => Ok(Self::MIN_DATA_LEN), + } + }, }; ( quote! { @@ -557,6 +570,10 @@ enum FixedFieldKind { value: FixedValueKind, optional: Option, }, + NestedLayoutOption { + ty: Type, + optional: Optional, + }, Vec { elem: FixedVecElementKind, capacity: Capacity, @@ -634,7 +651,10 @@ enum ComptimeOptionalLen { elem_size: proc_macro2::TokenStream, }, Option { - value_size: usize, + value_size: proc_macro2::TokenStream, + }, + NestedLayoutOption { + ty: proc_macro2::TokenStream, }, } @@ -651,9 +671,9 @@ impl ComptimeOptionalLen { let max_capacity = usize_lit(max_len_for_width(len_width_value)); quote!(#len_width + #max_capacity * #elem_size) } - ComptimeOptionalLen::Option { value_size } => { - let value_size = usize_lit(*value_size); - quote!(1usize + #value_size) + ComptimeOptionalLen::Option { value_size } => quote!(1usize + #value_size), + ComptimeOptionalLen::NestedLayoutOption { ty } => { + quote!(1usize + <#ty as ::wheels::layout::LayoutBounds>::MAX_DATA_LEN) } } } @@ -675,7 +695,7 @@ impl FixedFieldKind { value: Some(1 + value.size()), }), Some(Optional::Flexible) => Err(ComptimeOptionalLen::Option { - value_size: value.size(), + value_size: value_size_expr, }), None => Ok(SlotLen { expr: value_size_expr, @@ -683,6 +703,15 @@ impl FixedFieldKind { }), } } + Self::NestedLayoutOption { ty, optional } => match optional { + Optional::Fixed => Ok(SlotLen { + expr: quote!((1usize + <#ty as ::wheels::layout::FixedSizeLayout>::DATA_LEN)), + value: None, + }), + Optional::Flexible => { + Err(ComptimeOptionalLen::NestedLayoutOption { ty: quote!(#ty) }) + } + }, Self::Vec { elem, capacity } => { let elem_size_expr = elem.size_expr(); let len_width_lit = capacity.len_width_lit(); @@ -715,6 +744,16 @@ impl FixedFieldKind { None } } + Self::NestedLayoutOption { + ty, + optional: Optional::Fixed, + } => Some(quote!(#ty: ::wheels::layout::FixedSizeLayout)), + Self::NestedLayoutOption { + ty, + optional: Optional::Flexible, + } => Some( + quote!(#ty: ::wheels::layout::Encodable + ::wheels::layout::Decodable + ::wheels::layout::LayoutBounds), + ), Self::Vec { elem, .. } => { if elem.needs_pod_bound() { let ty = elem.ty(); @@ -802,6 +841,7 @@ impl FixedFieldKind { error: syn::Error::new(field_ident.span(), message), })) } + Self::NestedLayoutOption { .. } => Ok(None), Self::Vec { elem, capacity } => { let FixedVecElementKind::FixedValue(elem) = elem else { return Ok(None); @@ -907,6 +947,39 @@ impl FixedFieldKind { } } } + Self::NestedLayoutOption { + ty, + optional: Optional::Fixed, + } => quote! { + Self::__validate_option(bytes, #offset_expr, #field_name)?; + if bytes[#offset_expr] != 0 { + let start = #offset_expr + 1usize; + let end = start + <#ty as ::wheels::layout::FixedSizeLayout>::DATA_LEN; + let _ = <#ty as ::wheels::layout::Decodable>::decode(&bytes[start..end])?; + } + }, + Self::NestedLayoutOption { + ty, + optional: Optional::Flexible, + } => quote! { + if bytes.len() != #offset_expr { + if bytes.len() < #offset_expr + 1usize { + return Err(::wheels::DataLayoutError::TruncatedPayload); + } + if bytes[#offset_expr] != 1 { + return Err(::wheels::DataLayoutError::InvalidOptionTag); + } + let start = #offset_expr + 1usize; + let value_len = bytes.len() - start; + if value_len < <#ty as ::wheels::layout::LayoutBounds>::MIN_DATA_LEN { + return Err(::wheels::DataLayoutError::TruncatedPayload); + } + if value_len > <#ty as ::wheels::layout::LayoutBounds>::MAX_DATA_LEN { + return Err(::wheels::DataLayoutError::LengthExceedsCapacity); + } + let _ = <#ty as ::wheels::layout::Decodable>::decode(&bytes[start..])?; + } + }, Self::Vec { elem, capacity } => { let len_width_lit = capacity.len_width_lit(); let elem_size = elem.size_expr(); @@ -1038,6 +1111,48 @@ impl FixedFieldKind { }, } } + Self::NestedLayoutOption { ty, optional } => { + let value_size = quote!(<#ty as ::wheels::layout::FixedSizeLayout>::DATA_LEN); + let encode_some = quote! { + bytes[#offset] = 1; + let start = #offset + 1usize; + let end = start + #value_size; + let remaining = ::wheels::layout::Encodable::encode_to( + value, + &mut bytes[start..end], + )?; + if !remaining.is_empty() { + return Err(::wheels::DataLayoutError::InvalidDataLength); + } + }; + match optional { + Optional::Fixed => quote! { + #fields_encode_expr + + if let Some(value) = &self.#field_ident { + #encode_some + } else { + bytes[#offset] = 0; + bytes[#offset + 1usize..#offset + 1usize + #value_size].fill(0); + } + }, + Optional::Flexible => quote! { + #fields_encode_expr + + if let Some(value) = &self.#field_ident { + bytes[#offset] = 1; + let start = #offset + 1usize; + let remaining = ::wheels::layout::Encodable::encode_to( + value, + &mut bytes[start..], + )?; + if !remaining.is_empty() { + return Err(::wheels::DataLayoutError::InvalidDataLength); + } + } + }, + } + } Self::Vec { elem, capacity } => { let elem_size = elem.size_expr(); let len_width = capacity.len_width_lit(); @@ -1194,6 +1309,36 @@ impl FixedFieldKind { } } } + Self::NestedLayoutOption { ty, optional } => { + let return_ty = quote!( + core::option::Option<<#ty as ::wheels::layout::Decodable>::View<'a>> + ); + match optional { + Optional::Fixed => Ok(quote! { + pub fn #field_ident(&self) -> #return_ty { + (self.bytes[#offset] != 0).then(|| { + let start = #offset + 1usize; + let end = start + <#ty as ::wheels::layout::FixedSizeLayout>::DATA_LEN; + <#ty as ::wheels::layout::Decodable>::decode(&self.bytes[start..end]) + .expect("validated nested fixed-layout Option") + }) + } + }), + Optional::Flexible => Ok(quote! { + pub fn #field_ident(&self) -> #return_ty { + if self.bytes.len() == #offset { + return None; + } + Some( + <#ty as ::wheels::layout::Decodable>::decode( + &self.bytes[#offset + 1usize..], + ) + .expect("validated nested flexible Option"), + ) + } + }), + } + } Self::Vec { elem, capacity } => { let elem_ty = elem.ty(); let elem_size = elem.size_expr(); @@ -1397,6 +1542,34 @@ impl FixedFieldKind { }) } } + Self::NestedLayoutOption { ty, optional } => match optional { + Optional::Fixed => Ok(quote! { + pub fn #field_mut_ident( + &mut self, + ) -> core::result::Result< + ::wheels::layout::FixedLayoutOptionMut<'a, S, #ty>, + ::pinocchio::error::ProgramError, + > { + ::wheels::layout::FixedLayoutOptionMut::new( + self.storage, + #offset, + ) + } + }), + Optional::Flexible => Ok(quote! { + pub fn #field_mut_ident( + &mut self, + ) -> core::result::Result< + ::wheels::layout::FlexibleLayoutOptionMut<'a, S, #ty>, + ::pinocchio::error::ProgramError, + > { + ::wheels::layout::FlexibleLayoutOptionMut::new( + self.storage, + #offset, + ) + } + }), + }, Self::Vec { elem, capacity } => { let elem_ty = elem.ty(); let elem_size = elem.size_expr(); @@ -1523,10 +1696,20 @@ fn parse_field_layout(field: &syn::Field, is_last_field: bool) -> syn::Result Ok(FixedFieldKind::Value { + value, + optional: Some(optional), + }), + Err(_) if is_last_field => Ok(FixedFieldKind::NestedLayoutOption { + ty: inner.clone(), + optional, + }), + Err(_) => Err(syn::Error::new_spanned( + field, + "Option containing a user-defined layout must be the final field", + )), + }; } if attribute.is_some() { diff --git a/rust/wheels-macros/src/lib.rs b/rust/wheels-macros/src/lib.rs index f135fb9..b606741 100644 --- a/rust/wheels-macros/src/lib.rs +++ b/rust/wheels-macros/src/lib.rs @@ -142,6 +142,12 @@ mod variable_offset_layout; /// implements `FixedSizeLayout`. Fixed-capacity generated views return /// `FixedLayoutSlice<'_, T>`. Final extendable Vec getters return /// `ExtendableVec`. +/// - `Option` for a user-defined layout type is supported as the final +/// field. Without `#[flexible]`, `T` must implement `FixedSizeLayout` and +/// the field reserves a tag and fixed-size payload. With `#[flexible]`, +/// `T` may have a fixed or variable encoded size and must implement +/// `Encodable`, `Decodable`, and `LayoutBounds`; `None` omits the field and +/// `Some` uses the actual encoded payload length. /// /// APIs /// ==== @@ -167,6 +173,8 @@ mod variable_offset_layout; /// returning a mutable storage-backed view /// - mutable views expose `_mut()` helpers. Plain aligned POD fields /// return a mutable guard, encoded bool/Option fields return slot helpers, +/// user-defined nested-layout options return `FixedLayoutOptionMut` or +/// `FlexibleLayoutOptionMut`, /// fixed-capacity Vec fields return `FixedCapacityVec`, and trailing /// extendable Vec fields return `ExtendableVec`. /// @@ -307,6 +315,10 @@ pub fn fixed_offset_layout(attr: TokenStream, item: TokenStream) -> TokenStream /// return `FixedLayoutSlice<'_, T>`. With `variable`, `T` must implement /// `Encodable`, `PrefixDecodable`, and `LayoutBounds`, and generated views /// return `VariableLayoutSlice<'_, T>`. +/// - `Option` for a user-defined layout type is supported when `T` +/// implements `FixedSizeLayout`. It uses tagged encoding and may be +/// followed by other fields because their offsets are computed at decode +/// time. It is not supported with `option = implicit`. /// /// Field attributes: /// - `#[flexible = N]` diff --git a/rust/wheels-macros/src/variable_offset_layout.rs b/rust/wheels-macros/src/variable_offset_layout.rs index 3ecec95..1927277 100644 --- a/rust/wheels-macros/src/variable_offset_layout.rs +++ b/rust/wheels-macros/src/variable_offset_layout.rs @@ -18,7 +18,7 @@ use syn::{ const FIELD_ATTRIBUTES: &[&str] = &["capacity", "extendable", "flexible", "element_size"]; const LAYOUT_NAME: &str = "variable_offset_layout"; const UNSUPPORTED_FIELD_MESSAGE: &str = - "variable_offset_layout fields must be bool, Pubkey, integer primitives, or fixed-size arrays of integer primitives"; + "variable_offset_layout fields must be bool, Pubkey, integer primitives, fixed-size arrays of integer primitives, or tagged Option where T implements FixedSizeLayout"; const INTEGER_FIELD_MESSAGE: &str = "field must be an integer primitive or bool"; const MAX_LEN_WIDTH: usize = 8; @@ -421,6 +421,9 @@ enum FieldLayout { value: FixedValueKind, optional: OptionalKind, }, + FixedLayoutOption { + ty: Type, + }, Vec { elem: VecElementKind, flexible: Flexible, @@ -490,6 +493,7 @@ impl FieldLayout { fn is_fixed(&self) -> bool { match self { FieldLayout::Value { optional, .. } => *optional == OptionalKind::No, + FieldLayout::FixedLayoutOption { .. } => false, FieldLayout::Vec { .. } => false, } } @@ -509,6 +513,10 @@ impl FieldLayout { } } } + Self::FixedLayoutOption { ty } => { + let value_size = quote!(<#ty as ::wheels::layout::FixedSizeLayout>::DATA_LEN); + Err(((quote!(1), Some(1)), (quote!(1 + #value_size), None))) + } Self::Vec { elem, flexible } => { let elem_size_expr = elem.size_expr(); let len_width_lit = usize_lit(flexible.len_width); @@ -541,6 +549,15 @@ impl FieldLayout { }, } } + Self::FixedLayoutOption { ty } => { + quote! { + len += if self.#field_ident.is_some() { + 1 + <#ty as ::wheels::layout::FixedSizeLayout>::DATA_LEN + } else { + 1 + }; + } + } Self::Vec { elem, flexible } => { let len_width = usize_lit(flexible.len_width); let capacity = usize_lit(flexible.capacity()); @@ -692,6 +709,48 @@ impl FieldLayout { } } } + Self::FixedLayoutOption { ty } => quote! { + if offset >= bytes.len() { + ::pinocchio_log::log!( + "Missing Option tag for field {} at offset {}", + #field_name, + offset, + ); + return Err(::wheels::DataLayoutError::MissingOptionTag); + } + + match bytes[offset] { + 0 => { + offset += 1; + } + 1 => { + let data_offset = offset + 1; + let end = data_offset + + <#ty as ::wheels::layout::FixedSizeLayout>::DATA_LEN; + if end > bytes.len() { + ::pinocchio_log::log!( + "Truncated payload for field {}: need {} bytes, have {}", + #field_name, + end, + bytes.len(), + ); + return Err(::wheels::DataLayoutError::TruncatedPayload); + } + let _ = <#ty as ::wheels::layout::Decodable>::decode( + &bytes[data_offset..end], + )?; + offset = end; + } + tag => { + ::pinocchio_log::log!( + "Invalid Option tag for field {}: tag = {}", + #field_name, + tag, + ); + return Err(::wheels::DataLayoutError::InvalidOptionTag); + } + } + }, Self::Vec { elem, flexible } => { let len_width_lit = usize_lit(flexible.len_width); let len_expr = checked_read_len_expr( @@ -857,6 +916,24 @@ impl FieldLayout { }, } } + Self::FixedLayoutOption { ty } => quote! { + if let core::option::Option::Some(value) = &self.#field_ident { + bytes[offset] = 1; + let start = offset + 1; + let end = start + <#ty as ::wheels::layout::FixedSizeLayout>::DATA_LEN; + let remaining = ::wheels::layout::Encodable::encode_to( + value, + &mut bytes[start..end], + )?; + if !remaining.is_empty() { + return Err(::wheels::DataLayoutError::InvalidDataLength); + } + offset = end; + } else { + bytes[offset] = 0; + offset += 1; + } + }, Self::Vec { elem, flexible } => { let len_width = usize_lit(flexible.len_width); match elem { @@ -934,6 +1011,7 @@ impl FieldLayout { None } } + Self::FixedLayoutOption { ty } => Some(quote!(#ty: ::wheels::layout::FixedSizeLayout)), Self::Vec { elem, .. } => { let ty = elem.ty(); match elem { @@ -1239,6 +1317,29 @@ impl FieldLayout { } } } + Self::FixedLayoutOption { ty } => { + let offset_expr = find_data_offset(struct_name, field_offsets); + Ok(quote! { + pub fn #field_ident( + &self, + ) -> core::option::Option< + <#ty as ::wheels::layout::Decodable>::View<'a>, + > { + let offset = #offset_expr; + if self.bytes[offset] == 0 { + return None; + } + let start = offset + 1; + let end = start + <#ty as ::wheels::layout::FixedSizeLayout>::DATA_LEN; + Some( + <#ty as ::wheels::layout::Decodable>::decode( + &self.bytes[start..end], + ) + .expect("validated nested fixed-layout Option"), + ) + } + }) + } Self::Vec { elem, flexible } => { let elem_ty = elem.ty(); let elem_size = elem.size_expr(); @@ -1381,17 +1482,26 @@ fn parse_field_layout( )); } - return Ok(FieldLayout::Value { - value: parse_value_kind(inner, UNSUPPORTED_FIELD_MESSAGE)?, - optional: match option_encoding { - StructOptionEncoding::Tagged => OptionalKind::Tagged, - StructOptionEncoding::Implicit => { - let index = *implicit_option_index; - *implicit_option_index += 1; - OptionalKind::Implicit(index) - } - }, - }); + return match parse_value_kind(inner, UNSUPPORTED_FIELD_MESSAGE) { + Ok(value) => Ok(FieldLayout::Value { + value, + optional: match option_encoding { + StructOptionEncoding::Tagged => OptionalKind::Tagged, + StructOptionEncoding::Implicit => { + let index = *implicit_option_index; + *implicit_option_index += 1; + OptionalKind::Implicit(index) + } + }, + }), + Err(_) if option_encoding == StructOptionEncoding::Tagged => { + Ok(FieldLayout::FixedLayoutOption { ty: inner.clone() }) + } + Err(_) => Err(syn::Error::new_spanned( + field, + "Option with a user-defined fixed-size layout requires tagged Option encoding", + )), + }; } if !attribute.is_empty() { @@ -1700,6 +1810,7 @@ fn exact_data_lens(layouts: &[FieldLayout]) -> Option> { OptionalKind::Tagged => BTreeSet::from([1, 1 + value.size()]), OptionalKind::Implicit(_) => BTreeSet::from([0, value.size()]), }, + FieldLayout::FixedLayoutOption { .. } => return None, FieldLayout::Vec { .. } => return None, }; @@ -2032,6 +2143,7 @@ fn borrowed_requirement(layout: &FieldLayout) -> Option { optional_kind: *optional, }), }, + FieldLayout::FixedLayoutOption { .. } => None, FieldLayout::Vec { elem, flexible } => elem .borrowed_slice_alignment() .filter(|align| *align > 1) @@ -2087,6 +2199,7 @@ fn possible_len_residues(layout: &FieldLayout, modulus: usize) -> BTreeSet BTreeSet::from([1 % modulus, (1 + value.size()) % modulus]), OptionalKind::Implicit(_) => BTreeSet::from([0, value.size() % modulus]), }, + FieldLayout::FixedLayoutOption { .. } => (0..modulus).collect(), FieldLayout::Vec { elem, flexible } => { let Some(elem_size) = elem.known_size() else { return (0..modulus).collect(); @@ -2285,6 +2398,15 @@ fn advance_offset_expr( } } } + FieldLayout::FixedLayoutOption { ty } => quote! {{ + let offset = #expr; + offset + + if self.bytes[offset] == 0 { + 1 + } else { + 1 + <#ty as ::wheels::layout::FixedSizeLayout>::DATA_LEN + } + }}, FieldLayout::Vec { elem, flexible } => { let len_width = usize_lit(flexible.len_width); let len_expr = validated_len_expr( diff --git a/rust/wheels/src/layout/mod.rs b/rust/wheels/src/layout/mod.rs index 476dfe8..f6ada25 100644 --- a/rust/wheels/src/layout/mod.rs +++ b/rust/wheels/src/layout/mod.rs @@ -60,6 +60,7 @@ //! - `[T; N]`, where `T` is one of those integer primitives //! - [`Pubkey`](crate::Pubkey)/`Address` //! - `Option` for supported fixed-value types +//! - tagged `Option` containing a user-defined layout //! - `Vec` for supported fixed-value element types except `bool` //! //! The following shapes are intentionally not supported: @@ -71,11 +72,16 @@ //! [`fixed_offset_layout!`](crate::fixed_offset_layout) also supports `Vec` //! where `T` is a user-defined fixed-size layout type. The generated getter //! returns [`FixedLayoutSlice`] for fixed-capacity fields or [`ExtendableVec`] -//! for a final extendable Vec field. +//! for a final extendable Vec field. A user-defined `Option` must be the +//! final field. A normal option requires `T: FixedSizeLayout`; with +//! `#[flexible]`, `T` may have a fixed or variable encoded size and all bytes +//! are omitted when absent. //! //! [`variable_offset_layout!`](crate::variable_offset_layout) supports `Vec` //! where `T` is a user-defined layout type. Those fields must choose //! `#[element_size = fixed]` or `#[element_size = variable]` explicitly. +//! User-defined `Option` fields use tagged encoding and require +//! `T: FixedSizeLayout`; they are not supported with `option = implicit`. //! //! # Choosing a Layout Macro //! @@ -97,6 +103,7 @@ //! | `Vec` of supported scalar/key types | Uses `#[capacity = N]` to reserve space for `N` elements. Views expose active `len` and a `_capacity()` method. | Uses `#[flexible = N]` to encode only active elements. Views return borrowed slices like `&[T]`. | //! | Extendable `Vec` | Allowed only as the final field with `#[extendable = N]`, where `N` can be `1..=8`. Canonical `encode()` writes only active bytes. `decode()` may receive larger storage and exposes spare trailing bytes as [`ExtendableVec::capacity`]. | Not supported. Every Vec uses `#[flexible = N]` and models only active encoded elements. | //! | `Vec` of user-defined layout types | Requires `T: FixedSizeLayout`; uses `#[capacity = N]` or final `#[extendable = N]`. Fixed-capacity getters return [`FixedLayoutSlice`]; final extendable getters return [`ExtendableVec`]. | Requires `#[element_size = fixed]` or `#[element_size = variable]`. Fixed elements return [`FixedLayoutSlice`]; variable elements return [`VariableLayoutSlice`]. | +//! | `Option` of a user-defined layout | Must be the final field. A normal option requires `T: FixedSizeLayout` and reserves a tag plus `T::DATA_LEN` bytes. With `#[flexible]`, `T: Encodable + Decodable + LayoutBounds` may have variable size; `None` omits all bytes and `Some` uses the encoded payload length. | Requires `T: FixedSizeLayout`; uses tagged encoding and dynamically advances later field offsets. It is not supported with `option = implicit`. | //! | Mutation | `decode_mut(storage)` is generated for every fixed layout. Fixed-capacity Vec fields return [`FixedCapacityVec`] and can grow active `len` up to schema capacity without resizing storage. Final extendable Vec fields return [`ExtendableVec`] and may resize storage. | Not currently generated. | //! | Prefix decoding | Constant-size layouts implement [`PrefixDecodable`]. Trailing variable-length layouts implement [`Decodable`]; final extendable Vec decodes the supplied storage region, while final flexible Option remains exactly framed. | Normal layouts implement [`PrefixDecodable`]. Layouts using `option = implicit` need exact framing and implement [`Decodable`]. | //! | Alignment | Use `buffer_offset = 0..=7` when the input starts at a known offset from an 8-byte aligned base. Use `buffer_offset = unknown` only when generated views do not borrow alignment-sensitive fields. | Use `buffer_offset = 0..=7` when the input starts at a known offset from an 8-byte aligned base; use `buffer_offset = unknown` only when generated views do not borrow alignment-sensitive fields. | @@ -140,6 +147,7 @@ //! | `bool` | [`LayoutBoolMut`] | Exposes `get()` and `set(bool)` because the encoded form is a backing `u8`.

`view.enabled_mut()?.set(true)?;` | //! | Fixed `Option` | [`LayoutOptionMut`] or [`LayoutBoolOptionMut`] | Updates the tag and payload in place; the reserved option slot size does not change.

`view.authority_mut()?.set(Some(key))?;` | //! | Trailing flexible `Option` | [`LayoutOptionMut`] or [`LayoutBoolOptionMut`] | `None` resizes storage back to the field offset; `Some` resizes to tag plus payload length.

`view.delegate_mut()?.set(None)?;` | +//! | Final `Option` with a nested layout | [`FixedLayoutOptionMut`] or [`FlexibleLayoutOptionMut`] | Encodes a replacement nested value directly into storage. A normal option requires `T: FixedSizeLayout` and retains its reserved payload bytes; `#[flexible]` accepts any bounded nested layout and resizes storage to its encoded length.

`view.config_mut()?.set(Some(&config))?;` | //! | `#[capacity = N] Vec` | [`FixedCapacityVec`] | Can `push`, `pop`, `set`, `truncate`, and `clear` active elements up to schema capacity `N`; it never resizes storage.

`view.items_mut()?.push(item)?;` | //! | Final `#[extendable = N] Vec` | [`ExtendableVec`] | Can `push`, `extend_from_slice`, `pop`, `set`, `truncate`, and `clear`; it may resize storage to grow capacity because the field is trailing.

`view.tail_mut()?.push(item)?;` | //! @@ -217,7 +225,8 @@ pub use fixed_capacity_vec::FixedCapacityVec; pub use fixed_slice::{FixedLayoutSlice, FixedLayoutSliceIter}; pub use storage::{LayoutStorage, LayoutStorageMut, MaxLenStorage}; pub use value_mut::{ - LayoutBoolMut, LayoutBoolOptionMut, LayoutCopyMut, LayoutOptionMut, LayoutValueMut, + FixedLayoutOptionMut, FlexibleLayoutOptionMut, LayoutBoolMut, LayoutBoolOptionMut, + LayoutCopyMut, LayoutOptionMut, LayoutValueMut, }; pub use variable_slice::{VariableLayoutSlice, VariableLayoutSliceIter}; diff --git a/rust/wheels/src/layout/value_mut.rs b/rust/wheels/src/layout/value_mut.rs index 2900c39..d5770ec 100644 --- a/rust/wheels/src/layout/value_mut.rs +++ b/rust/wheels/src/layout/value_mut.rs @@ -6,7 +6,7 @@ use core::{ use bytemuck::Pod; use pinocchio::error::ProgramError; -use super::LayoutStorageMut; +use super::{Encodable, FixedSizeLayout, LayoutBounds, LayoutStorageMut}; use crate::DataLayoutError; // CHECKPOINT(CU): generated fixed-layout getters pass compile-time constant @@ -274,6 +274,123 @@ where } } +/// Mutable slot for an `Option` whose payload is a fixed-size layout. +/// +/// Nested layouts are encoded field-by-field, so this helper replaces the +/// complete nested value instead of treating its Rust representation as bytes. +pub struct FixedLayoutOptionMut<'a, S, T> +where + S: LayoutStorageMut + ?Sized, + T: FixedSizeLayout, +{ + storage: &'a S, + offset: usize, + _marker: PhantomData, +} + +impl<'a, S, T> FixedLayoutOptionMut<'a, S, T> +where + S: LayoutStorageMut + ?Sized, + T: FixedSizeLayout, +{ + #[doc(hidden)] + pub fn new(storage: &'a S, offset: usize) -> Result { + let bytes = storage.borrow_data()?; + ensure_range(&bytes, offset, 1 + T::DATA_LEN)?; + drop(bytes); + + Ok(Self { + storage, + offset, + _marker: PhantomData, + }) + } + + pub fn set(&mut self, value: Option<&T>) -> Result<(), ProgramError> { + match value { + Some(value) => self.set_some(value), + None => self.set_none(), + } + } + + fn set_some(&mut self, value: &T) -> Result<(), ProgramError> { + let start = self.offset + 1; + let end = checked_end(start, T::DATA_LEN)?; + let mut bytes = self.storage.borrow_data_mut()?; + ensure_range(&bytes, self.offset, 1 + T::DATA_LEN)?; + let remaining = value + .encode_to(&mut bytes[start..end]) + .map_err(ProgramError::from)?; + if !remaining.is_empty() { + return Err(DataLayoutError::InvalidDataLength.into()); + } + bytes[self.offset] = 1; + Ok(()) + } + + fn set_none(&mut self) -> Result<(), ProgramError> { + let mut bytes = self.storage.borrow_data_mut()?; + ensure_range(&bytes, self.offset, 1)?; + bytes[self.offset] = 0; + Ok(()) + } +} + +/// Mutable slot for a final flexible `Option` containing a nested layout. +pub struct FlexibleLayoutOptionMut<'a, S, T> +where + S: LayoutStorageMut + ?Sized, + T: Encodable + LayoutBounds, +{ + storage: &'a S, + offset: usize, + _marker: PhantomData, +} + +impl<'a, S, T> FlexibleLayoutOptionMut<'a, S, T> +where + S: LayoutStorageMut + ?Sized, + T: Encodable + LayoutBounds, +{ + #[doc(hidden)] + pub fn new(storage: &'a S, offset: usize) -> Result { + if storage.data_len() < offset { + return Err(DataLayoutError::InvalidDataLength.into()); + } + Ok(Self { + storage, + offset, + _marker: PhantomData, + }) + } + + pub fn set(&mut self, value: Option<&T>) -> Result<(), ProgramError> { + let Some(value) = value else { + return self.storage.resize(self.offset); + }; + + let value_len = value.encoded_len().map_err(ProgramError::from)?; + if !(T::MIN_DATA_LEN..=T::MAX_DATA_LEN).contains(&value_len) { + return Err(DataLayoutError::InvalidDataLength.into()); + } + + let start = checked_end(self.offset, 1)?; + let end = checked_end(start, value_len)?; + self.storage.resize(end)?; + + let mut bytes = self.storage.borrow_data_mut()?; + ensure_range(&bytes, self.offset, 1 + value_len)?; + let remaining = value + .encode_to(&mut bytes[start..end]) + .map_err(ProgramError::from)?; + if !remaining.is_empty() { + return Err(DataLayoutError::InvalidDataLength.into()); + } + bytes[self.offset] = 1; + Ok(()) + } +} + /// Mutable slot for a layout-encoded `Option`. pub struct LayoutBoolOptionMut<'a, S> where diff --git a/rust/wheels/tests/fixed_offset_layout.rs b/rust/wheels/tests/fixed_offset_layout.rs index 32a3172..0174df7 100644 --- a/rust/wheels/tests/fixed_offset_layout.rs +++ b/rust/wheels/tests/fixed_offset_layout.rs @@ -566,6 +566,208 @@ struct FixedTrailingOptionArgs { delegate: Option, } +#[derive(Clone, Debug, PartialEq, Eq)] +#[fixed_offset_layout(buffer_offset = unknown)] +struct NestedFixedConfig { + authority: Pubkey, + threshold: u16, + enabled: bool, +} + +#[fixed_offset_layout(buffer_offset = 0)] +struct FixedNestedOptionArgs { + header: u8, + config: Option, +} + +#[fixed_offset_layout(buffer_offset = 0)] +struct FlexibleNestedOptionArgs { + header: u8, + #[flexible] + config: Option, +} + +#[fixed_offset_layout(buffer_offset = unknown)] +struct NestedVariableConfig { + version: u8, + #[extendable = 1] + payload: Vec, +} + +#[fixed_offset_layout(buffer_offset = 0)] +struct FlexibleVariableNestedOptionArgs { + header: u8, + #[flexible] + config: Option, +} + +#[test] +fn fixed_offset_layout_supports_flexible_variable_nested_option() { + assert_eq!(FlexibleVariableNestedOptionArgs::MIN_DATA_LEN, 1); + assert_eq!(FlexibleVariableNestedOptionArgs::MAX_DATA_LEN, 259); + + let storage = TestStorage::new( + FlexibleVariableNestedOptionArgs { + header: 7, + config: None, + } + .encode() + .unwrap(), + ); + let config = NestedVariableConfig { + version: 3, + payload: vec![9, 8, 7], + }; + + assert_eq!( + FlexibleVariableNestedOptionArgs { + header: 7, + config: Some(NestedVariableConfig { + version: 3, + payload: vec![9, 8, 7], + }), + } + .encode() + .unwrap(), + vec![7, 1, 3, 3, 9, 8, 7], + ); + + { + let mut view = FlexibleVariableNestedOptionArgs::decode_mut(&storage).unwrap(); + view.config_mut().unwrap().set(Some(&config)).unwrap(); + } + { + let bytes = storage.bytes(); + let aligned = aligned_copy::<16>(&bytes); + let view = FlexibleVariableNestedOptionArgs::decode(&aligned.0[..bytes.len()]).unwrap(); + let config_view = view.config().unwrap(); + + assert_eq!(config_view.version(), 3); + assert_eq!(config_view.payload().as_slice(), &[9, 8, 7]); + } + + let shorter = NestedVariableConfig { + version: 4, + payload: vec![5], + }; + { + let mut view = FlexibleVariableNestedOptionArgs::decode_mut(&storage).unwrap(); + view.config_mut().unwrap().set(Some(&shorter)).unwrap(); + } + assert_eq!(storage.bytes(), vec![7, 1, 4, 1, 5]); + + { + let mut view = FlexibleVariableNestedOptionArgs::decode_mut(&storage).unwrap(); + view.config_mut().unwrap().set(None).unwrap(); + } + assert_eq!(storage.bytes(), vec![7]); + assert_eq!(storage.resize_lens(), vec![7, 5, 1]); +} + +#[test] +fn fixed_offset_layout_rejects_invalid_flexible_nested_option() { + for (bytes, expected_error) in [ + (vec![7, 0, 3, 1, 9], DataLayoutError::InvalidOptionTag), + (vec![7, 1, 3, 3, 9], DataLayoutError::LengthExceedsCapacity), + (vec![7; 260], DataLayoutError::InvalidDataLength), + ] { + let aligned = aligned_copy::<264>(&bytes); + assert_eq!( + FlexibleVariableNestedOptionArgs::decode(&aligned.0[..bytes.len()]).unwrap_err(), + expected_error, + ); + } +} + +#[test] +fn fixed_offset_layout_supports_fixed_nested_option() { + assert_eq!(NestedFixedConfig::DATA_LEN, 35); + assert_eq!(FixedNestedOptionArgs::DATA_LEN, 37); + + let none = FixedNestedOptionArgs { + header: 7, + config: None, + } + .encode() + .unwrap(); + assert_eq!(none.len(), FixedNestedOptionArgs::DATA_LEN); + assert_eq!(&none[..2], &[7, 0]); + assert!(none[2..].iter().all(|byte| *byte == 0)); + + let config = NestedFixedConfig { + authority: Pubkey::from([4; 32]), + threshold: 9, + enabled: true, + }; + let some = FixedNestedOptionArgs { + header: 7, + config: Some(config.clone()), + } + .encode() + .unwrap(); + let aligned = aligned_copy::<64>(&some); + let view = FixedNestedOptionArgs::decode(&aligned.0[..some.len()]).unwrap(); + let config_view = view.config().unwrap(); + + assert_eq!(view.header(), 7); + assert_eq!(config_view.authority(), &config.authority); + assert_eq!(config_view.threshold(), config.threshold); + assert_eq!(config_view.enabled(), config.enabled); +} + +#[test] +fn fixed_offset_layout_supports_mutable_flexible_nested_option() { + assert_eq!(FlexibleNestedOptionArgs::MIN_DATA_LEN, 1); + assert_eq!(FlexibleNestedOptionArgs::MAX_DATA_LEN, 37); + + let storage = TestStorage::new( + FlexibleNestedOptionArgs { + header: 3, + config: None, + } + .encode() + .unwrap(), + ); + let config = NestedFixedConfig { + authority: Pubkey::from([8; 32]), + threshold: 11, + enabled: true, + }; + + { + let mut view = FlexibleNestedOptionArgs::decode_mut(&storage).unwrap(); + view.config_mut().unwrap().set(Some(&config)).unwrap(); + } + + assert_eq!( + storage.resize_lens(), + vec![FlexibleNestedOptionArgs::MAX_DATA_LEN] + ); + { + let bytes = storage.bytes(); + let aligned = aligned_copy::<64>(&bytes); + let view = FlexibleNestedOptionArgs::decode(&aligned.0[..bytes.len()]).unwrap(); + let config_view = view.config().unwrap(); + assert_eq!(config_view.authority(), &config.authority); + assert_eq!(config_view.threshold(), config.threshold); + assert!(config_view.enabled()); + } + + { + let mut view = FlexibleNestedOptionArgs::decode_mut(&storage).unwrap(); + view.config_mut().unwrap().set(None).unwrap(); + } + + assert_eq!(storage.bytes(), vec![3]); + assert_eq!( + storage.resize_lens(), + vec![ + FlexibleNestedOptionArgs::MAX_DATA_LEN, + FlexibleNestedOptionArgs::MIN_DATA_LEN, + ] + ); +} + #[test] fn fixed_offset_layout_supports_pubkey_and_trailing_flexible_option() { assert_eq!(FixedTrailingOptionArgs::MIN_DATA_LEN, 34); diff --git a/rust/wheels/tests/variable_offset_layout.rs b/rust/wheels/tests/variable_offset_layout.rs index 1351315..4a27400 100644 --- a/rust/wheels/tests/variable_offset_layout.rs +++ b/rust/wheels/tests/variable_offset_layout.rs @@ -190,6 +190,77 @@ struct FixedVerifierEntry { weight: u64, } +#[variable_offset_layout(buffer_offset = 0)] +struct NestedFixedOptionArgs { + header: u8, + config: Option, + checksum: u16, +} + +#[test] +fn variable_layout_supports_tagged_nested_fixed_option() { + assert_eq!(NestedFixedOptionArgs::DATA_LEN_RANGE, (4, 76)); + + let none = NestedFixedOptionArgs { + header: 3, + config: None, + checksum: 0xBEEF, + } + .encode() + .unwrap(); + assert_eq!( + none, + [vec![3, 0], 0xBEEF_u16.to_le_bytes().to_vec()].concat() + ); + + let config = FixedVerifierEntry { + verifier_identity: Pubkey::from([1; 32]), + verifier_bond: Pubkey::from([2; 32]), + weight: 11, + }; + let some = NestedFixedOptionArgs { + header: 3, + config: Some(config.clone()), + checksum: 0xBEEF, + } + .encode() + .unwrap(); + let mut framed = some.clone(); + framed.extend_from_slice(&[9, 10]); + let (view, remaining) = NestedFixedOptionArgs::decode_prefix(&framed).unwrap(); + let config_view = view.config().unwrap(); + + assert_eq!(view.header(), 3); + assert_eq!(config_view.verifier_identity(), &config.verifier_identity); + assert_eq!(config_view.verifier_bond(), &config.verifier_bond); + assert_eq!(config_view.weight(), config.weight); + assert_eq!(view.checksum(), 0xBEEF); + assert_eq!(remaining, &[9, 10]); +} + +#[test] +fn variable_layout_rejects_invalid_nested_option_encoding() { + let mut bytes = NestedFixedOptionArgs { + header: 3, + config: None, + checksum: 0xBEEF, + } + .encode() + .unwrap(); + bytes[1] = 2; + + assert_eq!( + NestedFixedOptionArgs::decode(&bytes).unwrap_err(), + DataLayoutError::InvalidOptionTag + ); + + bytes[1] = 1; + assert_eq!( + NestedFixedOptionArgs::decode(&bytes).unwrap_err(), + DataLayoutError::TruncatedPayload + ); +} + #[variable_offset_layout(buffer_offset = unknown)] struct FixedEntryRegistryArgs { registry_revision: u64,