Core Api Laravel Package

Technical Evaluation

Architecture fit: fleetbase/core-api remains a Composer-installed Laravel package and the system of record for the Fleetbase API surface, but v1.6.71 widens its footprint from domain endpoints into platform configuration and cross-cutting infrastructure. Four additions matter to a TPM: (1) an internal socket-settings API (GET/POST int/v1/settings/socket) that lets administrators manage realtime channel auth — switch, mode (off/log/enforce), token TTL, allowed origins, publisher origin — with a signed GET int/v1/socket/config the socket server polls at runtime; (2) parent_uuid on internal Category responses, enabling a console to build a category tree from a flat list (Storefront's nested product categories); (3) a fix to Find::httpFilterForModel() that was caching filter resolution per model class for the life of the process, ignoring a controller's own $filter and request audience; (4) cache keys now carrying the database connection ({api_query}:mysql:… / {api_query}:sandbox:…). The prior phone option on VerificationCode::generateSmsVerificationFor() remains the relevant capability for profile-change flows where the number being verified differs from the number on file. Net: the package is becoming both a domain API and a runtime control plane, which raises the bar on who reviews and approves upgrades.

Integration feasibility: Still low-to-moderate effort. No migrations. The release notes state "otherwise none" for upgrade steps, and deploy.sh already runs php artisan cache:clear, which resolves the cache-key transition (old entries otherwise expire in 5 minutes for lists, 1 hour for models). The socket-settings feature is opt-in: every value falls back to the environment until an administrator saves something, and a socket server older than fleetbase/fleetbase v0.7.70 keeps reading its own environment. The one integration task with a deadline is client-side: driverAssigned.* is still published but is now deprecated, and lifecycle events for records with an assigned driver are additionally published on driver.{public_id} and driver.{uuid}. Any client following the {type}.{id} convention should be validated against the new channels, and any client relying solely on driverAssigned.* should be scheduled for migration. Confirm storefront's dependency pin still resolves against ^1.6.71 and that no other package pins fleetbase/core-api below it.

Technical risk: Higher than the previous release, and mostly in the "already shipped, silently wrong" category rather than in the new features. The filter-cache bug (#315) is a cross-tenant correctness and potential data-exposure issue: under Octane, the first controller to list a model decided the filter for every other, so Fleet-Ops' order filter was applied to Storefront's order lists and a network's orders page could list every order in the company. Any instance running an earlier version on Octane should be treated as having had incorrect scoping in production and reviewed accordingly — upgrade is remediation, but it is worth checking logs and prior exposure. The live/test cache bleed (#312) is the mirror risk on the data-hygiene side: a console request in test mode could be served the cached live response for the same query and vice versa, because console sessions carry no API credential to distinguish them; the connection-scoped key fix closes this, but it also means test-mode consoles previously saw live data. The socket-settings feature introduces a privileged write surface: SOCKETCLUSTER_AUTH_KEY stays in the environment and is never stored or returned, and turning the switch on without a key is refused, and every save is written to the activity log — but the authorization boundary on int/v1/settings/socket and the blast radius of an enforce-mode misconfiguration (wrong allowed origins locking out legitimate realtime clients) need explicit confirmation. The SMS/verification risks carry forward: external provider delivery, code enumeration, replay, and abuse if the phone option is exposed without authorization checks.

Key questions: Who is permitted to call int/v1/settings/socket, and is that permission separated from ordinary admin roles? What is the rollout path from off to log to enforce, and can we run log in production long enough to validate origins before enforcing? Which of our clients subscribe to driverAssigned.*, and what is their migration date to driver.{public_id} / driver.{uuid}? Do we run Octane anywhere, and on which versions was the filter-cache bug live? How do we audit historical cross-app filter leakage and test/live cache bleed for customer impact? Which socket server version is deployed, and does it meet fleetbase/fleetbase v0.7.70? For verification flows: which SMS providers are supported, how are codes stored/expired/rate-limited, is there per-phone and per-IP throttling, how are international numbers handled, and what audit logging exists for sends and verifications? Is the package versioned predictably enough to plan around (three of five changes here are fixes to prior behavior)?

Integration Approach

Stack fit: Laravel/PHP backend with Composer; Eloquent, queues, notifications, and — newly relevant — Octane and a realtime socket layer. Compatible with Fleetbase core-api and storefront v0.4.25, which requires fleetbase/core-api ^1.6.70; ^1.6.71 satisfies that constraint, but verify resolution explicitly. Socket settings depend on a paired runtime component (fleetbase/fleetbase v0.7.70) that polls the signed config endpoint.

Migration path: Run composer update fleetbase/core-api to ^1.6.71, then run php artisan cache:clear (already in deploy.sh) so old-format cache keys do not linger. No code changes are required for existing endpoints. For phone-change endpoints, the calling service/controller should pass the new phone option, as previously noted. For realtime, migrate client event subscriptions from driverAssigned.* to driver.{public_id}/driver.{uuid}; both are published today, so this is a safe, non-flag-day change. For socket settings, leave the feature untouched at first — environment values remain the defaults — and adopt console management only after the authorization question is settled.

Compatibility: Additive and backward compatible at the API level. Two soft edges: driverAssigned.* is deprecated (published, not removed), and the socket-settings UI requires socket server >= v0.7.70 to take effect — older servers silently ignore the new config and keep reading their own environment, which is a "looks configured but isn't" trap worth documenting. Verify the storefront dependency resolves cleanly and that no other package pins an older core-api version.

Sequencing: (1) Upgrade core-api to ^1.6.71 and clear cache. (2) Confirm the filter-cache fix in a staging environment that mirrors production's Octane setup — specifically re-test Storefront order lists and any cross-app list endpoint, since the bug's symptom was over-broad results rather than errors. (3) Verify test-mode consoles no longer surface live data. (4) Upgrade the socket server to fleetbase/fleetbase v0.7.70. (5) Migrate client event subscriptions off driverAssigned.*. (6) Only then introduce socket settings through the console, starting in log mode, then enforce. (7) Test phone-change flows for users with an existing number, users with no number on file, and international numbers; update API documentation and any client SDKs that expose phone-change endpoints.

Operational Impact

Maintenance: Low ongoing effort via Composer updates, but the surface being maintained has grown: socket auth configuration is now a supported administrative object with a mode, a TTL, an origin allowlist, and an activity-logged change history. Treat changes to mode and origins as change-managed configuration, not incidental admin tinkering. Continue monitoring SMS provider credentials, delivery rates, and costs, and keep an eye on release cadence — three of five changes in this release are corrective, which suggests tracking patch releases promptly rather than batching.

Support: Add two runbooks. First, realtime auth: symptoms are clients that stop receiving events or fail channel authorization after an origin or mode change — the recovery path is reverting the saved setting (environment fallback reasserts) and checking the activity log for the last save. Note that enabling the switch without SOCKETCLUSTER_AUTH_KEY is refused, so "it won't turn on" has a documented explanation. Second, the existing SMS failure runbook (retry, fallback channel, manual verification) still applies; the phone option should reduce tickets where phone changes previously reported success but sent no code.

Scaling: Socket config is polled by the socket server and applied at runtime with no restart, so config changes scale without a deploy — but token TTL and allowed origins become levers that affect connection volume and re-auth load; test TTL changes against peak concurrency. SMS throughput still depends on the provider; use queues for high-volume sends and consider provider failover if verification is business-critical. Cache keys now include the connection, which modestly increases key cardinality across live and sandbox — negligible, but worth knowing if you monitor cache hit rates.

Failure modes: Realtime clients silently missing driver lifecycle events (fixed channels exist, but subscribers must migrate before driverAssigned.* is removed); socket settings saved in the console but not applied because the socket server predates v0.7.70; enforce mode with an incomplete origin allowlist locking out legitimate clients; cross-app filter leakage on pre-1.6.71 Octane deployments; test-mode consoles served live cached data on pre-1.6.71; SMS not delivered (carrier/provider), invalid or unreachable numbers, rate limiting, expired codes, and provider outages. The earlier silent-success bug for subjects without a phone is fixed, but callers must still handle delivery failures and present actionable errors.

Ramp-up: Minimal developer ramp-up for the upgrade itself; moderate for the new capabilities. Document parent_uuid for anyone building category trees, document the deprecated event channels with a migration date, and document the socket settings' environment-fallback semantics and the socket server version dependency. QA should cover: Storefront order lists and cross-app list endpoints under Octane, test-mode versus live console responses, driver event delivery on both old and new channels, category tree rendering from a flat list, socket auth behavior in off/log/enforce and with/without an auth key, plus the phone-change scenarios and rate-limit/error paths carried forward from the prior assessment.