Repository navigation
THTO-220: feat: operation hooks to observe every query, mutation and subscription message (3.10.0) - #88
Conversation
…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>
There was a problem hiding this comment.
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
_hooksis empty, and a hook failure there is logged rather than raised into the subscription loop.
🤖 PR Reviewer · Grok 4.7 (xAI)
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>
There was a problem hiding this comment.
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_errorsdoes not cover this. Theeventsfixture is autouse-free, but pytest still instantiates every fixture in the module for each test. That fixture callsadd_operation_hook, so_hooksis 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_operationor_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)
There was a problem hiding this comment.
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_errorspins a 500 throughmutate. - Fixed since last review:
outcome.response = ...binds an instance attribute. Concurrent_Outcomeobjects do not share that slot. - Not flagged: a missing
operation_namereports the first definition, not the operation the server runs. The author says the event carries the named operation when the caller passesoperation_name, and single-operation documents stay unambiguous. - Not flagged: a field or argument named
query/mutation/subscriptioncan 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)
|
|
||
|
|
||
| def notify(event: OperationEvent) -> None: | ||
| for hook in list(_hooks): |
There was a problem hiding this comment.
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)There was a problem hiding this comment.
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
_hooksis mutated/read without synchronization. In multi-threaded use (the client has… · New The fallback return value contradicts the docstring (“else the first one”) and can misreport… · New_hooksis mutated/read without synchronization. In multi-threaded use (the client has… · New The HTTP server shutdown sequence is incomplete:HTTPServer.shutdown()stops the serve loop but… · New The changelog describesOperationEventas containingstart, but the implemented field is… · New
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.hookswithOperationEvent, hook registry helpers, and instrumentation helpers. - Wraps
execute/async_executeand 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
| 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) | ||
|
|
||
|
|
| 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" |
| 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}") |
| 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) |
|
|
||
| ## [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. |


Evidence
The red and green test logs behind this PR (
tests/red-b6a5442.log,tests/green.log), from your checkout: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).fnreceives anOperationEvent(kind, name, document, variables, environment,started_at,duration,responseorerror):execute/async_executefinish. The resend from 3.9.2 counts as the same operation;query/mutatereturn the same thing as before (there is a test for both).set_logger: it survives resetting theGraphQLClientsingleton, which Valiot workers do in forked children.execute/async_executekeep their signatures. The POST moved to private_post_operation/_async_post_operationso 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
How Has This Been Tested?
Tests first (
b6a5442, red becausepygqlc.hooksdid not exist:ImportError: cannot import name 'hooks' from 'pygqlc'). Hermetic, followingtest_operation_name.py: a real local HTTP server and the subscription loop fed the way the router feeds it.kind="query",name="Plans", environment,duration > 0, raw responseanonymousGQLResponseException,mutatestill returns(None, errors)remove_operation_hookkind="subscription", its variables and the message payloadAfter the red commit, one adjustment to the test itself: its subscription fixture lacked the
runskey that the realsubscribe()creates, and it compared the callback's flattened shape. Now it only checks that the callback still receives its message.The 25 errors are the tests that need a live backend (
API/WSS/TOKEN); they fail the same way onmainin this environment.uv.lockdoesn't change: the PR adds no dependencies (uv lock --upgradehere 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.
observed_operationswallows the exception." The exception is thrown back atyieldand propagates, since there is no handler around thatyield. A new test pins it on the real server:test_without_hooks_a_failed_request_still_returns_its_errors(9143366)._Outcome.responseis shared between concurrent calls." Assigning tooutcome.responsecreates an instance attribute; the class attribute is only the default.Checklist:
🤖 Generated with Claude Code