0
# Wire Runtime
1
2
Wire Runtime provides core functionality for encoding, decoding, and working with Protocol Buffer messages in Kotlin multiplatform applications. It serves as the foundation for Wire-generated protobuf classes, offering cross-platform serialization capabilities, immutable message classes with builders, and efficient binary protobuf data handling.
3
4
## Package Information
5
6
- **Package Name**: wire-runtime
7
- **Package Type**: maven
8
- **Language**: Kotlin (Multiplatform)
9
- **Installation**:
10
```kotlin
11
implementation("com.squareup.wire:wire-runtime:4.9.11")
12
```
13
14
## Core Imports
15
16
```kotlin
17
import com.squareup.wire.*
18
import com.squareup.wire.ProtoAdapter.*
19
import okio.ByteString
20
import okio.BufferedSource
21
import okio.BufferedSink
22
```
23
24
## Basic Usage
25
26
```kotlin
27
import com.squareup.wire.*
28
import okio.Buffer
29
30
// Create a message using generated Wire classes
31
val person = Person.Builder()
32
.name("John Doe")
33
.age(30)
34
.email("john@example.com")
35
.build()
36
37
// Encode message to binary format
38
val encoded: ByteArray = person.encode()
39
val encodedByteString: ByteString = person.encodeByteString()
40
41
// Decode message from binary format
42
val decoded: Person = Person.ADAPTER.decode(encoded)
43
44
// Work with protocol buffer I/O directly
45
val buffer = Buffer()
46
val writer = ProtoWriter(buffer)
47
ProtoAdapter.STRING.encodeWithTag(writer, 1, "Hello Wire!")
48
49
val reader = ProtoReader(buffer)
50
val tag = reader.nextTag() // Returns 1
51
val message = ProtoAdapter.STRING.decode(reader) // Returns "Hello Wire!"
52
```
53
54
## Architecture
55
56
Wire Runtime is built around several key architectural components:
57
58
- **Message Framework**: Abstract base classes for protocol buffer messages and builders
59
- **Adapter Pattern**: `ProtoAdapter` handles encoding/decoding for each type with built-in adapters for all protobuf types
60
- **I/O System**: `ProtoReader` and `ProtoWriter` provide low-level protocol buffer reading and writing
61
- **Multiplatform Design**: Core API defined with `expect` classes, platform-specific implementations
62
- **Type Safety**: Strong typing with generic constraints ensuring message/builder relationships
63
- **Unknown Field Preservation**: Maintains compatibility by preserving unknown fields during encoding/decoding
64
65
## Capabilities
66
67
### Message Framework
68
69
Core message classes and builders that form the foundation of all Wire-generated protocol buffer classes.
70
71
```kotlin { .api }
72
abstract class Message<M : Message<M, B>, B : Message.Builder<M, B>>(
73
adapter: ProtoAdapter<M>,
74
unknownFields: ByteString
75
) {
76
val unknownFields: ByteString
77
val adapter: ProtoAdapter<M>
78
abstract fun newBuilder(): B
79
fun encode(sink: BufferedSink)
80
fun encode(): ByteArray
81
fun encodeByteString(): ByteString
82
}
83
84
abstract class Message.Builder<M : Message<M, B>, B : Builder<M, B>> {
85
fun addUnknownFields(unknownFields: ByteString): Builder<M, B>
86
fun addUnknownField(tag: Int, fieldEncoding: FieldEncoding, value: Any?): Builder<M, B>
87
fun clearUnknownFields(): Builder<M, B>
88
fun buildUnknownFields(): ByteString
89
abstract fun build(): M
90
}
91
```
92
93
[Message Framework](./message-framework.md)
94
95
### Protocol Buffer I/O
96
97
Low-level reading and writing of protocol buffer wire format data with support for all protobuf field types.
98
99
```kotlin { .api }
100
class ProtoReader(source: BufferedSource) {
101
fun beginMessage(): Long
102
fun endMessageAndGetUnknownFields(token: Long): ByteString
103
fun nextTag(): Int
104
fun peekFieldEncoding(): FieldEncoding?
105
fun readString(): String
106
fun readBytes(): ByteString
107
fun readVarint32(): Int
108
fun readVarint64(): Long
109
fun readFixed32(): Int
110
fun readFixed64(): Long
111
}
112
113
class ProtoWriter(sink: BufferedSink) {
114
fun writeTag(fieldNumber: Int, fieldEncoding: FieldEncoding)
115
fun writeString(value: String)
116
fun writeBytes(value: ByteString)
117
fun writeVarint32(value: Int)
118
fun writeVarint64(value: Long)
119
fun writeFixed32(value: Int)
120
fun writeFixed64(value: Long)
121
}
122
```
123
124
[Protocol Buffer I/O](./protobuf-io.md)
125
126
### Proto Adapters
127
128
Type-safe encoding and decoding adapters for all protocol buffer types, including built-in adapters for scalars, collections, and Google Well-Known Types.
129
130
```kotlin { .api }
131
abstract class ProtoAdapter<E>(
132
fieldEncoding: FieldEncoding,
133
type: KClass<*>?,
134
typeUrl: String?,
135
syntax: Syntax,
136
identity: E? = null,
137
sourceFile: String? = null
138
) {
139
abstract fun encodedSize(value: E): Int
140
abstract fun encode(writer: ProtoWriter, value: E)
141
abstract fun decode(reader: ProtoReader): E
142
fun encode(value: E): ByteArray
143
fun decode(bytes: ByteArray): E
144
fun asPacked(): ProtoAdapter<List<E>>
145
fun asRepeated(): ProtoAdapter<List<E>>
146
147
companion object {
148
val STRING: ProtoAdapter<String>
149
val BYTES: ProtoAdapter<ByteString>
150
val INT32: ProtoAdapter<Int>
151
val INT64: ProtoAdapter<Long>
152
val BOOL: ProtoAdapter<Boolean>
153
val FLOAT: ProtoAdapter<Float>
154
val DOUBLE: ProtoAdapter<Double>
155
// ... all built-in adapters
156
}
157
}
158
```
159
160
[Proto Adapters](./proto-adapters.md)
161
162
### Enum Support
163
164
Support for protocol buffer enums with proper value mapping and unknown value handling.
165
166
```kotlin { .api }
167
interface WireEnum {
168
val value: Int
169
}
170
171
abstract class EnumAdapter<E : WireEnum>(
172
type: KClass<E>,
173
syntax: Syntax,
174
identity: E?
175
) : ProtoAdapter<E> {
176
protected abstract fun fromValue(value: Int): E?
177
}
178
```
179
180
[Enum Support](./enum-support.md)
181
182
### Field Annotations
183
184
Annotations for marking generated message fields with encoding metadata and serialization behavior.
185
186
```kotlin { .api }
187
@Target(AnnotationTarget.FIELD)
188
@Retention(AnnotationRetention.RUNTIME)
189
annotation class WireField(
190
val tag: Int,
191
val adapter: String,
192
val label: Label = Label.OPTIONAL,
193
val redacted: Boolean = false,
194
val declaredName: String = "",
195
val jsonName: String = "",
196
val oneofName: String = "",
197
val schemaIndex: Int = -1
198
)
199
200
enum class Label {
201
REQUIRED, OPTIONAL, REPEATED, ONE_OF, PACKED, OMIT_IDENTITY
202
}
203
```
204
205
[Field Annotations](./field-annotations.md)
206
207
### Time and Duration Types
208
209
Cross-platform time and duration types that map to Google Well-Known Types.
210
211
```kotlin { .api }
212
expect class Duration {
213
fun getSeconds(): Long
214
fun getNano(): Int
215
}
216
217
expect class Instant {
218
fun getEpochSecond(): Long
219
fun getNano(): Int
220
}
221
222
fun durationOfSeconds(seconds: Long, nano: Long): Duration
223
fun ofEpochSecond(epochSecond: Long, nano: Long): Instant
224
```
225
226
[Time Types](./time-types.md)
227
228
### Any Message Support
229
230
Support for `google.protobuf.Any` messages allowing type-safe packing and unpacking of arbitrary protocol buffer messages.
231
232
```kotlin { .api }
233
class AnyMessage(
234
val typeUrl: String,
235
val value: ByteString = ByteString.EMPTY
236
) : Message<AnyMessage, Nothing> {
237
fun <T> unpack(adapter: ProtoAdapter<T>): T
238
fun <T> unpackOrNull(adapter: ProtoAdapter<T>): T?
239
240
companion object {
241
fun pack(message: Message<*, *>): AnyMessage
242
val ADAPTER: ProtoAdapter<AnyMessage>
243
}
244
}
245
```
246
247
[Any Message Support](./any-message.md)
248
249
## Common Field Encodings
250
251
```kotlin { .api }
252
enum class FieldEncoding(val value: Int) {
253
VARINT(0),
254
FIXED64(1),
255
LENGTH_DELIMITED(2),
256
FIXED32(5)
257
}
258
259
enum class Syntax {
260
PROTO_2,
261
PROTO_3
262
}
263
```