docs: Update CLAUDE.md with memory leak investigation session

- Documented v0.4.1 through v0.4.9 fix attempts - Listed all protection mechanisms in place - Recorded key learnings about WordPress hooks and recursion - Status: unresolved, documented as known incompatibility Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
docs: Add known plugin incompatibilities section
2026-02-02 20:10:09 +01:00 · 2026-02-02 20:07:50 +01:00 · 2026-02-02 20:05:59 +01:00
5 changed files with 108 additions and 15 deletions
@@ -7,11 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [0.4.9] - 2026-02-02
+
+### Changed
+
+- **Reverted nuclear option** - Restored conditional the_content filter usage
+  - `get_post_data()` now uses the_content filter only when NOT in shortcode context, NOT at depth > 1, and NOT loading page template
+  - All other protections remain in place (render depth, page template loading flag, main template lock, shortcode context)
+  - Memory leak investigation to be continued later
+
 ## [0.4.8] - 2026-02-02

 ### Fixed

- **Nuclear option: NEVER apply the_content filter** - Completely removed the_content filter usage
+- **Nuclear option: NEVER apply the_content filter** - Completely removed the_content filter usage (reverted in 0.4.9)
  - `get_post_data()` now ALWAYS strips shortcodes and uses raw content
  - NEVER calls `apply_filters('the_content', ...)` or `get_the_excerpt()`
  - FediStream posts don't need shortcode processing in their content anyway
@@ -274,7 +283,8 @@ Initial release of WP FediStream - a WordPress plugin for streaming music over A

 ---

-[Unreleased]: https://src.bundespruefstelle.ch/magdev/wp-fedistream/compare/v0.4.8...HEAD
+[Unreleased]: https://src.bundespruefstelle.ch/magdev/wp-fedistream/compare/v0.4.9...HEAD
+[0.4.9]: https://src.bundespruefstelle.ch/magdev/wp-fedistream/compare/v0.4.8...v0.4.9
 [0.4.8]: https://src.bundespruefstelle.ch/magdev/wp-fedistream/compare/v0.4.7...v0.4.8
 [0.4.7]: https://src.bundespruefstelle.ch/magdev/wp-fedistream/compare/v0.4.6...v0.4.7
 [0.4.6]: https://src.bundespruefstelle.ch/magdev/wp-fedistream/compare/v0.4.5...v0.4.6
@@ -552,3 +552,58 @@ wp-fedistream/
 - Uses Gitea API directly for release creation (not GitHub Actions)
 - Submodule uses relative URL for CI compatibility
 - Composer symlinks from `lib/wc-licensed-product-client` to vendor
+
+### 2026-02-02 - Memory Leak Investigation v0.4.1 through v0.4.9
+
+**Summary:** Investigated memory exhaustion issue when WP FediStream is used with WP Prometheus plugin. Multiple fix attempts were made but the root cause remains unresolved.
+
+**Problem:**
+
+- PHP Fatal error: Allowed memory size exhausted (1GB)
+- Error locations varied: Twig StagingExtension.php, Environment.php, ExtensionSet.php, WordPress class-wp-hook.php
+- Only occurs when WP Prometheus plugin is also active
+- Suspected infinite recursion through WordPress hook system
+
+**Fix Attempts (v0.4.1 - v0.4.8):**
+
+1. **v0.4.1** - Added recursion depth tracking in `get_post_data()`, skip `the_content` filter at depth > 1
+2. **v0.4.2** - Added `$in_shortcode_context` flag, all shortcode render methods enter context before data loading
+3. **v0.4.3** - Changed boolean to counter (`$shortcode_context_depth`), added context to `template-wrapper.php`
+4. **v0.4.4** - Fixed `get_the_excerpt()` which internally triggers `the_content` filter
+5. **v0.4.5** - Added render depth tracking in `Plugin::render()`, strip shortcodes from content
+6. **v0.4.6** - Added `$loading_page_template` flag to block shortcode rendering during page template loading
+7. **v0.4.7** - Added `$rendering_main_template` hard lock in `Plugin::render()`, reduced MAX_RENDER_DEPTH to 2
+8. **v0.4.8** - Nuclear option: ALWAYS skip `the_content` filter (didn't work, reverted)
+
+**v0.4.9 - Current State:**
+
+- Reverted nuclear option
+- Kept all other protections in place
+- Issue documented in README.md as known incompatibility
+
+**Files Modified:**
+
+- `includes/Frontend/TemplateLoader.php` - Multiple recursion protection mechanisms
+- `includes/Frontend/Shortcodes.php` - Shortcode context entry, page template loading check
+- `includes/Frontend/template-wrapper.php` - Page template loading flag, main template render flag
+- `includes/Plugin.php` - Render depth tracking, main template rendering lock
+- `README.md` - Added Known Issues section
+
+**Protection Mechanisms in Place:**
+
+1. `$recursion_depth` counter in `get_post_data()` (max 3)
+2. `$shortcode_context_depth` counter for nested shortcodes
+3. `$loading_page_template` flag blocks shortcode rendering during page load
+4. `$rendering_main_template` flag in `Plugin::render()` blocks parallel renders
+5. `MAX_RENDER_DEPTH = 2` in `Plugin::render()`
+6. Skip `the_content` and `get_the_excerpt()` when in protected context
+7. Strip shortcodes from content when skipping content filter
+
+**Key Learnings:**
+
+- `get_the_excerpt()` internally calls `apply_filters('the_content', ...)` when generating auto-excerpts
+- `the_content` filter triggers `do_shortcode()` which can cause recursive shortcode processing
+- WordPress hook system (class-wp-hook.php) can itself be the recursion point
+- The interaction between FediStream and WP Prometheus appears to be at a fundamental WordPress level
+
+**Status:** UNRESOLVED - Documented as known incompatibility, investigation to continue later
@@ -2,7 +2,7 @@

 Stream music over ActivityPub - Build your own music streaming platform for Musicians and Labels.

-[![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.4.9-blue.svg)](CHANGELOG.md)
 [![PHP](https://img.shields.io/badge/PHP-%3E%3D8.3-purple.svg)](https://php.net)
 [![WordPress](https://img.shields.io/badge/WordPress-%3E%3D6.4-blue.svg)](https://wordpress.org)
 [![License](https://img.shields.io/badge/license-GPL--2.0%2B-green.svg)](https://www.gnu.org/licenses/gpl-2.0.html)
@@ -39,6 +39,18 @@ WP FediStream is a WordPress plugin that enables musicians, bands, and labels to
 - [ActivityPub Plugin](https://wordpress.org/plugins/activitypub/) - For Fediverse integration
 - [WooCommerce](https://woocommerce.com/) 10.0+ - For selling music

+## Known Issues
+
+### Plugin Incompatibilities
+
+The following plugins are known to cause issues when used together with WP FediStream:
+
+| Plugin        | Issue                                                             | Status              |
+|---------------|-------------------------------------------------------------------|---------------------|
+| WP Prometheus | Memory exhaustion (PHP Fatal error) when viewing FediStream pages | Under investigation |
+
+If you encounter memory issues or PHP fatal errors, try deactivating these plugins temporarily to isolate the problem.
+
 ## License Key

 WP FediStream requires a valid license key for frontend functionality (player, shortcodes, ActivityPub). The admin dashboard works without a license, allowing you to configure the plugin before activation.
@@ -289,18 +289,34 @@ class TemplateLoader {
        // Track recursion to prevent infinite loops from shortcodes in content.
        ++self::$recursion_depth;

-        // ALWAYS skip the_content filter to prevent any possible recursion.
-        // FediStream posts don't need shortcode processing in their content.
-        // This is the nuclear option but it guarantees no recursion.
-        $excerpt = $post->post_excerpt;
-        if ( empty( $excerpt ) ) {
-            // Generate a simple excerpt without triggering the_content filter.
-            $excerpt = wp_trim_words( wp_strip_all_tags( $post->post_content ), 55, '&hellip;' );
+        // Skip the_content filter if:
+        // 1. We're in a shortcode context (prevents recursive shortcode processing)
+        // 2. We're at depth > 1 (nested data loading)
+        // 3. We're loading a page template
+        $skip_content_filter = self::$shortcode_context_depth > 0
+            || self::$recursion_depth > 1
+            || self::$loading_page_template;
+
+        // When skipping content filter, use raw excerpt to avoid get_the_excerpt()
+        // triggering the_content filter internally when generating auto-excerpts.
+        if ( $skip_content_filter ) {
+            $excerpt = $post->post_excerpt;
+            if ( empty( $excerpt ) ) {
+                // Generate a simple excerpt without triggering the_content filter.
+                $excerpt = wp_trim_words( wp_strip_all_tags( $post->post_content ), 55, '&hellip;' );
+            }
+        } else {
+            $excerpt = get_the_excerpt( $post );
        }

-        // Strip shortcodes and sanitize content - never apply the_content filter.
-        $content = strip_shortcodes( $post->post_content );
-        $content = wp_kses_post( $content );
+        // When skipping content filter, strip shortcodes to prevent them from
+        // being processed by anything else that might call do_shortcode on the output.
+        if ( $skip_content_filter ) {
+            $content = strip_shortcodes( $post->post_content );
+            $content = wp_kses_post( $content );
+        } else {
+            $content = apply_filters( 'the_content', $post->post_content );
+        }

        $data = array(
            'id'        => $post->ID,
@@ -3,7 +3,7 @@
 * Plugin Name: WP FediStream
 * Plugin URI: https://src.bundespruefstelle.ch/magdev/wp-fedistream
 * Description: Stream music over ActivityPub - Build your own music streaming platform for Musicians and Labels.
- * Version: 0.4.8
+ * Version: 0.4.9
 * Requires at least: 6.4
 * Requires PHP: 8.3
 * Author: Marco Graetsch
@@ -26,7 +26,7 @@ if ( ! defined( 'ABSPATH' ) ) {
 *
 * @var string
 */
-define( 'WP_FEDISTREAM_VERSION', '0.4.8' );
+define( 'WP_FEDISTREAM_VERSION', '0.4.9' );

 /**
 * Plugin file path.