macros: Add support for #[scylla(transparent)] attribute #1506

ziara1 · 2025-12-11T08:22:49Z

Motivation

Users often employ the newtype pattern (i.e., define single-field structs) to wrap the driver's types that implement {De,S}erialize{Value,Row}. In such cases, they are currently forced to manually implement (trivially) the respective de/ser traits for those new types, which results in unnecessary boilerplate code.

Solution

Add support for a new item-level attribute, #[scylla(transparent)].
It is supported on:

single-field structs (the original use case),
single-variant enums (technically identical to single-field structs).

The semantics are simple: delegate the trait method's implementation (serialization, deserialization, and type checking) to the only field/variant of the struct/enum.

What's done

Implemented transparent logic in DeserializeValue derive

Refactored deserialize_value_derive to delegate to a new derive_transparent function when the attribute is present.
The implementation ensures that:

type_check delegates to the inner type.
deserialize delegates to the inner type and wraps the result in the newtype constructor.
Generic where clauses are handled correctly by merging generated predicates with existing user predicates using make_where_clause().

Implemented transparent logic in SerializeValue derive

Modified serialize_value_derive to handle the transparent attribute.

For structs: Serializes the single field directly.
For enums: Matches the single variant and serializes its inner field.
Added validation to ensure the attribute is only used on items with exactly one field.

Updated Attribute Parsing

Updated StructAttrs and Attributes definitions in both deserialize and serialize modules to parse the #[scylla(transparent)] boolean flag via darling.

What has been tested

Tests

I added a comprehensive suite of tests covering:

Tuple Structs: struct Wrapper(i32)
Named Structs: struct Wrapper { val: i32 }
Enums: Single variant tuple and named enums.
Nested Composition: Outer(Inner(i32)) to verify deep delegation.
Type Safety: Verified that type_check correctly propagates errors (e.g., trying to read an int column as text through a wrapper fails).
Error Propagation: Verified that deserialization errors (e.g., not enough bytes) are correctly propagated from the inner type through the wrapper.

Fixes: #1293

Pre-review checklist

I have split my patch into logically separate commits.
All commit messages clearly explain what they change and why.
I added relevant tests for new features and bug fixes.
All commits compile, pass static checks and pass test.
PR description sums up the changes and reasons why they should be introduced.
I have provided docstrings for the public items that I want to introduce.
I have adjusted the documentation in ./docs/source/.
I added appropriate Fixes: annotations to PR description.

github-actions · 2025-12-11T08:24:54Z

cargo semver-checks found no API-breaking changes in this PR.
Checked commit: 24dd668

Copilot

Pull request overview

This pull request adds support for the #[scylla(transparent)] attribute to the SerializeValue and DeserializeValue derive macros. This attribute enables wrapper types (newtypes) to transparently serialize and deserialize as their inner type, similar to serde's transparent attribute. The implementation handles structs with single fields (both named and unnamed/tuple structs) and enums with a single variant containing one field.

Key Changes:

Added transparent attribute support to SerializeValue derive macro with validation for single-field structs and single-variant enums
Added transparent attribute support to DeserializeValue derive macro with corresponding validation and proper lifetime handling
Both implementations delegate serialization/deserialization to the inner field's type implementation

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 9 comments.

File	Description
scylla-macros/src/serialize/value.rs	Adds transparent attribute field and implements transparent serialization logic for single-field structs and single-variant enums by delegating to the inner field's SerializeValue implementation
scylla-macros/src/deserialize/value.rs	Adds transparent attribute field and implements transparent deserialization logic through a new derive_transparent function that properly handles lifetimes and delegates to the inner field's DeserializeValue implementation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

scylla-macros/src/serialize/value.rs

scylla-macros/src/deserialize/value.rs

scylla-macros/src/serialize/value.rs

scylla-macros/src/deserialize/value.rs

scylla-macros/src/serialize/value.rs

scylla-macros/src/deserialize/value.rs

scylla-macros/src/serialize/value.rs

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

scylla-macros/src/serialize/value.rs

scylla-macros/src/deserialize/value.rs

Lorak-mmk · 2025-12-16T08:33:46Z

scylla-macros/src/deserialize/value.rs

+    let input: syn::DeriveInput = syn::parse(tokens_input)?;
+
+    let attrs = StructAttrs::from_attributes(&input.attrs)?;
+    if attrs.transparent {
+        return derive_transparent(&input, &attrs);
+    }


In the non-transparent case this will cause the struct attrs to be parsed twice: first time here, and then in StructDesc::new below.
One way to fix that that comes to my mind is to move this if below line let s = StructDesc::new... and use s.attrs instead of attrs. I did not test that, so it may not work. Is there a reason you chose the current approach? Do you see any downsides of my proposed approach?

I tried moving the check after StructDesc::new, but StructDesc strictly requires named fields during initialization. Since transparent structs are often tuple structs, StructDesc::new fails for them.

scylla-macros/src/serialize/value.rs

scylla-macros/src/deserialize/value.rs

Lorak-mmk · 2025-12-16T09:55:30Z

scylla-macros/src/deserialize/value.rs

+                typ: &#crate_path::ColumnType,
+            ) -> ::std::result::Result<(), #crate_path::TypeCheckError> {
+                <#inner_type as #crate_path::DeserializeValue<#frame_lifetime, #metadata_lifetime>>::type_check(typ)
+            }


You mapped the type name in error in deserialize below, but not here. Why?

scylla-cql does not export a helper function to replace the Rust name in TypeCheckError (like value_deser_error_replace_rust_name for DeserializationError).

scylla-macros/src/serialize/value.rs

Lorak-mmk · 2025-12-16T09:59:10Z

scylla-macros/src/serialize/value.rs

+            return Ok(parse_quote! {
+                #[automatically_derived]
+                impl #impl_generics #implemented_trait for #struct_name #ty_generics #where_clause {
+                    fn serialize<'b>(
+                        &self,
+                        typ: &#crate_path::ColumnType,
+                        writer: #crate_path::CellWriter<'b>,
+                    ) -> ::std::result::Result<#crate_path::WrittenCellProof<'b>, #crate_path::SerializationError> {
+                        #crate_path::SerializeValue::serialize(&self.#field_accessor, typ, writer)
+                    }
+                }
+            });


Should error be mapped to correct name here too?

scylla-macros/src/serialize/value.rs

Lorak-mmk · 2025-12-16T10:00:07Z

scylla-macros/src/serialize/value.rs

+                        match self {
+                            #pattern_match => #crate_path::SerializeValue::serialize(inner, typ, writer)
+                        }


ditto about name mapping

ziara1 · 2026-01-08T18:46:41Z

@wprzytula

wprzytula · 2026-01-08T19:10:26Z

@ziara1 Please squash fixes into corresponding commits.

ziara1 · 2026-01-08T20:38:55Z

@wprzytula done

wprzytula requested a review from Copilot December 11, 2025 08:48

wprzytula assigned ziara1 Dec 11, 2025

Copilot started reviewing on behalf of wprzytula December 11, 2025 08:58 View session

Copilot AI reviewed Dec 11, 2025

View reviewed changes

ziara1 force-pushed the feature/scylla_transparent branch from 9139086 to 4dc482e Compare December 13, 2025 18:07

ziara1 changed the title ~~Support #[scylla(transparent)] attribute by derive macros~~ macros: Add support for #[scylla(transparent)] attribute Dec 13, 2025

ziara1 marked this pull request as ready for review December 13, 2025 20:25

wprzytula requested a review from Copilot December 13, 2025 20:26

wprzytula added the area/proc-macros Related to procedural macros label Dec 13, 2025

Copilot started reviewing on behalf of wprzytula December 13, 2025 20:27 View session

Copilot AI reviewed Dec 13, 2025

View reviewed changes

scylla-macros/src/serialize/value.rs Outdated Show resolved Hide resolved

scylla-macros/src/deserialize/value.rs Outdated Show resolved Hide resolved

wprzytula requested a review from Lorak-mmk December 13, 2025 20:51

Lorak-mmk requested changes Dec 16, 2025

View reviewed changes

ziara1 force-pushed the feature/scylla_transparent branch 2 times, most recently from 3d47496 to d21a98a Compare January 3, 2026 10:04

ziara1 requested review from Lorak-mmk and wprzytula January 3, 2026 13:15

ziara1 added 2 commits January 8, 2026 21:30

Support #[scylla(transparent)] attribute by derive macros

77e8c99

add documentation

24dd668

ziara1 force-pushed the feature/scylla_transparent branch from d21a98a to 24dd668 Compare January 8, 2026 20:30

wprzytula added this to the 1.5.0 milestone Jan 12, 2026

macros: Add support for #[scylla(transparent)] attribute #1506

Are you sure you want to change the base?

macros: Add support for #[scylla(transparent)] attribute #1506

Uh oh!

Conversation

ziara1 commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Solution

What's done

Implemented transparent logic in DeserializeValue derive

Implemented transparent logic in SerializeValue derive

Updated Attribute Parsing

What has been tested

Tests

Pre-review checklist

Uh oh!

github-actions bot commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Lorak-mmk Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

ziara1 Jan 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Lorak-mmk Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

ziara1 Jan 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Lorak-mmk Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Lorak-mmk Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

ziara1 commented Jan 8, 2026

Uh oh!

wprzytula commented Jan 8, 2026

Uh oh!

ziara1 commented Jan 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ziara1 commented Dec 11, 2025 •

edited

Loading

github-actions bot commented Dec 11, 2025 •

edited

Loading