Grpc endpoints followup

[badnikhil]

gRPC test rig — follow-up: auth, response metadata & round-trip tests

Follow-up to #94 (which merged the base gRPC test rig). This PR adds the two
remaining gRPC surfaces API Dash needs to exercise — auth-via-metadata and
response metadata — plus a pytest round-trip suite, and documents the
whole service so every feature has a concrete, reproducible recipe.

What this PR adds (on top of #94)

• SecureEcho — auth via call metadata. Accepts authorization: Bearer test-token or x-api-key: test-apikey; anything else → UNAUTHENTICATED. Success echoes [authenticated] <msg>. (grpc/server.py, grpc/proto/apidash_test.proto, docs/grpc/auth.md)
• EchoMetadata response metadata — in addition to echoing your request metadata into the body, it now returns initial metadata (x-server, x-echoed-count) and trailing metadata (x-trailer), so response-metadata handling can be tested. (grpc/server.py, docs/grpc/metadata.md)
• tests/grpc/test_grpc.py — 12 round-trip tests (one per feature) against a running server. Protobuf stubs are generated on the fly from the proto at collection time (nothing generated is committed); the module skips gracefully when grpcio/-tools are missing or no server is reachable, so CI stays green. (requirements-dev.txt: grpcio + grpcio-tools + grpcio-reflection; docs/grpc/README.md: Tests section)

Run it

docker compose -f grpc/docker-compose.yml up --build

Point API Dash at localhost:9000 (plaintext) or localhost:9001 (TLS → Use TLS + Allow Invalid Certificates). Discover methods via Reflect, or import grpc/proto/apidash_test.proto and Fetch services.

Full service reference — apidash.test.TestService

Every method, and how to reproduce it in API Dash (each also has a page under docs/grpc/):

Feature	Method	Behavior	Reproduce in API Dash
Unary	Echo	echoes your message + server time + an incrementing seq	send {message} → echoed back
Unary (random)	GetRandomUser	a random mock user (name / email / age / country)	send empty → populated user
Server streaming	StreamTicks	N ticks of random values (default 10)	set count → receive N messages
Client streaming	SumNumbers	fold streamed numbers → sum / count / average	stream numbers → totals
Bidirectional	Chat	echoes each message back with a server timestamp	stream messages → echoes
Metadata (req + resp)	EchoMetadata	echoes request metadata into the body; returns x-server/x-echoed-count (initial) + x-trailer (trailing)	add metadata → see it echoed + response headers
Auth	SecureEcho	requires authorization: Bearer test-token or x-api-key: test-apikey, else UNAUTHENTICATED	Auth tab → Bearer test-token (or API-key header x-api-key: test-apikey) → [authenticated] …; none/wrong → UNAUTHENTICATED
Errors	RaiseError	returns the gRPC status code you request	set code=5 → NOT_FOUND
Reflection	grpc.reflection.v1alpha.ServerReflection	service/method discovery (API Dash tries v1, falls back to v1alpha)	hit Reflect

Tests

docker compose -f grpc/docker-compose.yml up --build -d
pip install -r requirements-dev.txt
pytest tests/grpc/test_grpc.py

12 passed against a live server — reflection, Echo, GetRandomUser, StreamTicks (count=5 → 5 ticks), SumNumbers, Chat (bidi), EchoMetadata (request echo + initial/trailing response metadata), SecureEcho ×4 (no creds → UNAUTHENTICATED, Bearer → ok, x-api-key → ok, wrong → UNAUTHENTICATED), RaiseError code=5 → NOT_FOUND. Skips (does not fail) when grpcio/-tools are missing or no server is on localhost:9000.

Why gRPC needs its own Docker (not a FastAPI route)

gRPC is HTTP/2-based, with its own wire framing, Protobuf messages, server reflection and long-lived streams — it can't be a FastAPI route, and Azure App Service's single HTTP/HTTPS port can't host it (same reason as the MQTT rig). So local testing ships a real gRPC server via Docker, defining our own apidash.test.TestService with mock/random data so every feature has a concrete, reproducible use-case.

Scope: local testing only. A shared, always-on hosted gRPC endpoint is a separate, maintainer-owned decision.