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
The following commit(s) were added to refs/heads/main by this push:
new 465a4e33c 🔄 synced local 'docs/guide/' with remote 'docs/guide/'
465a4e33c is described below
commit 465a4e33cb6d0b1bf0b3423ce0209c68f15000e0
Author: chaokunyang <[email protected]>
AuthorDate: Thu Sep 4 16:17:46 2025 +0000
🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/java_serialization_guide.md | 56 ++++++++++++++++++++--------------
1 file changed, 33 insertions(+), 23 deletions(-)
diff --git a/docs/guide/java_serialization_guide.md
b/docs/guide/java_serialization_guide.md
index 7f1f7a2af..059668176 100644
--- a/docs/guide/java_serialization_guide.md
+++ b/docs/guide/java_serialization_guide.md
@@ -108,28 +108,30 @@ public class Example {
## ForyBuilder options
-| Option Name | Description
[...]
-| ----------------------------------- |
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
-| `timeRefIgnored` | Whether to ignore reference tracking
of all time types registered in `TimeSerializers` and subclasses of those types
when ref tracking is enabled. If ignored, ref tracking of every time type can
be enabled by invoking `Fory#registerSerializer(Class, Serializer)`. For
example, `fory.registerSerializer(Date.class, new DateSerializer(fory, true))`.
Note that enabling ref tracking should happen before serializer codegen of any
types which contain time [...]
-| `compressInt` | Enables or disables int compression
for smaller size.
[...]
-| `compressLong` | Enables or disables long compression
for smaller size.
[...]
-| `compressString` | Enables or disables string compression
for smaller size.
[...]
-| `classLoader` | The classloader should not be updated;
Fory caches class metadata. Use `LoaderBinding` or `ThreadSafeFory` for
classloader updates.
[...]
-| `compatibleMode` | Type forward/backward compatibility
config. Also Related to `checkClassVersion` config. `SCHEMA_CONSISTENT`: Class
schema must be consistent between serialization peer and deserialization peer.
`COMPATIBLE`: Class schema can be different between serialization peer and
deserialization peer. They can add/delete fields independently. [See
more](#class-inconsistency-and-class-version-check).
[...]
-| `checkClassVersion` | Determines whether to check the
consistency of the class schema. If enabled, Fory checks, writes, and checks
consistency using the `classVersionHash`. It will be automatically disabled
when `CompatibleMode#COMPATIBLE` is enabled. Disabling is not recommended
unless you can ensure the class won't evolve.
[...]
-| `checkJdkClassSerializable` | Enables or disables checking of
`Serializable` interface for classes under `java.*`. If a class under `java.*`
is not `Serializable`, Fory will throw an `UnsupportedOperationException`.
[...]
-| `registerGuavaTypes` | Whether to pre-register Guava types
such as `RegularImmutableMap`/`RegularImmutableList`. These types are not
public API, but seem pretty stable.
[...]
-| `requireClassRegistration` | Disabling may allow unknown classes to
be deserialized, potentially causing security risks.
[...]
-| `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.
[...]
-| `metaCompressor` | Set a compressor for meta compression.
Note that the passed MetaCompressor should be thread-safe. By default, a
`Deflater` based compressor `DeflaterMetaCompressor` will be used. Users can
pass other compressor such as `zstd` for better compression rate.
[...]
-| `deserializeNonexistentClass` | Enables or disables
deserialization/skipping of data for non-existent classes.
[...]
-| `codeGenEnabled` | Disabling may result in faster initial
serialization but slower subsequent serializations.
[...]
-| `asyncCompilationEnabled` | If enabled, serialization uses
interpreter mode first and switches to JIT serialization after async serializer
JIT for a class is finished.
[...]
-| `scalaOptimizationEnabled` | Enables or disables Scala-specific
serialization optimization.
[...]
-| `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 serialize enum by
name instead of ordinal.
[...]
+| Option Name | Description
[...]
+| --------------------------- |
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| `timeRefIgnored` | Whether to ignore reference tracking of all
time types registered in `TimeSerializers` and subclasses of those types when
ref tracking is enabled. If ignored, ref tracking of every time type can be
enabled by invoking `Fory#registerSerializer(Class, Serializer)`. For example,
`fory.registerSerializer(Date.class, new DateSerializer(fory, true))`. Note
that enabling ref tracking should happen before serializer codegen of any types
which contain time fields. [...]
+| `compressInt` | Enables or disables int compression for
smaller size.
[...]
+| `compressLong` | Enables or disables long compression for
smaller size.
[...]
+| `compressString` | Enables or disables string compression for
smaller size.
[...]
+| `classLoader` | The classloader should not be updated; Fory
caches class metadata. Use `LoaderBinding` or `ThreadSafeFory` for classloader
updates.
[...]
+| `compatibleMode` | Type forward/backward compatibility config.
Also Related to `checkClassVersion` config. `SCHEMA_CONSISTENT`: Class schema
must be consistent between serialization peer and deserialization peer.
`COMPATIBLE`: Class schema can be different between serialization peer and
deserialization peer. They can add/delete fields independently. [See
more](#class-inconsistency-and-class-version-check).
[...]
+| `checkClassVersion` | Determines whether to check the consistency of
the class schema. If enabled, Fory checks, writes, and checks consistency using
the `classVersionHash`. It will be automatically disabled when
`CompatibleMode#COMPATIBLE` is enabled. Disabling is not recommended unless you
can ensure the class won't evolve.
[...]
+| `checkJdkClassSerializable` | Enables or disables checking of `Serializable`
interface for classes under `java.*`. If a class under `java.*` is not
`Serializable`, Fory will throw an `UnsupportedOperationException`.
[...]
+| `registerGuavaTypes` | Whether to pre-register Guava types such as
`RegularImmutableMap`/`RegularImmutableList`. These types are not public API,
but seem pretty stable.
[...]
+| `requireClassRegistration` | Disabling may allow unknown classes to be
deserialized, potentially causing security risks.
[...]
+| `requireClassRegistration` | Set max depth for deserialization, when depth
exceeds, an exception will be thrown. This can be used to refuse
deserialization DDOS attack.
[...]
+
+| `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. | `true` |
+| `metaShareEnabled` | Enables or disables meta share mode. | `true` if
`CompatibleMode.Compatible` is set, otherwise false. |
+| `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. | `true` if
`CompatibleMode.Compatible` is set, otherwise false. |
+| `metaCompressor` | Set a compressor for meta compression. Note that the
passed MetaCompressor should be thread-safe. By default, a `Deflater` based
compressor `DeflaterMetaCompressor` will be used. Users can pass other
compressor such as `zstd` for better compression rate. |
`DeflaterMetaCompressor` |
+| `deserializeNonexistentClass` | Enables or disables deserialization/skipping
of data for non-existent classes. | `true` if `CompatibleMode.Compatible` is
set, otherwise false. |
+| `codeGenEnabled` | Disabling may result in faster initial serialization but
slower subsequent serializations. | `true` |
+| `asyncCompilationEnabled` | If enabled, serialization uses interpreter mode
first and switches to JIT serialization after async serializer JIT for a class
is finished. | `false` |
+| `scalaOptimizationEnabled` | Enables or disables Scala-specific
serialization optimization. | `false` |
+| `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`. | `true`
|
+| `serializeEnumByName` | When Enabled, fory serialize enum by name instead of
ordinal. | `false` |
## Advanced Usage
@@ -1167,7 +1169,9 @@ Custom memory allocators are useful for:
- **Debugging**: Add logging or tracking to monitor memory usage
- **Off-heap Memory**: Integrate with off-heap memory management systems
-### Security & Class Registration
+### Security
+
+#### Class Registration
`ForyBuilder#requireClassRegistration` can be used to disable class
registration, this will allow to deserialize objects
unknown types,
@@ -1217,6 +1221,12 @@ simplify
the customization of class check mechanism. You can use this checker or
implement more sophisticated checker by
yourself.
+#### Limit max deserization depth
+
+Fory also provides a `ForyBuilder#withMaxDepth` to limit max deserialization
depth. The default max depth is 50.
+
+If max depth is reached, Fory will throw `ForyException`. This can be used to
prevent malicious data from causing stack overflow or other issues.
+
### Register class by name
Register class by id will have better performance and smaller space overhead.
But in some cases, management for a bunch
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
