1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
/*
* Copyright 2017-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/
package kotlinx.serialization.protobuf
import kotlinx.serialization.*
import kotlinx.serialization.modules.*
import kotlinx.serialization.protobuf.internal.*
import kotlin.js.*
/**
* Implements [encoding][encodeToByteArray] and [decoding][decodeFromByteArray] 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
* ```
*
* @param encodeDefaults specifies whether default values are encoded.
* False by default; meaning that properties with values equal to defaults will be elided.
* @param serializersModule application-specific [SerializersModule] to provide custom serializers.
*/
@ExperimentalSerializationApi
public sealed class ProtoBuf(
internal val encodeDefaults: Boolean,
override val serializersModule: SerializersModule
) : BinaryFormat {
/**
* The default instance of [ProtoBuf].
*/
public companion object Default : ProtoBuf(false, EmptySerializersModule)
override fun <T> encodeToByteArray(serializer: SerializationStrategy<T>, value: T): ByteArray {
val output = ByteArrayOutput()
val encoder = ProtobufEncoder(this, ProtobufWriter(output), serializer.descriptor)
encoder.encodeSerializableValue(serializer, value)
return output.toByteArray()
}
override fun <T> decodeFromByteArray(deserializer: DeserializationStrategy<T>, bytes: ByteArray): T {
val input = ByteArrayInput(bytes)
val decoder = ProtobufDecoder(this, ProtobufReader(input), deserializer.descriptor)
return decoder.decodeSerializableValue(deserializer)
}
}
/**
* Creates an instance of [ProtoBuf] configured from the optionally given [ProtoBuf instance][from]
* and adjusted with [builderAction].
*/
@ExperimentalSerializationApi
public fun ProtoBuf(from: ProtoBuf = ProtoBuf, builderAction: ProtoBufBuilder.() -> Unit): ProtoBuf {
val b = ProtoBufBuilder(from)
b.builderAction()
return ProtoBufImpl(b.encodeDefaults, b.serializersModule)
}
/**
* Builder of the [ProtoBuf] instance provided by `ProtoBuf` factory function.
*/
@ExperimentalSerializationApi
public class ProtoBufBuilder internal constructor(proto: ProtoBuf) {
/**
* Specifies whether default values of Kotlin properties should be encoded.
*/
public var encodeDefaults: Boolean = proto.encodeDefaults
/**
* Module with contextual and polymorphic serializers to be used in the resulting [ProtoBuf] instance.
*/
public var serializersModule: SerializersModule = proto.serializersModule
}
@ExperimentalSerializationApi
private class ProtoBufImpl(encodeDefaults: Boolean, serializersModule: SerializersModule) :
ProtoBuf(encodeDefaults, serializersModule)
|
