or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-io-grpc--grpc-protobuf-lite

API for gRPC over Protocol Buffers with proto message classes generated by the Lite Runtime library

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.grpc/grpc-protobuf-lite@1.73.x

To install, run

npx @tessl/cli install tessl/maven-io-grpc--grpc-protobuf-lite@1.73.0

index.mddocs/

gRPC Protobuf Lite

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.

Package Information

  • Package Name: io.grpc:grpc-protobuf-lite

  • Package Type: Maven

  • Language: Java

  • Installation:

    <dependency>
  <groupId>io.grpc</groupId>
  <artifactId>grpc-protobuf-lite</artifactId>
  <version>1.73.0</version>
</dependency>

    Gradle:

    implementation 'io.grpc:grpc-protobuf-lite:1.73.0'

Core Imports

import io.grpc.protobuf.lite.ProtoLiteUtils;
import io.grpc.MethodDescriptor.Marshaller;
import io.grpc.Metadata.BinaryMarshaller;
import com.google.protobuf.ExtensionRegistryLite;

Basic Usage

import io.grpc.protobuf.lite.ProtoLiteUtils;
import io.grpc.MethodDescriptor.Marshaller;
import io.grpc.Metadata.BinaryMarshaller;
import com.google.protobuf.MessageLite;
import com.google.protobuf.ExtensionRegistryLite;

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

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

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

// Set global extension registry (if needed)
ExtensionRegistryLite registry = ExtensionRegistryLite.newInstance();
// ... configure registry
ProtoLiteUtils.setExtensionRegistry(registry);

Architecture

gRPC Protobuf Lite is built around a few key components:

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

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

Capabilities

Marshaller Creation

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

/**
 * Creates a Marshaller for protos of the same type as defaultInstance.
 * @param defaultInstance the default instance of the message type
 * @return Marshaller for the message type
 * @since 1.0.0
 */
public static <T extends MessageLite> Marshaller<T> marshaller(T defaultInstance);

/**
 * Creates a Marshaller with custom recursion depth limit.
 * @param defaultInstance the default instance of the message type  
 * @param recursionLimit custom limit for recursion depth, negative values use default
 * @return Marshaller for the message type with recursion limit
 * @since 1.56.0
 */
public static <T extends MessageLite> Marshaller<T> marshallerWithRecursionLimit(
    T defaultInstance, int recursionLimit);

Metadata Marshalling

Creates binary marshallers for protobuf messages in gRPC metadata headers.

/**
 * Produce a metadata marshaller for a protobuf type.
 * @param defaultInstance the default instance of the message type
 * @return BinaryMarshaller for metadata serialization
 * @since 1.0.0
 */
public static <T extends MessageLite> Metadata.BinaryMarshaller<T> metadataMarshaller(
    T defaultInstance);

Extension Registry Management

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

/**
 * Sets the global registry for proto marshalling shared across all servers and clients.
 * Warning: This API will likely change over time. Do not modify registry after setting.
 * @param newRegistry the extension registry to set globally
 * @since 1.0.0
 */
public static void setExtensionRegistry(ExtensionRegistryLite newRegistry);

Types

/**
 * Input stream backed by a protobuf message with zero-copy optimization.
 * Package-private class used internally by marshallers.
 */
final class ProtoInputStream extends InputStream implements Drainable, KnownLength {
    // Constructor
    ProtoInputStream(MessageLite message, Parser<?> parser);
    
    // InputStream methods
    public int read() throws IOException;
    public int read(byte[] b, int off, int len) throws IOException;
    public int available();
    
    // Drainable interface
    public int drainTo(OutputStream target) throws IOException;
    
    // Package-private access methods
    MessageLite message();
    Parser<?> parser();
}

/**
 * Internal marshaller implementation for protobuf messages.
 * Implements PrototypeMarshaller interface for efficient serialization.
 */
private static final class MessageMarshaller<T extends MessageLite> 
    implements PrototypeMarshaller<T> {
    
    public Class<T> getMessageClass();
    public T getMessagePrototype();  
    public InputStream stream(T value);
    public T parse(InputStream stream);
}

/**
 * Internal marshaller implementation for metadata.
 * Implements BinaryMarshaller interface for header serialization.
 */
private static final class MetadataMarshaller<T extends MessageLite>
    implements Metadata.BinaryMarshaller<T> {
    
    public byte[] toBytes(T value);
    public T parseBytes(byte[] serialized);
}

Error Handling

The library handles several error conditions:

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

Important Notes

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