Pluggy plugin hook for before and after a watch is processed

changedetectionio/pluggy_interface.py

@@ -129,6 +129,51 @@ class ChangeDetectionSpec:
         """
         pass
 
+    @hookspec
+    def update_handler_alter(update_handler, watch, datastore):
+        """Modify or wrap the update_handler before it processes a watch.
+
+        This hook is called after the update_handler (perform_site_check instance) is created
+        but before it calls call_browser() and run_changedetection(). Plugins can use this to:
+        - Wrap the handler to add logging/metrics
+        - Modify handler configuration
+        - Add custom preprocessing logic
+
+        Args:
+            update_handler: The perform_site_check instance that will process the watch
+            watch: The watch dict being processed
+            datastore: The application datastore
+
+        Returns:
+            object or None: Return a modified/wrapped handler, or None to keep the original.
+                           If multiple plugins return handlers, they are chained in registration order.
+        """
+        pass
+
+    @hookspec
+    def update_finalize(update_handler, watch, datastore, processing_exception):
+        """Called after watch processing completes (success or failure).
+
+        This hook is called in the finally block after all processing is complete,
+        allowing plugins to perform cleanup, update metrics, or log final status.
+
+        The plugin can access update_handler.last_logging_insert_id if it was stored
+        during update_handler_alter, and use processing_exception to determine if
+        the processing succeeded or failed.
+
+        Args:
+            update_handler: The perform_site_check instance (may be None if creation failed)
+            watch: The watch dict that was processed (may be None if not loaded)
+            datastore: The application datastore
+            processing_exception: The exception from the main processing block, or None if successful.
+                                 This does NOT include cleanup exceptions - only exceptions from
+                                 the actual watch processing (fetch, diff, etc).
+
+        Returns:
+            None: This hook doesn't return a value
+        """
+        pass
+
 
 # Set up Plugin Manager
 plugin_manager = pluggy.PluginManager(PLUGIN_NAMESPACE)
@@ -499,4 +544,66 @@ def get_plugin_template_paths():
                 template_paths.append(templates_dir)
                 logger.debug(f"Added plugin template path: {templates_dir}")
 
-    return template_paths
+    return template_paths
+
+
+def apply_update_handler_alter(update_handler, watch, datastore):
+    """Apply update_handler_alter hooks from all plugins.
+
+    Allows plugins to wrap or modify the update_handler before it processes a watch.
+    Multiple plugins can chain modifications - each plugin receives the result from
+    the previous plugin.
+
+    Args:
+        update_handler: The perform_site_check instance to potentially modify
+        watch: The watch dict being processed
+        datastore: The application datastore
+
+    Returns:
+        object: The (potentially modified/wrapped) update_handler
+    """
+    # Get all plugins that implement the update_handler_alter hook
+    results = plugin_manager.hook.update_handler_alter(
+        update_handler=update_handler,
+        watch=watch,
+        datastore=datastore
+    )
+
+    # Chain results - each plugin gets the result from the previous one
+    current_handler = update_handler
+    if results:
+        for result in results:
+            if result is not None:
+                logger.debug(f"Plugin modified update_handler for watch {watch.get('uuid')}")
+                current_handler = result
+
+    return current_handler
+
+
+def apply_update_finalize(update_handler, watch, datastore, processing_exception):
+    """Apply update_finalize hooks from all plugins.
+
+    Called in the finally block after watch processing completes, allowing plugins
+    to perform cleanup, update metrics, or log final status.
+
+    Args:
+        update_handler: The perform_site_check instance (may be None)
+        watch: The watch dict that was processed (may be None)
+        datastore: The application datastore
+        processing_exception: The exception from processing, or None if successful
+
+    Returns:
+        None
+    """
+    try:
+        # Call all plugins that implement the update_finalize hook
+        plugin_manager.hook.update_finalize(
+            update_handler=update_handler,
+            watch=watch,
+            datastore=datastore,
+            processing_exception=processing_exception
+        )
+    except Exception as e:
+        # Don't let plugin errors crash the worker
+        logger.error(f"Error in update_finalize hook: {e}")
+        logger.exception(f"update_finalize hook exception details:")

changedetectionio/worker.py

@@ -119,7 +119,10 @@ async def async_update_worker(worker_id, q, notification_q, app, datastore, exec
         # to prevent race condition with wait_for_all_checks()
 
         fetch_start_time = round(time.time())
-        
+
+        # Track processing exception for plugin finalization
+        processing_exception = None
+
         try:
             if uuid in list(datastore.data['watching'].keys()) and datastore.data['watching'][uuid].get('url'):
                 changed_detected = False
@@ -154,6 +157,10 @@ async def async_update_worker(worker_id, q, notification_q, app, datastore, exec
                     update_handler = processor_module.perform_site_check(datastore=datastore,
                                                                          watch_uuid=uuid)
 
+                    # Allow plugins to modify/wrap the update_handler
+                    from changedetectionio.pluggy_interface import apply_update_handler_alter
+                    update_handler = apply_update_handler_alter(update_handler, watch, datastore)
+
                     update_signal = signal('watch_small_status_comment')
                     update_signal.send(watch_uuid=uuid, status="Fetching page..")
 
@@ -498,6 +505,8 @@ async def async_update_worker(worker_id, q, notification_q, app, datastore, exec
                 gc.collect()
 
         except Exception as e:
+            # Store the processing exception for plugin finalization hook
+            processing_exception = e
 
             logger.error(f"Worker {worker_id} unexpected error processing {uuid}: {e}")
             logger.exception(f"Worker {worker_id} full exception details:")
@@ -547,6 +556,21 @@ async def async_update_worker(worker_id, q, notification_q, app, datastore, exec
                     logger.error(f"Worker {worker_id} error during cleanup: {cleanup_error}")
                     logger.exception(f"Worker {worker_id} full exception details:")
 
+                # Call plugin finalization hook after all cleanup is done
+                try:
+                    from changedetectionio.pluggy_interface import apply_update_finalize
+                    finalize_handler = update_handler if 'update_handler' in locals() else None
+                    finalize_watch = watch if 'watch' in locals() else None
+                    apply_update_finalize(
+                        update_handler=finalize_handler,
+                        watch=finalize_watch,
+                        datastore=datastore,
+                        processing_exception=processing_exception
+                    )
+                except Exception as finalize_error:
+                    logger.error(f"Worker {worker_id} error in finalize hook: {finalize_error}")
+                    logger.exception(f"Worker {worker_id} full exception details:")
+
             del(uuid)
 
             # Brief pause before continuing to avoid tight error loops (only on error)