@fleetbase/fleetops-engine 0.6.66 → 0.6.68

package/server/src/Support/Telematics/Safee/Transport.php

@@ -0,0 +1,210 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support\Telematics\Safee;
+
+use Fleetbase\FleetOps\Exceptions\TelematicProviderException;
+use Fleetbase\FleetOps\Exceptions\TelematicRateLimitExceededException;
+use Illuminate\Contracts\Encryption\DecryptException;
+use Illuminate\Http\Client\ConnectionException;
+use Illuminate\Http\Client\Response;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Facades\Http;
+
+/** Safee's documented OAuth and per-user request budget, shared across workers. */
+class Transport
+{
+    protected ?string $token    = null;
+    protected ?float $expiresAt = null;
+
+    public function __construct(protected string $baseUrl, protected array $credentials)
+    {
+        $this->token = $credentials['access_token'] ?? null;
+    }
+
+    public function fingerprint(): string
+    {
+        $credentials = $this->credentials;
+        ksort($credentials);
+
+        return hash('sha256', $this->baseUrl . '|' . json_encode($credentials, JSON_THROW_ON_ERROR));
+    }
+
+    public function accountKey(): string
+    {
+        return hash('sha256', implode('|', [$this->baseUrl, $this->credentials['realm_id'] ?? '', $this->credentials['username'] ?? $this->credentials['access_token'] ?? '']));
+    }
+
+    public function request(string $method, string $endpoint, array|\stdClass $payload, float $deadline, int $timeout, int $connectTimeout): array
+    {
+        $refreshed = false;
+        while (true) {
+            if (!$this->token || ($this->expiresAt !== null && $this->expiresAt <= $this->wallTime() + 5)) {
+                $this->token = $this->cachedToken($deadline, $timeout, $connectTimeout);
+            }
+            $this->reserveRequest($deadline);
+            try {
+                $request = Http::withHeaders([
+                    'Accept'          => 'application/json', 'Content-Type' => 'application/json',
+                    'Accept-Language' => $this->credentials['language'] ?? 'en',
+                    'Authorization'   => trim(($this->credentials['authorization_scheme'] ?? 'Bearer') . ' ' . $this->token),
+                ])->timeout($this->remaining($deadline, $timeout))
+                    ->connectTimeout($this->remaining($deadline, $connectTimeout));
+                $response = $method === 'GET' ? $request->get($this->baseUrl . $endpoint) : $request->post($this->baseUrl . $endpoint, $payload);
+            } catch (ConnectionException $e) {
+                throw new TelematicProviderException('Safee request timed out or could not connect.', ['endpoint' => $endpoint], previous: $e);
+            }
+            $this->checkThrottle($response);
+            // A rejected token is refreshed once; a second rejection fails as an unsuccessful response.
+            if ($response->status() === 401 && !$refreshed && $this->canAuthenticate()) {
+                $refreshed   = true;
+                $this->token = $this->cachedToken($deadline, $timeout, $connectTimeout, $this->token);
+                continue;
+            }
+            if ($response->failed()) {
+                throw new TelematicProviderException('Safee API request failed with status ' . $response->status(), ['endpoint' => $endpoint, 'status' => $response->status()]);
+            }
+            $json = $response->json();
+            if (!is_array($json) || !array_key_exists('code', $json) || !is_numeric($json['code']) || (float) $json['code'] !== 0.0) {
+                throw new TelematicProviderException('Safee returned an invalid or unsuccessful response.', ['endpoint' => $endpoint]);
+            }
+
+            return $json;
+        }
+    }
+
+    public function authenticate(float $deadline, int $timeout = 30, int $connectTimeout = 5): string
+    {
+        return $this->cachedToken($deadline, $timeout, $connectTimeout);
+    }
+
+    protected function canAuthenticate(): bool
+    {
+        foreach (['realm_id', 'client_id', 'client_secret', 'username', 'password'] as $field) {
+            if (empty($this->credentials[$field])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    protected function cachedToken(float $deadline, int $timeout, int $connectTimeout, ?string $rejected = null): string
+    {
+        if (!$this->canAuthenticate()) {
+            throw new \InvalidArgumentException('Safee realm, client and user credentials are required to authenticate.');
+        }
+        $key = 'safee:token:' . $this->fingerprint();
+
+        return Cache::lock($key . ':lock', 60)->block($this->remaining($deadline, 2), function () use ($key, $deadline, $timeout, $connectTimeout, $rejected) {
+            $cached = null;
+            if ($encrypted = Cache::get($key)) {
+                try {
+                    $cached = json_decode(Crypt::decryptString($encrypted), true, 512, JSON_THROW_ON_ERROR);
+                } catch (DecryptException|\JsonException) {
+                    // Only the disposable token cache is recoverable this way.
+                    Cache::forget($key);
+                }
+            }
+            if (is_array($cached) && is_string($cached['access_token'] ?? null) && $cached['access_token'] !== $rejected && ($cached['expires_at'] ?? 0) > $this->wallTime() + 5) {
+                $this->expiresAt = (float) $cached['expires_at'];
+
+                return $cached['access_token'];
+            }
+            $refresh         = is_array($cached) && is_string($cached['refresh_token'] ?? null) ? $cached['refresh_token'] : null;
+            $tokens          = $this->tokenRequest($deadline, $timeout, $connectTimeout, $refresh);
+            $lifetime        = is_numeric($tokens['expires_in'] ?? null) ? max(0, (int) $tokens['expires_in']) : 0;
+            $this->expiresAt = $lifetime > 0 ? $this->wallTime() + $lifetime : null;
+            if ($lifetime > 0) {
+                $tokens['expires_at'] = $this->expiresAt;
+                Cache::put($key, Crypt::encryptString(json_encode($tokens, JSON_THROW_ON_ERROR)), max($lifetime, min(86400, (int) ($tokens['refresh_expires_in'] ?? $lifetime))));
+            } else {
+                // An undocumented expiry must not create a long-lived cached token.
+                Cache::forget($key);
+            }
+
+            return $tokens['access_token'];
+        });
+    }
+
+    protected function tokenRequest(float $deadline, int $timeout, int $connectTimeout, ?string $refresh = null): array
+    {
+        $body = ['grant_type' => $refresh ? 'refresh_token' : 'password', 'client_id' => $this->credentials['client_id'], 'client_secret' => $this->credentials['client_secret']];
+        $body += $refresh ? ['refresh_token' => $refresh] : ['username' => $this->credentials['username'], 'password' => $this->credentials['password']];
+        $this->reserveRequest($deadline);
+        try {
+            $response = Http::asForm()->acceptJson()->timeout($this->remaining($deadline, $timeout))
+                ->connectTimeout($this->remaining($deadline, $connectTimeout))
+                ->post($this->baseUrl . '/auth/realms/' . rawurlencode($this->credentials['realm_id']) . '/protocol/openid-connect/token', $body);
+        } catch (ConnectionException $e) {
+            throw new TelematicProviderException('Safee authentication timed out or could not connect.', previous: $e);
+        }
+        $this->checkThrottle($response);
+        // Expired/revoked refresh tokens may be exchanged for a new password grant once.
+        if ($refresh && in_array($response->status(), [400, 401], true)) {
+            return $this->tokenRequest($deadline, $timeout, $connectTimeout);
+        }
+        if ($response->failed()) {
+            throw new TelematicProviderException('Safee authentication failed with status ' . $response->status());
+        }
+        $tokens = $response->json();
+        if (!is_array($tokens) || !is_string($tokens['access_token'] ?? null) || $tokens['access_token'] === '') {
+            throw new TelematicProviderException('Safee authentication did not return an access token.');
+        }
+
+        return array_intersect_key($tokens, array_flip(['access_token', 'refresh_token', 'expires_in', 'refresh_expires_in']));
+    }
+
+    protected function reserveRequest(float $deadline): void
+    {
+        $key = 'safee:rate:' . $this->accountKey();
+        Cache::lock($key . ':lock', 5)->block($this->remaining($deadline, 2), function () use ($key, $deadline) {
+            $this->remaining($deadline, 1);
+            $now      = $this->wallTime();
+            $until    = (float) Cache::get($key . ':blocked', 0);
+            $requests = array_values(array_filter(Cache::get($key, []), fn ($at) => $at > $now - 1));
+            if ($until > $now || count($requests) >= 50) {
+                throw new TelematicRateLimitExceededException('Safee request budget exhausted.', ['retry_after' => max(1, (int) ceil(max($until, ($requests[0] ?? $now) + 1) - $now))]);
+            }
+            $requests[] = $now;
+            Cache::put($key, $requests, 2);
+        });
+    }
+
+    protected function checkThrottle(Response $response): void
+    {
+        if ($response->status() !== 429) {
+            return;
+        }
+        $header = $response->header('Retry-After');
+        $delay  = is_numeric($header) ? (int) ceil((float) $header) : max(1, (strtotime($header ?: '') ?: time() + 1) - time());
+        $delay  = max(1, min($delay, 3600));
+        $key    = 'safee:rate:' . $this->accountKey();
+        Cache::lock($key . ':lock', 5)->block(1, function () use ($key, $delay) {
+            $until = max((float) Cache::get($key . ':blocked', 0), $this->wallTime() + $delay);
+            Cache::put($key . ':blocked', $until, (int) ceil($until - $this->wallTime()));
+        });
+
+        throw new TelematicRateLimitExceededException('Safee rate limited the request.', ['retry_after' => $delay]);
+    }
+
+    protected function remaining(float $deadline, int $maximum): int
+    {
+        $remaining = (int) floor($deadline - $this->time());
+        if ($remaining < 1) {
+            throw new TelematicProviderException('Safee request time budget exhausted before another operation could start.');
+        }
+
+        return min(max(1, $maximum), $remaining);
+    }
+
+    protected function time(): float
+    {
+        return hrtime(true) / 1_000_000_000;
+    }
+
+    protected function wallTime(): float
+    {
+        return microtime(true);
+    }
+}

package/server/src/Support/Telematics/TelematicService.php

@@ -152,6 +152,11 @@ class TelematicService
      */
     public function discoverDevices(Telematic $telematic, array $options = []): string
     {
+        $provider = $this->registry->resolve($telematic->provider);
+        if ($provider instanceof \Fleetbase\FleetOps\Contracts\TelemetryProviderInterface
+            && (Telemetry\Configuration::options($provider)['manual_batch_sync'] ?? false)) {
+            return $this->queueTelemetrySync($telematic, $options);
+        }
         $jobId = (string) Str::uuid();
         dispatch(new SyncTelematicDevicesJob($telematic, $options, $jobId));
 
@@ -167,6 +172,43 @@ class TelematicService
         return $jobId;
     }
 
+    /** Queue current telemetry through bounded, durable batches for opted-in providers. */
+    public function queueTelemetrySync(Telematic $telematic, array $options = [], ?string $jobId = null): string
+    {
+        $settings = Telemetry\Configuration::options($this->registry->resolve($telematic->provider));
+        if (!Telemetry\Inbox::enabled($telematic) || !($settings['polling_enabled'] ?? false)) {
+            throw ValidationException::withMessages(['telematic' => ['Telemetry synchronization is disabled for this connection.']]);
+        }
+        $jobId ??= (string) Str::uuid();
+
+        return \Illuminate\Support\Facades\DB::transaction(function () use ($telematic, $options, $settings, $jobId) {
+            $connection = Telematic::withoutGlobalScopes()->where('uuid', $telematic->uuid)->lockForUpdate()->firstOrFail();
+            if (!Telemetry\Inbox::enabled($connection)) {
+                throw ValidationException::withMessages(['telematic' => ['Telemetry synchronization is disabled for this connection.']]);
+            }
+            $job = (new \Fleetbase\FleetOps\Jobs\PollTelematicTelemetry($connection->uuid, $jobId, $options))
+                ->onQueue($settings['poll_queue'] ?? 'default');
+            $queued = Telemetry\Queue::dispatch($job);
+            if (!$queued) {
+                $existing = data_get($connection->meta, 'last_sync_job_id');
+                if ($existing && in_array(data_get($connection->meta, 'last_sync_result'), Telemetry\Inbox::PENDING_REQUEST_RESULTS, true)) {
+                    return $existing;
+                }
+                // A scheduled sweep holds this connection's poll lease. Record the request so
+                // the next sweep adopts and completes it, rather than rejecting the user.
+            }
+            $connection->status = 'synchronizing';
+            $connection->meta   = array_merge($connection->meta ?? [], [
+                'last_sync_job_id'     => $jobId, 'last_sync_run_uuid' => null, 'last_sync_run_job_id' => null,
+                'last_sync_started_at' => now()->toDateTimeString(), 'last_sync_result' => 'queued',
+                'last_sync_phase'      => $queued ? 'queued' : 'waiting_for_sweep', 'last_sync_error' => null, 'last_sync_failed_reason' => null,
+            ]);
+            $connection->save();
+
+            return $jobId;
+        });
+    }
+
     /**
      * Link a device to a telematic.
      */
@@ -511,7 +553,8 @@ class TelematicService
         $this->setDeviceAttributeIfPresent($device, 'model', $payload['model'] ?? $payload['device_model'] ?? null);
         $this->setDeviceAttributeIfPresent($device, 'provider', $payload['provider'] ?? $payload['device_provider'] ?? $telematic?->provider);
         $this->setDeviceAttributeIfPresent($device, 'type', $payload['type'] ?? null);
-        $this->setDeviceAttributeIfPresent($device, 'internal_id', $payload['internal_id'] ?? $externalId);
+        // Partial messages must not replace an existing identity with the external ID fallback.
+        $this->setDeviceAttributeIfPresent($device, 'internal_id', $payload['internal_id'] ?? (filled($device->internal_id) ? null : $externalId));
         $this->setDeviceAttributeIfPresent($device, 'imei', $payload['imei'] ?? null);
         $this->setDeviceAttributeIfPresent($device, 'imsi', $payload['imsi'] ?? null);
         $this->setDeviceAttributeIfPresent($device, 'serial_number', $payload['serial_number'] ?? null);
@@ -762,6 +805,7 @@ class TelematicService
 
     protected function broadcastTelemetry(object $event, bool $afterCommit): void
     {
+        $event = Telemetry\Configuration::withBroadcastQueue($event);
         if ($afterCommit) {
             \Illuminate\Support\Facades\DB::afterCommit(fn () => broadcast($event));
         } else {

package/server/src/Support/Telematics/Telemetry/Configuration.php

@@ -23,6 +23,22 @@ class Configuration
         return array_replace(config('telematics.telemetry', []), $provider->telemetryOptions());
     }
 
+    /** Queue for connection-level jobs that predate durable polling (discovery and connection tests). */
+    public static function pollQueue(): string
+    {
+        return config('telematics.telemetry.poll_queue') ?: 'default';
+    }
+
+    /** Route a telemetry broadcast to the configured queue without changing other callers of the event. */
+    public static function withBroadcastQueue(object $event): object
+    {
+        if ($queue = config('telematics.telemetry.broadcast_queue')) {
+            $event->broadcastQueue = $queue;
+        }
+
+        return $event;
+    }
+
     public static function forConnection(Telematic $connection): array
     {
         return self::options(self::provider($connection));

package/server/src/Support/Telematics/Telemetry/Inbox.php

@@ -10,6 +10,9 @@ use Illuminate\Support\Str;
 
 class Inbox
 {
+    /** Manual request states that a sweep may still finalize. */
+    public const PENDING_REQUEST_RESULTS = ['queued', 'running', 'retrying'];
+
     public function accept(Telematic $telematic, array $payload, string $source, ?string $run = null, ?string $receivedAt = null): string
     {
         $json = json_encode($payload, JSON_THROW_ON_ERROR);
@@ -51,10 +54,53 @@ class Inbox
             if ((clone $items)->whereIn('status', ['pending', 'processing', 'retry'])->exists()) {
                 return;
             }
-            $failed = (clone $items)->sum('failed');
+            $failed  = (clone $items)->sum('failed');
+            $applied = (clone $items)->sum('applied');
+            $status  = $run->status === 'incomplete' ? 'incomplete' : ($failed ? 'partial' : 'completed');
             DB::table('telematic_sync_runs')->where('uuid', $id)->update([
-                'status'  => $run->status === 'incomplete' ? 'incomplete' : ($failed ? 'partial' : 'completed'),
-                'applied' => (clone $items)->sum('applied'), 'failed' => $failed, 'updated_at' => now(),
+                'status'  => $status,
+                'applied' => $applied, 'failed' => $failed, 'updated_at' => now(),
+            ]);
+            // An incomplete fetch can still have accepted batches, but the poll
+            // job owns its retry/failure lifecycle. Draining them must not end the
+            // manual request while its next fetch attempt is still queued.
+            if ($status === 'incomplete') {
+                return;
+            }
+            $connection = Telematic::withoutGlobalScopes()->where('uuid', $run->telematic_uuid)->lockForUpdate()->first();
+            if (!$connection || !self::enabled($connection)) {
+                return;
+            }
+            $meta   = $connection->meta ?? [];
+            $result = [
+                'last_sync_result'                                                         => $status === 'completed' ? 'success' : $status,
+                'last_sync_phase'                                                          => $status, 'last_sync_progress_at' => now()->toDateTimeString(),
+                'last_sync_fetched_total'                                                  => (int) $run->units, 'last_sync_page_count' => (int) $run->pages,
+                'last_sync_total'                                                          => (int) $applied, 'last_sync_linked_total' => (int) $applied,
+                'last_sync_failed_total'                                                   => (int) $failed,
+                'last_sync_error'                                                          => $status === 'completed' ? null : ($run->error ?? 'Some units could not be applied; inspect telemetry diagnostics.'),
+                $status === 'completed' ? 'last_sync_completed_at' : 'last_sync_failed_at' => now()->toDateTimeString(),
+            ];
+            // A previous sweep may finish after another manual request was queued.
+            // Only the run explicitly associated with that request may finalize it.
+            if (data_get($meta, 'last_sync_run_uuid') === $id && data_get($meta, 'last_sync_run_job_id')
+                && data_get($meta, 'last_sync_run_job_id') === data_get($meta, 'last_sync_job_id')) {
+                $connection->status = $status === 'completed' ? 'active' : 'error';
+                $connection->meta   = array_merge($meta, $result);
+                $connection->save();
+
+                return;
+            }
+            // A completed scheduled sweep proves the connection is healthy, so it replaces a
+            // stale failure. It never finalizes or overrides a manual request still in flight,
+            // and a partial sweep leaves the last reported state alone.
+            if ($status !== 'completed' || in_array(data_get($meta, 'last_sync_result'), self::PENDING_REQUEST_RESULTS, true)) {
+                return;
+            }
+            // Written without model events: sweeps run every minute and the model logs every save.
+            DB::table('telematics')->where('uuid', $connection->uuid)->update([
+                'status' => in_array($connection->status, ['error', 'synchronizing'], true) ? 'active' : $connection->status,
+                'meta'   => json_encode(array_merge($meta, $result), JSON_THROW_ON_ERROR),
             ]);
         });
     }

package/server/src/Support/Telematics/Telemetry/Ingestor.php

@@ -103,7 +103,7 @@ class Ingestor
             }
             if ($newer || $contactChanged) {
                 $snapshot = $device->fresh() ?? $device;
-                DB::afterCommit(fn () => broadcast(new DeviceTelemetryUpdated($snapshot)));
+                DB::afterCommit(fn () => broadcast(Configuration::withBroadcastQueue(new DeviceTelemetryUpdated($snapshot))));
             }
 
             return ['device' => $device, 'event' => $stored, 'events' => $stored ? [$stored] : [], 'sensors' => $sensors, 'duplicate' => $duplicate, 'invalid_position' => !$valid];