You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pylons-grpc-relay/README.md
+49-1Lines changed: 49 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -214,4 +214,52 @@ The relay server handles the conversion between:
214
214
```
215
215
216
216
## Testing
217
-
See [INCIDENT_REPORT.md](INCIDENT_REPORT.md) for detailed testing procedures and data contracts.
217
+
See [INCIDENT_REPORT.md](INCIDENT_REPORT.md) for detailed testing procedures and data contracts.
218
+
219
+
## Enhanced Diagnostics and Patching (May 2025)
220
+
221
+
The gRPC relay has been significantly enhanced to aid in diagnosing and incrementally fixing issues with gRPC calls, particularly those originating from clients that might not correctly wrap messages in the `google.protobuf.Any` type as expected by the target Pylons node.
222
+
223
+
### Key Features:
224
+
225
+
1.**Detailed Logging**:
226
+
* The relay now produces verbose logs (to `grpc_relay.log` and stdout) for each gRPC call.
227
+
***`[MSG_FLOW]`**: Traces messages at various stages:
228
+
*`request_received_by_relay`: Initial incoming request with metadata.
229
+
*`client_msg_raw_unpacked`: After the relay receives a message from the client, showing its raw `TypeUrl` and a snippet of its `Value`. This is crucial for seeing what the client actually sent.
230
+
*`client_msg_patched_pre_send` / `client_msg_unpatched_pre_send`: Shows the message just before it's sent to the target, indicating if a patch was applied.
231
+
*`target_msg_sent_successfully`: Confirmation of successful send to target.
232
+
*`target_response_received_by_relay`: Response received from the target.
233
+
*`target_response_sent_to_client`: Confirmation of successful send of target's response back to the client.
234
+
***`[ERROR_DETAIL]`**: Provides detailed context when an error occurs, including:
235
+
*`Method`: The gRPC method name.
236
+
*`Stage`: Where in the relay's processing the error happened (e.g., `client_recv_error`, `target_send_error`, `patch_application_error`).
237
+
*`MsgTypeURL`, `MsgValueLen`, `MsgValueSnippet`: Details of the message being processed when the error occurred.
238
+
*`Metadata`: Incoming request metadata.
239
+
***`PatchInfo`**: Both `[MSG_FLOW]` and `[ERROR_DETAIL]` logs include patch information:
240
+
*`PatchNotAttempted`: No patch was tried for this message.
241
+
*`PatchAttempted(Name:..., Success:false, ...)`: A patch was tried but was not successful (e.g., conditions for patching weren't fully met, or the patch logic itself had an issue).
242
+
*`PatchApplied(Name:..., Success:true, OriginalURL:..., PatchedURL:...)`: A patch was successfully applied, showing the original and new `TypeUrl`.
* The relay now includes a mechanism to "patch" incoming messages before forwarding them to the target gRPC server.
246
+
* Currently, the primary patch (`any_typeurl_rewrap`) focuses on fixing issues where client messages are not correctly wrapped in `google.protobuf.Any`.
247
+
* It uses a predefined map `knownRequestPayloadTypeURLs` in `relay.go`. This map links gRPC method names (e.g., `/pylons.pylons.Query/ListItemByOwner`) to their expected `TypeUrl` (e.g., `type.googleapis.com/pylons.pylons.QueryListItemByOwnerRequest`).
248
+
***How it works**:
249
+
1. If an incoming message's `TypeUrl` is empty or different from the `expectedTypeURL` for that method, AND the message `Value` is not empty:
250
+
* The relay assumes `Value` contains the raw protobuf bytes of the actual request.
251
+
* It creates a new `anypb.Any` message, setting its `TypeUrl` to the `expectedTypeURL` and its `Value` to the original message's `Value`.
252
+
2. If the incoming message's `TypeUrl` already matches the expected one, or if no specific mapping exists for the method, the message is passed through as-is (or with minimal intervention).
253
+
***Adding New Patches/Mappings**: To support fixing new methods or refining existing ones, update the `knownRequestPayloadTypeURLs` map in `relay.go`.
254
+
255
+
3.**Identifying Incorrect Calls**:
256
+
* Look for `[ERROR_DETAIL]` logs, especially "target_send_error" with "failed to marshal" messages.
257
+
* Examine the preceding `[MSG_FLOW]` logs for that method, particularly the `client_msg_raw_unpacked` stage. This will show the `TypeUrl` and `Value` snippet sent by the client.
258
+
* If `TypeUrl` is empty or incorrect, and `Value` seems to contain the actual payload, this method is a candidate for adding/updating its entry in `knownRequestPayloadTypeURLs`.
259
+
260
+
### Environment Variables:
261
+
262
+
*`TARGET_ADDRESS`: The address (host:port) of the target gRPC server (e.g., `pylons.api.m.stavr.tech:443`). Do NOT include `http://` or `https://`.
263
+
*`PORT`: The port on which this relay server will listen (e.g., `50051`).
264
+
265
+
This enhanced relay aims to simplify debugging and allow for rapid, iterative fixes to client-server gRPC communication issues without requiring immediate client-side code changes.
0 commit comments