Skip to content

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

Merged
barucAlmaguer merged 3 commits into
mainfrom
baruc/thto-220-pygqlc-operation-hooks
Oct 19, 2026
Merged

barucAlmaguer merged 3 commits into
mainfrom
baruc/thto-220-pygqlc-operation-hooks

Conversation

@barucAlmaguer

@barucAlmaguer barucAlmaguer commented Oct 19, 2026 •

Copy link
Copy Markdown
Member

Supersedes #87 (same commits; the branch was renamed to the org's user/ISSUE-id-description convention for THTO-220, and renaming a PR's branch closes it). Earlier review threads are on #87.

Evidence

The red and green test logs behind this PR (tests/red-b6a5442.log, tests/green.log), from your checkout:

git fetch -q origin refs/pr-proof/88 && d=$(mktemp -d) && git archive FETCH_HEAD | tar -x -C "$d" && (open "$d/index.html" 2>/dev/null || xdg-open "$d/index.html")

This repository is public, so the real worker run observed through these hooks is not published here: it is in the evidence of valiot/python-tooling#273 (the consumer).

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   # 8 passed
uv run pytest                                                   # 93 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#273 uses this hook, and valiot/prolamsa#28 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.

Review fixes

The two threads from the automated review were checked against the code and did not hold. Each reply has the check.

  • "Without hooks, observed_operation swallows the exception." The exception is thrown back at yield and propagates, since there is no handler around that yield. A new test pins it on the real server: test_without_hooks_a_failed_request_still_returns_its_errors (9143366).
  • "_Outcome.response is shared between concurrent calls." Assigning to outcome.response creates an instance attribute; the class attribute is only the default.

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>
@linear-code

linear-code Bot commented Oct 19, 2026

Copy link
Copy Markdown

THTO-220

@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 are wired around execute/async_execute and subscription messages, and the observe-only contract holds when a hook is registered. With no hooks registered, observed_operation swallows the operation's exception. query/mutate then return (None, []) instead of the error.

Findings

# Severity File Issue
1 High pygqlc/hooks.py No-hooks path swallows exceptions from execute/async_execute
2 Low pygqlc/hooks.py _Outcome.response is a class attribute, so concurrent calls share one response slot

Notes

  • Not flagged: the process-wide registry and the lack of request-mutating middleware. The author says both are intentional.
  • The hook path re-raises correctly (except BaseException as raised: error = raised; raise), and tests cover a raising hook and a 500 while a hook is registered. None of those tests run with an empty registry, so the swallowed-exception path is untested.
  • Subscription observation is correctly skipped when _hooks is empty, and a hook failure there is logged rather than raised into the subscription loop.

🤖 PR Reviewer · Grok 4.7 (xAI)

Comment thread pygqlc/hooks.py Resolved
Comment thread pygqlc/hooks.py Resolved
The empty registry takes its own path through observed_operation; this pins
that the error still reaches query/mutate's error handling.

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 still change what a failed query/mutate returns when no hook is registered. That is the default path, and the CHANGELOG says retries and errors are unchanged. Both findings from the last review are still in pygqlc/hooks.py.

Findings

# Severity File Issue
1 High pygqlc/hooks.py Still open (#88 (comment)): no-hooks path swallows exceptions from execute/async_execute
2 Low pygqlc/hooks.py Still open (#88 (comment)): _Outcome.response is a class attribute, so concurrent calls share one response slot

Notes

  • test_without_hooks_a_failed_request_still_returns_its_errors does not cover this. The events fixture is autouse-free, but pytest still instantiates every fixture in the module for each test. That fixture calls add_operation_hook, so _hooks is not empty when the test runs. The empty-registry branch is never exercised.
  • Not re-commented inline. Both findings were already posted and have no reply. The new commits do not change observed_operation or _Outcome.
  • The hook path does re-raise, and a raising hook is caught in notify. That part matches the stated contract.

🤖 PR Reviewer · Grok 4.7 (xAI)

@barucAlmaguer
barucAlmaguer marked this pull request as ready for review October 19, 2026 20:12
Copilot AI balanced review requested due to automatic review settings October 19, 2026 20:12
@barucAlmaguer
barucAlmaguer merged commit bf5b970 into main Oct 19, 2026
4 of 7 checks passed
@barucAlmaguer
barucAlmaguer deleted the baruc/thto-220-pygqlc-operation-hooks branch October 19, 2026 20:13

@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 without changing the no-hook POST path. The empty-registry exception path and _Outcome.response are correct, matching the author's checks. The process-wide hook list is still mutated while other threads snapshot it, which can replace a real operation error with a registry RuntimeError.

Findings

# Severity File Issue
1 Medium pygqlc/hooks.py Concurrent add/remove during notify can raise RuntimeError and hide the operation's own exception

Notes

  • Fixed since last review: the empty-registry path does not swallow the with-body exception. test_without_hooks_a_failed_request_still_returns_its_errors pins a 500 through mutate.
  • Fixed since last review: outcome.response = ... binds an instance attribute. Concurrent _Outcome objects do not share that slot.
  • Not flagged: a missing operation_name reports the first definition, not the operation the server runs. The author says the event carries the named operation when the caller passes operation_name, and single-operation documents stay unambiguous.
  • Not flagged: a field or argument named query/mutation/subscription can be picked as the definition. No current consumer document in this repo hits that, and the tests use plain definitions.
  • Subscription errors, complete, and connection-init messages are not reported. The README says "once per subscription message"; the code only notifies the payload branch. Worth a README clarification, not a behavior bug for the timeline use case.
  • Tests cover the sync query, async mutation, named operation, 500, broken hook, removal, and one subscription payload against a real local server.

🤖 PR Reviewer · Grok 4.7 (xAI)

Comment thread pygqlc/hooks.py


def notify(event: OperationEvent) -> None:
for hook in list(_hooks):

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.

Only when hooks are registered, and only if one thread registers or removes a hook while another thread is inside execute/async_execute or _subscription_loop.

notify snapshots with list(_hooks) and then calls each hook. add_operation_hook and remove_operation_hook mutate that same list with no lock. CPython list iteration is not safe against a concurrent resize: the other thread can raise RuntimeError: list changed size during iteration out of list(), or remove can shift entries so a hook is skipped or called twice.

The stated consumer is a Temporal worker with many activities at once, and the registry is process-wide so it survives a singleton reset in forked children. A late add_operation_hook (or a test fixture's remove_operation_hook) then races every in-flight operation. That exception is not a hook exception, so the except below does not catch it. It leaves observed_operation's finally and replaces the body's GQLResponseException (raise new_exc from None in contextlib). query/mutate then return the registry error instead of the server error.

Copy under a lock, and mutate under the same lock:

_lock = threading.Lock()

def add_operation_hook(hook):
    with _lock:
        if hook not in _hooks:
            _hooks.append(hook)

def _snapshot():
    with _lock:
        return tuple(_hooks)

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

5 open issues
What changed in this PR

Adds a process-wide “operation hooks” mechanism so consumers can observe every GraphQL query/mutation completion (including retries) and each subscription message, and bumps the library minor version accordingly.

Changes:

  • Introduces pygqlc.hooks with OperationEvent, hook registry helpers, and instrumentation helpers.
  • Wraps execute/async_execute and subscription message handling to emit hook events.
  • Adds documentation + changelog entry and a test suite validating the hook behavior.
File Description
tests/​pygqlc/​gql_client/​test_operation_hooks.py Adds integration-style tests validating hook notifications for queries, mutations, failures, and subscription messages.
pygqlc/​hooks.py Implements the hook registry, OperationEvent, operation-name parsing, and notification helpers.
pygqlc/​__version__.py Bumps version to 3.10.0.
pygqlc/​GraphQLClient.py Instruments operations and subscription messages to emit hook events; factors POST logic into private helpers.
README.md Documents how to register and use operation hooks and what OperationEvent contains.
CHANGELOG.md Adds 3.10.0 entry describing the new hook feature.

Review effort: Lite

Comment thread pygqlc/hooks.py
Comment on lines +44 to +53
def add_operation_hook(hook: OperationHook) -> None:
if hook not in _hooks:
_hooks.append(hook)


def remove_operation_hook(hook: OperationHook) -> None:
if hook in _hooks:
_hooks.remove(hook)


Comment thread pygqlc/hooks.py
Comment on lines +54 to +62
def operation_of(document: str, operation_name: Optional[str] = None) -> tuple:
"""(kind, name) of the operation a document runs: the one `operation_name`
names, else the first one. A bare selection set (`{ plans { id } }`) is an
anonymous query."""
definitions = [(m.group(1), m.group(2)) for m in _DEFINITION.finditer(document)]
for kind, name in definitions:
if operation_name is None or name == operation_name:
return kind, name or "anonymous"
return "query", operation_name or "anonymous"
Comment thread pygqlc/hooks.py
Comment on lines +65 to +70
def notify(event: OperationEvent) -> None:
for hook in list(_hooks):
try:
hook(event)
except Exception as error: # a hook must never break the operation it observes
log(LogLevel.WARNING, f"pygqlc operation hook {hook!r} failed: {error!r}")
Comment on lines +49 to +65
httpd = http.server.HTTPServer(("127.0.0.1", 0), _Server)
thread = threading.Thread(target=httpd.serve_forever, daemon=True)
thread.start()
gql = GraphQLClient()
host, port = httpd.server_address
gql.addEnvironment(
"hooks-test",
url=f"http://{host}:{port}/api",
wss="ws://127.0.0.1:1/socket/websocket",
post_timeout=5,
)
try:
with gql.enterEnvironment("hooks-test"):
yield gql
finally:
httpd.shutdown()
thread.join(timeout=5)
Comment thread CHANGELOG.md

## [3.10.0] - 2026-10-18

- [Added] Operation hooks (`pygqlc.hooks.add_operation_hook` / `remove_operation_hook`): a function that observes every operation the client runs, called once per query or mutation when `execute`/`async_execute` finish (a resend included) and once per subscription message, with an `OperationEvent` (kind, name, document, variables, environment, start, duration, response or error). Consumers can trace or measure their GraphQL traffic (Valiot workers use it to put each call on a timeline next to the screen that triggered the work) without wrapping the client. Hooks only observe: a hook's exception is logged and never reaches the caller, and `query`/`mutate` return exactly what they returned before. The registry is process-wide like `set_logger`, so it survives a reset of the `GraphQLClient` singleton. With no hooks registered the client does no extra work; the POST body, retries and errors are unchanged.
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.

2 participants