Pollsockets Laravel Laravel Package

Technical Evaluation

Package: pollsockets/pollsockets-laravel — Laravel package providing HTTP-polling-based realtime subscriptions (a "sockets without WebSockets" transport), with server-side channel/subscription management backing the PollSockets client SDKs.

Release under review: 2.0.0 (from 1.4.0). Changelog content is a single line: "v2: millisecond cursor and client origin" (PR #23). The major-version bump, not the prose, is the primary signal — we should treat this as a breaking release until proven otherwise.

Architecture fit. The package occupies the realtime-notification layer of a Laravel app: a poll endpoint the browser hits on an interval, a cursor marking "how far the client has read," and channel authorization reusing Laravel's auth/guard model. That remains a sound fit for our use case (low-to-moderate fan-out notifications, no sticky-session/WebSocket infrastructure, works behind standard HTTP load balancers and CDNs with the poll route excluded from cache). Two dimensions change in 2.0.0:

• Cursor resolution moves to milliseconds. This implies the cursor is now a higher-precision timestamp/id pair rather than a second-granularity marker. Architecturally this is the right direction — second-granularity cursors are the classic source of duplicate delivery (two messages in the same second) and dropped messages (a message written between the read and the cursor advance). It should reduce the need for client-side dedupe we would otherwise have had to build. The cost is that the cursor is now a typed contract between server and client, and its format is versioned.
• "Client origin" is added to the delivery model. Most likely this attributes polled messages to the originating client/tab/device (or to the originating request origin for CORS/multi-tenant purposes). Either reading means the payload shape and/or the subscription registration payload changed. It may also mean server-side state per origin, which affects how we scale the poll endpoint.

Integration feasibility. Low-to-moderate effort, but it is a coordinated upgrade, not a drop-in. The package must be upgraded in lockstep with every PollSockets client SDK (JS/browser, and any mobile SDK) because the cursor is produced by the server and round-tripped by the client. We control the browser client, so feasibility is good; the constraint is that we cannot do a partial rollout — a v1 client talking to a v2 server will send a v1 cursor and will either error or silently re-receive the backlog.

Technical risk. Medium-high, concentrated in three places:

1. Cursor format break (highest). Any cursor persisted outside a single page session — in localStorage, in a since query parameter, in a mobile app's local DB, or in a resumed session — is a v1-format value. On first poll after deploy it will be rejected, coerced, or interpreted as epoch-0, producing either a recoverable full backlog replay or an unrecoverable error loop. Replay storms are the realistic failure: every open tab reconnects and requests "everything since the beginning."
2. Client/server version skew. If we deploy the server first, all existing tabs (which loaded v1 JS) start failing on their next poll. If we deploy clients first, they hit a v1 server that doesn't understand millisecond cursors. The window must be closed with either a compatibility shim or a hard reload.
3. Payload/authorization semantics. "Client origin" may participate in channel authorization or CORS. If origin is used to scope deliveries, a mis-set Origin header (proxy, CDN, mobile webview) could silently route a client into an empty or wrong channel stream — hard to detect in monitoring because the request still returns 200.

Key questions for the maintainer / spike (blocking the estimate):

• Is the v2 cursor wire-compatible in either direction, or strictly one-way? Is there a documented upgrade/migration note beyond the changelog line?
• What exactly is "client origin" — request Origin header, a client-generated ID, or connection provenance? Does it participate in authorization or only in telemetry/routing?
• Is there a config flag to keep v1 cursor semantics for a deprecation window, or is 2.0.0 a clean cut?
• What are the minimum PHP/Laravel versions for 2.0.0? (Not stated; must be confirmed against our runtime before we schedule anything.)
• What is the documented behavior for an unparseable cursor — 400, 422, reset-to-now, or replay-all? This determines whether a skew event is an incident or a non-event.
• Is there a published deprecation/support window for 1.4.x?

Integration Approach

Stack fit. Laravel-native package, no new infrastructure (no Redis pub/sub requirement introduced by this release, no socket server). It slots into the existing HTTP tier. The two things it touches that we care about are (a) the client bundle, which we version and ship ourselves, and (b) our runtime matrix (PHP/Laravel), which must be re-verified against 2.0.0's composer constraints before commitment.

Migration path. Recommended: server-side dual-accept shim, then client rollout, then shim removal. Concretely — deploy a thin adapter in front of the package's poll handler that inspects the incoming cursor and, if it is in v1 format, translates it to the v2 millisecond cursor (or, if translation is not reliably possible, responds with an explicit "resync required" signal the v1 client already knows how to handle by resetting to now). This converts a hard cutover into an ordinary rolling deploy. If the maintainer offers a config-level compatibility mode, use that instead — it is cheaper and better supported.

Compatibility matrix to validate before scheduling:

The only cell that must be engineered away is the middle one (v1 client, v2 server), and it exists for exactly as long as it takes open tabs to reload.

Sequencing.

1. Spike (0.5–1 day): read 2.0.0 source/composer.json; answer the blocking questions; confirm cursor parse-failure behavior and PHP/Laravel constraints. Pin down whether "origin" is authz-relevant.
2. Compatibility decision: shim vs. forced-resync vs. config flag. Write it down; this is the go/no-go artifact.
3. Deploy 2.0.0 server-side behind the shim with the poll endpoint feature-flagged per environment; ship to staging with v1 clients still attached and assert no 4xx/5xx on /poll.
4. Roll clients (browser bundle + any mobile SDK) with an explicit cache-bust; verify a v2 client on a v2 server end-to-end, including reconnect-after-sleep and multi-tab-same-user.
5. Observe one full traffic cycle (include a low-traffic window so long-lived idle tabs reconnect at least once).
6. Remove the shim and any v1 cursor-handling code; update the internal runbook and pin the version in composer.

Do not bundle this with an unrelated release. The skew window is the whole risk, and it needs a clean change log of its own.

Operational Impact

Maintenance. Net positive if the team is small: millisecond cursors remove a class of duplicate/dropped-message bugs we would otherwise carry as application-level workarounds, and the "origin" dimension likely removes bespoke correlation code from our consumer. Cost is one forced client upgrade and a permanent, documented dependency: our client bundle version is now coupled to the server package version. That coupling must be recorded in the runbook — future minor bumps may again touch the cursor contract, and "it's only a minor" will not be a safe assumption.

Support. Expect a short tail of user-visible weirdness during the skew window: stale tabs that never reloaded, mobile webviews with cached JS, and users resuming a backgrounded tab. The support-facing symptom is "notifications stopped" or "I got a flood of old notifications" — both map to cursor mismatch. Prepare a one-line remedy for the help desk (hard reload / clear site data) and a dashboard that separates poll requests returning errors from poll requests returning an unexpectedly large batch (the latter is the replay-storm signature and is invisible in a pure error-rate view).

Scaling. Millisecond cursors do not change request volume — polling is polling. Two things to watch: (1) a replay storm is a genuine load event, since each reconnecting client requests the full backlog at once; the poll endpoint should have a per-response batch cap and a rate limit configured before rollout, not after; (2) if "client origin" causes the server to track state per origin rather than per subscription, fan-out memory grows with tab count — verify whether that state is in-process or in a shared store, because in-process state breaks horizontal scaling and requires sticky routing we do not currently have.

Failure modes.

The silent-empty-stream row is the one to design against: it produces no error signal, so it needs an active health check — a synthetic client that subscribes and asserts receipt of a server-emitted heartbeat within N seconds.

Ramp-up. Half a day for a Laravel-fluent engineer who has not touched the package, given: the v1→v2 cursor note, the shim (or the decision not to have one), the "origin" semantics, and the resync runbook. The concepts (channel, subscription, cursor, poll loop) are simple; the difficulty is entirely in the version-skew choreography, which is why step 2 of the sequencing — an explicit written compatibility decision — is the deliverable that matters. Absent that, the estimate for this upgrade is not credible and should not be committed.