feat(server): implement Resource Scoping for tasks and push notifications

.github/actions/spelling/allow.txt

@@ -92,6 +92,7 @@ openapiv2
 opensource
 otherurl
 pb2
+poolclass
 postgres
 POSTGRES
 postgresql

pyproject.toml

@@ -39,6 +39,7 @@ postgresql = ["sqlalchemy[asyncio,postgresql-asyncpg]>=2.0.0"]
 mysql = ["sqlalchemy[asyncio,aiomysql]>=2.0.0"]
 signing = ["PyJWT>=2.0.0"]
 sqlite = ["sqlalchemy[asyncio,aiosqlite]>=2.0.0"]
+db-cli = ["alembic>=1.14.0"]
 
 sql = ["a2a-sdk[postgresql,mysql,sqlite]"]
 
@@ -49,6 +50,7 @@ all = [
   "a2a-sdk[grpc]",
   "a2a-sdk[telemetry]",
   "a2a-sdk[signing]",
+  "a2a-sdk[db-cli]",
 ]
 
 [project.urls]
@@ -347,3 +349,17 @@ docstring-code-format = true
 docstring-code-line-length = "dynamic"
 quote-style = "single"
 indent-style = "space"
+
+
+[tool.alembic]
+
+# path to migration scripts.
+script_location = "src/a2a/migrations"
+
+# additional paths to be prepended to sys.path. defaults to the current working directory.
+prepend_sys_path = [
+    "src"
+]
+
+[project.scripts]
+a2a-db = "a2a.a2a_db_cli:run_migrations"

src/a2a/a2a_db_cli.py

@@ -0,0 +1,156 @@
+import argparse
+import logging
+import os
+
+from importlib.resources import files
+
+
+try:
+    from alembic import command
+    from alembic.config import Config
+
+except ImportError as e:
+    raise ImportError(
+        "CLI requires Alembic. Install with: 'pip install a2a-sdk[db-cli]'."
+    ) from e
+
+
+def _add_shared_args(
+    parser: argparse.ArgumentParser, is_sub: bool = False
+) -> None:
+    """Add common arguments to the given parser."""
+    prefix = 'sub_' if is_sub else ''
+    parser.add_argument(
+        '--database-url',
+        dest=f'{prefix}database_url',
+        help='Database URL to use for the migrations. If not set, the DATABASE_URL environment variable will be used.',
+    )
+    parser.add_argument(
+        '--tasks-table',
+        dest=f'{prefix}tasks_table',
+        help='Custom tasks table to update. If not set, the default is "tasks".',
+    )
+    parser.add_argument(
+        '--push-notification-configs-table',
+        dest=f'{prefix}push_notification_configs_table',
+        help='Custom push notification configs table to update. If not set, the default is "push_notification_configs".',
+    )
+    parser.add_argument(
+        '-v',
+        '--verbose',
+        dest=f'{prefix}verbose',
+        help='Enable verbose output (sets sqlalchemy.engine logging to INFO)',
+        action='store_true',
+    )
+    parser.add_argument(
+        '--sql',
+        dest=f'{prefix}sql',
+        help='Run migrations in sql mode (generate SQL instead of executing)',
+        action='store_true',
+    )
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the argument parser for the migration tool."""
+    parser = argparse.ArgumentParser(description='A2A Database Migration Tool')
+
+    # Global options
+    parser.add_argument(
+        '--add_columns_owner_last_updated-default-owner',
+        dest='owner',
+        help="Value for the 'owner' column (used in specific migrations). If not set defaults to 'unknown'",
+    )
+    _add_shared_args(parser)
+
+    subparsers = parser.add_subparsers(dest='cmd', help='Migration command')
+
+    # Upgrade command
+    up_parser = subparsers.add_parser(
+        'upgrade', help='Upgrade to a later version'
+    )
+    up_parser.add_argument(
+        'revision',
+        nargs='?',
+        default='head',
+        help='Revision target (default: head)',
+    )
+    up_parser.add_argument(
+        '--add_columns_owner_last_updated-default-owner',
+        dest='sub_owner',
+        help="Value for the 'owner' column (used in specific migrations). If not set defaults to 'legacy_v03_no_user_info'",
+    )
+    _add_shared_args(up_parser, is_sub=True)
+
+    # Downgrade command
+    down_parser = subparsers.add_parser(
+        'downgrade', help='Revert to a previous version'
+    )
+    down_parser.add_argument(
+        'revision',
+        nargs='?',
+        default='base',
+        help='Revision target (e.g., -1, base or a specific ID)',
+    )
+    _add_shared_args(down_parser, is_sub=True)
+
+    return parser
+
+
+def run_migrations() -> None:
+    """CLI tool to manage database migrations."""
+    # Configure logging to show INFO messages
+    logging.basicConfig(level=logging.INFO, format='%(levelname)s  %(message)s')
+
+    parser = create_parser()
+    args = parser.parse_args()
+
+    # Default to upgrade head if no command is provided
+    if not args.cmd:
+        args.cmd = 'upgrade'
+        args.revision = 'head'
+
+    # Locate the bundled alembic.ini
+    ini_path = files('a2a').joinpath('alembic.ini')
+    cfg = Config(str(ini_path))
+
+    # Dynamically set the script location
+    migrations_path = files('a2a').joinpath('migrations')
+    cfg.set_main_option('script_location', str(migrations_path))
+
+    # Consolidate owner, db_url, tables, verbose and sql values
+    owner = args.owner or getattr(args, 'sub_owner', None)
+    db_url = args.database_url or getattr(args, 'sub_database_url', None)
+    task_table = args.tasks_table or getattr(args, 'sub_tasks_table', None)
+    push_notification_configs_table = (
+        args.push_notification_configs_table
+        or getattr(args, 'sub_push_notification_configs_table', None)
+    )
+
+    verbose = args.verbose or getattr(args, 'sub_verbose', False)
+    sql = args.sql or getattr(args, 'sub_sql', False)
+
+    # Pass custom arguments to the migration context
+    if owner:
+        cfg.set_main_option(
+            'add_columns_owner_last_updated_default_owner', owner
+        )
+    if db_url:
+        os.environ['DATABASE_URL'] = db_url
+    if task_table:
+        cfg.set_main_option('tasks_table', task_table)
+    if push_notification_configs_table:
+        cfg.set_main_option(
+            'push_notification_configs_table', push_notification_configs_table
+        )
+    if verbose:
+        cfg.set_main_option('verbose', 'true')
+
+    # Execute the requested command
+    if args.cmd == 'upgrade':
+        logging.info('Upgrading database to %s', args.revision)
+        command.upgrade(cfg, args.revision, sql=sql)
+    elif args.cmd == 'downgrade':
+        logging.info('Downgrading database to %s', args.revision)
+        command.downgrade(cfg, args.revision, sql=sql)
+
+    logging.info('Done.')

src/a2a/alembic.ini

@@ -0,0 +1,35 @@
+# A generic, single database configuration.
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = WARNING
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

src/a2a/migrations/README.md

@@ -0,0 +1,113 @@
+# A2A SDK Database Migrations
+
+This directory handles the database schema updates for the A2A SDK. It uses a bundled CLI tool to simplify the migration process.
+
+## Installation
+
+To use the `a2a-db` migration tool, install the `a2a-sdk` with the `db-cli` extra.
+
+| Extra | `uv` Command | `pip` Command |
+| :--- | :--- | :--- |
+| **CLI Only** | `uv add "a2a-sdk[db-cli]"` | `pip install "a2a-sdk[db-cli]"` |
+| **All Extras** | `uv add "a2a-sdk[all]"` | `pip install "a2a-sdk[all]"` |
+
+
+## User Guide for Integrators
+
+When you install the `a2a-sdk`, you get a built-in command `a2a-db` which updates your database to make it compatible with the latest version of the SDK.
+
+### 1. Recommended: Back up your database
+
+Before running migrations, it is recommended to back up your database.
+
+### 2. Set your Database URL
+Migrations require the `DATABASE_URL` environment variable to be set with an `async-compatible` driver. 
+You can set it globally with `export DATABASE_URL`. Examples for SQLite, PostgreSQL and MySQL, respectively:
+
+```bash
+export DATABASE_URL="sqlite+aiosqlite://user:pass@host:port/your_database_name"
+
+export DATABASE_URL="postgresql+asyncpg://user:pass@localhost/your_database_name"
+
+export DATABASE_URL="mysql+aiomysql://user:pass@localhost/your_database_name"
+```
+
+Or you can use the `--database-url` flag to specify the database URL for a single command.
+
+
+### 3. Apply Migrations
+Always run this command after installing or upgrading the SDK to ensure your database matches the required schema. This will upgrade the tables `tasks` and `push_notification_configs` in your database by adding columns `owner` and `last_updated` and an index `(owner, last_updated)` to the `tasks` table and a column `owner` to the `push_notification_configs` table.
+
+```bash
+uv run a2a-db
+```
+
+### 4. Customizing Defaults with Flags
+#### --add_columns_owner_last_updated-default-owner
+Allows you to pass custom values for the new `owner` column. If not set, it will default to the value `legacy_v03_no_user_info`.
+
+```bash
+uv run a2a-db --add_columns_owner_last_updated-default-owner "admin_user"
+```
+#### --database-url
+You can use the `--database-url` flag to specify the database URL for a single command.
+
+```bash
+uv run a2a-db --database-url "sqlite+aiosqlite:///my_database.db"
+```
+#### --tasks-table / --push-notification-configs-table
+Custom tasks and push notification configs tables to update. If not set, the default are `tasks` and `push_notification_configs`.
+
+```bash
+uv run a2a-db --tasks-table "my_tasks" --push-notification-configs-table "my_configs"
+```
+#### -v / --verbose
+Enables verbose output by setting `sqlalchemy.engine` logging to `INFO`.
+
+```bash
+uv run a2a-db -v
+```
+#### --sql
+Enables running migrations in `offline` mode. Migrations are generated as SQL scripts and printed to stdout instead of being run against the database.
+
+```bash
+uv run a2a-db --sql
+```
+
+### 5. Rolling Back
+If you need to revert a change:
+
+```bash
+# Step back one version
+uv run a2a-db downgrade -1
+
+# Downgrade to a specific revision ID
+uv run a2a-db downgrade <revision_id>
+
+# Revert all migrations
+uv run a2a-db downgrade base
+
+# Revert all migrations in offline mode
+uv run a2a-db downgrade head:base --sql
+```
+
+Note: All flags except `--add_columns_owner_last_updated-default-owner` can be used during rollbacks.
+
+---
+
+## Developer Guide for SDK Contributors
+
+If you are modifying the SDK models and need to generate new migration files, use the following workflow.
+
+### Creating a New Migration
+Developers should use the raw `alembic` command locally to generate migrations. Ensure you are in the project root.
+
+```bash
+# Detect changes in models.py and generate a script
+uv run alembic revision --autogenerate -m "description of changes"
+```
+
+### Internal Layout
+- `env.py`: Configures the migration engine and applies the mandatory `DATABASE_URL` check.
+- `versions/`: Contains the migration history.
+- `script.py.mako`: The template for all new migration files.

src/a2a/migrations/__init__.py

@@ -0,0 +1 @@
+"Alembic database migration package."