ProtoBuf

Implements encoding and decoding classes to/from bytes using Proto2[https://developers.google.com/protocol-buffers/docs/proto] specification. It is typically used by constructing an application-specific instance, with configured specific behaviour and, if necessary, registered custom serializers (in SerializersModule provided by serializersModule constructor parameter).

Correspondence between Protobuf message definitions and Kotlin classes

Given a ProtoBuf definition with one required field, one optional field and one optional field with a custom default value:

message MyMessage {
required int32 first = 1;
optional int32 second = 2;
optional int32 third = 3 [default = 42];
}

The corresponding Serializable class should match the ProtoBuf definition and should use the same default values:

@Serializable
data class MyMessage(val first: Int, val second: Int = 0, val third: Int = 42)

By default, protobuf fields ids are being assigned to Kotlin properties in incremental order, i.e. the first property in the class has id 1, the second has id 2, and so forth. If you need a more stable order (e.g. to avoid breaking changes when reordering properties), provide custom ids using ProtoNumber annotation.

By default, all integer numbers are encoded using varint[https://developers.google.com/protocol-buffers/docs/encoding#varints] encoding. This behaviour can be changed via ProtoType annotation.

Known caveats and limitations

Lists are represented as repeated fields. Because format spec says that if the list is empty, there are no elements in the stream with such tag, you must explicitly mark any field of list type with default = emptyList(). Same for maps. There's no special support for oneof protobuf fields. However, this implementation supports standard kotlinx.serialization's polymorphic and sealed serializers, using their default form (message of serialName: string and other embedded message with actual content).

Proto3 support

This implementation does not support repeated packed fields, so you won't be able to deserialize Proto3 lists. However, other messages could be decoded. You have to remember that since fields in Proto3 messages by default are implicitly optional, corresponding Kotlin properties have to be nullable with default value null.

Usage example

// Serialize to ProtoBuf bytes. Default values are omitted.
val encoded = ProtoBuf.encodeToByteArray(MyMessage(15)) // [0x08, 0x0f]

// Deserialize ProtoBuf bytes will use default values of the MyMessage class
val decoded = ProtoBuf.decodeFromByteArray<MyMessage>(encoded) // MyMessage(first=15, second=0, third=42)

// Serialize to ProtoBuf hex string with all values
val encoded2 = ProtoBuf { encodeDefaults = true }.encodeToHexString(MyMessage(15)) // "080f1000182a"

// Deserialize from ProtoBuf hex string
val decoded2 = ProtoBuf.decodeFromHexString<MyMessage>(encoded2) // MyMessage(first=15, second=0, third=42)

Check existence of optional fields

Null values can be used as the default value for optional fields to implement more complex use-cases that rely on checking if a field was set or not.

@Serializable
data class MyMessage(val first: Int, private val _second: Int? = null, private val _third: Int? = null) {

val second: Int
get() = _second ?: 0

val third: Int
get() = _third ?: 42

fun hasSecond() = _second != null

fun hasThird() = _third != null
}

// Serialize to ProtoBuf bytes, removing all default (null) values
val encoded = ProtoBuf.encodeToByteArray(MyMessage(15)) // [0x08, 0x0f]

// Deserialize ProtoBuf bytes
val decoded = ProtoBuf.decodeFromByteArray<MyMessage>(encoded) // MyMessage(first = 15, _second = null, _third = null)
decoded.hasSecond() // false
decoded.second // 0
decoded.hasThird() // false
decoded.third // 42

// Serialize to ProtoBuf bytes
val encoded2 = ProtoBuf.encodeToByteArray(MyMessage(15, 0, 0)) // [0x08, 0x0f, 0x10, 0x00, 0x18, 0x00]

// Deserialize ProtoBuf bytes
val decoded2 = ProtoBuf.decodeFromByteArray<MyMessage>(encoded2) // MyMessage(first=15, _second=0, _third=0)
decoded.hasSecond() // true
decoded.second // 0
decoded.hasThird() // true
decoded.third // 0

sealed class ProtoBuf : BinaryFormat

Parameters

encodeDefaults

specifies whether default values are encoded. False by default; meaning that properties with values equal to defaults will be elided.

serializersModule

application-specific SerializersModule to provide custom serializers.

Types

Default
Link copied to clipboard
common

The default instance of ProtoBuf.

object Default : ProtoBuf

Functions

decodeFromByteArray
Link copied to clipboard
common
open override fun <T> decodeFromByteArray(deserializer: DeserializationStrategy<T>, bytes: ByteArray): T
encodeToByteArray
Link copied to clipboard
common
open override fun <T> encodeToByteArray(serializer: SerializationStrategy<T>, value: T): ByteArray
equals
Link copied to clipboard
common
open operator override fun equals(other: Any?): Boolean
hashCode
Link copied to clipboard
common
open override fun hashCode(): Int
toString
Link copied to clipboard
common
open override fun toString(): String

Properties

serializersModule
Link copied to clipboard
common

application-specific SerializersModule to provide custom serializers.

open override val serializersModule: SerializersModule

Inheritors

ProtoBuf
Link copied to clipboard
common