Package com.tnsai.hooks

Class HookDispatcher

java.lang.Object

com.tnsai.hooks.HookDispatcher

public final class HookDispatcher
extends Object

Runs the registered Hook chain for an in-flight HookEvent (issue #58).

Semantics

1. Select hooks where hook.eventType().isAssignableFrom(event.getClass()).
2. Filter by Hook.matcher().matches(event).
3. Sort by Hook.priority() ascending (lowest first).
4. Apply each in order. Each result:
   • HookResult.Allow — continue to next hook
   • HookResult.Block — stop chain, return the Block
   • HookResult.Modify — replace the event; subsequent hooks see the modified event; return the Modify only if no further hook decided otherwise
5. If no hook matched or all returned Allow, return HookResult.Allow.

Isolation

Each Hook.apply(E) call is wrapped in a timeout (default 5s, configurable per dispatcher) + try/catch. Throws or timeouts are reduced to HookResult.Allow or HookResult.Block per HookFailurePolicy. A misbehaving hook never kills the chain or propagates an exception to the caller.

Concurrency

Safe to call dispatch(HookEvent) concurrently. The registration list is a CopyOnWriteArrayList so registration from a hot path is safe but not particularly fast — configure at startup, not on every call.

Since:

0.5.0 (issue #58)

Constructor Summary

Constructors

Constructor	Description
HookDispatcher()	Default: 5s timeout + fail-open (observability-first, not enforcement-first).
HookDispatcher(Duration timeoutPerHook, HookFailurePolicy failurePolicy)

Method Summary

Modifier and Type	Method	Description
void	clear()	Reset the registration list; primarily for tests.
<E extends HookEvent> HookResult<E>	dispatch(E event)	Run the hook chain for event and return the final decision.
<E extends HookEvent> void	register(Hook<E> hook)	Register a hook.
int	size()	Current hook count — for tests and monitoring.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

HookDispatcher

public HookDispatcher(Duration timeoutPerHook,
 HookFailurePolicy failurePolicy)

HookDispatcher

public HookDispatcher()

Default: 5s timeout + fail-open (observability-first, not enforcement-first).

Method Details

register

public <E extends HookEvent> void register(Hook<E> hook)

Register a hook. Hooks take effect on the next dispatch call. Safe to call from any thread; not intended for hot-path use (CopyOnWriteArrayList snapshot on each add).

size

public int size()

Current hook count — for tests and monitoring.

clear

public void clear()

Reset the registration list; primarily for tests.

dispatch

public <E extends HookEvent> HookResult<E> dispatch(E event)

Run the hook chain for event and return the final decision. Never throws (all hook exceptions reduce to HookResult per failure policy).