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
```