You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fory.apache.org by ch...@apache.org on 2026/09/22 01:01:27 UTC
(fory-site) branch main updated (3cc9b7f3bb1 -> 8931d1a9563)
This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a change to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
from 3cc9b7f3bb1 🔄 synced local 'docs/json/' with remote 'docs/json/'
new c14d9dfce64 🔄 synced local 'docs/object-serialization/' with remote 'docs/object-serialization/'
new 8931d1a9563 🔄 synced local 'docs/specification/' with remote 'docs/specification/'
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
docs/object-serialization/cpp/configuration.md | 35 ++++++++++++----------
docs/object-serialization/cpp/security.md | 4 +--
docs/object-serialization/csharp/configuration.md | 33 +++++++++++---------
docs/object-serialization/csharp/security.md | 4 +--
docs/object-serialization/dart/configuration.md | 11 +++++--
docs/object-serialization/dart/security.md | 4 +--
docs/object-serialization/go/configuration.md | 33 +++++++++++---------
docs/object-serialization/go/security.md | 4 +--
docs/object-serialization/java/configuration.md | 9 ++++--
docs/object-serialization/java/security.md | 3 +-
.../javascript/configuration.md | 9 ++++--
docs/object-serialization/javascript/security.md | 4 +--
docs/object-serialization/python/configuration.md | 9 ++++--
docs/object-serialization/python/security.md | 5 ++--
docs/object-serialization/rust/configuration.md | 33 +++++++++++---------
docs/object-serialization/rust/security.md | 4 +--
docs/object-serialization/swift/configuration.md | 9 ++++--
docs/object-serialization/swift/security.md | 4 +--
docs/specification/xlang_implementation_guide.md | 14 ++++++---
19 files changed, 142 insertions(+), 89 deletions(-)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 01/02: 🔄 synced local 'docs/object-serialization/' with remote 'docs/object-serialization/'
Posted by ch...@apache.org.
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 c14d9dfce646b73364002dd87257b94d7d0fac9a
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Tue Sep 22 01:01:22 2026 +0000
🔄 synced local 'docs/object-serialization/' with remote 'docs/object-serialization/'
---
docs/object-serialization/cpp/configuration.md | 35 ++++++++++++----------
docs/object-serialization/cpp/security.md | 4 +--
docs/object-serialization/csharp/configuration.md | 33 +++++++++++---------
docs/object-serialization/csharp/security.md | 4 +--
docs/object-serialization/dart/configuration.md | 11 +++++--
docs/object-serialization/dart/security.md | 4 +--
docs/object-serialization/go/configuration.md | 33 +++++++++++---------
docs/object-serialization/go/security.md | 4 +--
docs/object-serialization/java/configuration.md | 9 ++++--
docs/object-serialization/java/security.md | 3 +-
.../javascript/configuration.md | 9 ++++--
docs/object-serialization/javascript/security.md | 4 +--
docs/object-serialization/python/configuration.md | 9 ++++--
docs/object-serialization/python/security.md | 5 ++--
docs/object-serialization/rust/configuration.md | 33 +++++++++++---------
docs/object-serialization/rust/security.md | 4 +--
docs/object-serialization/swift/configuration.md | 9 ++++--
docs/object-serialization/swift/security.md | 4 +--
18 files changed, 132 insertions(+), 85 deletions(-)
diff --git a/docs/object-serialization/cpp/configuration.md b/docs/object-serialization/cpp/configuration.md
index 42d066000cf..8a4040b9df7 100644
--- a/docs/object-serialization/cpp/configuration.md
+++ b/docs/object-serialization/cpp/configuration.md
@@ -153,7 +153,7 @@ This limits the maximum depth for nested polymorphic object serialization (e.g.,
### max_schema_versions_per_type(uint32_t)
-Set the maximum accepted remote metadata versions for one logical type.
+Set the maximum cached remote metadata versions for one logical type.
```cpp
auto fory = Fory::builder()
@@ -163,6 +163,11 @@ auto fory = Fory::builder()
**Default:** `10`
+Schema-version limits bound cached metadata only. When a schema-version or
+logical-type cache limit is reached, valid data still deserializes after full
+metadata validation, without caching the new schema. Repeated reads of an
+uncached schema may cost more; existing cached schemas remain reusable.
+
### max_type_fields(uint32_t)
Set the maximum fields accepted in one received remote struct metadata body.
@@ -190,7 +195,7 @@ auto fory = Fory::builder()
### max_average_schema_versions_per_type(uint32_t)
-Set the average accepted remote metadata versions across accepted remote types.
+Set the average cached remote metadata versions across cached remote types.
The effective global floor is `8192` schemas.
```cpp
@@ -236,19 +241,19 @@ auto fory = Fory::builder().build_thread_safe(); // Returns ThreadSafeFory
## Configuration Summary
-| Option | Description | Default |
-| ------------------------------------------------ | ------------------------------------------------- | --------- |
-| `xlang(bool)` | Use xlang mode | `true` |
-| `compatible(bool)` | Enable schema evolution | `true` |
-| `track_ref(bool)` | Enable reference tracking | `true` |
-| `max_graph_memory_bytes(int64_t)` | Approximate graph-memory gate per root read | `128 MiB` |
-| `max_unbacked_container_items(int64_t)` | Unbacked collection/map work per root read | `8192` |
-| `max_dyn_depth(uint32_t)` | Maximum nesting depth for dynamic types | `5` |
-| `max_type_fields(uint32_t)` | Max fields in one received struct metadata body | `512` |
-| `max_type_meta_bytes(uint32_t)` | Max encoded bytes in one received metadata body | `4096` |
-| `max_schema_versions_per_type(uint32_t)` | Max remote metadata versions for one logical type | `10` |
-| `max_average_schema_versions_per_type(uint32_t)` | Average remote metadata versions across types | `3` |
-| `check_struct_version(bool)` | Enable struct version checking | `false` |
+| Option | Description | Default |
+| ------------------------------------------------ | -------------------------------------------------------- | --------- |
+| `xlang(bool)` | Use xlang mode | `true` |
+| `compatible(bool)` | Enable schema evolution | `true` |
+| `track_ref(bool)` | Enable reference tracking | `true` |
+| `max_graph_memory_bytes(int64_t)` | Approximate graph-memory gate per root read | `128 MiB` |
+| `max_unbacked_container_items(int64_t)` | Unbacked collection/map work per root read | `8192` |
+| `max_dyn_depth(uint32_t)` | Maximum nesting depth for dynamic types | `5` |
+| `max_type_fields(uint32_t)` | Max fields in one received struct metadata body | `512` |
+| `max_type_meta_bytes(uint32_t)` | Max encoded bytes in one received metadata body | `4096` |
+| `max_schema_versions_per_type(uint32_t)` | Max cached remote metadata versions for one logical type | `10` |
+| `max_average_schema_versions_per_type(uint32_t)` | Average cached remote metadata versions across types | `3` |
+| `check_struct_version(bool)` | Enable struct version checking | `false` |
## Security
diff --git a/docs/object-serialization/cpp/security.md b/docs/object-serialization/cpp/security.md
index 860505ee983..684d229e173 100644
--- a/docs/object-serialization/cpp/security.md
+++ b/docs/object-serialization/cpp/security.md
@@ -43,8 +43,8 @@ Security-related configuration:
positive value for a trusted workload that needs a different collection/map/struct gate.
- Keep `max_dyn_depth(...)` as low as your model permits to reject unexpectedly deep polymorphic
graphs.
-- Keep the remote schema metadata limits at their defaults unless the data is not malicious and a
- trusted peer sends larger metadata or many schema versions.
+- Keep remote metadata size limits at their defaults unless a trusted peer needs larger metadata.
+ Schema-version limits bound caching; additional valid schemas are decoded without caching.
- Prefer concrete fields over broad polymorphic fields for untrusted input.
## Verification
diff --git a/docs/object-serialization/csharp/configuration.md b/docs/object-serialization/csharp/configuration.md
index 7ac807affcf..753caff49cf 100644
--- a/docs/object-serialization/csharp/configuration.md
+++ b/docs/object-serialization/csharp/configuration.md
@@ -35,18 +35,18 @@ ThreadSafeFory threadSafe = Fory.Builder().BuildThreadSafe();
`Fory.Builder().Build()` uses:
-| Option | Default | Description |
-| --------------------------------- | ----------- | ------------------------------------------------- |
-| `TrackRef` | `false` | Reference tracking disabled |
-| `Compatible` | `true` | Compatible schema-evolution metadata enabled |
-| `CheckStructVersion` | `false` | Struct schema hash checks disabled |
-| `MaxDepth` | `20` | Max dynamic nesting depth |
-| `MaxGraphMemoryBytes` | `134217728` | Approximate graph-memory gate per root read |
-| `MaxUnbackedContainerItems` | `8192` | Unbacked collection/map work per root read |
-| `MaxTypeFields` | `512` | Max fields in one received struct metadata body |
-| `MaxTypeMetaBytes` | `4096` | Max encoded bytes in one received metadata body |
-| `MaxSchemaVersionsPerType` | `10` | Max remote metadata versions for one logical type |
-| `MaxAverageSchemaVersionsPerType` | `3` | Average remote metadata versions across types |
+| Option | Default | Description |
+| --------------------------------- | ----------- | -------------------------------------------------------- |
+| `TrackRef` | `false` | Reference tracking disabled |
+| `Compatible` | `true` | Compatible schema-evolution metadata enabled |
+| `CheckStructVersion` | `false` | Struct schema hash checks disabled |
+| `MaxDepth` | `20` | Max dynamic nesting depth |
+| `MaxGraphMemoryBytes` | `134217728` | Approximate graph-memory gate per root read |
+| `MaxUnbackedContainerItems` | `8192` | Unbacked collection/map work per root read |
+| `MaxTypeFields` | `512` | Max fields in one received struct metadata body |
+| `MaxTypeMetaBytes` | `4096` | Max encoded bytes in one received metadata body |
+| `MaxSchemaVersionsPerType` | `10` | Max cached remote metadata versions for one logical type |
+| `MaxAverageSchemaVersionsPerType` | `3` | Average cached remote metadata versions across types |
## Builder Options
@@ -151,7 +151,7 @@ Fory fory = Fory.Builder()
### `MaxSchemaVersionsPerType(int value)`
-Sets the maximum accepted remote metadata versions for one logical type.
+Sets the maximum cached remote metadata versions for one logical type.
```csharp
Fory fory = Fory.Builder()
@@ -159,9 +159,14 @@ Fory fory = Fory.Builder()
.Build();
```
+Schema-version limits bound cached metadata only. When a schema-version or
+logical-type cache limit is reached, valid data still deserializes after full
+metadata validation, without caching the new schema. Repeated reads of an
+uncached schema may cost more; existing cached schemas remain reusable.
+
### `MaxAverageSchemaVersionsPerType(int value)`
-Sets the average accepted remote metadata versions across accepted remote types.
+Sets the average cached remote metadata versions across cached remote types.
The effective global floor is `8192` schemas.
```csharp
diff --git a/docs/object-serialization/csharp/security.md b/docs/object-serialization/csharp/security.md
index 58c33374be8..3f6dbe7a0e2 100644
--- a/docs/object-serialization/csharp/security.md
+++ b/docs/object-serialization/csharp/security.md
@@ -42,8 +42,8 @@ Security-related configuration:
- Set `MaxDepth(...)` to reject unexpectedly deep dynamic object graphs.
- Set `MaxGraphMemoryBytes(...)` as an approximate gate for collection, map, array, struct, and
object-heavy payloads. It is not an exact heap cap; leaf values are gated by remaining input bytes.
-- Keep the remote schema metadata limits at their defaults unless the data is not malicious and a
- trusted peer sends larger metadata or many schema versions.
+- Keep remote metadata size limits at their defaults unless a trusted peer needs larger metadata.
+ Schema-version limits bound caching; additional valid schemas are decoded without caching.
- Prefer generated or registered concrete models over broad dynamic fields for untrusted input.
## Verification
diff --git a/docs/object-serialization/dart/configuration.md b/docs/object-serialization/dart/configuration.md
index e3108436516..1051712c068 100644
--- a/docs/object-serialization/dart/configuration.md
+++ b/docs/object-serialization/dart/configuration.md
@@ -91,7 +91,7 @@ final fory = Fory(maxDepth: 128);
### Remote schema metadata limits
Compatible mode can receive remote metadata for schema evolution. These limits
-bound metadata size and accepted schema versions:
+bound metadata size and cached schema versions:
```dart
final fory = Fory(
@@ -105,10 +105,15 @@ final fory = Fory(
- `maxTypeFields` limits fields in one received struct metadata body.
- `maxTypeMetaBytes` limits encoded body bytes in one received TypeMeta body, excluding the 8-byte
header and any extended-size varint.
-- `maxSchemaVersionsPerType` limits accepted remote metadata versions for one logical type.
-- `maxAverageSchemaVersionsPerType` limits the average across accepted remote types. The
+- `maxSchemaVersionsPerType` limits cached remote metadata versions for one logical type.
+- `maxAverageSchemaVersionsPerType` limits the average across cached remote types. The
effective global floor is `8192` schemas.
+Schema-version limits bound cached metadata only. When a schema-version or
+logical-type cache limit is reached, valid data still deserializes after full
+metadata validation, without caching the new schema. Repeated reads of an
+uncached schema may cost more; existing cached schemas remain reusable.
+
### `maxGraphMemoryBytes`
Sets an approximate graph-memory gate for one root deserialization. The estimate mainly covers
diff --git a/docs/object-serialization/dart/security.md b/docs/object-serialization/dart/security.md
index a3f5d4ca85e..0e6831caf5d 100644
--- a/docs/object-serialization/dart/security.md
+++ b/docs/object-serialization/dart/security.md
@@ -42,8 +42,8 @@ Security-related configuration:
- Set `maxDepth` to reject unexpectedly deep payload shapes.
- Keep `maxGraphMemoryBytes` at the default for most inputs, or set an explicit positive byte gate
for known trusted collection/map/struct-heavy payloads.
-- Keep the remote schema metadata limits at their defaults unless the data is not malicious and a
- trusted peer sends larger metadata or many schema versions.
+- Keep remote metadata size limits at their defaults unless a trusted peer needs larger metadata.
+ Schema-version limits bound caching; additional valid schemas are decoded without caching.
- Prefer generated schemas and explicit field metadata over broad dynamic fields for untrusted input.
## Verification
diff --git a/docs/object-serialization/go/configuration.md b/docs/object-serialization/go/configuration.md
index 50850328dd6..456ec7bb2da 100644
--- a/docs/object-serialization/go/configuration.md
+++ b/docs/object-serialization/go/configuration.md
@@ -33,18 +33,18 @@ f := fory.New(fory.WithXlang(true))
Default settings:
-| Option | Default | Description |
-| ------------------------------- | --------- | ------------------------------------------------- |
-| TrackRef | false | Reference tracking disabled |
-| MaxDepth | 20 | Maximum nesting depth |
-| IsXlang | true | Xlang mode enabled |
-| Compatible | true | Compatible schema-evolution metadata enabled |
-| MaxGraphMemoryBytes | 134217728 | Approximate graph-memory gate per root read |
-| MaxUnbackedContainerItems | 8192 | Unbacked collection/map work per root read |
-| MaxTypeFields | 512 | Max fields in one received struct metadata body |
-| MaxTypeMetaBytes | 4096 | Max encoded bytes in one received metadata body |
-| MaxSchemaVersionsPerType | 10 | Max remote metadata versions for one logical type |
-| MaxAverageSchemaVersionsPerType | 3 | Average remote metadata versions across types |
+| Option | Default | Description |
+| ------------------------------- | --------- | -------------------------------------------------------- |
+| TrackRef | false | Reference tracking disabled |
+| MaxDepth | 20 | Maximum nesting depth |
+| IsXlang | true | Xlang mode enabled |
+| Compatible | true | Compatible schema-evolution metadata enabled |
+| MaxGraphMemoryBytes | 134217728 | Approximate graph-memory gate per root read |
+| MaxUnbackedContainerItems | 8192 | Unbacked collection/map work per root read |
+| MaxTypeFields | 512 | Max fields in one received struct metadata body |
+| MaxTypeMetaBytes | 4096 | Max encoded bytes in one received metadata body |
+| MaxSchemaVersionsPerType | 10 | Max cached remote metadata versions for one logical type |
+| MaxAverageSchemaVersionsPerType | 3 | Average cached remote metadata versions across types |
### With Options
@@ -179,15 +179,20 @@ f := fory.New(fory.WithMaxTypeMetaBytes(4096))
### WithMaxSchemaVersionsPerType
-Set the maximum accepted remote metadata versions for one logical type:
+Set the maximum cached remote metadata versions for one logical type:
```go
f := fory.New(fory.WithMaxSchemaVersionsPerType(10))
```
+Schema-version limits bound cached metadata only. When a schema-version or
+logical-type cache limit is reached, valid data still deserializes after full
+metadata validation, without caching the new schema. Repeated reads of an
+uncached schema may cost more; existing cached schemas remain reusable.
+
### WithMaxAverageSchemaVersionsPerType
-Set the average accepted remote metadata versions across accepted remote types.
+Set the average cached remote metadata versions across cached remote types.
The effective global floor is `8192` schemas:
```go
diff --git a/docs/object-serialization/go/security.md b/docs/object-serialization/go/security.md
index 0ad71c55137..88a8b8284de 100644
--- a/docs/object-serialization/go/security.md
+++ b/docs/object-serialization/go/security.md
@@ -39,8 +39,8 @@ Security-related configuration:
- Register only the expected structs before deserializing untrusted data.
- Use `WithMaxDepth(...)` to reject unexpectedly deep payloads.
-- Keep the remote schema metadata limits at their defaults unless the data is not malicious and a
- trusted peer sends larger metadata or many schema versions.
+- Keep remote metadata size limits at their defaults unless a trusted peer needs larger metadata.
+ Schema-version limits bound caching; additional valid schemas are decoded without caching.
- Prefer concrete struct fields over broad `any` or interface-typed fields for untrusted input.
## Verification
diff --git a/docs/object-serialization/java/configuration.md b/docs/object-serialization/java/configuration.md
index 0f403e8f509..eb354c25128 100644
--- a/docs/object-serialization/java/configuration.md
+++ b/docs/object-serialization/java/configuration.md
@@ -42,8 +42,8 @@ This page documents all configuration options available through `ForyBuilder`.
| `maxUnbackedContainerItems` | Maximum collection elements and map entries whose repeated read bodies are not backed by input progress during one root deserialization. Zero is strict. [...]
| `maxTypeFields` | Maximum fields accepted in one received remote struct metadata body. [...]
| `maxTypeMetaBytes` | Maximum encoded body bytes accepted for one received TypeDef or TypeMeta body, excluding the 8-byte header and any extended-size varint. [...]
-| `maxSchemaVersionsPerType` | Maximum accepted remote metadata versions for one logical type. [...]
-| `maxAverageSchemaVersionsPerType` | Average accepted remote metadata versions across all accepted remote types. The effective global floor is `8192` metadata entries. [...]
+| `maxSchemaVersionsPerType` | Maximum cached remote metadata versions for one logical type. [...]
+| `maxAverageSchemaVersionsPerType` | Average cached remote metadata versions across all cached remote types. The effective global floor is `8192` metadata entries. [...]
| `suppressClassRegistrationWarnings` | Whether to suppress class registration warnings. The warnings can be used for security audit, but may be annoying, this suppression will be enabled by default. [...]
| `metaShareEnabled` | Enables or disables meta share mode. [...]
| `scopedMetaShareEnabled` | Scoped meta share focuses on a single serialization process. Metadata created or identified during this process is exclusive to it and is not shared with by other serializations. [...]
@@ -54,6 +54,11 @@ This page documents all configuration options available through `ForyBuilder`.
| `copyRef` | When disabled, the copy performance will be better. But fory deep copy will ignore circular and shared reference. Same reference of an object graph will be copied into different objects in one `Fory#copy`. [...]
| `serializeEnumByName` | When enabled, Fory serializes enum names instead of numeric enum tags. Without this option, Fory writes declaration ordinals by default, or explicit stable ids when the enum is configured with `@ForyEnumId`. [...]
+Schema-version limits bound cached metadata only. When a schema-version or
+logical-type cache limit is reached, valid data still deserializes after full
+metadata validation, without caching the new schema. Repeated reads of an
+uncached schema may cost more; existing cached schemas remain reusable.
+
### Custom Metadata Compressors
When passing a custom `MetaCompressor` to `withMetaCompressor`, keep it thread-safe and implement
diff --git a/docs/object-serialization/java/security.md b/docs/object-serialization/java/security.md
index 77f6ac43505..50b4543a728 100644
--- a/docs/object-serialization/java/security.md
+++ b/docs/object-serialization/java/security.md
@@ -63,8 +63,9 @@ Security-related options:
- `withMaxTypeFields(...)` and `withMaxTypeMetaBytes(...)` bound the field count
and encoded body size of one received remote metadata body.
- `withMaxSchemaVersionsPerType(...)` and
- `withMaxAverageSchemaVersionsPerType(...)` bound accepted remote metadata versions without
+ `withMaxAverageSchemaVersionsPerType(...)` bound cached remote metadata versions without
changing registration, dynamic loading, or schema-evolution semantics.
+ Additional valid schemas are decoded without caching after either limit is reached.
- `withDeserializeUnknownClass(false)` avoids materializing unknown classes from metadata.
- `checkJdkClassSerializable(true)` keeps the JDK serializability check for `java.*` classes.
- Class registration warnings can be useful during security audits; use
diff --git a/docs/object-serialization/javascript/configuration.md b/docs/object-serialization/javascript/configuration.md
index 51c05446898..bdf3700e06f 100644
--- a/docs/object-serialization/javascript/configuration.md
+++ b/docs/object-serialization/javascript/configuration.md
@@ -62,12 +62,17 @@ const fory = new Fory({
| `maxUnbackedContainerItems` | `8192` | Unbacked collection elements and map entries allowed during one root deserialization |
| `maxTypeFields` | `512` | Maximum fields accepted in one received remote struct metadata body |
| `maxTypeMetaBytes` | `4096` | Maximum encoded body bytes accepted for one received TypeMeta body |
-| `maxSchemaVersionsPerType` | `10` | Maximum accepted remote metadata versions for one logical type |
-| `maxAverageSchemaVersionsPerType` | `3` | Average accepted remote metadata versions across accepted remote types |
+| `maxSchemaVersionsPerType` | `10` | Maximum cached remote metadata versions for one logical type |
+| `maxAverageSchemaVersionsPerType` | `3` | Average cached remote metadata versions across cached remote types |
| `useSliceString` | `false` | Optional string-reading optimization for Node.js. Leave at default unless benchmarked |
| `hps` | unset | Optional fast string helper from `@apache-fory/hps` (Node.js 20+) |
| `hooks.afterCodeGenerated` | unset | Callback to inspect the generated serializer code, useful for debugging |
+Schema-version limits bound cached metadata only. When a schema-version or
+logical-type cache limit is reached, valid data still deserializes after full
+metadata validation, without caching the new schema. Repeated reads of an
+uncached schema may cost more; existing cached schemas remain reusable.
+
## Reference Tracking
Global reference tracking must be enabled before field-level reference metadata can take effect:
diff --git a/docs/object-serialization/javascript/security.md b/docs/object-serialization/javascript/security.md
index 8b0f959030d..5dfabdd9615 100644
--- a/docs/object-serialization/javascript/security.md
+++ b/docs/object-serialization/javascript/security.md
@@ -45,8 +45,8 @@ Security-related configuration:
- Keep `maxTypeFields` and `maxTypeMetaBytes` at their defaults unless the data
is not malicious and a trusted peer sends larger remote metadata.
- Keep `maxSchemaVersionsPerType` and
- `maxAverageSchemaVersionsPerType` at their defaults unless the data is not
- malicious and a trusted peer sends many remote schema versions.
+ `maxAverageSchemaVersionsPerType` at their defaults to bound caching.
+ Additional valid schemas are decoded without caching.
- Prefer explicit `Type.struct(...)` schemas over `Type.any()` for untrusted input.
- Pass `hps` only from the official package version you deploy with Fory.
diff --git a/docs/object-serialization/python/configuration.md b/docs/object-serialization/python/configuration.md
index 04652322e70..e8176a459be 100644
--- a/docs/object-serialization/python/configuration.md
+++ b/docs/object-serialization/python/configuration.md
@@ -70,8 +70,8 @@ class ThreadSafeFory:
| `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. |
| `max_type_meta_bytes` | `int` | `4096` | Maximum encoded body bytes accepted for one received TypeDef body, excluding the 8-byte header and any extended-size varint. |
-| `max_schema_versions_per_type` | `int` | `10` | Maximum accepted remote metadata versions for one logical type. |
-| `max_average_schema_versions_per_type` | `int` | `3` | Average accepted remote metadata versions across accepted remote types. The effective global floor is `8192` schemas. |
+| `max_schema_versions_per_type` | `int` | `10` | Maximum cached remote metadata versions for one logical type. |
+| `max_average_schema_versions_per_type` | `int` | `3` | Average cached remote metadata versions across cached remote types. The effective global floor is `8192` schemas. |
| `max_graph_memory_bytes` | `int` | `134217728` | Approximate graph-memory gate for one root deserialization. Explicit non-positive values are rejected. |
| `max_unbacked_container_items` | `int` | `8192` | Maximum collection elements and map entries whose repeated reads are not backed by input progress. Zero is strict. |
| `policy` | `DeserializationPolicy \| None` | `None` | Deserialization policy used for security checks. Strongly recommended when `strict=False`. |
@@ -79,6 +79,11 @@ class ThreadSafeFory:
| `meta_compressor` | `Any` | `None` | Optional metadata compressor used for compatible-mode metadata encoding. |
| `fory_factory` | `Callable \| None` | `None` | `ThreadSafeFory` factory hook. When set, `ThreadSafeFory` creates instances via this callback; otherwise it forwards `**kwargs` to `Fory` construction. |
+Schema-version limits bound cached metadata only. When a schema-version or
+logical-type cache limit is reached, valid data still deserializes after full
+metadata validation, without caching the new schema. Repeated reads of an
+uncached schema may cost more; existing cached schemas remain reusable.
+
## Key Methods
```python
diff --git a/docs/object-serialization/python/security.md b/docs/object-serialization/python/security.md
index df3c5cba6b9..e5da4a7d2f6 100644
--- a/docs/object-serialization/python/security.md
+++ b/docs/object-serialization/python/security.md
@@ -80,8 +80,9 @@ Received remote metadata is also limited:
- `max_type_fields` limits the number of fields accepted in one received struct metadata body.
- `max_type_meta_bytes` limits the encoded body bytes accepted for one received TypeDef body.
-- `max_schema_versions_per_type` limits accepted remote metadata versions for one logical type.
-- `max_average_schema_versions_per_type` limits the average across accepted remote types.
+- `max_schema_versions_per_type` limits cached remote metadata versions for one logical type.
+- `max_average_schema_versions_per_type` limits the average across cached remote types.
+ Additional valid schemas are decoded without caching after either schema-version limit is reached.
- `max_graph_memory_bytes` sets an approximate gate for materialized graph memory during one root
deserialization. The estimate mainly covers lists, tuples, sets, dicts, object arrays, structs,
and Python objects. It skips leaf values such as strings, binary data, primitive scalars, and
diff --git a/docs/object-serialization/rust/configuration.md b/docs/object-serialization/rust/configuration.md
index 1ba92cd25bc..35ef7cec1b1 100644
--- a/docs/object-serialization/rust/configuration.md
+++ b/docs/object-serialization/rust/configuration.md
@@ -91,7 +91,7 @@ Note: Static data types (non-dynamic types) are secure by nature and not subject
### Remote Schema Metadata Limits
Compatible mode can receive remote metadata for schema evolution. These limits
-bound metadata size and accepted schema versions:
+bound metadata size and cached schema versions:
```rust
let fory = Fory::builder()
@@ -105,11 +105,16 @@ let fory = Fory::builder()
- `max_type_fields` defaults to `512` and limits fields in one received struct metadata body.
- `max_type_meta_bytes` defaults to `4096` and limits encoded body bytes in one received TypeDef or
TypeMeta body, excluding the 8-byte header and any extended-size varint.
-- `max_schema_versions_per_type` defaults to `10` and limits accepted remote metadata versions for
+- `max_schema_versions_per_type` defaults to `10` and limits cached remote metadata versions for
one logical type.
-- `max_average_schema_versions_per_type` defaults to `3` and limits the average across accepted
+- `max_average_schema_versions_per_type` defaults to `3` and limits the average across cached
remote types. The effective global floor is `8192` schemas.
+Schema-version limits bound cached metadata only. When a schema-version or
+logical-type cache limit is reached, valid data still deserializes after full
+metadata validation, without caching the new schema. Repeated reads of an
+uncached schema may cost more; existing cached schemas remain reusable.
+
### Graph Memory Budget
`max_graph_memory_bytes(...)` sets an approximate graph-memory gate for one root read. The estimate
@@ -179,17 +184,17 @@ let fory = Fory::builder()
## Configuration Summary
-| Option | Description | Default |
-| --------------------------------------------- | ------------------------------------------------- | --------- |
-| `compatible(bool)` | Enable schema evolution | `true` |
-| `xlang(bool)` | Use xlang mode | `true` |
-| `max_dyn_depth(u32)` | Maximum nesting depth for dynamic types | `5` |
-| `max_graph_memory_bytes(usize)` | Approximate graph-memory gate per root read | `128 MiB` |
-| `max_unbacked_container_items(usize)` | Unbacked collection/map work per root read | `8192` |
-| `max_type_fields(usize)` | Max fields in one received struct metadata body | `512` |
-| `max_type_meta_bytes(usize)` | Max encoded bytes in one received metadata body | `4096` |
-| `max_schema_versions_per_type(usize)` | Max remote metadata versions for one logical type | `10` |
-| `max_average_schema_versions_per_type(usize)` | Average remote metadata versions across types | `3` |
+| Option | Description | Default |
+| --------------------------------------------- | -------------------------------------------------------- | --------- |
+| `compatible(bool)` | Enable schema evolution | `true` |
+| `xlang(bool)` | Use xlang mode | `true` |
+| `max_dyn_depth(u32)` | Maximum nesting depth for dynamic types | `5` |
+| `max_graph_memory_bytes(usize)` | Approximate graph-memory gate per root read | `128 MiB` |
+| `max_unbacked_container_items(usize)` | Unbacked collection/map work per root read | `8192` |
+| `max_type_fields(usize)` | Max fields in one received struct metadata body | `512` |
+| `max_type_meta_bytes(usize)` | Max encoded bytes in one received metadata body | `4096` |
+| `max_schema_versions_per_type(usize)` | Max cached remote metadata versions for one logical type | `10` |
+| `max_average_schema_versions_per_type(usize)` | Average cached remote metadata versions across types | `3` |
## Compatible Mode
diff --git a/docs/object-serialization/rust/security.md b/docs/object-serialization/rust/security.md
index abc79510c3a..955f24a2832 100644
--- a/docs/object-serialization/rust/security.md
+++ b/docs/object-serialization/rust/security.md
@@ -44,8 +44,8 @@ Security-related configuration:
positive byte gate for trusted workloads with different legitimate collection/map/struct sizes.
- Keep `max_unbacked_container_items(...)` at `8192` unless trusted compact codecs require a
larger root allowance. Zero rejects every unbacked item.
-- Keep the remote schema metadata limits at their defaults unless the data is not malicious and a
- trusted peer sends larger metadata or many schema versions.
+- Keep remote metadata size limits at their defaults unless a trusted peer needs larger metadata.
+ Schema-version limits bound caching; additional valid schemas are decoded without caching.
- Prefer concrete typed fields over `dyn Any` or broad trait-object fields for untrusted input.
## Verification
diff --git a/docs/object-serialization/swift/configuration.md b/docs/object-serialization/swift/configuration.md
index d2fac386c15..aa28257974a 100644
--- a/docs/object-serialization/swift/configuration.md
+++ b/docs/object-serialization/swift/configuration.md
@@ -117,9 +117,9 @@ Compatible-mode remote metadata is also limited:
- `maxTypeFields` defaults to `512` and limits fields in one received struct metadata body.
- `maxTypeMetaBytes` defaults to `4096` and limits encoded body bytes in one received TypeMeta body,
excluding the 8-byte header and any extended-size varint.
-- `maxSchemaVersionsPerType` defaults to `10` and limits accepted remote metadata versions for one
+- `maxSchemaVersionsPerType` defaults to `10` and limits cached remote metadata versions for one
logical type.
-- `maxAverageSchemaVersionsPerType` defaults to `3` and limits the average across accepted remote
+- `maxAverageSchemaVersionsPerType` defaults to `3` and limits the average across cached remote
types. The effective global floor is `8192` schemas.
```swift
@@ -134,6 +134,11 @@ let fory = Fory(
)
```
+Schema-version limits bound cached metadata only. When a schema-version or
+logical-type cache limit is reached, valid data still deserializes after full
+metadata validation, without caching the new schema. Repeated reads of an
+uncached schema may cost more; existing cached schemas remain reusable.
+
## Recommended Presets
### Default service payloads
diff --git a/docs/object-serialization/swift/security.md b/docs/object-serialization/swift/security.md
index 4ae45d115cc..b5a29e915f5 100644
--- a/docs/object-serialization/swift/security.md
+++ b/docs/object-serialization/swift/security.md
@@ -44,8 +44,8 @@ Security-related configuration:
- 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.
-- Keep the remote schema metadata limits at their defaults unless the data is not malicious and a
- trusted peer sends larger metadata or many schema versions.
+- Keep remote metadata size limits at their defaults unless a trusted peer needs larger metadata.
+ Schema-version limits bound caching; additional valid schemas are decoded without caching.
## Verification
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org
(fory-site) 02/02: 🔄 synced local 'docs/specification/' with remote 'docs/specification/'
Posted by ch...@apache.org.
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 8931d1a9563ac680fc7f837f71d75e26f14be4f6
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Tue Sep 22 01:01:23 2026 +0000
🔄 synced local 'docs/specification/' with remote 'docs/specification/'
---
docs/specification/xlang_implementation_guide.md | 14 ++++++++++----
1 file changed, 10 insertions(+), 4 deletions(-)
diff --git a/docs/specification/xlang_implementation_guide.md b/docs/specification/xlang_implementation_guide.md
index 84335495fd1..78378f2a88b 100644
--- a/docs/specification/xlang_implementation_guide.md
+++ b/docs/specification/xlang_implementation_guide.md
@@ -1188,14 +1188,20 @@ no local header was available before parsing, this miss-only path may lazily
build local metadata and compare its 52-bit header hash with the validated
received hash. Hash equality selects local metadata without a byte or field
comparison and without consuming a remote schema-version count.
-Otherwise, check schema-version limits, build the required read state, publish
-to the persistent metadata cache, and then record the schema count. Failed or
+Otherwise, build and validate the required read state. If the schema-version and
+logical-type cache quotas have room, publish to the persistent metadata cache
+and then record the schema count. A full cache does not reject valid metadata:
+continue decoding without caching it or its derived serializers and layouts.
+Existing metadata references own this uncached state for their required lifetime.
+Root reset must prevent stale logical lookup and cumulative growth across requests.
+Reusable backing slots may retain bounded values until overwritten; immediate
+physical clearing is not required. Failed or
incompatible metadata must not publish to the persistent cache and must not
consume schema-version counts. Pure id-based enum, ext, and typed-union values
do not carry TypeDef or TypeMeta bodies and must stay on the normal type-id plus
user-type-id path. Compatible named enum, ext, and union metadata normally has
-one version, but it still counts against accepted remote metadata totals when it
-is sent as shared metadata and is a non-local metadata miss. `maxTypeFields`
+one version, but it still counts against cached remote metadata totals when it
+is published after a non-local metadata miss. `maxTypeFields`
applies only to struct field lists.
The miss-only local candidate must be derived inside the metadata owner from
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org