Add Notion plugin: tasks, polling app, MCP server

[cosmicBboy]

Adds plugins/notion (flyteplugins-notion), a Notion integration for Flyte 2.

What's included

Read/write from tasks — NotionClient, an async client covering search, pages, databases, database queries, blocks, page creation (database rows and child pages), updates, and archiving, plus exported property/block builder helpers (title_property, select_property, paragraph_block, ...). Errors carry Notion's error code in NotionAPIError; 429s are retried. Credentials come from a mounted flyte.Secret (NOTION_TOKEN).

React to Notion changes — Notion has no webhooks, so NotionAppEnvironment detects changes by polling: a setup/management dashboard (/) plus a poll endpoint (GET /api/poll?database_id=...&since=..., protected by an X-Poll-Token shared secret) that queries a database for pages edited since a cursor, normalizes them into NotionEvent objects, and dispatches to on_event handlers. launch_task launches runs idempotently via dedupe labels keyed on page + edit timestamp, so overlapping polls never double-process an edit. examples/poll_for_updates.py shows the webhook-free alternative: a flyte.Trigger scheduled task calling query_database_since directly.

MCP server for agents on Flyte — the read/write surface doubles as MCP tools via build_mcp_server / notion_mcp_app_env. Read-only by default; read_only=False adds page creation/updates/block appending; include_destructive=True additionally exposes archive_page. Tool annotations come from the registry. Change detection is intentionally not an MCP tool — that stays with the app environment or a scheduled task.

Tests

56 tests covering the client (respx-mocked Notion API, including last_edited_time filter construction and title-property nesting), property/block helpers, event dedupe semantics, the MCP tool registry/server, dispatch idempotency, and the app dashboard/poll endpoint (token enforcement, database allowlist, handler dispatch).

Examples

• examples/write_to_notion.py — database rows and child pages from tasks
• examples/poll_for_updates.py — trigger-based change polling
• examples/notion_mcp_server.py — MCP server for agents

Review pass

A follow-up commit fixes issues found while reviewing this branch.

Robustness and security

• The poll token compares as bytes. hmac.compare_digest raises TypeError on str operands containing non-ASCII, and X-Poll-Token is attacker-controlled: ASGI servers hand Starlette raw header bytes which it decodes as latin-1, so a crafted header turned a clean 401 into a 500.
• Retry-After is parsed defensively and clamped at 60s. The header may carry an HTTP-date, which raised ValueError, and a large value would previously have slept unbounded.

Dashboard and docs

• The recent-events table read the 25 oldest events instead of the newest — [:25] on a deque that appends on the right — so it froze after the first 25 events.
• Configured database ids are HTML-escaped like every other interpolated value.
• The _dispatch module docstring described webhook redelivery; this plugin polls, so it now describes overlapping poll windows instead.

2 new tests cover these.

Follow-up: async launching and label-only idempotency

launch_task no longer blocks the app's event loop. It and blocking_run are now async-first, wrapped with flyte's @syncify, so handlers await launch_task.aio(...). Previously the synchronous call stalled the whole event loop for the duration of two control-plane round-trips plus a launch — with every other in-flight webhook queued behind it, against sender timeouts measured in seconds. The synchronous form still works for scripts. A regression test asserts four concurrent launches overlap; against the old blocking call it measures 0.81s instead of 0.42s and fails.

Idempotency is now purely label-based. The run-name allocation is gone — it probed up to 32 candidate names via Run.get before launching under the winner. That raced with concurrent launches, silently capped how many runs one dedupe key could ever have, and treated a name as an identity it never was. Runs now carry only the dedupe=<key> label and the control plane assigns the name. run_name_for, RUN_NAME_MAX, and the prefix / run_name_base arguments are removed.

The dedupe key is explicitly caller-supplied. dedupe_key() is a sensible default, not a requirement — any string chooses a different idempotency scope.

The module docstring is also honest about the residual race: the label check is a read followed by a launch, so two simultaneous deliveries of one event can both launch. Redeliveries are seconds to minutes apart and dedupe reliably; closing the concurrent case needs a compare-and-set the control plane does not expose.

Follow-up: sync and async call forms on NotionClient

The 13 client methods are wrapped with flyte's @syncify, so each has two call forms — matching how the SDK itself exposes Run.listall, flyte.run, and flyte.serve:

# async: in `async def` tasks, webhook handlers, MCP tools
async with NotionClient() as client:
    result = await client.some_method.aio(...)

# blocking: in plain `def` tasks and scripts
with NotionClient() as client:          # note: `with`, not `async with`
    result = client.some_method(...)

__enter__/__exit__ were added so the blocking form is usable at all. They run __aenter__/__aexit__ on syncify's background loop — the same loop the syncified methods run on — so the httpx.AsyncClient is created and used on a single loop rather than straddling two.

Two call sites had to move to .aio() for correctness, not just style. Internal self. calls would otherwise deadlock, since syncify raises on a blocking call made from its own loop thread. And the MCP tool bridge (await getattr(client, name)(...)) would raise TypeError: object dict can't be used in 'await' expression on the returned value — and, had it not raised, would have stalled the MCP server's event loop for the duration of every tool call. Measured: 0 event-loop ticks during one blocking call.

The dynamic sync_*-method alternative was rejected: it works at runtime but both mypy and ty report "NotionClient" has no attribute "sync_..." and fall back to Any, so every typed caller breaks. @syncify in place resolves to SyncFunction[[...], ...] in both checkers. The package's mypy error count is unchanged at 12, all pre-existing, none in _client.py.

Tests, examples, and READMEs use .aio() on async paths and document both forms, including when not to reach for the blocking one.

Follow-up: typed event constants

on_event no longer needs hand-copied strings:

from flyteplugins.notion import events

@app_env.on_event(events.Page.EDITED)
async def handle(event): ...

flyteplugins.notion.events adds 1 classes / 1 constants, following the ActionPhase pattern in flyte.models — str enums grouped by event type, so a member drops in wherever a pattern string is accepted and a typo fails at import rather than by silently never matching. Polling yields a single event type today; the constant keeps registration consistent with the other plugins. Raw strings still work, for events the constants do not cover yet.

The enum base pins __str__/__format__ to str's. Without that, Python 3.11+ renders members as Class.MEMBER rather than the wire value — which would have leaked enum names into the dashboard and /api/status, since handler patterns flow into both.

Tests assert the constants equal what the parser actually produces (through the app's own _matches), that every ANY is the bare type its actions prefix, and that no value appears in two classes.

Follow-up: an end-to-end Testing guide

The README now ends with a numbered walkthrough against a real account, ordered so each step fails in isolation — exercise the client standalone before involving the platform, deploy the launched task before the app that looks it up, run it directly before any webhook is in play. Then wire up the provider, trigger a real event, and check the four places evidence lands: the provider's delivery log, /api/events, flyte get runs, and the resource itself. It ends with a troubleshooting table mapping each symptom to its cause, since 401, 503, and "200 but no run" are three different failures.

It also walks through the idempotency behaviour by hand, which is the part unit tests can only simulate.

Writing the guide surfaced a gap and it is fixed here: react_to_notion_changes.py — Notion was the only plugin whose app environment had no runnable example was looked up by name but defined nowhere, so anyone following the README end to end would have hit a task-not-found error at the first real event.

Verified mechanically rather than by eye: every referenced example path resolves, every flyte create secret name matches the actual _config.py default, every flyte deploy <file> <env> names a real TaskEnvironment, every flyte run task is defined, and every example file still executes.