gRPC Scripting API Support in Bruno (RFC)

[sanish-bruno]

gRPC Scripting Support in Bruno (Early Preview)

We're actively working on gRPC scripting support in Bruno, and we'd love to get early feedback from the community.

Planned Scripting APIs

We plan to expose req and res objects for gRPC, similar to HTTP, with support for both unary and streaming RPCs.

Request APIs

• req.methodPath
• req.getMessage(index)
• req.getMessages()
• req.messages (property access, equivalent to req.getMessages())
• req.setMessage(index, data)
• req.addMessage(data)
• req.addMessages(data[])
• req.getMetadata(key)
• req.metadata (property access, get all metadata)
• req.hasMetadata(key)
• req.setMetadata(key, value)
• req.cancel()
• req.end()

Response APIs

• res.getMessage(index)
• res.getMessages()
• res.messages (property access, equivalent to res.getMessages(), gRPC body equivalent)
• res.getMetadata(key)
• res.metadata (property access, get all metadata)
• res.hasMetadata() (check if metadata exists)
• res.getTrailers(key)
• res.hasTrailers() (check if trailers exist)
• res.getStatus() (get gRPC status code)
• res.getStatusText() (get gRPC status text)
• res.responseTime
• res.status

These APIs are designed to work consistently across:

• Unary
• Server streaming
• Client streaming
• Bidirectional streaming RPCs

Event-based Hooks

Unlike HTTP requests which use pre-request and post-response scripts, gRPC requests will use an event-based Hooks system. This approach is better suited for gRPC's streaming nature and allows for more granular control over the request/response lifecycle.

Why event-based hooks for gRPC?

• gRPC supports streaming RPCs where multiple messages can be sent/received over time
• Traditional pre-request/post-response scripts don't fit well with streaming workflows
• Event-based hooks allow you to react to specific events as they occur during the RPC lifecycle

Hooks can be defined at:

• Request level
• Folder level
• Collection level

Planned events include:

• beforeInvoke - Called before the gRPC call is invoked (similar to pre-request)
• afterResponse - Called after the gRPC call completes (similar to post-response)
• onMessage - Called for each incoming message in streaming RPCs (server streaming, bidirectional)

💡 We'd love your input! Are there other events you'd find useful for gRPC scripting? Please share your ideas and use cases - they'll help us design a more comprehensive hooks system. (ex. onError)

The API namespaces and exact hook signatures are yet to be finalized

We'd Love Your Feedback ❤️

If you use gRPC heavily or have experience with scripting in other tools, your input will help shape this feature.

Thanks for helping us build better gRPC support in Bruno! 🚀

[antoniovalentini]

Hi team, thanks for this. It's gonna be very useful.

My use case is fairly simple. In my service (unary calls) I have 2 main things to do:

• Pre-request validation: validate the JSON request fields before they are serialized and sent (e.g., checking UUID formats or range constraints that aren't strictly enforced by the .proto file), create guids, set datetimes and so on
• Post-response evaluation: capture fields from a successful response (e.g., an id or a session_token) and store them in environment variables using bru.setEnvVar to chain requests together

Your proposal covers way more than I personally need 😄

I just have a tiny question on status codes. How does the team plan to represent gRPC status codes in the scripting API? Will you stick to the standard 0-16 integer range? Or will you do any arbitrary mapping?

Thank you so much for your commitment!

[sanish-bruno]

@antoniovalentini we will be sticking to the 0 - 16 range for now! would you care to explain more on the arbitrary mapping part?

[antoniovalentini]

Nothing major. I just wanted to make sure there wasn't any mapping planned between gRPC status codes and HTTP ones for instance. Although I don't think there's even a 1:1 mapping between them.

[LunaticoCR]

Thanks for putting this together @sanish-bruno ! This would be a massive improvement.
One thing I would suggest is why not align the event names to gRPC terminology?
So instead of:

• beforeInvoke
• afterResponse
• onMessage

It could be:

• channelReady (Represents the moment the connection has been established)
• onNext (represents each message being sent)
• onCompleted (all messages have been sent)
• onError (this could be a new event type to do something if an error is detected)

Also, onNext and onCompleted can be generated both server and client side, would it make sense to add the ability to add hooks on both?