CtrlK
BlogDocsLog inGet started
Tessl Logo

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

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

Pending
Overview
Eval results
Files

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

Install with Tessl CLI

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