# Protocol Buffer Generated Files

This directory contains Python bindings generated from protocol buffer definitions.

## Current Status: MVP with Pre-generated Bindings

For the MVP phase, we're using **pre-generated proto bindings** that are committed to the repository. This simplifies the build process and avoids proto toolchain dependencies during development.

## Files

- `cas_simple_pb2.py` - Message definitions (Digest, Request/Response types)
- `cas_simple_pb2_grpc.py` - Service stub and servicer (ContentAddressableStorage)
- `cas_simple_pb2.pyi` - Type hints for IDE support
- `__init__.py` - Package initialization

## Why Pre-generated?

✅ **Simplicity** - No proto compilation needed for development  
✅ **Reproducibility** - Same bindings for all developers  
✅ **Fast builds** - No protoc step in CI/CD  
✅ **Version controlled** - Exact proto definitions tracked  

## Future: Full REAPI Integration (Week 2+)

When integrating full REAPI specification:

1. **Vendor proto sources** - Download .proto files from bazelbuild/remote-apis
2. **Generate bindings** - Use grpc_tools.protoc to create Python files
3. **Organize by version** - Separate v2, v3 into subdirectories:
   ```
   generated/
     simple/      # MVP proto (deprecated later)
     v2/          # REAPI v2 bindings
     v3/          # REAPI v3 bindings (future)
   ```

## Proto Package Names

The generated code uses specific package names for gRPC service registration:

- **MVP**: `build.bazel.remote.cas.v1` (simplified)
- **REAPI v2**: `build.bazel.remote.execution.v2` (standard)
- **REAPI v3**: `build.bazel.remote.execution.v3` (future)

These package names allow multiple versions to coexist on the same gRPC server.

## Regenerating (Future)

When proto sources are available:

```bash
# From project root
uv run python -m grpc_tools.protoc \
  -I protos \
  --python_out=src/cascache_server/api/generated \
  --grpc_python_out=src/cascache_server/api/generated \
  --pyi_out=src/cascache_server/api/generated \
  protos/cas_simple.proto

# Fix relative imports
sed -i 's/^import cas_simple_pb2/from . import cas_simple_pb2/' \
  src/cascache_server/api/generated/cas_simple_pb2_grpc.py
```

## Source Proto Definition (Reference)

The MVP proto was based on this simplified definition:

```proto
syntax = "proto3";
package build.bazel.remote.cas.v1;

message Digest {
  string hash = 1;
  int64 size_bytes = 2;
}

service ContentAddressableStorage {
  rpc FindMissingBlobs(FindMissingBlobsRequest) returns (FindMissingBlobsResponse);
  rpc BatchReadBlobs(BatchReadBlobsRequest) returns (BatchReadBlobsResponse);
  rpc BatchUpdateBlobs(BatchUpdateBlobsRequest) returns (BatchUpdateBlobsResponse);
}
```

For production use, we'll migrate to the full [REAPI specification](https://github.com/bazelbuild/remote-apis).
