Package com.tnsai.hooks.spi

Interface Hook<E extends HookEvent>

Type Parameters:
E - the concrete event type this hook observes
All Known Implementing Classes:
ExternalScriptHook
public interface Hook<E extends HookEvent>
Pluggable intercept point in the framework's event chain (issue #58).

A hook:

  1. Declares which event type it observes via eventType().
  2. Declares which instances to observe via matcher().
  3. Declares where in the chain it runs via priority() — lower numbers first; negative priorities run before zero-priority hooks.
  4. Returns a HookResult when invoked: Allow, Block, or Modify.

Implementations MUST be thread-safe — a single hook instance is shared across every dispatch. They SHOULD be pure functions of the event where possible; side effects (metrics, audit logs) are acceptable but should be fast and non-blocking.

Discovery: hooks register via ServiceLoader (drop a META-INF/services/com.tnsai.hooks.spi.Hook entry), or they can be added programmatically to a HookDispatcher.

Since:
0.5.0 (issue #58)

  • Method Summary

    Modifier and Type
    Method
    Description
    HookResult<E>
    apply(E event)
    Inspect the event and return a decision.
    Class<E>
    eventType()
    The event class this hook observes.
    default String
    id()
    Short stable identifier for logs / audit trail.
    default HookMatcher<E>
    matcher()
    Further filter which instances of eventType() this hook cares about.
    default int
    priority()
    Priority in the chain.

  • Method Details

    • eventType

      Class<E> eventType()
      The event class this hook observes. Must be a concrete subtype of HookEvent; the dispatcher uses Class.isAssignableFrom to decide whether an event-in-flight matches this hook, so subclasses are matched too.

    • matcher

      default HookMatcher<E> matcher()
      Further filter which instances of eventType() this hook cares about. Default: match all.

    • priority

      default int priority()
      Priority in the chain. Lower = earlier. Negative priorities run before any zero-priority hook — useful for "must run first" rules like security checks. Default 0.

    • id

      default String id()
      Short stable identifier for logs / audit trail. Default: class name. Implementations may override when multiple hook instances of the same class need to be distinguished.

    • apply

      HookResult<E> apply(E event)
      Inspect the event and return a decision.