0
# gRPC Protobuf Lite
1

2
API for gRPC over Protocol Buffers with proto message classes generated by the Lite Runtime library. This package provides utilities for gRPC communication using Protocol Buffers Lite, a lightweight version designed for constrained environments like Android. It enables efficient serialization and deserialization of protobuf lite messages in gRPC services.
3

4
## Package Information
5

6
- **Package Name**: io.grpc:grpc-protobuf-lite
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>io.grpc</groupId>
13
    <artifactId>grpc-protobuf-lite</artifactId>
14
    <version>1.73.0</version>
15
  </dependency>
16
  ```
17

18
  Gradle:
19
  ```gradle
20
  implementation 'io.grpc:grpc-protobuf-lite:1.73.0'
21
  ```
22

23
## Core Imports
24

25
```java
26
import io.grpc.protobuf.lite.ProtoLiteUtils;
27
import io.grpc.MethodDescriptor.Marshaller;
28
import io.grpc.Metadata.BinaryMarshaller;
29
import com.google.protobuf.ExtensionRegistryLite;
30
```
31

32
## Basic Usage
33

34
```java
35
import io.grpc.protobuf.lite.ProtoLiteUtils;
36
import io.grpc.MethodDescriptor.Marshaller;
37
import io.grpc.Metadata.BinaryMarshaller;
38
import com.google.protobuf.MessageLite;
39
import com.google.protobuf.ExtensionRegistryLite;
40

41
// Create a marshaller for a protobuf lite message
42
MyMessageLite defaultInstance = MyMessageLite.getDefaultInstance();
43
Marshaller<MyMessageLite> marshaller = ProtoLiteUtils.marshaller(defaultInstance);
44

45
// Create a marshaller with recursion limit
46
Marshaller<MyMessageLite> limitedMarshaller = ProtoLiteUtils.marshallerWithRecursionLimit(
47
    defaultInstance, 100);
48

49
// Create a metadata marshaller
50
BinaryMarshaller<MyMessageLite> metaMarshaller = ProtoLiteUtils.metadataMarshaller(defaultInstance);
51

52
// Set global extension registry (if needed)
53
ExtensionRegistryLite registry = ExtensionRegistryLite.newInstance();
54
// ... configure registry
55
ProtoLiteUtils.setExtensionRegistry(registry);
56
```
57

58
## Architecture
59

60
gRPC Protobuf Lite is built around a few key components:
61

62
- **ProtoLiteUtils**: Central utility class providing factory methods for creating marshallers
63
- **MessageMarshaller**: Internal implementation for streaming protobuf messages efficiently 
64
- **MetadataMarshaller**: Internal implementation for binary metadata serialization
65
- **ProtoInputStream**: Optimized input stream backed by protobuf messages with zero-copy optimization
66
- **Global Extension Registry**: Thread-safe shared registry for protobuf extensions
67

68
The library provides zero-copy optimization for in-memory transport when using ProtoInputStream, and supports configurable recursion limits for security in parsing untrusted data.
69

70
## Capabilities
71

72
### Marshaller Creation
73

74
Creates marshallers for converting protobuf lite messages to/from byte streams for gRPC method calls.
75

76
```java { .api }
77
/**
78
 * Creates a Marshaller for protos of the same type as defaultInstance.
79
 * @param defaultInstance the default instance of the message type
80
 * @return Marshaller for the message type
81
 * @since 1.0.0
82
 */
83
public static <T extends MessageLite> Marshaller<T> marshaller(T defaultInstance);
84

85
/**
86
 * Creates a Marshaller with custom recursion depth limit.
87
 * @param defaultInstance the default instance of the message type  
88
 * @param recursionLimit custom limit for recursion depth, negative values use default
89
 * @return Marshaller for the message type with recursion limit
90
 * @since 1.56.0
91
 */
92
public static <T extends MessageLite> Marshaller<T> marshallerWithRecursionLimit(
93
    T defaultInstance, int recursionLimit);
94
```
95

96
### Metadata Marshalling
97

98
Creates binary marshallers for protobuf messages in gRPC metadata headers.
99

100
```java { .api }
101
/**
102
 * Produce a metadata marshaller for a protobuf type.
103
 * @param defaultInstance the default instance of the message type
104
 * @return BinaryMarshaller for metadata serialization
105
 * @since 1.0.0
106
 */
107
public static <T extends MessageLite> Metadata.BinaryMarshaller<T> metadataMarshaller(
108
    T defaultInstance);
109
```
110

111
### Extension Registry Management
112

113
Manages the global extension registry used for parsing protobuf messages with extensions.
114

115
```java { .api }
116
/**
117
 * Sets the global registry for proto marshalling shared across all servers and clients.
118
 * Warning: This API will likely change over time. Do not modify registry after setting.
119
 * @param newRegistry the extension registry to set globally
120
 * @since 1.0.0
121
 */
122
public static void setExtensionRegistry(ExtensionRegistryLite newRegistry);
123
```
124

125
## Types
126

127
```java { .api }
128
/**
129
 * Input stream backed by a protobuf message with zero-copy optimization.
130
 * Package-private class used internally by marshallers.
131
 */
132
final class ProtoInputStream extends InputStream implements Drainable, KnownLength {
133
    // Constructor
134
    ProtoInputStream(MessageLite message, Parser<?> parser);
135
    
136
    // InputStream methods
137
    public int read() throws IOException;
138
    public int read(byte[] b, int off, int len) throws IOException;
139
    public int available();
140
    
141
    // Drainable interface
142
    public int drainTo(OutputStream target) throws IOException;
143
    
144
    // Package-private access methods
145
    MessageLite message();
146
    Parser<?> parser();
147
}
148

149
/**
150
 * Internal marshaller implementation for protobuf messages.
151
 * Implements PrototypeMarshaller interface for efficient serialization.
152
 */
153
private static final class MessageMarshaller<T extends MessageLite> 
154
    implements PrototypeMarshaller<T> {
155
    
156
    public Class<T> getMessageClass();
157
    public T getMessagePrototype();  
158
    public InputStream stream(T value);
159
    public T parse(InputStream stream);
160
}
161

162
/**
163
 * Internal marshaller implementation for metadata.
164
 * Implements BinaryMarshaller interface for header serialization.
165
 */
166
private static final class MetadataMarshaller<T extends MessageLite>
167
    implements Metadata.BinaryMarshaller<T> {
168
    
169
    public byte[] toBytes(T value);
170
    public T parseBytes(byte[] serialized);
171
}
172
```
173

174
## Error Handling
175

176
The library handles several error conditions:
177

178
- **Invalid Protocol Buffer**: Throws `StatusRuntimeException` with `Status.INTERNAL` code when parsing fails due to malformed protobuf data
179
- **Stream State Errors**: Throws `IllegalStateException` when accessing message from consumed ProtoInputStream  
180
- **IO Errors**: Propagates `IOException` from underlying stream operations
181
- **Size Validation**: Throws `RuntimeException` when stream size doesn't match expected size
182

183
## Important Notes
184

185
- **Experimental API**: The entire API is marked as experimental since protobuf lite API is not guaranteed to be stable
186
- **Thread Safety**: Extension registry setting is thread-safe, but don't modify the registry object after setting
187
- **Zero-Copy Optimization**: ProtoInputStream provides zero-copy streaming when parser types match
188
- **Memory Limits**: Default maximum message size is 4MB, matching gRPC internal limits
189
- **Android Compatibility**: Specifically designed for constrained environments like Android with smaller binary footprint