Skip to content

fix(hooks): hooks_installed removed a hook it did not install - #424

Merged
NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
PerryLink:fix/hooks-installed-restores
Sep 29, 2026
Merged

NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
PerryLink:fix/hooks-installed-restores

Conversation

@PerryLink

Copy link
Copy Markdown
Contributor

fix(hooks): hooks_installed removed a hook it did not install

The context manager restored the list by removing every entry matching a hook it had added, by
identity. A hook object that an application had already installed therefore matched too, and was
removed along with the block's own copy:

installed one hook before the block: 1
inside the block                 : 2 hook(s)
dispatches inside the block      : 2
after the block                  : 0 hook(s)     <- the caller's hook is gone
dispatches on the next call      : 0

Both pages that document it say the opposite — docs/hooks/api.md:144 and
docs/hooks/patterns.md:224, "restores the previous list on exit, even if the block raises".
An application that installs one audit or metrics hook at startup and later wraps a request in
hooks_installed for a temporary one loses the audit hook for the rest of the process, silently:
the block is the only thing that ran, and it looks like it cleaned up after itself.

Installing a hook that is already installed is legal — add_hook appends, and the hook list is a
list — so the block has to take its own copy back off and leave the caller's in place.

Deliberate choices tested:

  • Restore the previous list instead of counting removals. Removing exactly one occurrence per added hook would fix the reported case, but it is still a removal: with the same hook named twice in one block, or the same hook installed twice by the caller, "one per added" and "the list as it was" are different answers, and only the second is what the docs promise. Snapshotting is also exact when the block raises, which is the other half of the documented sentence.
  • The snapshot is taken before the hooks are added, under the same lock. Taking it after _extend_hooks would capture the block's own hooks, and taking it without the lock would race a concurrent add_hook; both are avoided by reading it first, under _hooks_mutex_for_registry, which is the lock the rest of the registry uses.
  • _remove_hooks is left alone. It is public-ish and its predicate semantics are right for a caller who wants "remove every copy"; the bug was using it to implement a restore.
  • The tests cover the case the old ones could not. test_hooks.py already checked that a temporary hook fires only inside the block, which passes either way because the temporary hook is not registered anywhere else. The new cases install the hook first, which is the only arrangement that distinguishes the two implementations.
# with remove-by-identity restored
144 passed, 2 failed
  FAIL hooks_installed/restores the previous list: got 0, want 1
  FAIL hooks_installed/the pre-installed hook still fires after the block: got [], want ['already']

# restored
$ python tests/test_hooks.py            146 passed, 0 failed   (141 before)
$ python tests/test_hooks_api.py        all hook API tests passed
$ python tests/test_router.py           all routing tests passed

Known limitation: this is the Python side. laya-ts/src/hooks.ts:270 carries the same
remove-by-identity logic in the port, in PR #308, so the same case is present in TypeScript until
that is addressed — worth doing in the same shape, but in a separate PR so this diff stays one
change.

@NandhaKishorM

Copy link
Copy Markdown
Owner

Thank you for finding this, a block really should not remove a hook the application installed itself. Restoring a snapshot causes two new problems, though: with two overlapping blocks the first exit removes the second block's hook and later reinstalls the first block's hook for good, and a hook added with add_hook inside the block is lost. Could you instead remove exactly one occurrence of each hook the block added (the most recent match by identity) under the registry lock? Please also add tests for interleaved blocks and for add_hook inside a block.

The context manager restored the list by removing every entry matching a hook it had added, by
identity. A hook object that an application had already installed therefore matched too, and was
removed along with the block's own copy:

```
installed one hook before the block: 1
inside the block                 : 2 hook(s)
after the block                  : 0 hook(s)     <- the caller's hook is gone
dispatches on the next call      : 0
```

`docs/hooks/api.md` and `docs/hooks/patterns.md` both say the block *"restores the previous list
on exit, even if the block raises"*. An application that installs one audit or metrics hook at
startup and later wraps a request in `hooks_installed` for a temporary one loses the audit hook
for the rest of the process, silently.

## The snapshot fix was wrong in two other ways

The first version of this fix saved `self.hooks` on entry and assigned it back on exit. The
review caught two cases that breaks, and both are real:

- **Two overlapping blocks.** The inner block installs its hook. The inner block exits and
  reinstates the snapshot taken *before* it, which is also before the outer block's hook was
  added — so the outer hook disappears while its `with` is still open. Worse, at the outer exit
  the outer snapshot is reinstated, so a hook that a *later* caller installed inside the window
  is removed for good.
- **A hook added with `add_hook` inside the block** is not in the snapshot, so it is discarded on
  exit even though the block did not put it there.

## What it does now

Removes **one occurrence per hook the block added**, the most recent match by identity, under the
registry lock. `_extend_hooks` appends, so a hook that was already installed sits earlier in the
list than the block's copy, which makes "most recent match" the block's own. Everything the block
did not add is left alone.

Deliberate choices tested:

- **One occurrence per hook, not one per list entry.** A hook named twice in one `hooks_installed(...)` call is added twice and removed twice, so the block still leaves nothing behind — while a hook the caller installed once keeps its own copy.
- **The lock is held for the read-modify-write.** The whole removal happens inside `_hooks_mutex_for_registry`, so a concurrent `add_hook` cannot be interleaved between the copy and the assignment.
- **`_remove_hooks` is left alone.** Its predicate semantics are right for a caller who wants "remove every copy"; the bug was using it to implement a restore.
- **The tests cover the arrangements the old ones could not.** The existing check installed a *temporary* hook that was registered nowhere else, which passes under any of the three implementations. The new ones install the hook first, nest two blocks, and add a hook inside a block — the only arrangements that distinguish them.

```
# with the snapshot version restored, the new tests fail:
  IndexError: list index out of range
  (f.hooks[0] after the block -- the hook added inside was discarded)

$ python tests/test_hooks.py            176 passed, 0 failed   (141 before)
$ python tests/test_hooks_api.py        all hook API tests passed
$ python -m pytest tests/test_serve.py tests/test_system_one_lang.py -q
31 passed
$ python -m ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120
All checks passed!
$ python -m compileall -q laya/ tests/
```

Verified against all four arrangements directly, with a weight-free fake agent: a hook installed
before the block survives and still fires once; a hook added inside survives; an inner block's
exit leaves the outer hook installed; and a hook named twice in one block leaves nothing behind.

Known limitation: this is the Python side. `laya-ts/src/hooks.ts` carries the same
remove-by-identity logic from PR NandhaKishorM#308, so the original defect is present in the port until that
is addressed — the same one-occurrence-per-hook change applies there, in a separate PR so this
diff stays one logical change.
@PerryLink
PerryLink force-pushed the fix/hooks-installed-restores branch from 250ba1b to 48f9760 Compare September 25, 2026 15:40
@NandhaKishorM
NandhaKishorM merged commit 84c5236 into NandhaKishorM:main Sep 29, 2026
22 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Passed checks and merged. Thank you @PerryLink! It ships in 0.3.22.

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