feat: Zero-downtime support for Database migration

[sokoliva]

Description

The old 0.3 version is not able to read the 1.0 entries from database because of the inconsistencies between 1.0 and 3.0 data types. This applies to both DatabaseTaskStore and DatabasePushNotificationConfigStore. This PR fixes this issue by allowing users to write 0.3 compatible entires during migration period.

Changes

• adds new conversion methods to compat/0_3/conversions.py
• update DatabaseTaskStore and DatabasePushNotificationConfigStore to accept new conversion methods
• utilize new conversion methods of DatabaseTaskStore and DatabasePushNotificationConfigStore

Tested

Created a database using 0.3 spec containing populated tables task and push_notification_configs. Ran uv run a2a-db using 1.0 spec against the database and added new entries using the new Zero-downtime feature, DatabaseTaskStore.core_to_model_conversion = core_to_compat_task_model and DatabasePushNotificationConfigStore.core_to_model_conversion = core_to_compat_push_notification_config_model. Succesfully read new entries using 0.3 spec.

Fixes #811 🦕

[gemini-code-assist]

Summary of Changes

Hello, 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 crucial changes to support zero-downtime database migrations by addressing data type incompatibilities between older (v0.3) and newer (v1.0) data models. It provides a mechanism for database stores to seamlessly convert between these versions, ensuring that existing 0.3 entries can be read and new 0.3 compatible entries can be written during a transition phase, thus preventing service disruption.

Highlights

• New Compatibility Conversion Methods: Introduced new conversion methods in a2a.compat.v0_3.conversions to handle data type inconsistencies between v0.3 and v1.0 for Task and PushNotificationConfig models, facilitating seamless data migration.
• Database Store Integration: Updated DatabaseTaskStore and DatabasePushNotificationConfigStore to leverage these new conversion methods, enabling them to read and write 0.3 compatible entries during a migration period.
• Flexible Conversion Hooks: Implemented flexible conversion hooks (core_to_model_conversion and model_to_core_conversion) in the database stores, allowing custom logic for data serialization and deserialization during the migration.

Changelog

• src/a2a/compat/v0_3/conversions.py
  • Added Fernet and database model imports.
  • Implemented core_to_compat_task_model for converting v1.0 Task to v0.3 TaskModel.
  • Implemented compat_task_model_to_core for converting v0.3 TaskModel back to v1.0 Task.
  • Implemented core_to_compat_push_notification_config_model for converting v1.0 TaskPushNotificationConfig to v0.3 PushNotificationConfigModel, with optional encryption.
  • Implemented compat_push_notification_config_model_to_core for converting v0.3 PushNotificationConfigModel back to v1.0 TaskPushNotificationConfig.
• src/a2a/server/tasks/database_push_notification_config_store.py
  • Updated imports to specifically include compat_push_notification_config_model_to_core.
  • Added core_to_model_conversion and model_to_core_conversion attributes to DatabasePushNotificationConfigStore for custom conversion logic.
  • Modified _to_orm and _from_orm methods to conditionally use the new conversion hooks.
  • Refactored _parse_config to utilize the new compat_push_notification_config_model_to_core function.
• src/a2a/server/tasks/database_task_store.py
  • Added TYPE_CHECKING import.
  • Removed direct import of types_v03.
  • Added core_to_model_conversion and model_to_core_conversion attributes to DatabaseTaskStore for custom conversion logic.
  • Modified _to_orm and _from_orm methods to conditionally use the new conversion hooks.
  • Refactored _from_orm to utilize the new conversions.compat_task_model_to_core function for legacy tasks.
• tests/compat/v0_3/test_conversions.py
  • Imported new conversion functions and database models, including Fernet.
  • Added test_task_db_conversion to verify Task model conversions.
  • Added test_push_notification_config_db_conversion to verify PushNotificationConfig model conversions without encryption.
  • Added test_push_notification_config_persistence_conversion_with_encryption to verify PushNotificationConfig model conversions with encryption.
• tests/server/tasks/test_database_push_notification_config_store.py
  • Imported MagicMock and new conversion functions.
  • Added test_custom_conversion to verify the functionality of the new conversion hooks.
  • Added test_core_to_0_3_model_conversion to test storing and retrieving v0.3 push notification configs using the new conversion utilities.
• tests/server/tasks/test_database_task_store.py
  • Imported MagicMock and new conversion functions.
  • Added test_custom_conversion to verify the functionality of the new conversion hooks.
  • Added test_core_to_0_3_model_conversion to test storing and retrieving v0.3 tasks using the new conversion utilities.

Activity

• No specific activity (comments, reviews, or progress updates) has been recorded for this pull request yet.

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

The pull request introduces new conversion utilities in src/a2a/compat/v0_3/conversions.py to facilitate persistence of v1.0 core protobuf Task and TaskPushNotificationConfig objects into v0.3 JSON-structured SQLAlchemy models, including encryption support for push notification configurations. The DatabaseTaskStore and DatabasePushNotificationConfigStore classes are updated to allow injecting these custom conversion functions, overriding the default serialization logic. New tests validate these conversion flows. Review comments suggest removing an unreliable hasattr(conversion, '__func__') check in both database stores and addressing minor stylistic issues by removing trailing commas in import statements.

[github-actions]

🧪 Code Coverage (vs 1.0-dev)

⬇️ Download Full Report

	Base	PR	Delta
src/a2a/server/tasks/database_push_notification_config_store.py	94.74%	95.14%	🟢 +0.40%
src/a2a/server/tasks/database_task_store.py	90.91%	91.52%	🟢 +0.61%
Total	89.89%	89.94%	🟢 +0.05%

Generated by coverage-comment.yml