This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 054358bf2c9b9f1ae60e6a970a083097a1943309 Author: chaokunyang <[email protected]> AuthorDate: Sun Jul 26 16:15:33 2026 +0000 π synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/rust/basic-serialization.md | 26 +- docs/guide/rust/custom-serializers.md | 176 ---------- docs/guide/rust/external-types.md | 558 ++++++++++++++++++++++++++++++++ docs/guide/rust/index.md | 6 +- docs/guide/rust/manual-serializers.md | 204 ++++++++++++ docs/guide/rust/native-serialization.md | 62 +++- docs/guide/rust/polymorphism.md | 308 ++++++++---------- docs/guide/rust/schema-evolution.md | 42 ++- docs/guide/rust/schema-metadata.md | 48 ++- docs/guide/rust/troubleshooting.md | 56 +++- docs/guide/rust/type-registration.md | 24 +- docs/guide/rust/xlang-serialization.md | 47 ++- 12 files changed, 1184 insertions(+), 373 deletions(-) diff --git a/docs/guide/rust/basic-serialization.md b/docs/guide/rust/basic-serialization.md index f45049d087..a0253dce93 100644 --- a/docs/guide/rust/basic-serialization.md +++ b/docs/guide/rust/basic-serialization.md @@ -180,6 +180,29 @@ let mut reader = Reader::new(&buf); let decoded: MyStruct = fory.deserialize_from(&mut reader)?; ``` +When the Rust value type uses an external structural serializer or manual +serializer, select it explicitly at the root: + +```rust +let bytes = fory.serialize_with::<UserSerializer>(&user)?; +let decoded: third_party::User = + fory.deserialize_with::<UserSerializer>(&bytes)?; +``` + +Carrier serializers compose the same selection for a root container: + +```rust +use fory::VecSerializer; + +let bytes = + fory.serialize_with::<VecSerializer<UserSerializer>>(&users)?; +let decoded: Vec<third_party::User> = + fory.deserialize_with::<VecSerializer<UserSerializer>>(&bytes)?; +``` + +See [External-Type Serialization](external-types.md) for field annotations, +all supported carriers, and registration. + ## Performance Tips - **Zero-Copy Deserialization**: Row format enables direct memory access without copying @@ -192,4 +215,5 @@ let decoded: MyStruct = fory.deserialize_from(&mut reader)?; - [Type Registration](type-registration.md) - Registering types - [References](references.md) - Shared and circular references -- [Custom Serializers](custom-serializers.md) - Manual serialization +- [Manual Serializers](manual-serializers.md) - Customized serialization +- [External-Type Serialization](external-types.md) - Third-party values and carrier roots diff --git a/docs/guide/rust/custom-serializers.md b/docs/guide/rust/custom-serializers.md deleted file mode 100644 index e5c273e0ab..0000000000 --- a/docs/guide/rust/custom-serializers.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: Custom Serializers -sidebar_position: 10 -id: custom_serializers -license: | - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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. ---- - -For types that don't support `#[derive(ForyStruct)]`, implement the `Serializer` trait manually. - -## When to Use Custom Serializers - -- External types from other crates -- Types with special serialization requirements -- Existing data format compatibility -- Performance-critical custom encoding - -## Implementing the Serializer Trait - -```rust -use fory::{Error, Fory, ForyDefault, ReadContext, Serializer, TypeResolver, WriteContext}; -use std::any::Any; - -#[derive(Debug, PartialEq, Default)] -struct CustomType { - value: i32, - name: String, -} - -impl Serializer for CustomType { - fn fory_write_data(&self, context: &mut WriteContext) -> Result<(), Error> { - context.writer.write_i32(self.value); - context.writer.write_var_u32(self.name.len() as u32); - context.writer.write_utf8_string(&self.name); - Ok(()) - } - - fn fory_read_data(context: &mut ReadContext) -> Result<Self, Error> { - let value = context.reader.read_i32()?; - let len = context.reader.read_var_u32()? as usize; - let name = context.reader.read_utf8_string(len)?; - Ok(Self { value, name }) - } - - fn fory_type_id_dyn(&self, type_resolver: &TypeResolver) -> Result<fory::TypeId, Error> { - Self::fory_get_type_id(type_resolver) - } - - fn as_any(&self) -> &dyn Any { - self - } -} - -// ForyDefault delegates to Default -impl ForyDefault for CustomType { - fn fory_default() -> Self { - Self::default() - } -} -``` - -> **Note**: When implementing `ForyDefault` manually, ensure your type also implements `Default` if you use `Self::default()`. -> Alternatively, you can construct a default instance directly in `fory_default()`. -> -> **Tip**: If your type supports `#[derive(ForyStruct)]`, you can use `#[fory(generate_default)]` to automatically generate both `ForyDefault` and `Default` implementations. - -## Manual Serializers and Arc Any - -If a manually registered serializer needs its type to round-trip behind -`Arc<dyn Any + Send + Sync>` or preserve `UnknownCase` payloads, implement the -send-sync Any reader and return the concrete value as a boxed `Any` value: - -```rust -impl Serializer for CustomType { - fn fory_read_data_as_send_sync_any( - context: &mut ReadContext, - ) -> Result<Box<dyn Any + Send + Sync>, Error> { - Ok(Box::new(Self::fory_read_data(context)?)) - } - - // Implement the ordinary Serializer methods as shown above. - // ... -} -``` - -Do not override this method for values that contain fields whose types are not -`Send + Sync`, such as `Rc<T>`, `RcWeak<T>`, `RefCell<T>`, or `Cell<T>`. - -## Registering Custom Serializers - -```rust -let mut fory = Fory::builder().xlang(false).build(); -fory.register_serializer::<CustomType>(100)?; - -let custom = CustomType { - value: 42, - name: "test".to_string(), -}; -let bytes = fory.serialize(&custom)?; -let decoded: CustomType = fory.deserialize(&bytes)?; -assert_eq!(custom, decoded); -``` - -## WriteContext and ReadContext - -The `WriteContext` and `ReadContext` provide access to: - -- **writer/reader**: Binary buffer operations -- **type_resolver**: Type registration information -- **ref_resolver**: Reference tracking (for shared/circular references) - -### Common Writer Methods - -```rust -// Primitive types -context.writer.write_i8(value); -context.writer.write_i16(value); -context.writer.write_i32(value); -context.writer.write_i64(value); -context.writer.write_f32(value); -context.writer.write_f64(value); -context.writer.write_bool(value); - -// Variable-length integers -context.writer.write_var_i32(value); -context.writer.write_var_u32(value); - -// Strings -context.writer.write_utf8_string(&string); -``` - -### Common Reader Methods - -```rust -// Primitive types -let value = context.reader.read_i8(); -let value = context.reader.read_i16(); -let value = context.reader.read_i32(); -let value = context.reader.read_i64(); -let value = context.reader.read_f32(); -let value = context.reader.read_f64(); -let value = context.reader.read_bool(); - -// Variable-length integers -let value = context.reader.read_var_i32(); -let value = context.reader.read_var_u32(); - -// Strings -let string = context.reader.read_utf8_string(len); -``` - -## Best Practices - -1. **Use variable-length encoding** for integers that may be small -2. **Write length first** for variable-length data -3. **Handle errors properly** in read methods -4. **Implement ForyDefault** for schema evolution support - -## Related Topics - -- [Type Registration](type-registration.md) - Registering serializers -- [Basic Serialization](basic-serialization.md) - Using ForyStruct derive -- [Schema Evolution](schema-evolution.md) - Compatible mode diff --git a/docs/guide/rust/external-types.md b/docs/guide/rust/external-types.md new file mode 100644 index 0000000000..354c37123d --- /dev/null +++ b/docs/guide/rust/external-types.md @@ -0,0 +1,558 @@ +--- +title: External-Type Serialization +sidebar_position: 14 +id: external_types +license: | + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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. +--- + +Rust external-type serialization lets an application serialize a type owned by +another crate without a wrapper value. Use a derived external structural +serializer for an accessible public schema, or a manual serializer for an +opaque or invariant-bearing type. + +## One serializer model + +A serializer implementation declares the Rust value type it handles: + +```rust +pub trait Serializer { + type Target; + + fn write_data( + value: &Self::Target, + context: &mut WriteContext, + ) -> Result<(), Error>; + + fn read_data(context: &mut ReadContext) -> Result<Self::Target, Error>; +} +``` + +For an ordinary local type, the type provides itself. For an external type, a +local serializer supplies the behavior without wrapping or converting the +application value. These methods handle body data; Fory's complete-value +`write` and `read` operations add the requested reference and type-information +envelopes. + +When a root is a container such as `Vec<third_party::User>`, compose +Fory-owned carrier serializers such as `VecSerializer<UserSerializer>`. These are +compile-time types and are never instantiated. + +There is no separate public field serializer, adapter, encoder, or decoder +trait. + +## External structural serializers + +Use an external structural serializer when every target field or enum variant is publicly +accessible and the target can be constructed directly with the same shape: + +```rust +use fory::ForyStruct; + +#[derive(ForyStruct)] +#[fory(target = third_party::User)] +struct UserSerializer { + name: String, + age: u32, +} +``` + +The external structural serializer is a schema and code-generation declaration. +Fory never constructs a `UserSerializer` value. Generated code reads fields +from `third_party::User` and constructs `third_party::User` directly. + +For an external enum or union, the external structural serializer declaration +defines the wire schema. In xlang mode, explicit Fory IDs and declaration-order +fallbacks define ENUM or UNION tags. Native data enums retain the existing +local `ForyUnion` tag rules; external-type serialization does not give explicit +IDs a new native meaning. The external enum's source declaration order does +not define the schema. Generated exhaustive matching still verifies the target +variant names and shapes. + +External structural serializers for structs and pure enums retain the existing +STRUCT and ENUM formats. Xlang-compatible data enums retain UNION, while +native struct-style enums retain the existing `xlang = false` Rust enum format. +The serializer declaration does not appear on the wire. + +Private, invariant-bearing, or `#[non_exhaustive]` targets are not eligible for +an external structural serializer. + +An xlang-compatible data enum uses `ForyUnion` and the existing union case +rules: + +```rust +use fory::{ForyUnion, UnknownCase}; + +#[derive(ForyUnion)] +#[fory(target = third_party::Value<UnknownCase>)] +enum ValueSerializer { + #[fory(default)] + Null, + Text(String), + Count(i64), + #[fory(unknown)] + Unknown(UnknownCase), +} +``` + +The target must represent the same runtime unknown carrier for lossless xlang +union reads. A third-party crate can remain independent of Fory by declaring a +generic enum such as `Value<U>`; the application sets the serializer target to +`Value<UnknownCase>`. A target that cannot carry unknown cases is not eligible +for lossless external xlang-union serialization. + +### Native struct-style enums + +With `xlang = false`, an external structural serializer supports the complete +Rust data-enum surface: unit variants, tuple variants with one or more fields, +named variants with one or more fields, and any mixture of those shapes. + +```rust +use fory::ForyUnion; + +#[derive(ForyUnion)] +#[fory(target = third_party::Command)] +enum CommandSerializer { + #[fory(default)] + Idle, + Create { + #[fory(with = UuidSerializer)] + id: uuid::Uuid, + label: String, + }, + Move(i32, i32), +} +``` + +`ForyUnion` remains the one derive for data-carrying Rust enums; there is no +separate native-enum macro. Direct, carrier, list-element, map key/value, and +heterogeneous tuple-position serializer annotations also work inside tuple and +named variant payloads. +Native struct-style enums work with both compatible and schema-consistent +native serialization. + +An xlang union case can carry at most one alternative value. Consequently, a +multi-field tuple or named Rust variant is native-only. Registering a serializer +for such an enum while `xlang = true` returns an error before registration is +published. Fory does not discard fields, synthesize hidden variant structs, or +silently encode the type as EXT. + +## Manual serializers + +Use a manual serializer for opaque types such as UUID or Jiff values: + +```rust +use fory::{Error, ReadContext, Serializer, WriteContext}; +use std::any::Any; +use std::sync::Arc; + +struct UuidSerializer; + +#[cold] +#[inline(never)] +fn invalid_uuid(error: uuid::Error) -> Error { + Error::invalid_data(error.to_string()) +} + +impl Serializer for UuidSerializer { + type Target = uuid::Uuid; + + fn write_data( + value: &uuid::Uuid, + context: &mut WriteContext, + ) -> Result<(), Error> { + context.writer.write_bytes(value.as_bytes()); + Ok(()) + } + + fn read_data(context: &mut ReadContext) -> Result<uuid::Uuid, Error> { + let bytes = context.reader.read_bytes(16)?; + uuid::Uuid::from_slice(bytes).map_err(invalid_uuid) + } + + // Required only for sync Arc dynamic carriers. + fn read_arc_any( + context: &mut ReadContext, + ) -> Result<Arc<dyn Any + Send + Sync>, Error> { + let value: Arc<dyn Any + Send + Sync> = + Arc::new(Self::read_data(context)?); + Ok(value) + } +} +``` + +Manual serializers use the existing EXT or NAMED_EXT wire kinds. Their internal +body evolution is application-owned. If a body length controls an allocation, +the manual serializer must use the read context's byte-availability and graph-memory +checks before reserving or allocating that storage. + +When a manual serializer is composed under a variable-size carrier, the +carrier's complete bytes after its count must average at least one byte per +declared element or map entry. Fory checks this once after writing the carrier +and returns an error for a body that is too compact for the paired +allocation-safety check. Fixed arrays, and zero-sized elements in `Vec`, +`VecDeque`, or `BinaryHeap`, do not allocate storage from that count and are +exempt. + +Fory invokes the optional `read_arc_any` method only after reserving the final +Arc owner; the method shown above performs that allocation once and must not +reserve the same outer owner again. A manual serializer that does not need sync +Arc dynamic carriers omits it and remains valid for typed, Box, and Rc uses; +attempting sync Arc materialization then returns an unsupported error. + +## Fields and nested values + +A static external value names its serializer explicitly: + +```rust +use fory::{ForyStruct, MutexSerializer, RefCellSerializer}; +use std::cell::RefCell; +use std::sync::Mutex; + +#[derive(ForyStruct)] +struct Request { + #[fory(with = UuidSerializer)] + request_id: uuid::Uuid, + + #[fory(with = UserSerializer)] + user: third_party::User, + + #[fory(with = RefCellSerializer<UserSerializer>)] + mutable_user: RefCell<third_party::User>, + + #[fory(with = MutexSerializer<UserSerializer>)] + locked_user: Mutex<third_party::User>, +} +``` + +`with` selects one serializer whose target is the exact declared field type. +For `Option`, `Box`, `Rc`, `Arc`, Fory weak-reference carriers, `RefCell`, and +`Mutex`, select the corresponding carrier serializer around the child +serializer. For example, use `OptionSerializer<UserSerializer>` for +`Option<third_party::User>` and `ArcSerializer<UserSerializer>` for +`Arc<third_party::User>`. `RefCell` and `Mutex` retain the child wire shape; +serialization of these direct fields uses one borrow or lock, and +deserialization constructs the holder directly without an additional heap +owner. Compatible schema evolution remains active for an external structural +serializer nested behind any of these wrappers. + +In a non-skipped derived field, keep every carrier constructor's canonical name +visible, optionally with its module path. This applies both to the field's Rust +type and to a `with` serializer tree. For example, write +`Vec<third_party::User>` and `VecSerializer<UserSerializer>` directly instead +of hiding either carrier tree behind a type alias or renamed import. Leaf +serializer aliases remain valid. Carrier aliases also remain valid at roots, +where Rust resolves the serializer type without field code generation. A +skipped field may also use a carrier alias because it emits no field schema and +uses only the selected serializer's default. + +A skipped external field can use `#[fory(skip, with = UserSerializer)]`. In that +case the serializer is used only for its fallible construction default; the +field contributes no schema or body bytes. Registration is unnecessary when +that skipped default is the serializer's only use. The default receives the +active read context and must reserve graph memory before any owned allocation. +Skipped list/map/tuple fields can retain recursive child serializer annotations, +although an empty container default does not invoke its children. + +List elements, map children, and tuple positions select serializers at their own +recursive schema nodes: + +```rust +use fory::{ForyStruct, VecSerializer}; +use std::collections::HashMap; + +#[derive(ForyStruct)] +struct Directory { + #[fory(with = VecSerializer<UserSerializer>)] + direct_users: Vec<third_party::User>, + + #[fory(list(element(with = UserSerializer)))] + users: Vec<third_party::User>, + + #[fory(map( + key(with = ExternalKeySerializer), + value(with = UserSerializer) + ))] + by_key: HashMap<third_party::Key, third_party::User>, + + #[fory(tuple( + element(index = 0, with = ExternalKeySerializer), + element(index = 1, list(element(with = UserSerializer))) + ))] + entry: (third_party::Key, Vec<third_party::User>), +} +``` + +Tuple indexes are zero-based. Unmentioned tuple positions use their ordinary +serializer, and tuple elements can contain the same recursive list, map, or +tuple metadata. Tuples are supported from arity 1 through 22. + +Recursive field selection covers `Vec`, `VecDeque`, `LinkedList`, `HashSet`, +`BTreeSet`, `BinaryHeap`, fixed arrays, `HashMap`, `BTreeMap`, and tuple +arities 1 through 22. `direct_users` selects a carrier serializer for the exact +Vec node; `users` selects the element serializer recursively. Both forms use the +same built-in Vec implementation and structural LIST representation. A serializer +annotation applies only to its declared node; it never silently propagates +through a composite. + +A node-local `#[fory(with = PackedUsersSerializer)]` may instead select one +manual serializer whose exact target is the whole `Vec`, map, set, array, or +tuple. That field uses opaque EXT/NAMED_EXT encoding and has no child schema. +It cannot also use `list`, `map`, `tuple`, `array`, `bytes`, or `encoding`. +Recursive list/map/tuple annotations are the distinct choice when the composite +should retain its structural wire kind and only its children need selected +serializers. This opaque customization is not a user-declared carrier +serializer and cannot compose child serializers. + +If that exact whole-container manual serializer is registered, erased polymorphic values +of the exact target use it. Ordinary unannotated typed fields and roots whose +children self-provide keep using the built-in structural container format; +explicit carrier serializer roots also keep their declared structural format. +Registration does not redirect those static paths. + +## Root values + +Ordinary local roots retain `serialize`, `serialize_to`, `deserialize`, and +`deserialize_from`. + +An external root selects its serializer: + +```rust +let bytes = fory.serialize_with::<UserSerializer>(&user)?; +let decoded = + fory.deserialize_with::<UserSerializer>(&bytes)?; +``` + +The complete serializer-selected root family is: + +- `serialize_with`; +- `serialize_to_with`; +- `deserialize_with`; +- `deserialize_from_with`. + +The serializer is a compile-time type parameter. No serializer instance, wrapper, +or mirror value is passed at runtime. + +For a container root, compose the corresponding Fory-owned carrier serializer: + +```rust +use fory::VecSerializer; + +fory.register::<UserSerializer>(100)?; + +let users: Vec<third_party::User> = load_users(); +let bytes = + fory.serialize_with::<VecSerializer<UserSerializer>>(&users)?; +let decoded: Vec<third_party::User> = + fory.deserialize_with::<VecSerializer<UserSerializer>>(&bytes)?; +``` + +`VecSerializer<UserSerializer>` targets `Vec<third_party::User>` and keeps the +normal LIST format. Register selected external structural serializers such as +`UserSerializer`; do not register the carrier serializer itself. + +Map keys, map values, and nested containers compose recursively: + +```rust +use fory::{HashMapSerializer, VecSerializer}; + +type DirectorySerializer = + HashMapSerializer<ExternalKeySerializer, VecSerializer<UserSerializer>>; + +let bytes = + fory.serialize_with::<DirectorySerializer>(&directory)?; +``` + +For nested lists, `VecSerializer<VecSerializer<UserSerializer>>` targets +`Vec<Vec<third_party::User>>`. + +Heterogeneous tuple roots compose by position: + +```rust +use fory::Tuple2Serializer; + +type EntrySerializer = + Tuple2Serializer<String, UserSerializer>; + +let bytes = + fory.serialize_with::<EntrySerializer>(&entry)?; +``` + +`EntrySerializer` targets `(String, third_party::User)`. The tuple carrier serializer +keeps the same native or heterogeneous LIST representation as an ordinary +two-position tuple. + +The complete carrier serializer family is: + +- `OptionSerializer`, `BoxSerializer`, `RcSerializer`, `ArcSerializer`, + `RcWeakSerializer`, `ArcWeakSerializer`, `RefCellSerializer`, and + `MutexSerializer`; +- `VecSerializer`, `VecDequeSerializer`, `LinkedListSerializer`, + `HashSetSerializer`, `BTreeSetSerializer`, `BinaryHeapSerializer`, and + `ArraySerializer`; +- `HashMapSerializer` and `BTreeMapSerializer`; +- `Tuple1Serializer` through `Tuple22Serializer`. + +There is no `Tuple0Serializer`: `()` has no child and remains self-provided. +`PhantomData<T>` also has no serialized child and needs no serializer +composition. + +`Cell<T>` is not a currently supported Rust serialization carrier and does not +have a `CellSerializer`. `RefCell<T>` is the supported interior-mutability +carrier. Standard-library `Weak<T>` is also not an alias for Fory's +`RcWeak<T>` or `ArcWeak<T>`. + +Every child argument is another serializer type. It can be an ordinary serializer targeting itself, +an external structural serializer, a manual leaf serializer, or another Fory-owned carrier +serializer. All four forms preserve the carrier's built-in encoding. An ordinary +local type is its own serializer, so +`HashMapSerializer<String, UserSerializer>` targets +`HashMap<String, third_party::User>`. +`ArraySerializer<S, N>` uses the same carrier selection as the chosen child +serializer. A canonical primitive serializer such as `i32` retains its +dense-array format, while an external structural or manual child serializer +uses LIST even if its target is a primitive Rust type. + +`VecSerializer<S>` also preserves the ordinary Vec format selected by its +child. `VecSerializer<i32>` uses `INT32_ARRAY`, +`VecSerializer<u8>` uses `BINARY`, and +`VecSerializer<UserSerializer>` uses LIST. A nested +`VecSerializer<VecSerializer<i32>>` uses an outer LIST whose element type is +the ordinary `INT32_ARRAY` representation. Serializer composition never turns a +canonical primitive vector into an object LIST. + +Generated fields keep their declared field schema. An unannotated `Vec<i32>` +field is `LIST<VARINT32>`, and +`#[fory(list(element(encoding = fixed)))] Vec<i32>` is `LIST<INT32>`. +`#[fory(array)]` selects a dense array and `#[fory(bytes)]` selects BINARY. All +of these forms, including `VecSerializer<S>` roots, preserve the built-in Vec +encoding selected by their declared schema. + +Fory never infers a serializer composition from a target type or from +registration. Name every external child serializer explicitly in the carrier serializer +type. A field can select an exact carrier serializer with `with`, such as +`#[fory(with = VecSerializer<UserSerializer>)]`. Use the inline +`list(element(...))` or `map(key(...), value(...))` grammar, or indexed +`tuple(element(...))` grammar, when serializers are selected at recursive child +nodes. + +An exact whole-container or whole-tuple manual serializer remains a valid opaque +root, but it uses EXT/NAMED_EXT instead of the built-in structural +representation and does not select child serializers. + +The `_with` method suffix means its generic argument selects the serializer, +matching `#[fory(with = UserSerializer)]`. + +## Registration + +Structural and manual serializers use the existing registration categories. +Choose one identity style for each serializer. + +Numeric registration: + +```rust +fory.register::<UserSerializer>(100)?; +fory.register::<CommandSerializer>(101)?; // Native struct-style enum. +fory.register_union::<ValueSerializer>(102)?; // Xlang-compatible union. +fory.register_serializer::<UuidSerializer>(103)?; +``` + +Name registration: + +```rust +fory.register_by_name::<UserSerializer>("example.User")?; +fory.register_by_name::<CommandSerializer>("example.Command")?; +fory.register_union_by_name::<ValueSerializer>("example.Value")?; +fory.register_serializer_by_name::<UuidSerializer>("example.Uuid")?; +``` + +Registration associates the wire identity with the serializer's target. One +`Fory` instance accepts only one registered dynamic serializer for a given +target. Registering it does not replace an ordinary static serializer or +implicitly select it for an unannotated field or root. Complete registration +before the first serialization operation. Register each structural or manual +external child; never register a carrier serializer. + +Carrier composition does not make the entire container a dynamic `Any` target. +If the exact whole container must participate in erased dynamic dispatch, +register a manual exact-target serializer and use its EXT/NAMED_EXT +representation. + +## Polymorphism + +Registered external targets participate in `Box<dyn Any>` and `Rc<dyn Any>` +through their target identity. A `Send + Sync` target also participates in +`Arc<dyn Any + Send + Sync>` when its structural derive generated the Arc +materializer or its manual serializer implemented `read_arc_any`. + +These erased carriers work in native and xlang modes when the selected concrete +serializer supports that mode. The Rust carrier and application trait name are +not written; xlang mode still requires each concrete target to have an +xlang-representable structural or EXT identity. + +Application traits extend a small object-safe `ForyObject` trait instead of +`Serializer`: + +```rust +use fory::{register_trait_type, ForyObject}; + +trait Animal: ForyObject { + fn name(&self) -> &str; +} + +register_trait_type!(Animal, Dog, third_party::Cat); +``` + +The concrete target list is closed and explicit. Each target can use an +ordinary serializer, an external structural serializer, or a manual serializer. + +For `Arc<dyn Trait>`, the sync form requires the trait and listed targets to +implement `Send + Sync`: + +```rust +use fory::{register_trait_type, ForyObject}; + +trait Animal: ForyObject + Send + Sync { + fn name(&self) -> &str; +} + +register_trait_type!(sync Animal, Dog, third_party::Cat); +``` + +Use either the non-sync or sync declaration and macro invocation for a given +trait, not both. + +Generated trait-root serializer names are private to the macro's module by +default. A library can export them with +`register_trait_type!(pub Animal, ...)` or +`register_trait_type!(pub sync Animal, ...)`; the trait and listed targets must +be visible at least as broadly. + +`Box<dyn Animal>` remains a direct root. The macro generates zero-sized +serializer types for `Rc<dyn Animal>` and, for the sync macro form, +`Arc<dyn Animal>` roots. It does not generate Rc/Arc value wrappers or perform +wrapper conversions. + +The trait carrier serializers are not registered by ID or name. Applications +register each allowed concrete target through its ordinary serializer, +external structural serializer, or manual serializer. + +## Related Topics + +- [Manual Serializers](manual-serializers.md) +- [Polymorphism](polymorphism.md) +- [Type Registration](type-registration.md) +- [Schema Evolution](schema-evolution.md) diff --git a/docs/guide/rust/index.md b/docs/guide/rust/index.md index 27a44e2153..e519a95fec 100644 --- a/docs/guide/rust/index.md +++ b/docs/guide/rust/index.md @@ -100,7 +100,7 @@ fn main() -> Result<(), Error> { Use xlang mode for cross-language payloads and schemas shared with other Fory implementations. Xlang mode is the default Rust wire mode, and Rust examples that use it set `.xlang(true)` explicitly so the mode choice is visible. -Use native mode for Rust-only traffic. Native mode is selected with `.xlang(false)` and keeps Rust object serialization in Rust-native form. It is optimized for Rust's type system and covers Rust-specific object features such as trait objects and shared-reference patterns that are not portable xlang payloads. Compatible mode is enabled by default. Set `.compatible(false)` only when every reader and writer uses the same Rust schema and you want faster serialization and smaller size. +Use native mode for Rust-only traffic. Native mode is selected with `.xlang(false)` and keeps Rust object serialization in Rust-native form. It supports native-only concrete targets and data-enum shapes that have no xlang representation. Dynamic `Any`, application trait, and shared-reference carriers can also be used in xlang mode when every selected concrete target is xlang-compatible. Compatible mode is enabled by default. Set `.compatible(false)` only when every reader and writer uses [...] See [Xlang Serialization](xlang-serialization.md) for Rust xlang registration and interoperability rules, and [Native Serialization](native-serialization.md) for Rust-only payloads. @@ -196,6 +196,8 @@ fory-derive/ # Procedural macros - [Native Serialization](native-serialization.md) - Rust-only serialization - [References](references.md) - Shared and circular references - [Polymorphism](polymorphism.md) - Trait object serialization -- [Custom Serializers](custom-serializers.md) - Extend serialization behavior +- [Manual Serializers](manual-serializers.md) - Implement customized serialization behavior +- [External-Type Serialization](external-types.md) - External structural and manual serializers + plus carrier composition - [Row Format](row-format.md) - Zero-copy row-based format - [gRPC Support](grpc-support.md) - Fory payloads over tonic diff --git a/docs/guide/rust/manual-serializers.md b/docs/guide/rust/manual-serializers.md new file mode 100644 index 0000000000..c68071f954 --- /dev/null +++ b/docs/guide/rust/manual-serializers.md @@ -0,0 +1,204 @@ +--- +title: Manual Serializers +sidebar_position: 10 +id: manual_serializers +license: | + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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 a manual serializer when derive cannot express the type's serialized +representation or when an opaque encoding is intentional. A serializer is a +type-level implementation and names the value it handles through `Target`. + +For a public third-party struct or enum whose schema should remain structural, +prefer [External-Type Serialization](external-types.md). + +## Implement a Manual Serializer + +This example uses a local type as its own serializer: + +```rust +use fory::{Error, Fory, ReadContext, Serializer, WriteContext}; + +#[derive(Debug, PartialEq)] +struct Point { + value: i32, +} + +impl Serializer for Point { + type Target = Self; + + fn write_data(value: &Self, context: &mut WriteContext) -> Result<(), Error> { + context.writer.write_i32(value.value); + Ok(()) + } + + fn read_data(context: &mut ReadContext) -> Result<Self, Error> { + Ok(Self { + value: context.reader.read_i32()?, + }) + } + + fn default_value(_context: &mut ReadContext) -> Result<Self, Error> { + Ok(Self { value: 0 }) + } +} + +let mut fory = Fory::builder().xlang(false).build(); +fory.register_serializer::<Point>(100)?; + +let value = Point { value: 42 }; +let bytes = fory.serialize(&value)?; +let decoded: Point = fory.deserialize(&bytes)?; +assert_eq!(decoded, value); +# Ok::<(), Error>(()) +``` + +`write_data` and `read_data` handle the EXT body. Fory's complete-value +`write` and `read` operations supply the root or field reference and +type-information framing. + +`default_value` is optional. Implement it only when a null or missing +compatible field has a meaningful value. It receives the active `ReadContext`, +so a default that allocates can apply the same deserialization limits as a +normal read. + +## Serialize a Third-Party Opaque Type + +A separate serializer can target a type from another crate: + +```rust +use fory::{Error, ReadContext, Serializer, WriteContext}; + +struct UuidSerializer; + +#[cold] +#[inline(never)] +fn invalid_uuid(error: uuid::Error) -> Error { + Error::invalid_data(error.to_string()) +} + +impl Serializer for UuidSerializer { + type Target = uuid::Uuid; + + fn write_data( + value: &uuid::Uuid, + context: &mut WriteContext, + ) -> Result<(), Error> { + context.writer.write_bytes(value.as_bytes()); + Ok(()) + } + + fn read_data(context: &mut ReadContext) -> Result<uuid::Uuid, Error> { + let bytes = context.reader.read_bytes(16)?; + uuid::Uuid::from_slice(bytes).map_err(invalid_uuid) + } +} +``` + +Register the serializer, then select it at the root or field: + +```rust +fory.register_serializer::<UuidSerializer>(101)?; + +let bytes = fory.serialize_with::<UuidSerializer>(&uuid)?; +let decoded = + fory.deserialize_with::<UuidSerializer>(&bytes)?; +``` + +```rust +#[derive(ForyStruct)] +struct Request { + #[fory(with = UuidSerializer)] + id: uuid::Uuid, +} +``` + +Manual serializer bodies are opaque. Compatible mode does not map fields +inside them. + +## Support `Arc<dyn Any + Send + Sync>` + +If a manual serializer's target must be materialized behind +`Arc<dyn Any + Send + Sync>` or a synchronized application trait, implement +`read_arc_any`: + +```rust +use std::any::Any; +use std::sync::Arc; + +impl Serializer for Point { + type Target = Self; + + // Implement write_data, read_data, and any desired default as above. + + fn read_arc_any( + context: &mut ReadContext, + ) -> Result<Arc<dyn Any + Send + Sync>, Error> { + Ok(Arc::new(Self::read_data(context)?)) + } +} +``` + +The target must implement `Send + Sync`. If this method is omitted, typed, +`Box`, and `Rc` operations remain available, while synchronized `Arc` +materialization returns an error. + +## Registration by Name + +Use name registration when the serialized identity is a qualified name: + +```rust +fory.register_serializer_by_name::<UuidSerializer>( + "example.Uuid", +)?; +``` + +One `Fory` instance can register at most one serializer for a target. + +## Context Access + +`WriteContext` and `ReadContext` expose the binary writer and reader: + +```rust +context.writer.write_i8(value); +context.writer.write_i32(value); +context.writer.write_var_u32(value); +context.writer.write_f64(value); + +let value = context.reader.read_i8()?; +let value = context.reader.read_i32()?; +let value = context.reader.read_var_u32()?; +let value = context.reader.read_f64()?; +``` + +For variable-size bodies, validate readable bytes and graph-memory limits +before allocating from an encoded length. + +When a manual serializer is selected as a child of a variable-size carrier, +the carrier must emit at least one aggregate byte per declared element or map +entry after its count. Fory rejects serialization when the carrier's complete +header, metadata, framing, and child bodies are shorter than that count, so it +never emits bytes that the paired allocation-safety check cannot read. Fixed +arrays are exempt because their validated count does not control an +allocation; zero-sized elements in `Vec`, `VecDeque`, and `BinaryHeap` are also +exempt because those carriers allocate no backing storage for them. + +## Related Topics + +- [External-Type Serialization](external-types.md) +- [Type Registration](type-registration.md) +- [Schema Evolution](schema-evolution.md) diff --git a/docs/guide/rust/native-serialization.md b/docs/guide/rust/native-serialization.md index d00c1408e2..40a164ac25 100644 --- a/docs/guide/rust/native-serialization.md +++ b/docs/guide/rust/native-serialization.md @@ -32,8 +32,9 @@ Kotlin, or another non-Rust Fory implementation. Use native serialization when: - A payload is produced and consumed only by Rust applications. -- The data model uses Rust-specific object graph features such as `Rc<T>`, `Arc<T>`, weak - pointers, `RefCell<T>`, `Mutex<T>`, trait objects, or `dyn Any`. +- The data model uses Rust-specific object graph features such as typed `Rc<T>`, `Arc<T>`, weak + pointers, `RefCell<T>`, or `Mutex<T>`, or uses native-only concrete targets behind trait objects + or `dyn Any`. - You want faster serialization and smaller size, and every reader uses the same schema as the writer. - You need compatible schema evolution for Rust-only rolling deployments. @@ -87,8 +88,11 @@ every reader and writer always uses the same Rust schema. Register application structs and enum-like types before serialization: ```rust +// Choose a numeric ID: fory.register::<Order>(100)?; -fory.register_by_name::<Order>("example.Order")?; + +// Or, on a different Fory instance, choose a qualified name: +// fory.register_by_name::<Order>("example.Order")?; ``` Use explicit numeric IDs for compact payloads and stable deployments. Use named registration @@ -106,8 +110,9 @@ Native serialization owns the Rust-specific object surface: - Trait objects such as `Box<dyn Trait>`, `Rc<dyn Trait>`, and `Arc<dyn Trait>`. - Runtime type dispatch with `Box<dyn Any>`, `Rc<dyn Any>`, and `Arc<dyn Any + Send + Sync>` for registered non-container payloads. Wrap - containers in registered structs, enums, or unions before using them behind - erased `Any` carriers. + containers in registered structs, enums, or unions, or register an + exact-target manual serializer when an opaque EXT/NAMED_EXT representation + is appropriate. - Date and time carriers, including optional `chrono` support. Use [Basic Serialization](basic-serialization.md), [References](references.md), and @@ -144,12 +149,13 @@ when the target has been dropped. ## Trait Objects -Trait objects are Rust language features and belong in native serialization: +Trait objects are Rust language features, but their registered concrete targets +can use either native or xlang serialization. This example uses native mode: ```rust -use fory::{register_trait_type, Error, Fory, ForyStruct, Serializer}; +use fory::{register_trait_type, Error, Fory, ForyObject, ForyStruct}; -trait Animal: Serializer { +trait Animal: ForyObject { fn name(&self) -> &str; } @@ -180,6 +186,36 @@ fn main() -> Result<(), Error> { Register every concrete implementation that can appear behind the trait object. +## Third-Party Struct-Style Enums + +Native mode supports external structural serializers for Rust enums with unit, +tuple, and named multi-field variants: + +```rust +use fory::{Fory, ForyUnion}; + +#[derive(ForyUnion)] +#[fory(target = third_party::Command)] +enum CommandSerializer { + #[fory(default)] + Idle, + Move(i32, i32), + Create { id: u128, label: String }, +} + +let mut fory = Fory::builder() + .xlang(false) + .compatible(true) + .build(); +fory.register::<CommandSerializer>(101)?; +``` + +The same serializer works with `compatible(false)` when both peers use the +same schema. Multi-field tuple and named variants have no xlang union mapping, +so registering this serializer with `xlang(true)` returns an error. See +[External-Type Serialization](external-types.md) for field, carrier, root, and +manual serializer composition. + ## Performance Guidelines - Reuse a configured `Fory` instance and register types before concurrent use. @@ -195,12 +231,16 @@ Register every concrete implementation that can appear behind the trait object. | -------------------------------------- | ------------------------ | ----------------------- | | Rust-only payloads | Yes | Optional | | Non-Rust readers or writers | No | Yes | -| `Rc`, `Arc`, weak pointers | Yes | No | -| Trait objects and `dyn Any` | Yes | No | -| Same-schema compact payloads | Yes | No | +| Typed shared and weak references | Yes | No | +| Trait objects and `dyn Any` | Yes | Conditional | +| Same-schema compact payloads | Yes | Yes | | Compatible schema evolution by default | Yes | Yes | | Portable type mapping across languages | No | Yes | +Trait objects and `dyn Any` work in xlang mode only when every selected +concrete target has an xlang-compatible structural or EXT identity. The Rust +trait or erased-carrier identity is not written to the wire. + ## Troubleshooting ### A non-Rust implementation cannot read the payload diff --git a/docs/guide/rust/polymorphism.md b/docs/guide/rust/polymorphism.md index c0dbaf4539..49251da3d5 100644 --- a/docs/guide/rust/polymorphism.md +++ b/docs/guide/rust/polymorphism.md @@ -19,249 +19,221 @@ license: | limitations under the License. --- -Apache Foryβ’ supports polymorphic serialization through trait objects, enabling dynamic dispatch and type flexibility. +Apache Fory supports dynamic values through registered application traits and +the standard `Any` trait. -## Supported Trait Object Types +## Application Traits -- `Box<dyn Trait>` - Owned trait objects -- `Rc<dyn Trait>` - Reference-counted trait objects -- `Arc<dyn Trait>` - Thread-safe reference-counted trait objects -- `Vec<Box<dyn Trait>>`, `HashMap<K, Box<dyn Trait>>` - Collections of trait objects - -## Basic Trait Object Serialization +An application trait extends `ForyObject`. List every concrete target accepted +by the trait in `register_trait_type!`: ```rust -use fory::{Fory, register_trait_type}; -use fory::Serializer; -use fory::ForyStruct; +use fory::{ + register_trait_type, Fory, ForyObject, ForyStruct, +}; -trait Animal: Serializer { - fn speak(&self) -> String; +trait Animal: ForyObject { fn name(&self) -> &str; } #[derive(ForyStruct)] -struct Dog { name: String, breed: String } +struct Dog { + name: String, +} impl Animal for Dog { - fn speak(&self) -> String { "Woof!".to_string() } - fn name(&self) -> &str { &self.name } + fn name(&self) -> &str { + &self.name + } } #[derive(ForyStruct)] -struct Cat { name: String, color: String } +struct Cat { + name: String, +} impl Animal for Cat { - fn speak(&self) -> String { "Meow!".to_string() } - fn name(&self) -> &str { &self.name } + fn name(&self) -> &str { + &self.name + } } -// Register trait implementations register_trait_type!(Animal, Dog, Cat); +``` -#[derive(ForyStruct)] -struct Zoo { - star_animal: Box<dyn Animal>, -} +The concrete list contains runtime value types. Each type must also be +registered with the `Fory` instance: +```rust let mut fory = Fory::builder().xlang(false).build(); fory.register::<Dog>(100)?; fory.register::<Cat>(101)?; -fory.register::<Zoo>(102)?; +``` -let zoo = Zoo { - star_animal: Box::new(Dog { - name: "Buddy".to_string(), - breed: "Labrador".to_string(), - }), -}; +A listed third-party target can be registered through an external structural +serializer or manual serializer. The list still names the target, not that +serializer. -let bytes = fory.serialize(&zoo)?; -let decoded: Zoo = fory.deserialize(&bytes)?; +The generated names are private to the macro's module by default. A library +that exports the generated root serializers adds normal Rust visibility: -assert_eq!(decoded.star_animal.name(), "Buddy"); -assert_eq!(decoded.star_animal.speak(), "Woof!"); +```rust +register_trait_type!(pub Animal, Dog, Cat); ``` -## Serializing dyn Any Trait Objects - -Apache Foryβ’ supports serializing `Box<dyn Any>`, `Rc<dyn Any>`, and -`Arc<dyn Any + Send + Sync>` for dynamic type dispatch: +The trait and listed types must be visible at least as broadly as the generated +serializers. `pub(crate)` and restricted visibility are also supported. -**Key points:** +## Trait Object Fields -- Works with registered concrete non-container types that implement `Serializer` -- Requires downcasting after deserialization to access the concrete type -- Type information is preserved during serialization -- Useful for plugin systems and dynamic type handling +`Box<dyn Trait>` and `Rc<dyn Trait>` work directly in derived fields and nested +containers: ```rust +use std::collections::HashMap; use std::rc::Rc; -use std::any::Any; -let dog_any: Rc<dyn Any> = Rc::new(Dog { - name: "Rex".to_string(), - breed: "Golden".to_string() -}); - -// Serialize the Any wrapper -let bytes = fory.serialize(&dog_any)?; -let decoded: Rc<dyn Any> = fory.deserialize(&bytes)?; - -// Downcast back to the concrete type -let unwrapped = decoded.downcast_ref::<Dog>().unwrap(); -assert_eq!(unwrapped.name, "Rex"); +#[derive(ForyStruct)] +struct Shelter { + featured: Box<dyn Animal>, + shared: Rc<dyn Animal>, + animals: Vec<Box<dyn Animal>>, + by_name: HashMap<String, Rc<dyn Animal>>, +} ``` -For thread-safe scenarios, use `Arc<dyn Any + Send + Sync>`: +Fory checks the closed concrete list before materializing a value. Do not add +`#[fory(with = ...)]` to a trait-object node; its concrete serializer is chosen +dynamically from the registered target. + +For `Arc<dyn Trait>`, the trait must be thread-safe and the macro uses its sync +form: ```rust use std::sync::Arc; -use std::any::Any; - -let dog_any: Arc<dyn Any + Send + Sync> = Arc::new(Dog { - name: "Buddy".to_string(), - breed: "Labrador".to_string() -}); - -let bytes = fory.serialize(&dog_any)?; -let decoded: Arc<dyn Any + Send + Sync> = fory.deserialize(&bytes)?; -// Downcast to concrete type -let unwrapped = decoded.downcast_ref::<Dog>().unwrap(); -assert_eq!(unwrapped.name, "Buddy"); -``` +trait SharedAnimal: ForyObject + Send + Sync { + fn name(&self) -> &str; +} -`Box<dyn Any>`, `Rc<dyn Any>`, and `Arc<dyn Any + Send + Sync>` are supported -erased `Any` carriers for registered concrete non-container payloads. -Use `Arc<dyn Any + Send + Sync>` when the erased payload must be shareable -across threads; the concrete payload type must also satisfy `Send + Sync`. -Registered structs, enums, and unions that satisfy those bounds can be used as -the erased payload. +impl SharedAnimal for Dog { + fn name(&self) -> &str { + &self.name + } +} -The unsupported case is a generic container used directly as the top-level -erased payload. This applies to all erased `Any` carriers: `Box<dyn Any>`, -`Rc<dyn Any>`, and `Arc<dyn Any + Send + Sync>`. Unsupported direct payloads -include list-, map-, and set-like containers such as `Vec<T>`, `Vec<u8>`, -`HashMap<K, V>`, `HashSet<T>`, and `LinkedList<T>`. +impl SharedAnimal for Cat { + fn name(&self) -> &str { + &self.name + } +} -If you need to put a container in an erased `Any` payload, wrap it in a -registered struct, enum, or union and use that wrapper as the erased payload: - -```rust -use fory::{Fory, ForyStruct}; -use std::any::Any; -use std::sync::Arc; +register_trait_type!(sync SharedAnimal, Dog, Cat); #[derive(ForyStruct)] -struct IntList { - values: Vec<i32>, +struct SharedShelter { + featured: Arc<dyn SharedAnimal>, } - -let mut fory = Fory::builder().xlang(false).build(); -fory.register::<IntList>(100)?; - -let value: Arc<dyn Any + Send + Sync> = Arc::new(IntList { - values: vec![1, 2, 3], -}); -let bytes = fory.serialize(&value)?; -let decoded: Arc<dyn Any + Send + Sync> = fory.deserialize(&bytes)?; ``` -The wrapper makes the erased payload a concrete registered type while the -container remains a normal typed field. The same wrapper model is the supported -path for `Box<dyn Any>` and `Rc<dyn Any>`. +Every listed target in a sync declaration must implement `Send + Sync`. +Use `register_trait_type!(pub sync SharedAnimal, Dog, Cat)` when a library +exports the generated root serializers. -## Rc/Arc-Based Trait Objects in Structs +## Trait Object Roots -For fields with `Rc<dyn Trait>` or `Arc<dyn Trait>`, Fory automatically handles the conversion: +`Box<dyn Trait>` is an ordinary root: ```rust -use std::sync::Arc; -use std::rc::Rc; -use std::collections::HashMap; +let animal: Box<dyn Animal> = Box::new(Dog { + name: "Rex".to_string(), +}); -#[derive(ForyStruct)] -struct AnimalShelter { - animals_rc: Vec<Rc<dyn Animal>>, - animals_arc: Vec<Arc<dyn Animal>>, - registry: HashMap<String, Arc<dyn Animal>>, -} +let bytes = fory.serialize(&animal)?; +let decoded: Box<dyn Animal> = fory.deserialize(&bytes)?; +assert_eq!(decoded.name(), "Rex"); +``` -let mut fory = Fory::builder().xlang(false).build(); -fory.register::<Dog>(100)?; -fory.register::<Cat>(101)?; -fory.register::<AnimalShelter>(102)?; - -let shelter = AnimalShelter { - animals_rc: vec![ - Rc::new(Dog { name: "Rex".to_string(), breed: "Golden".to_string() }), - Rc::new(Cat { name: "Mittens".to_string(), color: "Gray".to_string() }), - ], - animals_arc: vec![ - Arc::new(Dog { name: "Buddy".to_string(), breed: "Labrador".to_string() }), - ], - registry: HashMap::from([ - ("pet1".to_string(), Arc::new(Dog { - name: "Max".to_string(), - breed: "Shepherd".to_string() - }) as Arc<dyn Animal>), - ]), -}; +Rust's orphan rules prevent an ordinary serializer implementation directly on +`Rc<dyn Trait>` and `Arc<dyn Trait>`. The macro generates serializer types for +those roots: -let bytes = fory.serialize(&shelter)?; -let decoded: AnimalShelter = fory.deserialize(&bytes)?; +```rust +let animal: Rc<dyn Animal> = Rc::new(Dog { + name: "Milo".to_string(), +}); -assert_eq!(decoded.animals_rc[0].name(), "Rex"); -assert_eq!(decoded.animals_arc[0].speak(), "Woof!"); +let bytes = + fory.serialize_with::<AnimalRcSerializer>(&animal)?; +let decoded = + fory.deserialize_with::<AnimalRcSerializer>(&bytes)?; +assert_eq!(decoded.name(), "Milo"); ``` -## Standalone Trait Object Serialization +```rust +let animal: Arc<dyn SharedAnimal> = Arc::new(Dog { + name: "Luna".to_string(), +}); + +let bytes = + fory.serialize_with::<SharedAnimalArcSerializer>(&animal)?; +let decoded = + fory.deserialize_with::<SharedAnimalArcSerializer>(&bytes)?; +assert_eq!(decoded.name(), "Luna"); +``` + +These APIs serialize the original `Rc` or `Arc`; there is no conversion wrapper. +The generated serializer types are not registered by ID or name. + +## Dynamic `Any` -Due to Rust's orphan rule, `Rc<dyn Trait>` and `Arc<dyn Trait>` cannot implement `Serializer` directly. For standalone serialization (not inside struct fields), the `register_trait_type!` macro generates wrapper types. +Fory supports: -**Note:** If you don't want to use wrapper types for concrete non-container payloads, you can serialize as `Box<dyn Any>`, `Rc<dyn Any>`, or `Arc<dyn Any + Send + Sync>` instead (see the dyn Any section above). +- `Box<dyn Any>`; +- `Rc<dyn Any>`; +- `Arc<dyn Any + Send + Sync>`. -The `register_trait_type!` macro generates `AnimalRc` and `AnimalArc` wrapper types: +The concrete target must be registered: ```rust -// For Rc<dyn Trait> -let dog_rc: Rc<dyn Animal> = Rc::new(Dog { +use std::any::Any; + +let value: Rc<dyn Any> = Rc::new(Dog { name: "Rex".to_string(), - breed: "Golden".to_string() }); -let wrapper = AnimalRc::from(dog_rc); -let bytes = fory.serialize(&wrapper)?; -let decoded: AnimalRc = fory.deserialize(&bytes)?; +let bytes = fory.serialize(&value)?; +let decoded: Rc<dyn Any> = fory.deserialize(&bytes)?; +let dog = decoded.downcast_ref::<Dog>().unwrap(); +assert_eq!(dog.name, "Rex"); +``` -// Unwrap back to Rc<dyn Animal> -let unwrapped: Rc<dyn Animal> = decoded.unwrap(); -assert_eq!(unwrapped.name(), "Rex"); +Use `Arc<dyn Any + Send + Sync>` when the erased value must be shared across +threads: -// For Arc<dyn Trait> -let dog_arc: Arc<dyn Animal> = Arc::new(Dog { +```rust +let value: Arc<dyn Any + Send + Sync> = Arc::new(Dog { name: "Buddy".to_string(), - breed: "Labrador".to_string() }); -let wrapper = AnimalArc::from(dog_arc); -let bytes = fory.serialize(&wrapper)?; -let decoded: AnimalArc = fory.deserialize(&bytes)?; - -let unwrapped: Arc<dyn Animal> = decoded.unwrap(); -assert_eq!(unwrapped.name(), "Buddy"); +let bytes = fory.serialize(&value)?; +let decoded: Arc<dyn Any + Send + Sync> = + fory.deserialize(&bytes)?; +let dog = decoded.downcast_ref::<Dog>().unwrap(); +assert_eq!(dog.name, "Buddy"); ``` -## Best Practices +Derived serializers support synchronized `Arc` materialization when their +targets satisfy `Send + Sync`. A manual serializer that needs this path +implements `read_arc_any`. -1. **Use `register_trait_type!`** to register all trait implementations -2. **Keep compatible mode enabled** for trait objects -3. **Register all concrete types** before serialization -4. **Prefer dyn Any** for simpler standalone serialization +Generic LIST, SET, and MAP identities do not identify one exact Rust generic +target behind `Any`. Put such a container in a registered struct, or register an +exact whole-container manual serializer when an opaque EXT representation is +intentional. ## Related Topics -- [References](references.md) - Rc/Arc shared references -- [Schema Evolution](schema-evolution.md) - Compatible mode -- [Type Registration](type-registration.md) - Registering types +- [External-Type Serialization](external-types.md) +- [References](references.md) +- [Type Registration](type-registration.md) diff --git a/docs/guide/rust/schema-evolution.md b/docs/guide/rust/schema-evolution.md index 199e684ade..f48f58782a 100644 --- a/docs/guide/rust/schema-evolution.md +++ b/docs/guide/rust/schema-evolution.md @@ -117,6 +117,32 @@ struct SameSchemaMessage { } ``` +## External Types + +An external structural serializer is the local schema for its target. Compatible +mode matches its declared fields and variants exactly as it does for an +equivalent locally derived type: + +```rust +#[derive(ForyStruct)] +#[fory(target = third_party::User)] +struct UserSerializer { + name: String, + age: u32, +} + +let mut fory = Fory::builder().xlang(false).compatible(true).build(); +fory.register::<UserSerializer>(100)?; + +let decoded: third_party::User = + fory.deserialize_with::<UserSerializer>(&bytes)?; +``` + +Peers must use the same numeric ID or registered name for the logical type. +Adding or removing fields follows the normal compatible-mode rules. A manual +serializer owns an opaque EXT body instead, so its implementation must define +any versioning inside that body. + ## Enum Support Apache Foryβ’ supports three types of enum variants with full schema evolution in Compatible mode: @@ -157,8 +183,9 @@ locally before deserializing unknown cases you need to preserve. `UnknownCase` stores its payload as `Arc<dyn Any + Send + Sync>`, so preserved payload types must satisfy `Send + Sync`. Direct generic containers are not -supported as erased `Any` payloads; wrap the container in a registered derived -type if an unknown case needs to preserve it. +supported as erased `Any` payloads by their structural carrier registration. +Wrap the container in a registered derived type, or register an exact-target +manual serializer when an opaque EXT/NAMED_EXT body is intentional. ### Enum Schema Evolution @@ -187,13 +214,17 @@ enum NewEvent { KeyPress(String), // New variant } -let mut fory = Fory::builder().xlang(false).build(); +let mut writer = Fory::builder().xlang(false).build(); +writer.register::<OldEvent>(100)?; + +let mut reader = Fory::builder().xlang(false).build(); +reader.register::<NewEvent>(100)?; // Serialize with old schema -let old_bytes = fory.serialize(&OldEvent::Click { x: 100, y: 200 })?; +let old_bytes = writer.serialize(&OldEvent::Click { x: 100, y: 200 })?; // Deserialize with new schema - timestamp gets default value (0) -let new_event: NewEvent = fory.deserialize(&old_bytes)?; +let new_event: NewEvent = reader.deserialize(&old_bytes)?; assert!(matches!(new_event, NewEvent::Click { x: 100, y: 200, timestamp: 0 })); ``` @@ -248,3 +279,4 @@ assert_eq!(data, decoded); - [Configuration](configuration.md) - Compatible mode settings - [Polymorphism](polymorphism.md) - Trait objects with schema evolution - [Xlang Serialization](xlang-serialization.md) - Schema evolution across languages +- [External-Type Serialization](external-types.md) - Compatible schemas for third-party values diff --git a/docs/guide/rust/schema-metadata.md b/docs/guide/rust/schema-metadata.md index 4aa3a892cf..1b81d3717b 100644 --- a/docs/guide/rust/schema-metadata.md +++ b/docs/guide/rust/schema-metadata.md @@ -221,9 +221,50 @@ struct Data { } ``` +An unannotated `Vec<i32>` field is `list<int32>` with the default varint +element encoding. The `fixed_values` field above remains a LIST and changes only +its element encoding to fixed-width `int32`. Use `#[fory(array)]` when the field +schema itself is a dense primitive array, or `#[fory(bytes)]` for binary +`Vec<u8>`. + `compress` has been removed. Use `encoding = varint` or `encoding = fixed` directly. +### External-Type Field Selection + +Use `with` to select a serializer whose target is the exact field type. The +serializer can be external structural, manual, or a carrier composition: + +```rust +use fory::{ForyStruct, VecSerializer}; +use std::collections::HashMap; + +#[derive(ForyStruct)] +struct Envelope { + #[fory(with = UserSerializer)] + user: third_party::User, + + #[fory(with = VecSerializer<UserSerializer>)] + direct_users: Vec<third_party::User>, + + #[fory(list(element(with = UserSerializer)))] + users: Vec<third_party::User>, + + #[fory(map(value(with = UserSerializer)))] + by_name: HashMap<String, third_party::User>, + + #[fory(tuple(element(index = 1, with = UserSerializer)))] + selected: (String, third_party::User), +} +``` + +`with` selects a serializer whose target is the exact field node, so +`direct_users` uses a carrier serializer for the whole Vec. Each recursive +annotation applies only at its child node. For example, a map key and value can +select different serializers. Tuple indices are zero-based. See +[External-Type Serialization](external-types.md) for the complete recursive +grammar and supported carriers. + ## Type Classification Fory classifies field types to determine default behavior: @@ -449,11 +490,14 @@ struct User { | `nullable` | `nullable` or `nullable = bool` | Control null flag writing | All fields | | `ref` | `ref` or `ref = bool` | Control reference tracking | `Rc`, `Arc`, weak types | | `encoding` | `encoding = varint/fixed/tagged` | Integer encoding method | `i32`, `u32`, `i64`, `u64` | -| `list` | `list(element(...))` | Element schema metadata | `Vec<T>` | -| `map` | `map(key(...), value(...))` | Key/value schema metadata | `HashMap<K, V>` | +| `list` | `list(element(...))` | Element schema metadata | Lists, sets, arrays | +| `map` | `map(key(...), value(...))` | Key/value schema metadata | `HashMap`, `BTreeMap` | +| `tuple` | `tuple(element(index = N, ...))` | Tuple-position schema metadata | Tuples | +| `with` | `with = Serializer` | Select a field serializer | External target nodes | ## Related Topics - [Basic Serialization](basic-serialization.md) - Getting started with Fory serialization - [Schema Evolution](schema-evolution.md) - Compatible mode and schema evolution - [Xlang Serialization](xlang-serialization.md) - Interoperability with Java, C++, Go, Python +- [External-Type Serialization](external-types.md) - Selecting serializers for third-party fields diff --git a/docs/guide/rust/troubleshooting.md b/docs/guide/rust/troubleshooting.md index 6f25c1f927..75a55d9667 100644 --- a/docs/guide/rust/troubleshooting.md +++ b/docs/guide/rust/troubleshooting.md @@ -38,8 +38,20 @@ fory.register::<MyStruct>(100)?; // Register before use Confirm that: -- Every serializable struct or trait implementation calls `fory.register::<T>(type_id)` -- The same IDs are reused on the deserialize side +- Every concrete dynamic target is registered through the matching structural, + union, or manual serializer API. +- The same ID or name mapping is reused on the deserialize side. + +For external-type serialization, register the selected external structural or +manual serializer, not its third-party target: + +```rust +fory.register::<UserSerializer>(100)?; +``` + +Do not register `VecSerializer<UserSerializer>` or another carrier serializer. +Register `UserSerializer`, then use recursive `list`, `map`, or `tuple` +annotations at fields, or select the carrier serializer at a root. ### Type Mismatch Errors @@ -57,6 +69,45 @@ let fory = Fory::builder() .build(); ``` +### External-Type Serialization Selection Errors + +If derive reports that `with` targets the wrong type, verify that the selected +serializer declares the exact field target: + +```rust +impl Serializer for UserSerializer { + type Target = third_party::User; + // ... +} +``` + +For a transparent holder, select the carrier serializer whose target is the +exact field type: + +```rust +#[fory(with = OptionSerializer<UserSerializer>)] +user: Option<third_party::User> +``` + +For an exact container field, a carrier serializer is also valid: + +```rust +#[fory(with = VecSerializer<UserSerializer>)] +users: Vec<third_party::User> +``` + +Use recursive collection syntax when selecting an element, map child, or tuple +position: + +```rust +#[fory(list(element(with = UserSerializer)))] +users: Vec<third_party::User> +``` + +If registration fails only in xlang mode, check whether the external structural +serializer contains a native Rust enum variant with multiple fields. That shape +has no xlang UNION representation; use native mode or change the shared schema. + ## Debugging Techniques ### Enable Panic on Error for Backtraces @@ -165,3 +216,4 @@ This keeps diagnostics consistent and makes opt-in panics work correctly. - [Configuration](configuration.md) - Fory options - [Type Registration](type-registration.md) - Registration best practices - [Schema Evolution](schema-evolution.md) - Compatible mode +- [External-Type Serialization](external-types.md) - Field and root serializer selection diff --git a/docs/guide/rust/type-registration.md b/docs/guide/rust/type-registration.md index d2830b99f0..0bb260ea4c 100644 --- a/docs/guide/rust/type-registration.md +++ b/docs/guide/rust/type-registration.md @@ -59,15 +59,30 @@ let mut fory = Fory::builder().xlang(true).build(); fory.register_by_name::<MyStruct>("com.example.MyStruct")?; ``` -## Register Custom Serializer +## Register a Manual Serializer -For types that need custom serialization logic: +For types that need customized serialization logic, register the manual +serializer: ```rust let mut fory = Fory::builder().xlang(false).build(); -fory.register_serializer::<CustomType>(100)?; +fory.register_serializer::<UuidSerializer>(100)?; ``` +An external structural serializer uses the ordinary structural registration +API: + +```rust +fory.register::<UserSerializer>(101)?; +``` + +The serializer's `Target` is the runtime value type. Registration does not +require a separate external-type API. At fields, `with` can select an exact +carrier serializer such as `VecSerializer<UserSerializer>`, while recursive +`list`, `map`, or `tuple` annotations select serializers at child nodes. At +roots, compose the same carrier serializers. Carrier serializers are not +registered. + ## Registration Consistency Rust registration APIs use explicit IDs or explicit names. Keep the same registration mapping on serializer and deserializer peers: @@ -122,4 +137,5 @@ let handles: Vec<_> = (0..4) - [Configuration](configuration.md) - Fory builder options - [Xlang Serialization](xlang-serialization.md) - xlang mode registration -- [Custom Serializers](custom-serializers.md) - Custom serialization +- [Manual Serializers](manual-serializers.md) - Customized serialization +- [External-Type Serialization](external-types.md) - Third-party targets and carrier roots diff --git a/docs/guide/rust/xlang-serialization.md b/docs/guide/rust/xlang-serialization.md index 0f83e18224..b9e6664932 100644 --- a/docs/guide/rust/xlang-serialization.md +++ b/docs/guide/rust/xlang-serialization.md @@ -35,8 +35,8 @@ let mut fory = Fory::builder().xlang(true).build(); // Register types with consistent IDs across languages fory.register::<MyStruct>(100)?; -// Or use name-based registration -fory.register_by_name::<MyStruct>("com.example.MyStruct")?; +// Or, on a different Fory instance, use name-based registration +// fory.register_by_name::<MyStruct>("com.example.MyStruct")?; ``` ## Type Registration for Xlang @@ -86,6 +86,48 @@ let bytes = fory.serialize(&person)?; // bytes can be deserialized by Java, Python, etc. ``` +### Third-Party Rust Types + +An external structural serializer gives a third-party Rust type the same xlang +schema as an equivalent local derive: + +```rust +#[derive(ForyStruct)] +#[fory(target = third_party::User)] +struct UserSerializer { + name: String, + age: u32, +} + +let mut fory = Fory::builder().xlang(true).build(); +fory.register::<UserSerializer>(100)?; + +let bytes = fory.serialize_with::<UserSerializer>(&user)?; +``` + +Container roots compose with carrier serializers and keep the ordinary xlang +LIST, MAP, tuple, or array representation: + +```rust +use fory::VecSerializer; + +let bytes = + fory.serialize_with::<VecSerializer<UserSerializer>>(&users)?; +``` + +Only xlang-representable schemas are accepted. A native Rust enum variant with +multiple tuple or named fields is supported with `xlang(false)`, but its +serializer registration is rejected in xlang mode. See +[External-Type Serialization](external-types.md). + +### Dynamic Rust Carriers + +`Box<dyn Any>`, `Rc<dyn Any>`, `Arc<dyn Any + Send + Sync>`, and application +`dyn Trait` carriers can be used in xlang mode when every selected concrete +target has an xlang-compatible structural or EXT identity. Fory writes the +concrete registered target identity; the Rust trait or erased-carrier identity +does not appear on the wire. + ### Java (Deserializer) ```java @@ -188,3 +230,4 @@ explicit array field attribute when the schema is dense `array<T>`. - [Configuration](configuration.md) - xlang mode configuration - [Schema Evolution](schema-evolution.md) - Compatible mode - [Type Registration](type-registration.md) - Registration methods +- [External-Type Serialization](external-types.md) - Third-party values in xlang mode --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
