Skip to content

feat: operation hooks to observe every query, mutation and subscription message (3.10.0) - #87

Closed
barucAlmaguer wants to merge 2 commits into
mainfrom
claude/operation-hooks
Closed

barucAlmaguer wants to merge 2 commits into
mainfrom
claude/operation-hooks

Conversation

@barucAlmaguer

@barucAlmaguer barucAlmaguer commented Oct 18, 2026 •

Copy link
Copy Markdown
Member

Description

Consumers that want to trace or measure their GraphQL traffic today have to wrap the client or monkeypatch it. Valiot's workers need exactly that: put every call a Temporal activity makes on a timeline, next to the screen that triggered the work. This adds a small, generic way to observe operations, with no change for anyone who doesn't use it.

  • pygqlc.hooks.add_operation_hook(fn) / remove_operation_hook(fn). fn receives an OperationEvent (kind, name, document, variables, environment, started_at, duration, response or error):
    • once per query or mutation, when execute/async_execute finish. The resend from 3.9.2 counts as the same operation;
    • once per subscription message.
  • Only observes. A hook's exception is logged at WARNING and never reaches the caller; query/mutate return the same thing as before (there is a test for both).
  • Process-wide registry, like set_logger: it survives resetting the GraphQLClient singleton, which Valiot workers do in forked children.
  • No hooks, no cost: without hooks the client does no extra work, and the POST body, resend policy and errors are unchanged.
  • execute/async_execute keep their signatures. The POST moved to private _post_operation/_async_post_operation so the hook can wrap the whole operation, resend included.

Not included (nothing needs it today): a middleware that modifies the request (headers, propagating traceparent). It can be added the day there is a consumer.

Version 3.10.0 (minor), with its CHANGELOG entry and a README section.

Type of change

  • New feature (non-breaking change which adds functionality)
  • This change requires a documentation update (included: README "Operation hooks")

How Has This Been Tested?

Tests first (b6a5442, red because pygqlc.hooks did not exist: ImportError: cannot import name 'hooks' from 'pygqlc'). Hermetic, following test_operation_name.py: a real local HTTP server and the subscription loop fed the way the router feeds it.

Test Shows
a query is reported with its name, timing and response kind="query", name="Plans", environment, duration > 0, raw response
an async mutation is reported as a mutation the async path; an anonymous mutation is anonymous
an operation name picks the operation it names multi-operation documents (valiot-app transactions)
a failed request is reported with its error and still returns errors a 500: the event carries the GQLResponseException, mutate still returns (None, errors)
a hook that raises does not change the result a hook's error never reaches the caller
a removed hook is not called remove_operation_hook
a subscription message is reported kind="subscription", its variables and the message payload

After the red commit, one adjustment to the test itself: its subscription fixture lacked the runs key that the real subscribe() creates, and it compared the callback's flattened shape. Now it only checks that the callback still receives its message.

uv run pytest tests/pygqlc/gql_client/test_operation_hooks.py   # 7 passed
uv run pytest                                                   # 92 passed, 25 errors (main: 85 passed, the same 25)
uvx ruff format --check pygqlc tests                            # 38 files already formatted
uvx bandit -r . -s B101 -ll --exclude .venv                     # no findings

The 25 errors are the tests that need a live backend (API/WSS/TOKEN); they fail the same way on main in this environment. uv.lock doesn't change: the PR adds no dependencies (uv lock --upgrade here only re-marked dependencies because of the local uv version).

On a real worker: valiot/python-tooling#272 uses this hook, and valiot/prolamsa#25 is the real run: "Resolver Empalmes" in prolamsa, 3 runs, with each of the worker's 69 GraphQL calls on the same timeline as the click, attributed to its activity. The hook also carried the error of the call that failed (upsertPlans, complexity). The API held up as designed. Draft until it's reviewed and published.

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have made corresponding changes to the documentation
  • I have added tests that prove my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules (valiotworkflows, after this one)

🤖 Generated with Claude Code

barucAlmaguer and others added 2 commits October 18, 2026 09:03
…iption messages

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…message (3.10.0)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@palantir-valiot palantir-valiot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall Assessment

Operation hooks wrap execute/async_execute and each subscription payload, and the observe-only contract holds for the paths the tests cover. Two implementation bugs break that contract under retry and under concurrent async calls.

Findings

# Severity File Issue
1 High pygqlc/hooks.py _Outcome.response is a class attribute, so concurrent operations share one response and a retry can report the wrong kind.
2 Medium pygqlc/hooks.py The hook registry has no lock; add/remove during notify can skip a hook or raise.

Notes

  • The no-hooks fast path is real: observed_operation and notify_subscription_message return before timing or regex work when _hooks is empty. The resend stays inside the context manager, so a successful retry is one event.
  • notify catches Exception and re-raises the operation's BaseException. A hook cannot swallow GQLResponseException. query/mutate still return (data, errors) as before.
  • Not flagged: connection-init and error subscription frames are not reported. The PR says "once per subscription message" and the call sits only on the payload path. Callers that want those frames need a different hook point; the payload path matches the test.
  • Not flagged: operation_of can match query/mutation/subscription inside a string or comment. That only mislabels the event; the POST body is unchanged.
  • Tests cover name selection, a 500, a raising hook, removal, and one subscription payload. They do not cover a retry or two overlapping async operations, which is where finding 1 shows up.
  • from pygqlc import hooks works as a submodule import even though hooks is not re-exported in __init__.py. That matches the README.

🤖 PR Reviewer · Grok 4.7 (xAI)

Comment thread pygqlc/hooks.py


class _Outcome:
response: Optional[dict] = None

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

_Outcome.response is a class attribute, not an instance attribute. Every observed_operation writes the same slot.

Two failures follow:

  1. Concurrent async_execute calls (the Temporal worker case this feature is for) share that slot. Operation A can finish, then operation B assigns outcome.response before A's finally builds the event. A's hook then sees B's response, or None if B already cleared it.
  2. On a resend, except BaseException sets error and re-raises into the finally, which notifies with error set. The retry then succeeds and assigns outcome.response, but nothing sets error = None. The success event still carries the first attempt's exception, so event.error or "ok" (the README example) reports a failure for a call that returned data.

Move response onto the instance (self.response = None in __init__), and clear error when the body returns normally:

class _Outcome:
    def __init__(self):
        self.response = None

try:
    yield outcome
    error = None
except BaseException as raised:
    error = raised
    raise

Comment thread pygqlc/hooks.py


OperationHook = Callable[[OperationEvent], None]
_hooks: list = []

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

_hooks is a process-wide list mutated by add_operation_hook / remove_operation_hook with no lock. notify snapshots with list(_hooks) and then each hook runs.

list.append and list.remove are not safe against another thread reading the list. A worker thread that registers or removes a hook while an operation thread is inside list(_hooks) or hook in _hooks can raise RuntimeError from the list resize, or skip a hook for that event.

Valiot workers register this around forked children and activity threads, which is exactly that overlap. A lock around add, remove, and the snapshot (same pattern as a process-wide registry) keeps notify from observing a half-updated list. The hook call itself should stay outside the lock so a slow hook does not block registration.

@linear-code

linear-code Bot commented Oct 19, 2026

Copy link
Copy Markdown

THTO-220

@barucAlmaguer

Copy link
Copy Markdown
Member Author

Superseded by #88: same commits on baruc/thto-220-pygqlc-operation-hooks, the org's user/ISSUE-id-description convention (THTO-220). Renaming this PR's branch would have closed it anyway, so the review continues there; this thread stays as history.

@barucAlmaguer
barucAlmaguer deleted the claude/operation-hooks branch October 19, 2026 17:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant