@fleetbase/fleetops-engine 0.6.70 → 0.6.72

package/server/src/Support/ProfileAccountManager.php

@@ -11,7 +11,9 @@ use Fleetbase\Models\Company;
 use Fleetbase\Models\CompanyUser;
 use Fleetbase\Models\User;
 use Fleetbase\Services\SmsService;
+use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Mail;
+use Illuminate\Support\Facades\Schema;
 use Illuminate\Support\Str;
 
 /**
@@ -174,7 +176,15 @@ class ProfileAccountManager
         $user->save();
         $user->setType($type);
 
-        static::attachToCompany($user, $companyUuid, $type);
+        try {
+            static::attachToCompany($user, $companyUuid, $type);
+        } catch (\Throwable $e) {
+            // Leave no account behind for a profile that was never created
+            static::removeSandboxCopy($user);
+            $user->forceDelete();
+
+            throw $e;
+        }
 
         return $user;
     }
@@ -355,6 +365,8 @@ class ProfileAccountManager
             return null;
         }
 
+        static::copyAccountToSandbox($user, $companyUuid);
+
         $role        = static::ROLES[$type] ?? static::ROLES['contact'];
         $companyUser = CompanyUser::where(['company_uuid' => $companyUuid, 'user_uuid' => $user->uuid])->first();
         if (!$companyUser) {
@@ -372,6 +384,47 @@ class ProfileAccountManager
         return $companyUser;
     }
 
+    /**
+     * Copy the account and its organization into the sandbox database for a
+     * test-key request. Users and companies always live in the live database,
+     * but memberships follow the request into the sandbox, whose foreign keys
+     * need both rows there too.
+     */
+    public static function copyAccountToSandbox(User $user, ?string $companyUuid = null): void
+    {
+        if (!session('is_sandbox')) {
+            return;
+        }
+
+        $live    = DB::connection($user->getConnectionName());
+        $sandbox = DB::connection('sandbox');
+        $account = (array) $live->table($user->getTable())->where('uuid', $user->uuid)->first();
+        $company = $companyUuid ? (array) $live->table('companies')->where('uuid', $companyUuid)->first() : [];
+
+        Schema::connection('sandbox')->disableForeignKeyConstraints();
+
+        try {
+            if ($company) {
+                $sandbox->table('companies')->updateOrInsert(['uuid' => $company['uuid']], array_diff_key($company, ['id' => true]));
+            }
+
+            $account['company_uuid'] = ($account['company_uuid'] ?? null) ?: $companyUuid;
+            $sandbox->table($user->getTable())->updateOrInsert(['uuid' => $user->uuid], array_diff_key($account, ['id' => true]));
+        } finally {
+            Schema::connection('sandbox')->enableForeignKeyConstraints();
+        }
+    }
+
+    /**
+     * Remove the sandbox copy of an account that is being discarded.
+     */
+    public static function removeSandboxCopy(User $user): void
+    {
+        if (session('is_sandbox')) {
+            DB::connection('sandbox')->table($user->getTable())->where('uuid', $user->uuid)->delete();
+        }
+    }
+
     public static function normalizeEmail(?string $email): ?string
     {
         $email = is_string($email) ? strtolower(trim($email)) : null;

package/server/src/Support/ResolvesOrderServiceStops.php

@@ -15,6 +15,7 @@ use Fleetbase\FleetOps\Models\TrackingNumber;
 use Fleetbase\FleetOps\Models\TrackingStatus;
 use Fleetbase\FleetOps\Models\Waypoint;
 use Fleetbase\LaravelMysqlSpatial\Types\Point;
+use Fleetbase\Support\ApiModelCache;
 use Fleetbase\Support\TemplateString;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\DB;
@@ -185,6 +186,7 @@ trait ResolvesOrderServiceStops
 
         $payload->current_waypoint_uuid = $place->uuid;
         $payload->saveQuietly();
+        ApiModelCache::invalidateModelCache($payload, $payload->company_uuid);
         $payload->setRelation('currentWaypoint', $place);
 
         if (($stop['waypoint'] ?? null) instanceof Waypoint) {
@@ -254,6 +256,7 @@ trait ResolvesOrderServiceStops
             $activityId = $waypoint->insertActivity($activity, $location, $proof);
             if ($activityId && $waypoint->tracking_number_uuid) {
                 DB::table((new TrackingNumber())->getTable())->where('uuid', $waypoint->tracking_number_uuid)->update(['status_uuid' => $activityId]);
+                ApiModelCache::invalidateModelCache(new TrackingNumber(), $payload->company_uuid ?? $order->company_uuid);
                 if ($waypoint->relationLoaded('trackingNumber')) {
                     $waypoint->trackingNumber->status_uuid = $activityId;
                     $waypoint->trackingNumber->unsetRelation('status');
@@ -391,6 +394,7 @@ trait ResolvesOrderServiceStops
         // @codeCoverageIgnoreEnd
 
         DB::table($payload->getTable())->where('uuid', $payload->uuid)->update([$column => $trackingNumberUuid]);
+        ApiModelCache::invalidateModelCache($payload, $payload->company_uuid ?? $order->company_uuid);
         $payload->{$column} = $trackingNumberUuid;
 
         return TrackingNumber::where('uuid', $trackingNumberUuid)->first();
@@ -417,6 +421,7 @@ trait ResolvesOrderServiceStops
 
         if ($activityId) {
             DB::table($trackingNumber->getTable())->where('uuid', $trackingNumber->uuid)->update(['status_uuid' => $activityId]);
+            ApiModelCache::invalidateModelCache($trackingNumber, $payload->company_uuid ?? $order->company_uuid);
             $trackingNumber->status_uuid = $activityId;
         }
 

package/server/src/Support/SocketChannels.php

@@ -0,0 +1,346 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\Contact;
+use Fleetbase\FleetOps\Models\Device;
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Entity;
+use Fleetbase\FleetOps\Models\Fleet;
+use Fleetbase\FleetOps\Models\IntegratedVendor;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Payload;
+use Fleetbase\FleetOps\Models\Place;
+use Fleetbase\FleetOps\Models\Position;
+use Fleetbase\FleetOps\Models\PurchaseRate;
+use Fleetbase\FleetOps\Models\ServiceArea;
+use Fleetbase\FleetOps\Models\ServiceQuote;
+use Fleetbase\FleetOps\Models\ServiceRate;
+use Fleetbase\FleetOps\Models\TrackingNumber;
+use Fleetbase\FleetOps\Models\TrackingStatus;
+use Fleetbase\FleetOps\Models\Trailer;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Models\Vendor;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Models\Zone;
+use Fleetbase\Models\Company;
+use Fleetbase\Models\User;
+use Fleetbase\Support\SocketCluster\SocketChannelRegistry;
+use Fleetbase\Support\SocketCluster\SocketPrincipal;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\Request;
+
+/**
+ * Who may subscribe to FleetOps realtime channels.
+ *
+ * Channel names are "{prefix}.{id}" where the prefix is the snake_case model name the lifecycle
+ * events broadcast on (plus `driverAssigned`, which the order's assigned-driver channel uses) and
+ * the id is the model's uuid or public_id.
+ *
+ * Console users and API credentials may subscribe to any of their own company's records. Drivers
+ * and customers get narrow access only:
+ *
+ * - a driver: their own driver record, their current vehicle and its devices and positions, and
+ *   orders assigned to them (directly, or through one of the order's payload entities);
+ * - a customer: orders they are the customer of, and the driver and vehicle of those orders while
+ *   they are active.
+ *
+ * Public tracking channels (`tracking.{opaque}`) are denied here to everyone: only a `tracking`
+ * token, whose scope names the channel exactly, can subscribe to one.
+ */
+class SocketChannels
+{
+    /**
+     * Order statuses after which a customer no longer sees the order's driver or vehicle.
+     */
+    public const TERMINAL_ORDER_STATUSES = ['completed', 'canceled'];
+
+    /**
+     * Prefixes resolved by the generic model resolver, with their model.
+     */
+    public const MODEL_PREFIXES = [
+        'order'           => Order::class,
+        'driver'          => Driver::class,
+        'driverAssigned'  => Driver::class,
+        'vehicle'         => Vehicle::class,
+        'trailer'         => Trailer::class,
+        'device'          => Device::class,
+        'waypoint'        => Waypoint::class,
+        'entity'          => Entity::class,
+        'place'           => Place::class,
+        'contact'         => Contact::class,
+        'fleet'           => Fleet::class,
+        'zone'            => Zone::class,
+        'service_area'    => ServiceArea::class,
+        'service_rate'    => ServiceRate::class,
+        'service_quote'   => ServiceQuote::class,
+        'purchase_rate'   => PurchaseRate::class,
+        'tracking_status' => TrackingStatus::class,
+        'tracking_number' => TrackingNumber::class,
+        'payload'         => Payload::class,
+    ];
+
+    /**
+     * Prefixes whose id may name more than one kind of record, with the models tried in order.
+     */
+    public const MORPH_PREFIXES = [
+        'customer'    => [Contact::class, Vendor::class],
+        'vendor'      => [Vendor::class, IntegratedVendor::class],
+        'facilitator' => [Vendor::class, IntegratedVendor::class, Contact::class],
+    ];
+
+    /**
+     * Register every FleetOps prefix and the driver principal resolver.
+     */
+    public static function register(SocketChannelRegistry $registry): void
+    {
+        foreach (self::MODEL_PREFIXES as $prefix => $modelClass) {
+            $registry->registerModel($prefix, $modelClass, static::narrowFor($prefix));
+        }
+
+        foreach (self::MORPH_PREFIXES as $prefix => $modelClasses) {
+            $registry->register($prefix, static::resolver($modelClasses, [static::class, 'narrowSelf']));
+        }
+
+        // Positions have no public_id, so they are looked up by uuid only.
+        $registry->register('position', static::resolver([Position::class], [static::class, 'narrowPosition'], false));
+
+        // tracking.{opaque} is reachable only through a tracking token's exact scope.
+        $registry->register(TrackingChannel::PREFIX, static fn (): bool => false);
+
+        $registry->registerPrincipalResolver([static::class, 'driverPrincipal']);
+    }
+
+    /**
+     * The narrow rule used for driver and customer principals on a generic model prefix.
+     */
+    public static function narrowFor(string $prefix): ?callable
+    {
+        return match ($prefix) {
+            'order'                    => [static::class, 'narrowOrder'],
+            'driver', 'driverAssigned' => [static::class, 'narrowDriver'],
+            'vehicle'                  => [static::class, 'narrowVehicle'],
+            'device'                   => [static::class, 'narrowDevice'],
+            'contact'                  => [static::class, 'narrowSelf'],
+            default                    => null,
+        };
+    }
+
+    /**
+     * A resolver over one or more models: company match for user and API principals, the narrow
+     * rule for driver and customer principals, deny for everyone else.
+     *
+     * @param array<int, class-string<Model>> $modelClasses
+     */
+    public static function resolver(array $modelClasses, ?callable $narrow = null, bool $byPublicId = true): \Closure
+    {
+        return static function (SocketPrincipal $principal, string $id, string $channel = '') use ($modelClasses, $narrow, $byPublicId): bool {
+            $narrowed = $principal->kind === 'driver' || $principal->kind === 'customer';
+            if ((!$principal->isCompanyScoped() && !$narrowed) || $id === '') {
+                return false;
+            }
+
+            $model = static::find($modelClasses, $principal, $id, $byPublicId);
+            if ($model === null) {
+                return false;
+            }
+
+            if ($principal->isCompanyScoped()) {
+                return $principal->cid !== null && $model->company_uuid === $principal->cid;
+            }
+
+            return $narrow !== null && (bool) $narrow($principal, $model);
+        };
+    }
+
+    /**
+     * The first of the models whose uuid (or public_id) is the id, in the principal's environment.
+     *
+     * @param array<int, class-string<Model>> $modelClasses
+     */
+    public static function find(array $modelClasses, SocketPrincipal $principal, string $id, bool $byPublicId = true): ?Model
+    {
+        foreach ($modelClasses as $modelClass) {
+            $model = $modelClass::on(static::connection($principal))
+                ->where(function ($query) use ($id, $byPublicId) {
+                    $query->where('uuid', $id);
+                    if ($byPublicId) {
+                        $query->orWhere('public_id', $id);
+                    }
+                })
+                ->first();
+
+            if ($model) {
+                return $model;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * The database connection for the principal's environment; null is the default one.
+     */
+    public static function connection(SocketPrincipal $principal): ?string
+    {
+        return $principal->env === 'test' ? 'sandbox' : null;
+    }
+
+    /**
+     * Orders: a driver's when assigned to them (directly or on one of its payload entities), a customer's own.
+     */
+    public static function narrowOrder(SocketPrincipal $principal, Model $order): bool
+    {
+        if ($principal->kind === 'customer') {
+            return static::isSelf($principal, $order->customer_uuid);
+        }
+
+        if ($principal->kind !== 'driver') {
+            return false;
+        }
+
+        if (static::isSelf($principal, $order->driver_assigned_uuid)) {
+            return true;
+        }
+
+        return !empty($order->payload_uuid)
+            && Entity::on($order->getConnectionName())
+                ->where('payload_uuid', $order->payload_uuid)
+                ->where('driver_assigned_uuid', $principal->sub)
+                ->exists();
+    }
+
+    /**
+     * Drivers: a driver only themselves; a customer the driver of one of their active orders.
+     */
+    public static function narrowDriver(SocketPrincipal $principal, Model $driver): bool
+    {
+        if ($principal->kind === 'driver') {
+            return static::isSelf($principal, $driver->uuid);
+        }
+
+        return $principal->kind === 'customer'
+            && static::activeCustomerOrders($principal, $driver->getConnectionName())
+                ->where('driver_assigned_uuid', $driver->uuid)
+                ->exists();
+    }
+
+    /**
+     * Vehicles: a driver their current vehicle; a customer the vehicle of one of their active orders,
+     * whether assigned to the order or driven by the order's driver.
+     */
+    public static function narrowVehicle(SocketPrincipal $principal, Model $vehicle): bool
+    {
+        if ($principal->kind === 'driver') {
+            return static::driverVehicleUuid($principal, $vehicle->getConnectionName()) === $vehicle->uuid;
+        }
+
+        if ($principal->kind !== 'customer') {
+            return false;
+        }
+
+        $connection = $vehicle->getConnectionName();
+        $drivers    = Driver::on($connection)->where('vehicle_uuid', $vehicle->uuid)->select('uuid')->toBase();
+
+        return static::activeCustomerOrders($principal, $connection)
+            ->where(function ($query) use ($vehicle, $drivers) {
+                $query->where('vehicle_assigned_uuid', $vehicle->uuid)->orWhereIn('driver_assigned_uuid', $drivers);
+            })
+            ->exists();
+    }
+
+    /**
+     * Devices: a driver those attached to themselves or to their current vehicle.
+     */
+    public static function narrowDevice(SocketPrincipal $principal, Model $device): bool
+    {
+        return $principal->kind === 'driver' && static::ownsDriverSubject($principal, $device->attachable_uuid, $device->getConnectionName());
+    }
+
+    /**
+     * Positions: a driver those recorded for themselves or for their current vehicle.
+     */
+    public static function narrowPosition(SocketPrincipal $principal, Model $position): bool
+    {
+        return $principal->kind === 'driver' && static::ownsDriverSubject($principal, $position->subject_uuid, $position->getConnectionName());
+    }
+
+    /**
+     * Contacts, customers, vendors, facilitators: a customer only themselves.
+     */
+    public static function narrowSelf(SocketPrincipal $principal, Model $model): bool
+    {
+        return $principal->kind === 'customer' && static::isSelf($principal, $model->uuid);
+    }
+
+    /**
+     * Claim a Sanctum-authenticated user who is a driver of the current company as a driver principal.
+     */
+    public static function driverPrincipal(Request $request, $user): ?SocketPrincipal
+    {
+        if (!$user instanceof User || !$user->uuid) {
+            return null;
+        }
+
+        $companyUuid = session('company') ?: $user->company_uuid;
+        if (!$companyUuid) {
+            return null;
+        }
+
+        $driver = Driver::where('user_uuid', $user->uuid)->where('company_uuid', $companyUuid)->first();
+        if (!$driver) {
+            return null;
+        }
+
+        $connection = $driver->getConnectionName();
+        $cpid       = Company::on($connection)->where('uuid', $companyUuid)->value('public_id');
+
+        return new SocketPrincipal(
+            kind: 'driver',
+            sub: (string) $driver->uuid,
+            cid: (string) $companyUuid,
+            cpid: is_string($cpid) && $cpid !== '' ? $cpid : null,
+            env: $connection === 'sandbox' ? 'test' : 'live',
+            ids: array_values(array_filter([$driver->uuid, $driver->public_id, $user->uuid, $user->public_id], fn ($id) => is_string($id) && $id !== '')),
+            adm: false,
+        );
+    }
+
+    /**
+     * The customer's orders that are not completed or canceled.
+     */
+    protected static function activeCustomerOrders(SocketPrincipal $principal, ?string $connection): Builder
+    {
+        return Order::on($connection)
+            ->whereIn('customer_uuid', array_values(array_unique([$principal->sub, ...$principal->ids])))
+            ->whereNotIn('status', self::TERMINAL_ORDER_STATUSES);
+    }
+
+    /**
+     * Whether a record's subject is the driver principal or the driver's current vehicle.
+     */
+    protected static function ownsDriverSubject(SocketPrincipal $principal, ?string $subjectUuid, ?string $connection): bool
+    {
+        if (!$subjectUuid) {
+            return false;
+        }
+
+        return static::isSelf($principal, $subjectUuid) || static::driverVehicleUuid($principal, $connection) === $subjectUuid;
+    }
+
+    /**
+     * Whether an id is the principal's own (its subject or one of its ids).
+     */
+    protected static function isSelf(SocketPrincipal $principal, mixed $id): bool
+    {
+        return is_string($id) && $id !== '' && ($id === $principal->sub || $principal->owns($id));
+    }
+
+    protected static function driverVehicleUuid(SocketPrincipal $principal, ?string $connection): ?string
+    {
+        $vehicleUuid = Driver::on($connection)->where('uuid', $principal->sub)->value('vehicle_uuid');
+
+        return is_string($vehicleUuid) && $vehicleUuid !== '' ? $vehicleUuid : null;
+    }
+}

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

@@ -13,6 +13,8 @@ use Fleetbase\FleetOps\Models\Sensor;
 use Fleetbase\FleetOps\Models\Telematic;
 use Fleetbase\FleetOps\Models\Trailer;
 use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Support\ApiCacheThrottle;
+use Fleetbase\FleetOps\Support\TrackingPublisher;
 use Fleetbase\LaravelMysqlSpatial\Types\Point as SpatialPoint;
 use Illuminate\Support\Carbon;
 use Illuminate\Support\Facades\Crypt;
@@ -759,7 +761,8 @@ class TelematicService
             'last_provider'       => $event->provider,
             'last_telemetry_data' => array_filter($eventData, fn ($value) => $value !== null),
         ]);
-        $trailer->save();
+        // Every telemetry event saves the trailer: model events fire, cache invalidation is coalesced
+        ApiCacheThrottle::telemetryWrite($trailer, fn () => $trailer->save());
 
         $broadcast = new TrailerLocationChanged($trailer, ['source' => 'telematics', 'device_event_uuid' => $event->uuid, 'provider' => $event->provider, 'position_at' => $event->occurred_at?->toISOString()]);
         $this->broadcastTelemetry($broadcast, $eventData['_ordered_telemetry'] ?? false);
@@ -802,7 +805,8 @@ class TelematicService
                 'fuel_level' => $eventData['fuel_level'] ?? null,
             ], fn ($value) => $value !== null),
         ]);
-        $vehicle->save();
+        // Every telemetry event saves the vehicle: model events fire, cache invalidation is coalesced
+        ApiCacheThrottle::telemetryWrite($vehicle, fn () => $vehicle->save());
 
         $broadcast = new VehicleLocationChanged($vehicle, [
             'source'            => 'telematics',
@@ -811,6 +815,7 @@ class TelematicService
             'position_at'       => $event->occurred_at?->toISOString(),
         ]);
         $this->broadcastTelemetry($broadcast, $eventData['_ordered_telemetry'] ?? false);
+        app(TrackingPublisher::class)->vehicleMoved($vehicle);
     }
 
     protected function broadcastTelemetry(object $event, bool $afterCommit): void

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

@@ -4,6 +4,7 @@ namespace Fleetbase\FleetOps\Support\Telematics\Telemetry;
 
 use Fleetbase\FleetOps\Jobs\ProcessTelematicDelivery;
 use Fleetbase\FleetOps\Models\Telematic;
+use Fleetbase\Support\ApiModelCache;
 use Illuminate\Support\Facades\Crypt;
 use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Str;
@@ -98,10 +99,16 @@ class Inbox
                 return;
             }
             // Written without model events: sweeps run every minute and the model logs every save.
+            $connectionStatus = in_array($connection->status, ['error', 'synchronizing'], true) ? 'active' : $connection->status;
             DB::table('telematics')->where('uuid', $connection->uuid)->update([
-                'status' => in_array($connection->status, ['error', 'synchronizing'], true) ? 'active' : $connection->status,
+                'status' => $connectionStatus,
                 'meta'   => json_encode(array_merge($meta, $result), JSON_THROW_ON_ERROR),
             ]);
+            // Cached device lists embed the telematic. Only a status change invalidates
+            // them: the sync meta changes on every sweep and may lag by the list TTL.
+            if ($connectionStatus !== $connection->status) {
+                ApiModelCache::invalidateModelCache($connection, $connection->company_uuid);
+            }
         });
     }
 }

package/server/src/Support/TrackingChannel.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\Support\SocketCluster\SocketToken;
+
+/**
+ * The public tracking channel of one customer on one order: `tracking.{opaque}`.
+ *
+ * The opaque id is derived by core-api (SocketToken::trackingId): lowercase, unpadded base32 of
+ * HMAC-SHA256(tracking key, "{order_uuid}:{customer_type}:{customer_uuid}"), first 26 characters,
+ * where the tracking key is derived from SOCKETCLUSTER_AUTH_KEY. Nobody can guess or enumerate it
+ * without the auth key, and it reveals nothing about the order.
+ *
+ * The channel registry denies the `tracking` prefix to every principal; the only way in is a
+ * `tracking` token from token(), whose scope names exactly this channel.
+ */
+final class TrackingChannel
+{
+    public const PREFIX = 'tracking';
+
+    /**
+     * The channel name for a customer's scope.
+     *
+     * @throws \RuntimeException when socket authentication is not configured
+     */
+    public static function name(TrackingScope $scope): string
+    {
+        return self::PREFIX . '.' . static::opaqueId($scope);
+    }
+
+    /**
+     * The opaque id for a customer's scope.
+     *
+     * @throws \RuntimeException when socket authentication is not configured
+     */
+    public static function opaqueId(TrackingScope $scope): string
+    {
+        return SocketToken::trackingId($scope->order_uuid, $scope->customer_type, $scope->customer_uuid);
+    }
+
+    /**
+     * Mint the token (kind `tracking`, 1800 s) that may subscribe to this scope's channel and nothing else.
+     *
+     * The caller (the public tracking API) checks its own grant for the scope first.
+     *
+     * @return array{token: string, expires_in: int, expires_at: string}
+     *
+     * @throws \RuntimeException when socket authentication is not configured
+     */
+    public static function token(TrackingScope $scope): array
+    {
+        return SocketToken::forTracking($scope);
+    }
+}