From 9165d8071a1caa6f25c676db8cb8fcdb1f5e22d8 Mon Sep 17 00:00:00 2001 From: Shawn Date: Sat, 7 Oct 2023 20:24:54 +0800 Subject: [PATCH] [Doc] upgrade docs (#985) * upgrade docs * upgrade docs --- README.md | 7 +++++-- docs/guide/java_object_graph_guide.md | 30 ++++++++++++++++++++++++--- go/README.md | 6 +++--- 3 files changed, 35 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 9a62b2affa..179b466bcd 100644 --- a/README.md +++ b/README.md @@ -342,8 +342,11 @@ print(foo_row.f2[100000], foo_row.f4[100000].f1, foo_row.f4[200000].f2[5]) Fury java object graph serialization support class schema forward/backward compatibility. The serialization peer and deserialization peer can add/delete fields independently. We plan to add support cross-language serialization after [meta compression](https://github.com/alipay/fury/issues/203) are finished. + ### Binary Compatibility -We are still improving our protocols, binary compatibility are not ensured between fury releases for now. Please `shade` fury if you will upgrade fury in the future. +We are still improving our protocols, binary compatibility are not ensured between fury major releases for now. +it's ensured between minor version only. Please +`versioning` your data by fury major version if you will upgrade fury in the future, see [how to upgrade fury](https://github.com/alipay/fury/blob/main/docs/guide/java_object_graph_guide.md#upgrade-fury) for further details. Binary compatibility will be ensured before fury 1.0. @@ -353,7 +356,7 @@ Static serialization are secure. But dynamic serialization such as fury java/pyt For example, the deserialization may invoke `init` constructor or `equals`/`hashCode` method, if the method body contains malicious code, the system will be at risks. Fury provides a class registration option and enabled by default for such protocols, which allows only deserializing trusted registered types or built-in types. - **Do not disable class registration unless you can ensure your environment is indeed secure**. + **Do not disable class registration unless you can ensure your environment is secure**. If this option is disabled, you are responsible for serialization security. You can configure `io.fury.resolver.ClassChecker` by `ClassResolver#setClassChecker` to control which classes are allowed for serialization. diff --git a/docs/guide/java_object_graph_guide.md b/docs/guide/java_object_graph_guide.md index 00914b89d2..c60ababc7e 100644 --- a/docs/guide/java_object_graph_guide.md +++ b/docs/guide/java_object_graph_guide.md @@ -202,7 +202,7 @@ fury.registerSerializer(Foo.class, new FooSerializer(fury)); unknown types, more flexible but **may be insecure if the classes contains malicious code**. -**Do not disable class registration unless you can ensure your environment is indeed secure**. +**Do not disable class registration unless you can ensure your environment is secure**. Malicious code in `init/equals/hashCode` can be executed when deserializing unknown/untrusted types when this option disabled. @@ -338,11 +338,35 @@ then upgrade serialization to fury in an async rolling-up way: if(JavaSerializer.serializedByJDK(bytes)){ ObjectInputStream objectInputStream=xxx; return objectInputStream.readObject(); - }else{ +} else { return fury.deserialize(bytes); - } +} ``` +### Upgrade fury +Currently binary compatibility is ensured for minor versions only. + +For example, if you are using fury`v0.2.0`, binary compatibility will be provided if you upgrade to fury `v0.2.1`. +But if upgrade to fury `v0.3.0`, no binary compatibility are ensured. In order to not break binary compatibility, you +need to write fury version as header to serialized data. For example, you can write version by: +```java +MemoryBuffer buffer = xxx; +buffer.writeVarInt(2); +fury.serialize(buffer, obj); +``` +Then for deserialization, you can: +```java +MemoryBuffer buffer = xxx; +int furyVersion = buffer.readVarInt() +Fury fury = getFury(furyVersion); +fury.deserialize(buffer); +``` +`getFury` is a method to load corresponding fury, you can shade and relocate different version of fury to different +package, and load fury by version. + +If you upgrade fury by minor version, or you won't have data serialized by older fury, you can upgrade fury directly, +no need to `versioning` the data. + ## Trouble shooting ### Class inconsistency and class version check If you create fury without setting `CompatibleMode` to `io.fury.config.CompatibleMode.COMPATIBLE`, and you got a strange diff --git a/go/README.md b/go/README.md index 99449574d3..be7ec4e26a 100644 --- a/go/README.md +++ b/go/README.md @@ -1,6 +1,6 @@ # Fury Go Fury is a blazing fast multi-language serialization framework powered by jit(just-in-time compilation) and zero-copy. -First Golang version are implemented using reflection, will come soon. - -We are implementing a static code generator to generate serializer code ahead to speed up serialization. \ No newline at end of file +Currently fury go are implemented using reflection. In future we plan to implement a static code generator +to generate serializer code ahead to speed up serialization, or implement a jit framework which generate asm instructions +to speed up serialization. \ No newline at end of file