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

@@ -106,6 +106,7 @@ style = "pep440"
 
 [dependency-groups]
 dev = [
+  "alembic>=1.14.0",
   "mypy>=1.15.0",
   "PyJWT>=2.0.0",
   "pytest>=8.3.5",
@@ -347,3 +348,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.cli:run_migrations"

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 = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+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/cli.py

@@ -0,0 +1,102 @@
+import argparse
+import os
+
+from importlib.resources import files
+
+from alembic import command
+from alembic.config import Config
+
+
+def run_migrations() -> None:
+    """CLI tool to manage database migrations."""
+    parser = argparse.ArgumentParser(description='A2A Database Migration Tool')
+
+    # Global options
+    parser.add_argument(
+        '-o',
+        '--owner',
+        help="Value for the 'owner' column (used in specific migrations). If not set defaults to 'unknown'",
+    )
+    parser.add_argument(
+        '-u',
+        '--database-url',
+        help='Database URL to use for the migrations. If not set, the DATABASE_URL environment variable will be used.',
+    )
+
+    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(
+        '-o', '--owner', dest='sub_owner', help='Alias for top-level --owner'
+    )
+    up_parser.add_argument(
+        '-u',
+        '--database-url',
+        dest='sub_database_url',
+        help='Alias for top-level --database-url',
+    )
+
+    # 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)',
+    )
+    down_parser.add_argument(
+        '-u',
+        '--database-url',
+        dest='sub_database_url',
+        help='Alias for top-level --database-url',
+    )
+
+    args = parser.parse_args()
+
+    # Consolidate owner value
+    owner = args.owner or getattr(args, 'sub_owner', None)
+    db_url = args.database_url or getattr(args, 'sub_database_url', None)
+    if db_url:
+        os.environ['DATABASE_URL'] = db_url
+
+    # Default to upgrade head if no command is provided
+    if not args.cmd:
+        args.cmd = 'upgrade'
+        args.revision = 'head'
+
+    # 1. Locate the bundled alembic.ini
+    ini_path = files('a2a').joinpath('alembic.ini')
+    cfg = Config(str(ini_path))
+
+    # 2. Dynamically set the script location
+    migrations_path = files('a2a').joinpath('migrations')
+    cfg.set_main_option('script_location', str(migrations_path))
+
+    # 3. Pass custom arguments to the migration context
+    if owner:
+        if args.cmd == 'downgrade':
+            parser.error(
+                "The --owner option is not supported for the 'downgrade' command."
+            )
+        cfg.set_main_option('owner', owner)
+
+    # 3. Execute the requested command
+    if args.cmd == 'upgrade':
+        print(f'Upgrading database to {args.revision}...')
+        command.upgrade(cfg, args.revision)
+    elif args.cmd == 'downgrade':
+        print(f'Downgrading database to {args.revision}...')
+        command.downgrade(cfg, args.revision)
+
+    print('Done.')

src/a2a/migrations/README.md

@@ -0,0 +1,88 @@
+# 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 for both users and developers of the SDK.
+
+## User Guide (For Integrators)
+
+When you install the `a2a-sdk`, you get a built-in command `a2a-db` which updates tables 'tasks' and 'push_notification_configs' in your database to make it compatible with the latest version of the SDK.
+
+### 1. Recommended: Backup your database
+
+Before running migrations, it is recommended to backup your database.
+
+### 2. Set your Database URL
+Migrations require the `DATABASE_URL` environment variable to be set with an **async-compatible** driver or you can use the `-u` flag to specify the database URL for a single command.
+
+```bash
+# SQLite example
+export DATABASE_URL="sqlite+aiosqlite://user:pass@host:port/your_database_name"
+
+# PostgreSQL example
+export DATABASE_URL="postgresql+asyncpg://user:pass@localhost/your_database_name"
+
+# MySQL example
+export DATABASE_URL="mysql+aiomysql://user:pass@localhost/your_database_name"
+```
+
+### 3. Apply Migrations
+Always run this command after installing or upgrading the SDK to ensure your database matches the required schema.
+
+```bash
+# Bring the database to the latest version
+a2a-db
+```
+
+### 4. Customizing Defaults
+Add owner to tasks migration allows you to pass custom values for the new `owner` column. For example, to set a specific default owner for existing tasks:
+
+```bash
+a2a-db -o "admin_user"
+```
+
+### 5. Rolling Back
+If you need to revert a change:
+
+```bash
+# Step back one version
+a2a-db downgrade -1
+```
+
+```bash
+# Downgrade to a specific revision ID
+a2a-db downgrade <revision_id>
+```
+
+```bash
+# Revert all migrations
+a2a-db downgrade base
+```
+
+---
+
+## 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 "describe your 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.
+
+## Troubleshooting
+
+### "Duplicate column name"
+If your database already has the required tables (e.g., created via `Base.metadata.create_all()` in a legacy script), you may need to "stamp" the database to tell the SDK that it is already up to date:
+
+```bash
+# Stamp the database without running SQL commands
+# (Requires raw alembic command for developer use)
+uv run alembic stamp head
+```

src/a2a/migrations/__init__.py

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

src/a2a/migrations/env.py

@@ -0,0 +1,102 @@
+import asyncio
+import os
+
+from logging.config import fileConfig
+
+from sqlalchemy import Connection, pool
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from a2a.server.models import Base
+from alembic import context
+
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Mandatory database configuration
+db_url = os.getenv('DATABASE_URL')
+if not db_url:
+    raise RuntimeError(
+        'DATABASE_URL environment variable is not set. '
+        "Please set it (e.g., export DATABASE_URL='sqlite+aiosqlite:///./my-database.db') before running migrations "
+        'or use the --database-url flag.'
+    )
+config.set_main_option('sqlalchemy.url', db_url)
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# add your model's MetaData object here for 'autogenerate' support
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    url = config.get_main_option('sqlalchemy.url')
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={'paramstyle': 'named'},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    """Run migrations in 'online' mode.
+
+    This function is called within a synchronous context (via run_sync)
+    to configure the migration context with the provided connection
+    and target metadata, then execute the migrations within a transaction.
+
+    Args:
+        connection: The SQLAlchemy connection to use for the migrations.
+    """
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """Run migrations using an Engine.
+
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+    """
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix='sqlalchemy.',
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

src/a2a/migrations/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}