instrumentation_middleware.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_diagnostics/instrumentation_middleware.py
 
"""
Instrumentation Middleware
==========================
 
Purpose
-------
Provide a single entry point (``apply_instrumentation``) for applying
recursive ID instrumentation to any Dash component tree, and a dispatcher
patch (``patch_callback_dispatcher``) that automatically instruments all
callback output trees via Dash's ``callback_map``.
 
Responsibilities
----------------
- ``apply_instrumentation()``: call ``instrument_ids()`` if instrumentation
  is active; return the component unchanged otherwise.
- ``patch_callback_dispatcher()``: wrap every callback in
  ``app.callback_map`` with a thin shim that passes its return value
  through ``apply_instrumentation()``.  Never double-wraps a callback.
- ``enable_instrumentation_middleware()``: single-call initialization
  entry point for app setup code; call once after all callbacks are
  registered.
- Log diagnostic events through ``_dbg()`` at appropriate levels.
 
Diagnostics
-----------
Domain: INSTRUMENTATION
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- ``apply_instrumentation()`` must be a no-op when
  ``instrumentation_active()`` is ``False``.
- ``patch_callback_dispatcher()`` must never double-wrap a callback that
  is already wrapped (guarded by ``_is_instrumentation_wrapper`` flag).
- Must not modify the component tree when instrumentation is disabled.
- Requires Dash (``pip install oc_diagnostics[dash]``).
"""
 
from dash import Dash
from oc_diagnostics.id_instrumentation import instrument_ids
from oc_diagnostics.unified_debug import (
    _dbg,
    instrumentation_active,
    instrumentation_verbose,
)
 
 
# -------------------------------------------------------------------
# Public API: apply instrumentation to any component tree
# -------------------------------------------------------------------
 
def apply_instrumentation(component):
    """
    Apply ID instrumentation to a component tree *if enabled*.
 
    - No manual recursion (instrument_ids handles that)
    - No structural ID rewrites
    - Logs only when instrumentation debug level is high enough
    """
 
    if not instrumentation_active():
        return component
 
    if instrumentation_verbose():
        _dbg("INSTRUMENTATION", "middleware", "Applying instrumentation", level=3)
 
    if isinstance(component, (list, tuple)):
        return type(component)(instrument_ids(c) for c in component)
 
    return instrument_ids(component)
 
 
# -------------------------------------------------------------------
# Patch Dash callback dispatcher via callback_map
# -------------------------------------------------------------------
 
def patch_callback_dispatcher(app: Dash):
    """
    Wrap all callbacks in app.callback_map so that their outputs
    are automatically passed through apply_instrumentation().
 
    This is the mechanism already proven to work in the main app.
    """
 
    callback_map = getattr(app, "callback_map", None)
 
    if not callback_map:
        if instrumentation_verbose():
            _dbg("INSTRUMENTATION", "dispatcher", "No callback_map found", level=2)
        return
 
    for output_id, cb_def in callback_map.items():
        # Dash stores callbacks in a dict under "callback"
        if "callback" not in cb_def:
            if instrumentation_verbose():
                _dbg(
                    "INSTRUMENTATION",
                    "dispatcher",
                    f"Skipping callback without 'callback' key: {output_id}",
                    level=2,
                )
            continue
 
        original = cb_def["callback"]
 
        # Avoid double wrapping
        if getattr(original, "_is_instrumentation_wrapper", False):
            continue
 
        # The default-argument binding (out_id=output_id) captures the *current*
        # value of output_id at function-definition time, preventing the classic
        # late-binding closure bug where all wrappers would share the final value
        # of the loop variable.  See OI-12 in AI_REVIEW_SYNTHESIS V2.md.
        def make_wrapper(original_callback, out_id=output_id):
            def wrapper(*args, **kwargs):
                result = original_callback(*args, **kwargs)
 
                if not instrumentation_active():
                    return result
 
                if instrumentation_verbose():
                    _dbg(
                        "INSTRUMENTATION",
                        "dispatcher",
                        f"Instrumenting callback output for {out_id}",
                        level=3,
                    )
 
                return apply_instrumentation(result)
 
            wrapper._is_instrumentation_wrapper = True
            return wrapper
 
        cb_def["callback"] = make_wrapper(original)
 
 
# -------------------------------------------------------------------
# Initialization entry point
# -------------------------------------------------------------------
 
def enable_instrumentation_middleware(app: Dash):
    """
    Call this once after:
 
    - The app is created
    - The layout is assigned
    - All callbacks (including UI event logger) are registered
 
    This matches the lifecycle that already works in the main app.
    """
 
    if instrumentation_verbose():
        _dbg("INSTRUMENTATION", "init", "Enabling instrumentation middleware", level=3)
 
    patch_callback_dispatcher(app)