Develop

.gitignore

@@ -0,0 +1 @@
+.worktrees/

Lib/ExtendedCDRsConf.php

@@ -15,7 +15,9 @@
 use MikoPBX\Modules\Config\ConfigClass;
 use MikoPBX\PBXCoreREST\Lib\PBXApiResult;
 use Modules\ModuleExtendedCDRs\bin\ConnectorDB;
+use Modules\ModuleExtendedCDRs\Lib\ModuleWatchdogCommand;
 use Modules\ModuleExtendedCDRs\Lib\RestAPI\Controllers\ApiController;
+use Modules\ModuleExtendedCDRs\Lib\WorkerRuntimePolicy;
 use Modules\ModuleExtendedCDRs\Models\ReportSettings;
 
 class ExtendedCDRsConf extends ConfigClass
@@ -131,7 +133,13 @@ public function createCronTasks(array &$tasks): void
         $busyboxPath= Util::which('busybox');
         $tasks[]    = "*/1 * * * * $busyboxPath find /storage/usbdisk*/mikopbx/tmp/ModuleExtendedCDRs/ -mmin +5 -type f -delete> /dev/null 2>&1".PHP_EOL;
         $phpPath    = Util::which('php');
-        $tasks[]    = "*/1 * * * * $phpPath -f {$this->moduleDir}/bin/safe.php > /dev/null 2>&1".PHP_EOL;
+        $watchdogCommand = ModuleWatchdogCommand::build(
+            $busyboxPath,
+            $phpPath,
+            $this->moduleDir,
+            WorkerRuntimePolicy::outerTimeoutSeconds()
+        );
+        $tasks[]    = "*/1 * * * * $watchdogCommand > /dev/null 2>&1".PHP_EOL;
 
         $reportsData = ReportSettings::find('sendingScheduledReport=1');
         foreach ($reportsData as $settings) {

Lib/ModuleWatchdogCommand.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\ModuleExtendedCDRs\Lib;
+
+final class ModuleWatchdogCommand
+{
+    public static function build(string $busybox, string $php, string $moduleDir, int $timeoutSeconds): string
+    {
+        if ($timeoutSeconds < 1) {
+            throw new \InvalidArgumentException('Watchdog timeout must be positive');
+        }
+
+        return implode(' ', [
+            escapeshellarg($busybox),
+            'timeout',
+            (string) $timeoutSeconds,
+            escapeshellarg($php),
+            '-f',
+            escapeshellarg(rtrim($moduleDir, '/') . '/bin/safe.php'),
+        ]);
+    }
+}

Lib/TemporaryFileGuard.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\ModuleExtendedCDRs\Lib;
+
+final class TemporaryFileGuard
+{
+    /** @var array<string, true> */
+    private array $paths = [];
+
+    public function track(string $path): void
+    {
+        if ($path !== '') {
+            $this->paths[$path] = true;
+        }
+    }
+
+    public function forget(string $path): void
+    {
+        unset($this->paths[$path]);
+    }
+
+    public function cleanup(): void
+    {
+        foreach (array_keys($this->paths) as $path) {
+            if (is_file($path) || is_link($path)) {
+                @unlink($path);
+            }
+            unset($this->paths[$path]);
+        }
+    }
+
+    public function __destruct()
+    {
+        $this->cleanup();
+    }
+}

Lib/WorkerDependencyException.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\ModuleExtendedCDRs\Lib;
+
+use RuntimeException;
+use Throwable;
+
+final class WorkerDependencyException extends RuntimeException
+{
+    private string $operation;
+
+    public function __construct(string $operation, Throwable $previous)
+    {
+        parent::__construct('Worker dependency operation failed', 0, $previous);
+        $this->operation = $operation;
+    }
+
+    public function operation(): string
+    {
+        return $this->operation;
+    }
+}

Lib/WorkerEventContext.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\ModuleExtendedCDRs\Lib;
+
+final class WorkerEventContext
+{
+    /**
+     * @return array<string, bool|string>
+     */
+    public static function make(array $request, string $outcome): array
+    {
+        return [
+            'event' => 'worker_event',
+            'action' => self::identifier((string) ($request['action'] ?? '')),
+            'function' => self::identifier((string) ($request['function'] ?? '')),
+            'needsReply' => isset($request['need-ret']),
+            'outcome' => self::identifier($outcome),
+        ];
+    }
+
+    private static function identifier(string $value): string
+    {
+        return substr((string) preg_replace('/[^A-Za-z0-9_-]/', '', $value), 0, 64);
+    }
+}

Lib/WorkerFailureContext.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\ModuleExtendedCDRs\Lib;
+
+use Throwable;
+
+final class WorkerFailureContext
+{
+    private const METRIC_KEYS = [
+        'pid',
+        'uptimeSeconds',
+        'memoryBytes',
+        'peakMemoryBytes',
+        'openFdCount',
+        'tcpSocketCount',
+    ];
+
+    public static function invokeOperation(bool $clientCreated, bool $expectsReply): string
+    {
+        if (!$clientCreated) {
+            return 'beanstalk_connect';
+        }
+        return $expectsReply ? 'beanstalk_request' : 'beanstalk_publish';
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public static function make(string $operation, Throwable $error, array $metrics, int $elapsedMs): array
+    {
+        $context = [
+            'event' => 'worker_dependency_failure',
+            'operation' => $operation,
+            'errorClass' => get_class($error),
+            'errorCategory' => 'dependency_failure',
+            'elapsedMs' => max(0, $elapsedMs),
+        ];
+
+        foreach (self::METRIC_KEYS as $key) {
+            if (array_key_exists($key, $metrics)) {
+                $context[$key] = $metrics[$key];
+            }
+        }
+
+        return $context;
+    }
+}

Lib/WorkerLogRateLimiter.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\ModuleExtendedCDRs\Lib;
+
+final class WorkerLogRateLimiter
+{
+    public static function shouldLog(string $path, int $now, int $intervalSeconds): bool
+    {
+        $handle = fopen($path, 'c+');
+        if ($handle === false) {
+            return false;
+        }
+        if (!flock($handle, LOCK_EX)) {
+            fclose($handle);
+            return false;
+        }
+
+        $contents = stream_get_contents($handle);
+        $lastLoggedAt = is_string($contents) ? (int) trim($contents) : 0;
+        $allowed = $lastLoggedAt === 0 || ($now - $lastLoggedAt) >= $intervalSeconds;
+        if ($allowed) {
+            ftruncate($handle, 0);
+            fseek($handle, 0);
+            fwrite($handle, (string) $now);
+            fflush($handle);
+        }
+
+        flock($handle, LOCK_UN);
+        fclose($handle);
+        return $allowed;
+    }
+}

Lib/WorkerProcessMetrics.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\ModuleExtendedCDRs\Lib;
+
+final class WorkerProcessMetrics
+{
+    /**
+     * @return array<string, int|null>
+     */
+    public static function collect(int $pid, int $startedAt, string $procRoot = '/proc'): array
+    {
+        $fdDirectory = rtrim($procRoot, '/') . '/' . $pid . '/fd';
+        $openFdCount = null;
+        $socketCount = null;
+
+        if (is_dir($fdDirectory)) {
+            $entries = glob($fdDirectory . '/*');
+            if (is_array($entries)) {
+                $openFdCount = count($entries);
+                $socketCount = 0;
+                foreach ($entries as $entry) {
+                    $target = @readlink($entry);
+                    if (is_string($target) && strpos($target, 'socket:[') === 0) {
+                        ++$socketCount;
+                    }
+                }
+            }
+        }
+
+        return [
+            'pid' => $pid,
+            'uptimeSeconds' => max(0, time() - $startedAt),
+            'memoryBytes' => memory_get_usage(true),
+            'peakMemoryBytes' => memory_get_peak_usage(true),
+            'openFdCount' => $openFdCount,
+            'tcpSocketCount' => $socketCount,
+        ];
+    }
+}

Lib/WorkerRuntimePolicy.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\ModuleExtendedCDRs\Lib;
+
+final class WorkerRuntimePolicy
+{
+    private const WATCHDOG_DEADLINE_SECONDS = 40;
+    private const OUTER_TIMEOUT_SECONDS = 50;
+    private const HEALTH_LOG_INTERVAL_SECONDS = 300;
+
+    public static function watchdogDeadlineSeconds(): int
+    {
+        return self::WATCHDOG_DEADLINE_SECONDS;
+    }
+
+    public static function outerTimeoutSeconds(): int
+    {
+        return self::OUTER_TIMEOUT_SECONDS;
+    }
+
+    public static function shouldLogHealth(int $now, int $lastLoggedAt): bool
+    {
+        return $lastLoggedAt === 0 || ($now - $lastLoggedAt) >= self::HEALTH_LOG_INTERVAL_SECONDS;
+    }
+}

Lib/WorkerWatchdogLease.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\ModuleExtendedCDRs\Lib;
+
+final class WorkerWatchdogLease
+{
+    /** @var resource|null */
+    private $handle;
+
+    /**
+     * @param resource $handle
+     */
+    private function __construct($handle)
+    {
+        $this->handle = $handle;
+    }
+
+    public static function tryAcquire(string $path, int $pid, int $startedAt): ?self
+    {
+        $directory = dirname($path);
+        if (!is_dir($directory) && !mkdir($directory, 0700, true) && !is_dir($directory)) {
+            throw new \RuntimeException("Unable to create watchdog lock directory: {$directory}");
+        }
+        $directoryMode = fileperms($directory);
+        if (is_link($directory) || $directoryMode === false || (($directoryMode & 0022) !== 0)) {
+            throw new \RuntimeException("Refusing insecure watchdog lock directory: {$directory}");
+        }
+        if (is_link($path)) {
+            throw new \RuntimeException("Refusing symlink watchdog lock: {$path}");
+        }
+
+        $handle = fopen($path, 'c+');
+        if ($handle === false) {
+            throw new \RuntimeException("Unable to open watchdog lock: {$path}");
+        }
+        $pathStat = lstat($path);
+        $handleStat = fstat($handle);
+        if ($pathStat === false || $handleStat === false
+            || $pathStat['dev'] !== $handleStat['dev'] || $pathStat['ino'] !== $handleStat['ino']) {
+            fclose($handle);
+            throw new \RuntimeException("Watchdog lock path changed while opening: {$path}");
+        }
+        if (!flock($handle, LOCK_EX | LOCK_NB)) {
+            fclose($handle);
+            return null;
+        }
+
+        $payload = json_encode(['pid' => $pid, 'startedAt' => $startedAt], JSON_UNESCAPED_SLASHES);
+        if ($payload === false || !ftruncate($handle, 0) || fseek($handle, 0) !== 0 || fwrite($handle, $payload) === false) {
+            flock($handle, LOCK_UN);
+            fclose($handle);
+            throw new \RuntimeException("Unable to write watchdog lock diagnostics: {$path}");
+        }
+        fflush($handle);
+
+        return new self($handle);
+    }
+
+    public function release(): void
+    {
+        if (!is_resource($this->handle)) {
+            return;
+        }
+        flock($this->handle, LOCK_UN);
+        fclose($this->handle);
+        $this->handle = null;
+    }
+
+    public function __destruct()
+    {
+        $this->release();
+    }
+}