Deserialization derive macros

[wprzytula]

Fixes #962

Derive macros for DeserializeValue and DeserializeRow are introduced.

An example feature-complete use

#[derive(scylla_macros::DeserializeValue, PartialEq, Eq, Debug)]
#[scylla(enforce_order, skip_name_checks, forbid_excess_udt_fields)]
struct Udt<'a> {
    a: &'a str,
    #[scylla(skip)]
    x: String,
    #[scylla(allow_missing)]
    b: Option<i32>,
    #[scylla(rename = "d", default_when_null)]
    c: i64,
}

#[derive(scylla_macros::DeserializeRow, PartialEq, Eq, Debug)]
#[scylla(enforce_order)
struct MyRow<'a> {
    a: &'a str,
    #[scylla(skip)]
    x: String,
    b: Option<i32>,
    #[scylla(rename = "d")]
    c: i64,
}

Features

Flavours

Both macros support both unordered (the default) and enforce_order flavours. These are analogous to Serialize{Value,Row} macros flavours, i.e.

• unordered matches by name and allows for arbitrary order of fields in Rust struct and of fields in CQL UDT or columns in CQL row;
• enforce_order matches by position, verifying that names match (unless skip_name_checks attribute is given). This is more strict, but also more performant (because the code, by expecting a specific order, can be more compact and less dynamic).

Struct attributes specific to DeserializeValue:

• forbid_excess_udt_fields - by default, if a UDT definition contains more fields than the Rust struct (in unordered flavour: anywhere, in enforce_order: in suffix), those excess fields are ignored. With forbid_excess_udt_fields attribute set, type check fails with an error in case such fields are present. For comparison, DeserializeRow always requires the same number of Rust fields and CQL columns, effectively rejecting rows with excess columns.

Field attributes common to DeserializeValue and DeserializeRow

• skip - a Rust struct field is skipped during type check and deserialization, and initialised with Default::default();
• rename = "X" - a Rust struct field is matched to CQL UDT field / row column with the name specified instead of its own name.

Field attributes specific to DeserializeValue

The following attributes are very important in production when adding new fields to a UDT, if one first updates clients, then the cluster. They allow for seamless transition in such case.

• allow_missing - if a Rust struct field's name is missing from CQL UDT definition, the field is initialised with Default::default();
• default_when_null - if a CQL UDT field contains null, but the Rust field's type expects non-null, deserialization would normally fail. With this attribute, the field is initialised with Default::default() instead.

Errors

The returned errors are rich and insightful, using the new deserialization error framework. They are well-tested.

Testing

All flavours and attributes should be tested in various combinations. Please verify that I didn't forget about any.

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]

cargo semver-checks detected some API incompatibilities in this PR.
Checked commit: f470d1d

See the following report for details:

cargo semver-checks output

./scripts/semver-checks.sh --baseline-rev 36d5edd3a06a6808ce19dd594ea4904c8b48c0c2
+ cargo semver-checks -p scylla -p scylla-cql --baseline-rev 36d5edd3a06a6808ce19dd594ea4904c8b48c0c2
     Cloning 36d5edd3a06a6808ce19dd594ea4904c8b48c0c2
     Parsing scylla v0.13.0 (current)
      Parsed [  21.923s] (current)
     Parsing scylla v0.13.0 (baseline)
      Parsed [  20.612s] (baseline)
    Checking scylla v0.13.0 -> v0.13.0 (no change)
     Checked [   0.072s] 76 checks: 76 pass, 0 skip
     Summary no semver update required
    Finished [  42.657s] scylla
     Parsing scylla-cql v0.2.0 (current)
      Parsed [  10.588s] (current)
     Parsing scylla-cql v0.2.0 (baseline)
      Parsed [  10.367s] (baseline)
    Checking scylla-cql v0.2.0 -> v0.2.0 (no change)
     Checked [   0.070s] 76 checks: 75 pass, 1 fail, 0 warn, 0 skip

--- failure auto_trait_impl_removed: auto trait no longer implemented ---

Description:
A public type has stopped implementing one or more auto traits. This can break downstream code that depends on the traits being implemented.
        ref: https://doc.rust-lang.org/reference/special-types-and-traits.html#auto-traits
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.33.0/src/lints/auto_trait_impl_removed.ron

Failed in:
  type UdtTypeCheckErrorKind is no longer UnwindSafe, in /home/runner/work/scylla-rust-driver/scylla-rust-driver/scylla-cql/src/types/deserialize/value.rs:1549
  type UdtTypeCheckErrorKind is no longer RefUnwindSafe, in /home/runner/work/scylla-rust-driver/scylla-rust-driver/scylla-cql/src/types/deserialize/value.rs:1549

     Summary semver requires new major version: 1 major and 0 minor checks failed
    Finished [  21.076s] scylla-cql
make: *** [Makefile:61: semver-rev] Error 1

[wprzytula]

Cassandra failure in CI is unrelated to the PR. @Lorak-mmk @muzarski will you take a look?

[wprzytula]

v1.1: more attribute verification & tests for that.

[wprzytula]

Rebased on main.

[wprzytula]

v1.2: addressed most of the review comments by @muzarski. Thank you very much for spotting bugs!

[muzarski]

v1.2: addressed most of the review comments by @muzarski. Thank you very much for spotting bugs!

Remember that previously, the doc tests were not executed in CI (the CI passed, even though there was a buggy test). Please, make sure that we include doc tests in CI. I briefly checked, and see that there is no cargo test --doc step in CI.

[wprzytula]

v1.2: addressed most of the review comments by @muzarski. Thank you very much for spotting bugs!

Remember that previously, the doc tests were not executed in CI (the CI passed, even though there was a buggy test). Please, make sure that we include doc tests in CI. I briefly checked, and see that there is no cargo test --doc step in CI.

The doc tests have always been executed in CI. The CI passed even though the test was buggy, because the tests failed to compile (as expected by the tests) because of different reasons than expected.

cargo test runs a superset of tests run by cargo test --doc.

[muzarski]

v1.2: addressed most of the review comments by @muzarski. Thank you very much for spotting bugs!

Remember that previously, the doc tests were not executed in CI (the CI passed, even though there was a buggy test). Please, make sure that we include doc tests in CI. I briefly checked, and see that there is no cargo test --doc step in CI.

The doc tests have always been executed in CI. The CI passed even though the test was buggy, because the tests failed to compile (as expected by the tests) because of different reasons than expected.

cargo test runs a superset of tests run by cargo test --doc.

Oh, makes sense. I forgot that all tests failed because of crate attribute value.

[Lorak-mmk]

Very nice, but big PR, took some time to review.

[muzarski]

Sorry, I totally forgot about my comment regarding panicking in case of a name mismatch. I think that we should do the check in DeserializeRow::deserialize, and panic just like in DeserializeValue::deserialize for udts. Otherwise, LGTM. Good job!

[wprzytula]

v1.3.1: added a field-column name check in DeserializeRow in enforce_order flavour.