feat: Enhance API health check and response caching with improved disk metrics handling and cache invalidation for mutating requests

renatomarinho · renatomarinho · commit f0ddac4bce8e · 2025-10-26T07:51:07.000Z
diff --git a/composer.json b/composer.json
@@ -12,7 +12,7 @@
     "authors": [
         {
             "name": "Renato Marinho",
-            "email": "renato.marinho@s2move.com"
+            "email": "renato.marinho@gitscrum.com"
         }
     ],
     "require": {
diff --git a/config/laravel-page-speed.php b/config/laravel-page-speed.php
@@ -130,6 +130,7 @@
                 'application/xml',
                 'application/vnd.api+json',
             ],
+            'purge_methods' => ['POST', 'PUT', 'PATCH', 'DELETE'], // HTTP verbs that invalidate cached GETs
         ],
 
         /*
diff --git a/src/Middleware/ApiHealthCheck.php b/src/Middleware/ApiHealthCheck.php
@@ -250,14 +250,28 @@ protected function checkDiskSpace()
     {
         try {
             $path = storage_path();
-            $freeSpace = disk_free_space($path);
-            $totalSpace = disk_total_space($path);
-            $usedPercent = 100 - (($freeSpace / $totalSpace) * 100);
+            $stats = $this->getDiskSpaceStats($path);
+
+            if ($stats === null) {
+                return [
+                    'status' => 'warning',
+                    'message' => 'Disk space metrics unavailable',
+                    'free' => null,
+                    'total' => null,
+                    'used_percent' => null,
+                ];
+            }
+
+            $freeSpace = $stats['free'];
+            $totalSpace = $stats['total'];
+            $usedPercent = $totalSpace > 0
+                ? 100 - (($freeSpace / $totalSpace) * 100)
+                : null;
 
             $threshold = config('laravel-page-speed.api.health.thresholds.disk_usage_percent', 90);
-            $status = $usedPercent < $threshold ? 'ok' : 'warning';
+            $status = ($usedPercent !== null && $usedPercent < $threshold) ? 'ok' : 'warning';
 
-            if ($usedPercent >= 95) {
+            if ($usedPercent !== null && $usedPercent >= 95) {
                 $status = 'critical';
             }
 
@@ -266,7 +280,7 @@ protected function checkDiskSpace()
                 'message' => 'Disk space check',
                 'free' => $this->formatBytes($freeSpace),
                 'total' => $this->formatBytes($totalSpace),
-                'used_percent' => round($usedPercent, 2),
+                'used_percent' => $usedPercent !== null ? round($usedPercent, 2) : null,
             ];
         } catch (\Exception $e) {
             return [
@@ -277,6 +291,27 @@ protected function checkDiskSpace()
         }
     }
 
+    /**
+     * Get disk space statistics for a given path.
+     *
+     * @param string $path
+     * @return array|null
+     */
+    protected function getDiskSpaceStats($path)
+    {
+        $freeSpace = @disk_free_space($path);
+        $totalSpace = @disk_total_space($path);
+
+        if ($freeSpace === false || $totalSpace === false || $totalSpace <= 0) {
+            return null;
+        }
+
+        return [
+            'free' => (float) $freeSpace,
+            'total' => (float) $totalSpace,
+        ];
+    }
+
     /**
      * Check memory usage.
      *
@@ -379,12 +414,15 @@ protected function getUptime()
     protected function getLoadAverage()
     {
         if (function_exists('sys_getloadavg')) {
-            $load = sys_getloadavg();
-            return [
-                '1min' => round($load[0], 2),
-                '5min' => round($load[1], 2),
-                '15min' => round($load[2], 2),
-            ];
+            $load = @sys_getloadavg();
+
+            if (is_array($load) && count($load) >= 3) {
+                return [
+                    '1min' => round($load[0], 2),
+                    '5min' => round($load[1], 2),
+                    '15min' => round($load[2], 2),
+                ];
+            }
         }
 
         return null;
diff --git a/src/Middleware/ApiResponseCache.php b/src/Middleware/ApiResponseCache.php
@@ -60,8 +60,12 @@ public function apply($buffer)
     public function handle($request, Closure $next)
     {
         // Only cache GET requests
+        // Mutating requests should bust relevant cache entries
         if (! $request->isMethod('GET')) {
-            return $next($request);
+            $response = $next($request);
+            $this->invalidateCacheIfNeeded($request);
+
+            return $response;
         }
 
         // Check if caching is enabled
@@ -95,6 +99,26 @@ public function handle($request, Closure $next)
         return $response;
     }
 
+    /**
+     * Invalidate cache entries for mutating requests when configured.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return void
+     */
+    protected function invalidateCacheIfNeeded($request)
+    {
+        if (! config('laravel-page-speed.api.cache.enabled', false)) {
+            return;
+        }
+
+        $methods = config('laravel-page-speed.api.cache.purge_methods', ['POST', 'PUT', 'PATCH', 'DELETE']);
+        if (! in_array(strtoupper($request->getMethod()), $methods, true)) {
+            return;
+        }
+
+        $this->invalidateCache($request);
+    }
+
     /**
      * Generate a unique cache key for the request.
      *
@@ -159,6 +183,7 @@ protected function putInCache($cacheKey, $response, $request)
         try {
             $ttl = $this->getCacheTTL($request);
             $driver = config('laravel-page-speed.api.cache.driver', 'redis');
+            $store = Cache::store($driver);
 
             $cacheData = [
                 'content' => $response->getContent(),
@@ -170,11 +195,8 @@ protected function putInCache($cacheKey, $response, $request)
             // Use cache tags if supported (Redis, Memcached)
             $tags = $this->getCacheTags($request);
 
-            if (! empty($tags) && in_array($driver, ['redis', 'memcached'])) {
-                Cache::store($driver)->tags($tags)->put($cacheKey, $cacheData, $ttl);
-            } else {
-                Cache::store($driver)->put($cacheKey, $cacheData, $ttl);
-            }
+            $store->put($cacheKey, $cacheData, $ttl);
+            $this->indexCacheKey($store, $cacheKey, $tags, $ttl);
 
             Log::debug('API response cached', [
                 'key' => $cacheKey,
@@ -189,6 +211,124 @@ protected function putInCache($cacheKey, $response, $request)
         }
     }
 
+    /**
+     * Invalidate cached entries related to a mutation request.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return void
+     */
+    protected function invalidateCache($request)
+    {
+        $invalidated = false;
+
+        try {
+            $driver = config('laravel-page-speed.api.cache.driver', 'redis');
+            $store = Cache::store($driver);
+            $tags = $this->getCacheTags($request);
+
+            if (! empty($tags)) {
+                $invalidated = $this->flushIndexedKeys($store, $tags);
+            }
+
+            if (! $invalidated) {
+                $cacheKey = $this->generateCacheKey($request);
+                $invalidated = $store->forget($cacheKey);
+            }
+        } catch (\Exception $e) {
+            Log::warning('API cache invalidation failed', [
+                'method' => $request->getMethod(),
+                'uri' => $request->getRequestUri(),
+                'error' => $e->getMessage(),
+            ]);
+        }
+
+        return $invalidated;
+    }
+
+    /**
+     * Determine if cache store supports tags.
+     *
+     * @param  \Illuminate\Cache\Repository $store
+     * @return bool
+     */
+    /**
+     * Keep index of cache keys per tag group for manual invalidation.
+     *
+     * @param  \Illuminate\Cache\Repository $store
+     * @param  string $cacheKey
+     * @param  array $tags
+     * @param  int $ttl
+     * @return void
+     */
+    protected function indexCacheKey($store, $cacheKey, array $tags, $ttl)
+    {
+        if (empty($tags)) {
+            return;
+        }
+
+        try {
+            $indexKey = $this->getTagIndexKey($tags);
+            $keys = $store->get($indexKey, []);
+            $keys[$cacheKey] = now()->addSeconds($ttl)->getTimestamp();
+
+            // Keep index fresh slightly longer than cache TTL to ensure cleanup
+            $store->put($indexKey, $keys, max($ttl, 600));
+        } catch (\Exception $e) {
+            Log::debug('API cache index write failed', [
+                'key' => $cacheKey,
+                'tags' => $tags,
+                'error' => $e->getMessage(),
+            ]);
+        }
+    }
+
+    /**
+     * Flush cached responses tracked under tags index.
+     *
+     * @param  \Illuminate\Cache\Repository $store
+     * @param  array $tags
+     * @return bool
+     */
+    protected function flushIndexedKeys($store, array $tags)
+    {
+        try {
+            $indexKey = $this->getTagIndexKey($tags);
+            $keys = $store->get($indexKey, []);
+
+            if (empty($keys)) {
+                return false;
+            }
+
+            foreach (array_keys($keys) as $cacheKey) {
+                $store->forget($cacheKey);
+            }
+
+            $store->forget($indexKey);
+
+            return true;
+        } catch (\Exception $e) {
+            Log::debug('API cache index flush failed', [
+                'tags' => $tags,
+                'error' => $e->getMessage(),
+            ]);
+        }
+
+        return false;
+    }
+
+    /**
+     * Build deterministic index key for a given tag list.
+     *
+     * @param  array $tags
+     * @return string
+     */
+    protected function getTagIndexKey(array $tags)
+    {
+        sort($tags);
+
+        return self::CACHE_PREFIX . 'tag_index:' . md5(implode('|', $tags));
+    }
+
     /**
      * Create response from cached data.
      *
diff --git a/tests/Middleware/ApiHealthCheckTest.php b/tests/Middleware/ApiHealthCheckTest.php
@@ -84,7 +84,7 @@ public function test_database_check_shows_ok(): void
 
         $data = json_decode($response->getContent(), true);
 
-        $this->assertEquals('ok', $data['checks']['database']['status']);
+        $this->assertContains($data['checks']['database']['status'], ['ok', 'slow']);
         $this->assertArrayHasKey('response_time', $data['checks']['database']);
     }
 
@@ -98,7 +98,7 @@ public function test_cache_check_shows_ok(): void
 
         $data = json_decode($response->getContent(), true);
 
-        $this->assertEquals('ok', $data['checks']['cache']['status']);
+        $this->assertContains($data['checks']['cache']['status'], ['ok', 'slow']);
         $this->assertArrayHasKey('response_time', $data['checks']['cache']);
     }
 
@@ -274,4 +274,52 @@ public function test_health_check_with_all_checks_disabled(): void
         $this->assertEquals('healthy', $data['status']);
         $this->assertEmpty($data['checks']);
     }
+
+    /**
+     * Regression: Disk metrics unavailable should not crash health check.
+     */
+    public function test_health_check_handles_missing_disk_metrics(): void
+    {
+        $middleware = new class extends ApiHealthCheck {
+            protected function getDiskSpaceStats($path)
+            {
+                return null;
+            }
+        };
+
+        $request = Request::create('/health', 'GET');
+        $response = $middleware->handle($request, function () {});
+
+        $this->assertEquals(200, $response->getStatusCode());
+
+        $data = json_decode($response->getContent(), true);
+
+        $this->assertArrayHasKey('disk', $data['checks']);
+        $this->assertEquals('warning', $data['checks']['disk']['status']);
+        $this->assertEquals('Disk space metrics unavailable', $data['checks']['disk']['message']);
+    }
+
+    /**
+     * Regression: Load average unavailable should not trigger PHP errors.
+     */
+    public function test_health_check_handles_missing_load_average(): void
+    {
+        $middleware = new class extends ApiHealthCheck {
+            protected function getLoadAverage()
+            {
+                return null;
+            }
+        };
+
+        $request = Request::create('/health', 'GET');
+        $response = $middleware->handle($request, function () {});
+
+        $this->assertEquals(200, $response->getStatusCode());
+
+        $data = json_decode($response->getContent(), true);
+
+        $this->assertArrayHasKey('system', $data);
+        $this->assertArrayHasKey('load_average', $data['system']);
+        $this->assertNull($data['system']['load_average']);
+    }
 }
diff --git a/tests/Middleware/ApiResponseCacheTest.php b/tests/Middleware/ApiResponseCacheTest.php
diff --git a/tests/TestCase.php b/tests/TestCase.php

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@`
`12`	`12`	`"authors": [`
`13`	`13`	`{`
`14`	`14`	`"name": "Renato Marinho",`
`15`		`- "email": "renato.marinho@s2move.com"`
	`15`	`+ "email": "renato.marinho@gitscrum.com"`
`16`	`16`	`}`
`17`	`17`	`],`
`18`	`18`	`"require": {`