feat: implement server interceptor at handler level

[guglielmo-san]

Description

Implement server interceptor, before and after the call to the default request handler.

Interceptors support "early return" both before and after handler invocation. For early return before handler invocation, only "after" methods of executed interceptors are invoked.

Release-As: 0.3.6

[gemini-code-assist]

Summary of Changes

Hello @guglielmo-san, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a robust server-side interceptor pattern for the request handling layer. It enables developers to inject custom logic both before and after the execution of any A2ARequestHandler method, providing powerful capabilities such as request/response modification and early termination of handler calls. This feature significantly enhances the extensibility and modularity of the server's request processing.

Highlights

• New Interceptor Mechanism: Introduced a HandlerInterceptor interface with before and after hooks, enabling custom logic execution around request handler calls.
• Early Return Support: Interceptors can now short-circuit the execution flow, either before the handler is called (returning a value directly) or after (stopping further after interceptors in the chain).
• Centralized Interception Logic: A new RequestHandlerInterceptor class wraps the DefaultRequestHandler to apply these interceptors consistently across all A2A request handler methods.
• Streaming Method Interception: Special handling is implemented for streaming methods like sendMessageStream and resubscribe to allow interception of individual items within the async generator.
• Enhanced Type Safety: New types such as HandlerCallInput, HandlerCallResult, and A2AStreamEventData have been introduced to improve type safety and clarity for the interceptor pattern and streaming events.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request implements a server-side interceptor for request handlers, which is a significant feature for managing cross-cutting concerns. The implementation uses the Decorator pattern to wrap the DefaultRequestHandler and introduce before and after hooks. The new RequestHandlerInterceptor class, along with its supporting interfaces and types, is well-designed. The pull request also includes a comprehensive suite of tests for the new functionality. I have identified a potential race condition in the streaming implementation due to missing await calls and have also provided a suggestion to improve the design's flexibility and testability by applying the Dependency Inversion Principle.