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 c4d060693864a77919ef0ae6f598cfb89c830cd1 Author: chaokunyang <[email protected]> AuthorDate: Sun Aug 2 17:06:26 2026 +0000 🔄 synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/csharp/basic-serialization.md | 10 ---------- docs/guide/dart/type-registration.md | 6 +++++- docs/guide/python/configuration.md | 2 +- docs/guide/python/schema-evolution.md | 19 +++++++++++++++++++ docs/guide/python/type-registration.md | 13 ++++++++++--- docs/guide/swift/configuration.md | 9 +++++++-- 6 files changed, 42 insertions(+), 17 deletions(-) diff --git a/docs/guide/csharp/basic-serialization.md b/docs/guide/csharp/basic-serialization.md index b6bf5a7cbb..0a96e8a754 100644 --- a/docs/guide/csharp/basic-serialization.md +++ b/docs/guide/csharp/basic-serialization.md @@ -117,16 +117,6 @@ ReadOnlySpan<byte> span = payload; MyType decoded = fory.Deserialize<MyType>(span); ``` -### Stream-style frame consumption - -```csharp -using System.Buffers; - -ReadOnlySequence<byte> sequence = GetFramedSequence(); -MyType first = fory.Deserialize<MyType>(ref sequence); -MyType second = fory.Deserialize<MyType>(ref sequence); -``` - ## Dynamic Payloads via Generic Object API When the compile-time type is unknown or heterogeneous, use the generic API with `object?`. diff --git a/docs/guide/dart/type-registration.md b/docs/guide/dart/type-registration.md index 743c0ec2e0..62df4a820a 100644 --- a/docs/guide/dart/type-registration.md +++ b/docs/guide/dart/type-registration.md @@ -106,7 +106,11 @@ See [Custom Serializers](custom-serializers.md) for how to implement a serialize ## Rules to Follow -- Register **before** the first `serialize` or `deserialize` call. +- Register **before** the first `serialize`, `serializeTo`, `serializeBuiltin`, + `serializeBuiltinTo`, `deserialize`, or `deserializeFrom` call. That first + root operation permanently closes registration for the `Fory` instance, even + if the operation fails; create a new instance when a different registry is + required. - Register **every** class that can appear in a message, not only the root type. - Do not register generated private-field access companions; register only concrete serialized types. diff --git a/docs/guide/python/configuration.md b/docs/guide/python/configuration.md index e150f34a5a..2714bf509a 100644 --- a/docs/guide/python/configuration.md +++ b/docs/guide/python/configuration.md @@ -64,7 +64,7 @@ class ThreadSafeFory: | -------------------------------------- | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `xlang` | `bool` | `True` | Use xlang mode. Set `False` for Python native mode. | | `ref` | `bool` | `False` | Enable reference tracking for shared/circular references. Disable for better performance if your data has no shared references. | -| `strict` | `bool` | `True` | Require type registration for security. Keep this enabled for production unless a policy owns trust decisions. | +| `strict` | `bool` | `True` | Require registration before loading application classes. Compatible unknown Structs use the data-only `UnknownStruct` carrier. | | `compatible` | `bool \| None` | `None` | Schema evolution mode. `None` enables compatible mode in both xlang and native mode. Set `False` only when every reader and writer uses the same schema. | | `max_depth` | `int` | `50` | Maximum deserialization depth for security, preventing stack overflow attacks. | | `max_type_fields` | `int` | `512` | Maximum fields accepted in one received remote struct metadata body. | diff --git a/docs/guide/python/schema-evolution.md b/docs/guide/python/schema-evolution.md index a66562b3e7..827e1477a4 100644 --- a/docs/guide/python/schema-evolution.md +++ b/docs/guide/python/schema-evolution.md @@ -88,6 +88,25 @@ print(user.email) # "[email protected]" - **Remove fields**: Old data with extra fields will be skipped - **Reorder fields**: Fields are matched by name, not position +## Unknown Remote Structs + +When compatible metadata describes a Struct that has no local registration, +Python returns `pyfory.UnknownStruct`. This fixed data-only carrier exposes the +remote fields through mapping-style access and can be serialized again with its +original schema: + +```python +value = reader.deserialize(data) +assert isinstance(value, pyfory.UnknownStruct) +print(value["name"]) + +forwarded = reader.serialize(value) +``` + +This behavior also applies with `strict=True`: Fory does not import, generate, +or instantiate the sender-named Python class. Register the matching class on a +reader that should materialize the application type instead. + ## Same-Schema Class Optimization Use `compatible=False` only when the class schema used to deserialize every payload is always the same diff --git a/docs/guide/python/type-registration.md b/docs/guide/python/type-registration.md index 9e5589595b..627a3ea3ff 100644 --- a/docs/guide/python/type-registration.md +++ b/docs/guide/python/type-registration.md @@ -74,9 +74,16 @@ for model_class in [User, Order, Product, Invoice]: ## Strict Mode Relationship -With `strict=True`, deserialization accepts only registered types. Register all -application classes before serializing or deserializing payloads, and keep the -same registration IDs or names on every peer that shares those payloads. +With `strict=True`, Fory loads and instantiates only registered application +classes. Register application classes before serializing or deserializing +payloads, and keep the same registration IDs or names on every peer that shares +those payloads. + +Compatible metadata has one data-only exception: when a remote Struct has no +local registration, deserialization returns the fixed framework +`pyfory.UnknownStruct` value instead of loading or generating the sender's +class. Register the class locally when the application requires a concrete +application object. ## Related Topics diff --git a/docs/guide/swift/configuration.md b/docs/guide/swift/configuration.md index 44c56ed822..3dd20dd9ec 100644 --- a/docs/guide/swift/configuration.md +++ b/docs/guide/swift/configuration.md @@ -91,7 +91,12 @@ let fory = Fory(compatible: false, checkClassVersion: true) ### Size and Depth Limits -`maxDepth` bounds decoded payload nesting depth. +`maxDepth` limits how deeply deserialization may materialize values whose concrete types are +selected dynamically through `Any`. Statically declared arrays, dictionaries, structs, classes, +and unions do not consume this limit. + +TypeMeta generic metadata has a fixed maximum nesting depth of `20`. Writers reject metadata above +this limit, and readers apply the same limit. `maxGraphMemoryBytes` sets an approximate graph-memory gate for one root deserialization. The estimate mainly covers materialized arrays, dictionaries, sets, structs, classes, and objects. It @@ -150,7 +155,7 @@ Security-related configuration: - Register only the expected generated models before deserializing untrusted payloads. - Use `checkClassVersion` with `compatible: false` for intentional same-schema payloads. -- Set `maxDepth` for the largest nesting depth your service accepts. +- Set `maxDepth` for the largest dynamic `Any` nesting depth your service accepts. - Set `maxGraphMemoryBytes` as an approximate gate for collection, map, array, struct, class, and object-heavy payloads. It is not an exact heap cap; leaf values are gated by remaining input bytes. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
