Skip to content

Commit 6e3f4eb

Browse files
committed
docs(api): send directives as call metadata on a gRPC listener (MAG-3814)
The Directives page said directives are HTTP headers, and every example was curl, so a gRPC client had no way to tell that lava-select-provider works for it. It does: the gRPC listener passes call metadata through the same directive parsing as an HTTP request (smart-router#415 adds the regression test). The page now says so and shows the grpcurl / Go / Python forms, plus that response headers come back as lowercase metadata.
1 parent a719c1d commit 6e3f4eb

2 files changed

Lines changed: 32 additions & 2 deletions

File tree

‎docs/api/directives.md‎

Lines changed: 31 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description: "Per-request header directives to bypass the cache, pin a specific
55

66
# Directives
77

8-
Override Smart Router's default behaviour for a single request by setting HTTP headers. Use them when the default routing, caching, or timeout policy isn't what you want for this specific call.
8+
Override Smart Router's default behaviour for a single request by setting request headers: HTTP headers, or call metadata on a gRPC listener ([Over gRPC](#over-grpc)). Use them when the default routing, caching, or timeout policy isn't what you want for this specific call.
99

1010
## Request headers at a glance
1111

@@ -44,6 +44,8 @@ curl -X POST http://127.0.0.1:3360 \
4444
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
4545
```
4646

47+
A gRPC call pins the same way, with the header sent as call metadata. See [Over gRPC](#over-grpc).
48+
4749
## Force a cache refresh
4850

4951
```
@@ -137,6 +139,34 @@ curl -X POST http://127.0.0.1:3360 \
137139
-d '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x..."],"id":1}'
138140
```
139141

142+
## Over gRPC
143+
144+
A gRPC listener reads the same directives from **call metadata**. gRPC sends metadata as HTTP/2 headers, and the router passes it through the same directive parsing as an HTTP request. Use the names above unchanged:
145+
146+
```bash
147+
grpcurl -plaintext \
148+
-H 'lava-select-provider: my-cosmos-upstream-1' \
149+
127.0.0.1:3361 \
150+
cosmos.bank.v1beta1.Query/TotalSupply
151+
```
152+
153+
In code, attach the metadata to the call:
154+
155+
=== "Go"
156+
157+
```go
158+
ctx := metadata.AppendToOutgoingContext(ctx, "lava-select-provider", "my-cosmos-upstream-1")
159+
resp, err := client.TotalSupply(ctx, &banktypes.QueryTotalSupplyRequest{})
160+
```
161+
162+
=== "Python"
163+
164+
```python
165+
response = stub.TotalSupply(request, metadata=[("lava-select-provider", "my-cosmos-upstream-1")])
166+
```
167+
168+
The [response headers](#response-headers) come back as response metadata with lowercase names. `lava-provider-address` names the upstream that served the call, and `grpcurl -v` prints it.
169+
140170
## Response headers
141171

142172
Smart Router annotates every response with metadata about how the relay was served. These are the primary signal for debugging routing and failover from the client side.

‎docs/configuration/failover/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Smart Router's failover policies fall into three groups:
3434
| Group | Examples | Where tuned |
3535
|---|---|---|
3636
| CLI flags | `--set-relay-retry-limit`, `--default-processing-timeout`, `--min-relay-timeout` | startup args |
37-
| Per-request headers | `lava-relay-timeout`, `lava-select-provider` | HTTP headers — see [Request headers](../../api/directives.md) |
37+
| Per-request headers | `lava-relay-timeout`, `lava-select-provider` | HTTP headers, or gRPC call metadata — see [Request headers](../../api/directives.md) |
3838
| Chain-derived defaults | integrity lag threshold, hedge tick | computed from the chain spec; not currently exposed as YAML |
3939

4040
Where a knob isn't tunable, that's called out on the policy's page.

0 commit comments

Comments
 (0)