# Project Plan: Google-gRPC as the Canonical Perl Engine

## Core Architectural Goal

The primary mission of the `Google-gRPC` distribution is to serve as a high-performance, C-less gRPC engine for the broader Perl ecosystem. By decisively bypassing the massive Google `grpc-c` C++ runtime, this module provides a lightweight, non-blocking HTTP/2 transport layer natively integrated with Perl.

This module acts as the crucial abstraction layer isolating complex network mechanics from higher-level consumers (such as `DBD::Spanner`, `DBD::BigQuery`, or generic Application microservices). Downstream implementations should remain thin and strictly focused on parsing business logic, while `Google-gRPC` provides the bulletproof transport foundation.

## 1. Transport Abstraction (The Net::Curl Core)

Instead of relying on monolithic C++ background threads and `grpc::CompletionQueue`, `Google-gRPC` harnesses the CPAN `Net::Curl::Multi` framework to multiplex binary streams globally.

*   **HTTP/2 Frame Masking:** The distribution must transparently handle all gRPC payload wrapping. It natively applies and strips the 5-byte header (`[1 byte compression flag] + [4 bytes length]`) over outgoing and incoming binary streams.
*   **Zero Event Loop Lock-In:** It must expose raw POSIX file descriptors and timeout semantics safely to the caller wrapper so that any event loop (AnyEvent, IO::Async, Mojolicious, or custom DB bindings like `AsyncWatcher`) can register polling operations seamlessly.

## 2. Robust Flow Control (Reinventing the Missing Wheels)

Because we are bypassing standard `grpc-c`, `Google-gRPC` is mandated to recreate several essential components of the gRPC specification natively:

*   **Exponential Backoff & Retry Interceptors:** Automatically detect transient gRPC network statuses (e.g., `14 UNAVAILABLE`, `4 DEADLINE_EXCEEDED`, `8 RESOURCE_EXHAUSTED`). Apply configurable retry policies with Jitter delays internally, silently yielding `WOULDBLOCK` back to the event loop rather than needlessly bubbling errors into the application.
*   **Backpressure Handling:** Monitor internal socket buffer scales natively. If a streaming RPC (like BigQuery paginations) is downloading chunks faster than the User Space event loop can evaluate them computationally, it must intelligently throttle read consumption to prevent `Net::Curl` from unbounded memory bloat.
*   **Trailing Metadata Evaluation:** Provide robust parsing of HTTP/2 trailing headers to evaluate dynamic `grpc-status` states properly without relying on naive JSON/REST validation blocks.

## 3. Serialization Agnosticism

`Google-gRPC` is responsible for transporting bytes safely. Deserialization happens here natively, but it leverages external dependencies loosely. 

*   Integration natively pairs with `protoc-gen-perl-upb` (Micro-Protobuf XS) for blazing-fast serialization speeds that preserve memory. The architecture must map `serialize()` and `parse()` functions securely on the fly against the stream without triggering unnecessary Perl scalar (`SV`) copies unless required.

## 4. First-Class Authentication Integration

The library must provide a clean and seamless interface to accept Application Default Credentials (ADC) tokens originating from `google-auth-library-perl`. 

*   Inject active scoped Bearer tokens into the `$curl` HTTP/2 headers efficiently (`authorization: Bearer <token>`).
*   In async deployments, track token lifecycles dynamically and organically request background refreshes before dropping into stream teardowns.

## Summary

By securing these responsibilities within the `Google-gRPC` distribution, you establish a universal, scalable platform. Independent maintainers building drivers for Google Cloud APIs are relieved of writing socket flow control, authentication negotiation, and HTTP/2 packet synchronization. They can exclusively utilize standard `Google::gRPC::Channel` and `Google::gRPC::Call` patterns directly in their XS and Perl bridges.
