Expose Pod, Image, and Gateway over HTTP using GRPC-Gateway (#1391)

<!-- This is an auto-generated description by cubic. -->

## Summary by cubic
Expose Pod, Image, and Gateway gRPC services over HTTP using
grpc-gateway, mounted at /api/v1/grpc-gateway. This lets clients call
JSON endpoints without a gRPC client.

- **New Features**
- Added grpc-gateway mux and server wiring (initGrpcGateway) and mounted
at /api/v1/grpc-gateway/*.
- Registered PodService, ImageService, and GatewayService handlers
against the gRPC port.
- Authorization header is forwarded to gRPC metadata; gRPC interceptors
handle auth.
- Updated gen_proto.sh to generate grpc-gateway code for
pod/image/gateway with generate_unbound_methods=true.
- Added generated reverse-proxy files: proto/pod.pb.gw.go,
proto/image.pb.gw.go, proto/gateway.pb.gw.go.

- **Dependencies**
  - Added protoc-gen-grpc-gateway@v2.27.1 to bin/setup.sh.
- Promoted github.com/grpc-ecosystem/grpc-gateway/v2 v2.25.0 to a direct
dependency.

<!-- End of auto-generated description by cubic. -->

Author: cooper-grc

Makefile

@@ -65,6 +65,14 @@ stop:
 protocol:
 	uv run ./bin/gen_proto.sh
 
+openapi:
+	@echo "Generating OpenAPI schemas..."
+	@mkdir -p docs/openapi
+	protoc -I ./googleapis -I ./pkg/types -I ./pkg/abstractions/pod/ --openapiv2_out=./docs/openapi --openapiv2_opt logtostderr=true ./pkg/abstractions/pod/pod.proto
+	protoc -I ./googleapis -I ./pkg/abstractions/image/ --openapiv2_out=./docs/openapi --openapiv2_opt logtostderr=true ./pkg/abstractions/image/image.proto
+	protoc -I ./googleapis -I ./pkg/types -I ./pkg/gateway/ --openapiv2_out=./docs/openapi --openapiv2_opt logtostderr=true ./pkg/gateway/gateway.proto
+	@echo "OpenAPI schemas generated in docs/openapi/"
+
 verify-protocol:
 	./bin/verify_proto.sh
 

bin/gen_proto.sh

@@ -21,17 +21,17 @@ protoc -I ./pkg/types/ --go_out=./proto --go_opt=paths=source_relative --go-grpc
 protoc -I ./pkg/types/ --python_betterproto_beta9_out=./sdk/src/beta9/clients/ ./pkg/types/types.proto
 
 protoc -I ./pkg/scheduler/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/scheduler/scheduler.proto
-protoc -I ./pkg/types -I ./pkg/gateway/ -I ./pkg/worker/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/worker/worker.proto
-protoc -I ./pkg/types -I ./pkg/gateway/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/gateway/gateway.proto
-protoc -I ./pkg/types -I ./pkg/gateway/ --python_betterproto_beta9_out=./sdk/src/beta9/clients/ ./pkg/gateway/gateway.proto
+protoc -I ./googleapis -I ./pkg/types -I ./pkg/gateway/ -I ./pkg/worker/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/worker/worker.proto
+protoc -I ./googleapis -I ./pkg/types -I ./pkg/gateway/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/gateway/gateway.proto
+protoc -I ./googleapis -I ./pkg/types -I ./pkg/gateway/ --python_betterproto_beta9_out=./sdk/src/beta9/clients/ ./pkg/gateway/gateway.proto
 
 # Repository services
-protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/types -I ./pkg/gateway/services/repository/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/gateway/services/repository/container_repo.proto
-protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/types -I ./pkg/gateway/services/repository/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/gateway/services/repository/worker_repo.proto
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/types -I ./pkg/gateway/services/repository/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/gateway/services/repository/container_repo.proto
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/types -I ./pkg/gateway/services/repository/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/gateway/services/repository/worker_repo.proto
 
 # Generate code for abstractions
-protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/abstractions/image/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/abstractions/image/image.proto
-protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/abstractions/image/ --python_betterproto_beta9_out=./sdk/src/beta9/clients/ ./pkg/abstractions/image/image.proto
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/abstractions/image/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/abstractions/image/image.proto
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/abstractions/image/ --python_betterproto_beta9_out=./sdk/src/beta9/clients/ ./pkg/abstractions/image/image.proto
 
 protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/abstractions/map/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/abstractions/map/map.proto
 protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/abstractions/map/ --python_betterproto_beta9_out=./sdk/src/beta9/clients/ ./pkg/abstractions/map/map.proto
@@ -51,8 +51,16 @@ protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/abstractions/taskqueue/ --python_betterp
 protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/abstractions/endpoint/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/abstractions/endpoint/endpoint.proto
 protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/abstractions/endpoint/ --python_betterproto_beta9_out=./sdk/src/beta9/clients/ ./pkg/abstractions/endpoint/endpoint.proto
 
-protoc -I $PROTOC_INCLUDE_PATH  -I ./pkg/types -I ./pkg/abstractions/pod/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/abstractions/pod/pod.proto
-protoc -I $PROTOC_INCLUDE_PATH  -I ./pkg/types -I ./pkg/abstractions/pod/ --python_betterproto_beta9_out=./sdk/src/beta9/clients/ ./pkg/abstractions/pod/pod.proto
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/types -I ./pkg/abstractions/pod/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/abstractions/pod/pod.proto
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/types -I ./pkg/abstractions/pod/ --grpc-gateway_out=./proto --grpc-gateway_opt paths=source_relative --grpc-gateway_opt generate_unbound_methods=true ./pkg/abstractions/pod/pod.proto 
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/types -I ./pkg/abstractions/pod/ --openapiv2_out=./docs/openapi --openapiv2_opt logtostderr=true ./pkg/abstractions/pod/pod.proto
+
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/abstractions/image/ --grpc-gateway_out=./proto --grpc-gateway_opt paths=source_relative --grpc-gateway_opt generate_unbound_methods=true ./pkg/abstractions/image/image.proto
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/abstractions/image/ --openapiv2_out=./docs/openapi --openapiv2_opt logtostderr=true ./pkg/abstractions/image/image.proto
+
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/types -I ./pkg/gateway/ --grpc-gateway_out=./proto --grpc-gateway_opt paths=source_relative --grpc-gateway_opt generate_unbound_methods=true ./pkg/gateway/gateway.proto
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/types -I ./pkg/gateway/ --openapiv2_out=./docs/openapi --openapiv2_opt logtostderr=true ./pkg/gateway/gateway.proto
+protoc -I $PROTOC_INCLUDE_PATH -I ./googleapis -I ./pkg/types -I ./pkg/abstractions/pod/ --python_betterproto_beta9_out=./sdk/src/beta9/clients/ ./pkg/abstractions/pod/pod.proto
 
 protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/abstractions/output/ --go_out=./proto --go_opt=paths=source_relative --go-grpc_out=./proto --go-grpc_opt=paths=source_relative ./pkg/abstractions/output/output.proto
 protoc -I $PROTOC_INCLUDE_PATH -I ./pkg/abstractions/output/ --python_betterproto_beta9_out=./sdk/src/beta9/clients/ ./pkg/abstractions/output/output.proto

bin/setup.sh

@@ -67,5 +67,7 @@ check_status
 
 echo "=> Installing go2proto"
 go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.31.0
+go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@v2.27.1
+go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest
 go install github.com/beam-cloud/go2proto@latest
 check_status

docs/openapi/README.md

@@ -0,0 +1,46 @@
+# OpenAPI Schemas
+
+This directory contains automatically generated OpenAPI (Swagger) schemas for the Beta9 gRPC Gateway endpoints.
+
+## Generated Schemas
+
+- `pod.swagger.json` - Pod service API endpoints
+- `image.swagger.json` - Image service API endpoints  
+- `gateway.swagger.json` - Gateway service API endpoints
+
+## How to Generate
+
+To regenerate the OpenAPI schemas, run:
+
+```bash
+make openapi
+```
+
+Or to regenerate all protocol buffers including OpenAPI:
+
+```bash
+make protocol
+```
+
+## Viewing the Schemas
+
+You can view these schemas using:
+
+1. **Swagger UI**: Upload the JSON files to [Swagger Editor](https://editor.swagger.io/)
+2. **Local Swagger UI**: Use tools like `swagger-ui-serve` or similar
+3. **API Documentation Tools**: Import into tools like Postman, Insomnia, etc.
+
+## API Endpoints
+
+The schemas include all the HTTP endpoints that gRPC Gateway exposes, including:
+
+- **Pod Service**: Container management, file operations, process control
+- **Image Service**: Container image operations
+- **Gateway Service**: Core gateway functionality
+
+## Notes
+
+- These schemas are automatically generated from `.proto` files
+- The HTTP annotations in the proto files define the REST endpoints
+- All endpoints support the same authentication and authorization as the gRPC services
+- The schemas include request/response models, parameter validation, and error responses