feat: improve TaskStore error reporting with domain-specific exceptio…

[kabir]

…ns (#516)

Replace generic RuntimeException with TaskSerializationException and TaskPersistenceException throughout the TaskStore persistence layer.

Wire execptions into MainEventQueueBusProcessor.

Fixes #516 🦕

[gemini-code-assist]

Summary of Changes

Hello @kabir, 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 significantly refines the error reporting mechanism within the TaskStore persistence layer. By replacing broad RuntimeException with a granular hierarchy of domain-specific exceptions, it provides clearer insights into the nature of failures, distinguishing between data serialization issues and underlying storage problems. This enhancement allows for more intelligent error handling, logging, and client communication, enabling better operational visibility and potential retry strategies for transient issues.

Highlights

• New Domain-Specific Exception Hierarchy: Introduced a new exception hierarchy for TaskStore operations, including TaskStoreException as the base, TaskSerializationException for data format issues, and TaskPersistenceException for database/storage failures. This replaces generic RuntimeException for more precise error handling.
• Enhanced JpaDatabaseTaskStore Error Handling: Updated JpaDatabaseTaskStore to catch JsonProcessingException and PersistenceException, re-throwing them as TaskSerializationException and TaskPersistenceException respectively. A new utility method, isTransientDatabaseError, was added to classify database errors as transient or permanent.
• MainEventBusProcessor Integration: Modified MainEventBusProcessor to specifically catch and handle the new TaskSerializationException and TaskPersistenceException. These are now mapped to InternalError events for clients, with distinct logging levels (WARN for transient, ERROR for permanent/serialization) and messages providing retry guidance or intervention requirements.
• Comprehensive Javadoc Updates: Extensive Javadoc has been added or updated across TaskStore, InMemoryTaskStore, and the new exception classes to clearly define the exception contract, usage examples, and handling strategies for different types of persistence failures.
• New Unit Tests for Exception Handling: Added a suite of new unit tests for MainEventBusProcessor and the new exception classes (TaskStoreException, TaskSerializationException, TaskPersistenceException) to ensure correct behavior, message formatting, and transient/non-transient classification.

Changelog

• .gitignore
  • Added backlog/ to ignored paths.
• extras/task-store-database-jpa/src/main/java/io/a2a/extras/taskstore/database/jpa/JpaDatabaseTaskStore.java
  • Imported new exception types: PersistenceException, TaskSerializationException, TaskPersistenceException.
  • Added isTransientDatabaseError method to classify database exceptions.
  • Replaced RuntimeException with TaskSerializationException for JSON processing errors in save, get, and list methods.
  • Introduced TaskPersistenceException for database-related failures in save, get, delete, and list methods, utilizing the isTransientDatabaseError classification.
• server-common/src/main/java/io/a2a/server/events/MainEventBusProcessor.java
  • Imported TaskPersistenceException and TaskSerializationException.
  • Updated Javadoc to detail exception handling for TaskStore persistence failures.
  • Implemented specific catch blocks for TaskSerializationException and TaskPersistenceException, logging them at appropriate levels (ERROR for serialization/permanent persistence, WARN for transient persistence) and wrapping them into InternalError events.
• server-common/src/main/java/io/a2a/server/tasks/InMemoryTaskStore.java
  • Updated Javadoc to clarify the exception behavior of the in-memory store, explaining why it does not throw TaskSerializationException or TaskPersistenceException.
• server-common/src/main/java/io/a2a/server/tasks/TaskPersistenceException.java
  • Added new class TaskPersistenceException extending TaskStoreException.
  • Included a isTransientFailure flag to indicate if a database error is temporary or permanent.
  • Provided various constructors to support different levels of detail and transient flag settings.
• server-common/src/main/java/io/a2a/server/tasks/TaskSerializationException.java
  • Added new class TaskSerializationException extending TaskStoreException.
  • Provided constructors for various scenarios of serialization/deserialization failures.
• server-common/src/main/java/io/a2a/server/tasks/TaskStore.java
  • Updated Javadoc to include a comprehensive 'Exception Contract' section, detailing when to throw TaskSerializationException and TaskPersistenceException.
  • Modified method signatures and Javadoc for save, get, delete, and list to declare throwing the new specific exception types.
• server-common/src/main/java/io/a2a/server/tasks/TaskStoreException.java
  • Added new base exception class TaskStoreException extending A2AServerException.
  • Included a taskId field to provide context for task-related exceptions.
  • Provided constructors to initialize the exception with messages, causes, and task IDs.
• server-common/src/test/java/io/a2a/server/events/MainEventBusProcessorExceptionTest.java
  • Added new unit tests for MainEventBusProcessor to verify its handling of TaskSerializationException and TaskPersistenceException.
  • Tests confirm correct logging levels (ERROR/WARN) and conversion to InternalError events, including preservation of task IDs.
• server-common/src/test/java/io/a2a/server/tasks/AbstractTaskStoreExceptionTest.java
  • Added new abstract base test class AbstractTaskStoreExceptionTest to provide common test methods for TaskStore related exceptions.
• server-common/src/test/java/io/a2a/server/tasks/TaskPersistenceExceptionTest.java
  • Added new unit tests for TaskPersistenceException, extending AbstractTaskStoreExceptionTest.
  • Tests cover constructor variations, the isTransient flag, and real-world transient/non-transient scenarios.
• server-common/src/test/java/io/a2a/server/tasks/TaskSerializationExceptionTest.java
  • Added new unit tests for TaskSerializationException, extending AbstractTaskStoreExceptionTest.
  • Tests cover constructor variations and serialization-specific error contexts.
• server-common/src/test/java/io/a2a/server/tasks/TaskStoreExceptionTest.java
  • Added new unit tests for TaskStoreException, extending AbstractTaskStoreExceptionTest.
  • Tests cover constructor variations and the taskId field.

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 is a significant improvement to error handling within the TaskStore persistence layer. Replacing generic RuntimeExceptions with domain-specific exceptions like TaskSerializationException and TaskPersistenceException provides much clearer and more robust error reporting. The new exception hierarchy is well-designed, thoroughly documented, and supported by a comprehensive test suite. My review includes a few suggestions to further improve the robustness of the transient error detection, enhance logging for better diagnostics, and simplify constructor logic for better maintainability.

[kabir]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a well-defined exception hierarchy for the TaskStore persistence layer, replacing generic RuntimeExceptions with domain-specific TaskSerializationException and TaskPersistenceException. This is a significant improvement for error reporting and handling. The changes are consistently applied across the JpaDatabaseTaskStore, and the MainEventBusProcessor is updated to handle these new exceptions gracefully. The accompanying documentation updates and thorough unit tests are excellent.

I've found a critical issue regarding the exception design where the new exceptions are implemented as checked exceptions but not declared in the TaskStore interface, which will cause compilation errors. Additionally, a key documented feature (isTransient flag) is missing from the implementation. I've left a detailed comment on this.

Once these points are addressed, this will be a solid enhancement to the project's robustness.

[kabir]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a well-designed exception hierarchy for the TaskStore persistence layer, replacing generic RuntimeExceptions with specific TaskSerializationException and TaskPersistenceException. The changes significantly improve error reporting and handling. The TaskStore interface and its implementations are updated accordingly, and the MainEventBusProcessor now gracefully handles these new exceptions by converting them to InternalError events for clients. The documentation has been thoroughly updated to reflect these new contracts, and the changes are accompanied by a comprehensive suite of unit tests. Overall, this is an excellent improvement to the codebase. I have one minor suggestion to remove a redundant catch block for improved code clarity.