Skip to content

Latest commit

 

History

History
94 lines (78 loc) · 5.46 KB

migration-guide.md

File metadata and controls

94 lines (78 loc) · 5.46 KB
Raw

akka-kryo-serialization - migration guide

Migration from akka-kryo-serialization to pekko-kryo-serialization

  • You should upgrade to akka-kryo-serialization 2.5.x before migrating to pekko-kryo-serialization.
  • To support efforts for live migration from Akka to Pekko, compat modules are available in both Akka and Pekko Kryo Serialization to help with wire compatibility of custom messages containing ActorRefs and ByteStrings. 
    # on Pekko
libraryDependencies += "io.altoo" %% "pekko-kryo-serialization-akka-compat" % "1.0.1"

# on Akka
libraryDependencies += "io.altoo" %% "pekko-kryo-serialization-akka-compat" % "2.5.2"
    Then configure (or derive from if using a custom initializer) AkkaCompatKryoInitializer on Pekko, and PekkoCompatKryoInitializer on Akka. 
    # on Pekko
pekko-kryo-serialization.kryo-initializer = "io.altoo.pekko.serialization.kryo.compat.AkkaCompatKryoInitializer"

# on Akka
kka-kryo-serialization.kryo-initializer = "io.altoo.akka.serialization.kryo.compat.PekkoCompatKryoInitializer"

Migration from 2.4.x to 2.5.x

  • EnumerationSerializer has been deprecated with 2.4.2, with 2.5.0 default serializer for scala.Enumeration has been switched to EnumerationNameSerializer, which is not backwards compatible.

Migration from 2.3.x to 2.4.x

No manual steps required

Migration from 2.2.x to 2.3.x

No manual steps required

Migration from 2.1.x to 2.2.x

  • java.util.Record serialization compatibility has been broken by Kryo 5.2. If serialized records must be read, backwards compatibility can be enabled, see kryo-5.2.0 release notes for more details.

Migration from 2.0.x to 2.1.x

No manual steps required

Migration from 1.1.x to 2.0.x

  • By moving to Kryo 5 data created by a previous versions is unlikely to be readable with this version. Please refer to Kryo's Migrationto v5 guide for hints how to migrate data if necessary.
  • Deprecated io.altoo.akka.serialization.kryo.LegacyKeyProvider has been removed, the DefaultKeyProvider can be extended and be configured to provide the same behaviour.
  • Deprecated io.altoo.akka.serialization.kryo.serializer.scala.ScalaProductSerializer has been removed since since the standard kryo serializer should be used instead. Persistent data created by previous versions would have to be migrated manually.
  • Scala collection class mappings provided by optional-basic-mappings have been extracted into optional-scala2_12-mappings and optional-scala2_13-mappings and can be merged if needed.

Migration from 1.0.x to 1.1.x

  • The deprecated legacyAes encryption mode has been removed. Any persistent data encrypted with the old format has to be manually migrated to a safer GCM based AES encryption.

Migration from 0.5.x/0.6.x to 1.0.x

  • Move serializer configuration from akka.actor.kryo to akka-kryo-serialization
  • Change akka serialization configuration to the new package name: 
    akka {
  actor {
    serializers {
      kryo = "io.altoo.akka.serialization.kryo.KryoSerializer"
    }
  }
}
  • KryoSerializationExtension is no longer necessary and must be removed from akka configuration.
  • If you were using the scala serializers independently adapt imports from com.romix.scala.serialization.kryo to io.altoo.akka.serialization.kryo.serializer.scala.
  • Configuration property idstrategy has been re-named to id-strategy and the default has been changed from incremental to default. Please read the documentation provided in the reference.conf for the different strategies and implications.
  • The configuration property kryo-custom-serializer-init has been replaced with kryo-initializer and requires the initialize class to extend the DefaultKryoInitializer.
  • The configuration property kryo-default-serializer has been removed and setting the default field serializer can be done by subclassing the DefaultKryoInitializer.
  • The configuration property custom-queue-builder has been replaced with queue-builder and now requires the custom queue build to extend the DefaultQueueBuilder.
  • The configuration property encryption.aes.custom-key-class has been replaced with encryption.aes.key-provider and requires the custom key provider to extend the DefaultKeyProvider.
  • The old encryption scheme is deemed problematic due to lacking authentication, if you have persisted data written in the old format configure legacyAes as post serialization transformation. Configure the io.altoo.akka.serialization.kryo.LegacyKeyProvider to provide the correct key using the old scheme. Example configuration: 
        encryption {
      aes {
        key-provider = "io.altoo.akka.serialization.kryo.LegacyKeyProvider"
        mode = "AES/CBC/PKCS5Padding"
        iv-length = 16
        key = j68KkRjq21ykRGAQ
      }
    }

If there are any further questions, please don't hesitate and open an issue on GitHub.