@fleetbase/fleetops-engine 0.6.70 → 0.6.72

package/server/src/Support/TrackingPublisher.php

@@ -0,0 +1,261 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Jobs\PublishTrackingUpdate;
+use Fleetbase\FleetOps\Models\Driver;
+use Fleetbase\FleetOps\Models\Entity;
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Vehicle;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Fleetbase\FleetOps\Tracking\TrackingContextBuilder;
+use Fleetbase\FleetOps\Tracking\TrackingIntelligenceService;
+use Fleetbase\FleetOps\Tracking\TrackingOptions;
+use Fleetbase\FleetOps\Tracking\TrackingStop;
+use Fleetbase\Support\SocketCluster\SocketClusterService;
+use Fleetbase\Support\SocketCluster\SocketToken;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Cache;
+
+/**
+ * Publishes per-customer updates to public tracking channels.
+ *
+ * The request-path hooks (orderChanged, stopChanged, driverMoved, vehicleMoved) do almost
+ * nothing: they bail out when socket authentication is off, throttle location changes through
+ * the cache, and queue a PublishTrackingUpdate job. The job builds and publishes the updates.
+ */
+class TrackingPublisher
+{
+    /**
+     * Seconds between position updates for one order (and between order lookups for one driver or vehicle).
+     */
+    public const LOCATION_INTERVAL = 5;
+
+    /**
+     * Seconds between ETA refreshes for one order driven by position changes.
+     */
+    public const ETA_INTERVAL = 60;
+
+    /**
+     * Most active orders a single driver or vehicle position change fans out to.
+     */
+    public const MAX_ORDERS_PER_SUBJECT = 25;
+
+    /**
+     * Order attributes whose change is published, with the reason reported.
+     */
+    public const ORDER_ATTRIBUTES = [
+        'status'                => TrackingUpdate::REASON_STATUS,
+        'started'               => TrackingUpdate::REASON_STATUS,
+        'dispatched'            => TrackingUpdate::REASON_STATUS,
+        'driver_assigned_uuid'  => TrackingUpdate::REASON_ASSIGNMENT,
+        'vehicle_assigned_uuid' => TrackingUpdate::REASON_ASSIGNMENT,
+        'time'                  => TrackingUpdate::REASON_ETA,
+        'distance'              => TrackingUpdate::REASON_ETA,
+    ];
+
+    public static function enabled(): bool
+    {
+        return SocketToken::enabled();
+    }
+
+    /**
+     * An order was saved: queue an update when a published attribute changed.
+     */
+    public function orderChanged(Order $order): bool
+    {
+        if (!static::enabled() || !$order->uuid) {
+            return false;
+        }
+
+        $changed = array_intersect_key(self::ORDER_ATTRIBUTES, $order->getChanges());
+        if ($changed === []) {
+            return false;
+        }
+
+        $reasons = array_values($changed);
+        $reason  = in_array(TrackingUpdate::REASON_STATUS, $reasons, true) ? TrackingUpdate::REASON_STATUS : $reasons[0];
+
+        return $this->queue($order->uuid, $reason, $order->getConnectionName());
+    }
+
+    /**
+     * An order's stops were edited: queue an update so customers see the new route and ETAs.
+     */
+    public function routeChanged(Order $order): bool
+    {
+        if (!static::enabled() || !$order->uuid) {
+            return false;
+        }
+
+        return $this->queue($order->uuid, TrackingUpdate::REASON_ROUTE, $order->getConnectionName());
+    }
+
+    /**
+     * A waypoint or entity activity changed: queue an update for its order.
+     */
+    public function stopChanged(Waypoint|Entity|null $subject): bool
+    {
+        if (!static::enabled() || !$subject || !$subject->payload_uuid) {
+            return false;
+        }
+
+        $connection = $subject->getConnectionName();
+        $orderUuid  = Order::on($connection)->where('payload_uuid', $subject->payload_uuid)->value('uuid');
+
+        return $orderUuid ? $this->queue($orderUuid, TrackingUpdate::REASON_STOP, $connection) : false;
+    }
+
+    /**
+     * A driver reported a position: queue a location update for each of their en-route orders.
+     */
+    public function driverMoved(Driver $driver): int
+    {
+        if (!static::enabled() || !$driver->uuid || !Cache::add('fleetops:tracking:driver:' . $driver->uuid, 1, self::LOCATION_INTERVAL)) {
+            return 0;
+        }
+
+        $connection = $driver->getConnectionName();
+
+        return $this->queueLocations($this->enRouteOrders($connection)->where('driver_assigned_uuid', $driver->uuid)->limit(self::MAX_ORDERS_PER_SUBJECT)->pluck('uuid'), $connection);
+    }
+
+    /**
+     * A vehicle reported a position: queue a location update for each en-route order it serves.
+     */
+    public function vehicleMoved(Vehicle $vehicle): int
+    {
+        if (!static::enabled() || !$vehicle->uuid || !Cache::add('fleetops:tracking:vehicle:' . $vehicle->uuid, 1, self::LOCATION_INTERVAL)) {
+            return 0;
+        }
+
+        $connection = $vehicle->getConnectionName();
+        $drivers    = Driver::on($connection)->where('vehicle_uuid', $vehicle->uuid)->select('uuid')->toBase();
+        $orders     = $this->enRouteOrders($connection)
+            ->where(function ($query) use ($vehicle, $drivers) {
+                $query->where('vehicle_assigned_uuid', $vehicle->uuid)->orWhereIn('driver_assigned_uuid', $drivers);
+            })
+            ->limit(self::MAX_ORDERS_PER_SUBJECT)
+            ->pluck('uuid');
+
+        return $this->queueLocations($orders, $connection);
+    }
+
+    /**
+     * Publish the full update to every customer of the order. Returns the channels published to.
+     */
+    public function publishOrder(Order $order, string $reason = TrackingUpdate::REASON_STATUS): int
+    {
+        if (!static::enabled()) {
+            return 0;
+        }
+
+        $stops   = $this->stopsFor($order);
+        $tracker = $this->trackerFor($order);
+        $sent    = 0;
+
+        foreach (TrackingScope::allForOrder($order, $this->waypointsOf($stops)) as $scope) {
+            $update = TrackingUpdate::for($order, $scope, $stops, $tracker);
+            $sent += (int) $this->send(TrackingChannel::name($scope), $update->toArray($reason));
+        }
+
+        return $sent;
+    }
+
+    /**
+     * Publish the position to every customer of the order who may see it. Returns the channels published to.
+     */
+    public function publishLocation(Order $order): int
+    {
+        if (!static::enabled()) {
+            return 0;
+        }
+
+        $stops = $this->stopsFor($order);
+        $sent  = 0;
+
+        foreach (TrackingScope::allForOrder($order, $this->waypointsOf($stops)) as $scope) {
+            $payload = (new TrackingUpdate($order, $scope, $stops))->locationPayload();
+            if ($payload !== null) {
+                $sent += (int) $this->send(TrackingChannel::name($scope), $payload);
+            }
+        }
+
+        return $sent;
+    }
+
+    /**
+     * Every stop of the order in route order, with completion state.
+     *
+     * @return Collection<int, TrackingStop>
+     */
+    protected function stopsFor(Order $order): Collection
+    {
+        return app(TrackingContextBuilder::class)->build($order, TrackingOptions::fromArray([], $order->company_uuid))->stops;
+    }
+
+    /**
+     * The tracking intelligence result for the order's ETAs; empty when it cannot be computed.
+     */
+    protected function trackerFor(Order $order): array
+    {
+        if (in_array(strtolower((string) $order->status), TrackingUpdate::TERMINAL_STATUSES, true)) {
+            return [];
+        }
+
+        try {
+            return app(TrackingIntelligenceService::class)->track($order);
+        } catch (\Throwable) {
+            return [];
+        }
+    }
+
+    protected function send(string $channel, array $payload): bool
+    {
+        return SocketClusterService::publish($channel, $payload);
+    }
+
+    protected function queue(string $orderUuid, string $reason, ?string $connection = null): bool
+    {
+        PublishTrackingUpdate::dispatch($orderUuid, $reason, $connection);
+
+        return true;
+    }
+
+    /**
+     * Queue a location update for each order not updated within the location interval.
+     */
+    protected function queueLocations(iterable $orderUuids, ?string $connection): int
+    {
+        $queued = 0;
+        foreach ($orderUuids as $orderUuid) {
+            if (Cache::add('fleetops:tracking:location:' . $orderUuid, 1, self::LOCATION_INTERVAL)) {
+                $queued += (int) $this->queue($orderUuid, TrackingUpdate::REASON_LOCATION, $connection);
+            }
+        }
+
+        return $queued;
+    }
+
+    /**
+     * Orders that have started and are not yet completed or canceled.
+     */
+    protected function enRouteOrders(?string $connection)
+    {
+        return Order::on($connection)
+            ->whereNotIn('status', TrackingUpdate::TERMINAL_STATUSES)
+            ->where(function ($query) {
+                $query->where('started', 1)->orWhereNotNull('started_at')->orWhere('status', 'started');
+            });
+    }
+
+    /**
+     * @param Collection<int, TrackingStop> $stops
+     *
+     * @return array<int, Waypoint>
+     */
+    protected function waypointsOf(Collection $stops): array
+    {
+        return $stops->map(fn (TrackingStop $stop) => $stop->waypoint)->filter()->values()->all();
+    }
+}

package/server/src/Support/TrackingScope.php

@@ -0,0 +1,182 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\Order;
+use Fleetbase\FleetOps\Models\Waypoint;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\Relation;
+
+/**
+ * One customer's view of one order, the unit a public tracking channel is scoped to.
+ *
+ * A stop's customer is the waypoint's `customer` morph (a Contact or a Vendor); stops without
+ * one belong to the order's customer. Every customer of an order therefore gets their own
+ * scope, their own `tracking.{opaque}` channel and their own sanitized updates.
+ *
+ * Identity is (order_uuid, customer_type, customer_uuid). customer_type is the morph class as
+ * stored on the order or waypoint (a fully qualified model class), normalized without a
+ * leading backslash so that every caller derives the same channel.
+ */
+final class TrackingScope implements \JsonSerializable
+{
+    public readonly string $order_uuid;
+
+    public readonly string $customer_type;
+
+    public readonly string $customer_uuid;
+
+    /**
+     * The order's company, when known. Not part of the scope's identity.
+     */
+    public readonly ?string $company_uuid;
+
+    private ?Order $order;
+
+    public function __construct(string $orderUuid, string $customerType, string $customerUuid, ?Order $order = null)
+    {
+        $customerType = static::normalizeType($customerType);
+
+        if ($orderUuid === '' || $customerType === '' || $customerUuid === '') {
+            throw new \InvalidArgumentException('A tracking scope requires an order, a customer type and a customer.');
+        }
+
+        $this->order_uuid    = $orderUuid;
+        $this->customer_type = $customerType;
+        $this->customer_uuid = $customerUuid;
+        $this->order         = $order && $order->uuid === $orderUuid ? $order : null;
+        $this->company_uuid  = $this->order?->company_uuid ?: null;
+    }
+
+    /**
+     * The scope of the order's own customer, or null when the order has none.
+     */
+    public static function forOrder(Order $order): ?self
+    {
+        return static::make($order, $order->customer_type, $order->customer_uuid);
+    }
+
+    /**
+     * The scope a stop belongs to: the waypoint's customer, else the order's customer.
+     */
+    public static function forStop(Order $order, ?Waypoint $waypoint = null): ?self
+    {
+        return static::make($order, $waypoint?->customer_type, $waypoint?->customer_uuid) ?? static::forOrder($order);
+    }
+
+    /**
+     * The scope of an explicit customer on an order.
+     */
+    public static function forCustomer(Order $order, Model $customer): self
+    {
+        return new self((string) $order->uuid, $customer->getMorphClass(), (string) $customer->uuid, $order);
+    }
+
+    /**
+     * Every customer scope of an order: the order's customer first, then each distinct waypoint customer.
+     *
+     * @param iterable<Waypoint>|null $waypoints the order's waypoints; loaded from the payload when null
+     *
+     * @return array<int, self>
+     */
+    public static function allForOrder(Order $order, ?iterable $waypoints = null): array
+    {
+        if ($waypoints === null) {
+            $waypoints = $order->payload_uuid ? Waypoint::on($order->getConnectionName())->where('payload_uuid', $order->payload_uuid)->without(['place'])->get(['uuid', 'payload_uuid', 'customer_uuid', 'customer_type']) : [];
+        }
+
+        $scopes = [];
+        if ($scope = static::forOrder($order)) {
+            $scopes[$scope->key()] = $scope;
+        }
+
+        foreach ($waypoints as $waypoint) {
+            $scope = $waypoint instanceof Waypoint ? static::make($order, $waypoint->customer_type, $waypoint->customer_uuid) : null;
+            if ($scope && !isset($scopes[$scope->key()])) {
+                $scopes[$scope->key()] = $scope;
+            }
+        }
+
+        return array_values($scopes);
+    }
+
+    /**
+     * The message the channel id is derived from: "{order_uuid}:{customer_type}:{customer_uuid}".
+     */
+    public function key(): string
+    {
+        return $this->order_uuid . ':' . $this->customer_type . ':' . $this->customer_uuid;
+    }
+
+    /**
+     * Whether this scope is the given customer (type and uuid).
+     */
+    public function is(?string $customerType, ?string $customerUuid): bool
+    {
+        return $customerUuid !== null
+            && $customerUuid !== ''
+            && $customerUuid === $this->customer_uuid
+            && static::normalizeType((string) $customerType) === $this->customer_type;
+    }
+
+    /**
+     * Whether this scope is the order's own customer.
+     */
+    public function isOrderCustomer(Order $order): bool
+    {
+        return $order->uuid === $this->order_uuid && $this->is($order->customer_type, $order->customer_uuid);
+    }
+
+    /**
+     * Whether a stop belongs to this scope: its waypoint's customer, else the order's customer.
+     */
+    public function ownsStop(Order $order, ?Waypoint $waypoint = null): bool
+    {
+        if ($waypoint && $waypoint->customer_uuid && $waypoint->customer_type) {
+            return $this->is($waypoint->customer_type, $waypoint->customer_uuid);
+        }
+
+        return $this->isOrderCustomer($order);
+    }
+
+    /**
+     * The order this scope is about, loaded once when not given.
+     */
+    public function order(): ?Order
+    {
+        return $this->order ??= Order::where('uuid', $this->order_uuid)->first();
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'order_uuid'    => $this->order_uuid,
+            'customer_type' => $this->customer_type,
+            'customer_uuid' => $this->customer_uuid,
+        ];
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->toArray();
+    }
+
+    /**
+     * A morph type as a model class without a leading backslash; morph map aliases resolve to their class.
+     */
+    public static function normalizeType(string $type): string
+    {
+        $type = ltrim(trim($type), '\\');
+
+        return ltrim((string) (Relation::getMorphedModel($type) ?? $type), '\\');
+    }
+
+    private static function make(Order $order, ?string $customerType, ?string $customerUuid): ?self
+    {
+        if (!$order->uuid || !$customerType || !$customerUuid) {
+            return null;
+        }
+
+        return new self((string) $order->uuid, $customerType, $customerUuid, $order);
+    }
+}