AnyCable for Laravel

[palkan]

Let's discuss how we can empower Laravel apps with AnyCable.

The discussion started here: beyondcode/laravel-websockets#190 (comment)

---

The idea is to start with a basic integration similar to our Node.js one: https://docs.anycable.io/guides/serverless

There are two main options to consider for the integration:

• Integrating with Laravel Echo (Reverb).
• Standalone AnyCable for Laravel integration.

Integration with Laravel Echo

Laravel Echo already provides APIs to implement real-time features in Laravel apps. Currently, Echo only support pub/sub channels and broadcasting, but Reverb is adding client-to-server commands support making Echo Channels bi-directional.

Making AnyCable compatible with Echo would be a huge win, because it would allow Laravel developers to use the framework they know without learning anything new.

There are three integration points:

1. Server-to-client broadcasts.
2. Client-to-server events/messages handling.
3. Client-side (JS) integration.

Server-to-client broadcasts

We need to implement a custom Broadcaster.

In the broadcast function, we MUST perform an HTTP request to broadcast a message to the channel: https://docs.anycable.io/ruby/broadcast_adapters?id=http-adapter

The auth method can be similar to other adapters (it's not related to AnyCable); in the validAuthenticationResponse we MAY generate a JWT identification token for AnyCable (to authenticate connection at the WS server side without making RPC calls) and a signed stream name for the channel (similar to Turbo Streams.

Client-to-server events/messages handling (RPC)

AnyCable communicates with the application over RPC (HTTP or gRPC) to handle WebSocket connection lifecycle events (Connect/Disconnect) and incoming messages (Commands).

Let's start with the HTTP version and implement a middleware to process AnyCable RPC requests.

The API schema (with examples) can be found here: anycable.stoplight.io.

Since Echo relies on HTTP request to authorize the access, we don't necessary need to implement Connect and Command with the "command": "subscribe" requests (we can assume that JWT and signed streams used instead).

We mostly care about handling incoming commands and processing disconnect events.

To handle incoming commands, we may use the API proposed here:

<?php

namespace App\Broadcasting;

use App\Room;
use App\User;

class ChatChannel
{
    public function createMessage(User $user, $data)
    {
        $room = $user->joinedChats()->findOrFail($data['room_id']);

        $message = new Message(['content' => $data['content'], 'user_id' => $user->id]);

        $room->messages()->save($message);
        
        broadcast(new ChatMessage($message));
    }
}

Thus, we need somehow to turn the following RPC payload into the command execution above:

{
  "env": {
    "url": "ws://cable.myapp.dev/cable",
    "headers": {
      "Cookie": "user_session=abc123",
      "Origin": "http://myapp.dev"
    }
  },
  "command": "message",
  "identifier": "{\"channel\":\"ChatChannel\"}", // This is the name of the class
  "data": "{\"action\":\"createMessage\",\"body\":\"Hello, PHP\"}", // This is the name of the function and the payload
  "connection_identifiers": "{\"user_id\":42}" // This is the current user information obtained from JWT or Connect call
}

Questions:

• How does Laravel Echo handle client disconnection (at the server side)?

• What would be an API to send a message from the server to the client in response to the command (smth like this->$transmit(...))?

Wispers

Laravel Echo also supports wispering, or sending messages to the channel without interacting with the app.

To support this, we would likely need to implement a custom routing logic at the Go server side (similar to Turbo Streams, etc.). Or we can promote this feature to be generic (not Laravel-specific).

Client-side (JS) integration

There are two options:

• We can implement a custom connector on top of anycable-client

• We can add Pusher protocol support to AnyCable, so we can re-use existing Pusher connector.

I would start with the first one for the PoC, and as soon as we cover all the other parts, I would go with the Pusher protocol implementation.

Standalone AnyCable for Laravel integration

We can forget about Echo/Reverb and bring Action Cable-like channels to Laravel (similarly how we did for JS in our JS SDK).

You can learn more about conceptual differences between Echo and Action Cable protocols/abstractions here: https://anycable.substack.com/p/any-cables-monthly-18.

This approach doesn't require any client-side changes (we can use anycable-client) and hacking around Laravel Broadcasting.

I think, we can still re-use event classes, but not channels (or maybe we can extend channels to support subscribe and unsubscribe callbacks).

The API (RPC) part must be implemented in full.

I believe this approach can be more beneficial (since I personally like Action Cable abstraction more), but it's gonna be a hard sell for the community (competing with the official solution is not a good idea).

Still, I think, it's worth considering.

---

Known limitations

Currently, AnyCable has no built-int Presence tracking mechanism. Though it's expected to come later this year, and having Laravel as a potential user of this feature would be great for fine-tuning.

[Eyad-Bereh]

I would like to explain my perspective on this topic, but before I start I want to answer a few questions that were asked here.

How does Laravel Echo handle client disconnection (at the server side)?

At the server side, Laravel doesn't have any idea about Pusher subscribers and whether they're connected or disconnected.
Previously, the laravel-websockets package had a ConnectionClosed event that will be triggered when a user disconnects from a server. Pusher has webhooks that get triggered upon certain events.
Unfortunately, there's no explicit way to know when a user has disconnected because the webhook cannot be configured to be triggered in such events.
The nearest thing to that would be creating a webhook that gets triggered on the subscription_count event, but unfortunately it's not giving consistent results, and I don't think that it's reliable.
Here's a sample of the data it sends:

[2024-02-09 14:25:32] local.INFO: {"time_ms":1707488731030,"events":[{"channel":"my-channel","name":"subscription_count","subscription_count":1}]}  
[2024-02-09 14:25:34] local.INFO: {"time_ms":1707488732581,"events":[{"channel":"my-channel","name":"subscription_count","subscription_count":2}]}  
[2024-02-09 14:26:33] local.INFO: {"time_ms":1707488792766,"events":[{"channel":"my-channel","name":"subscription_count","subscription_count":1}]}  
[2024-02-09 14:26:37] local.INFO: {"time_ms":1707488796067,"events":[{"channel":"my-channel","name":"subscription_count","subscription_count":2}]}  
[2024-02-09 14:34:24] local.INFO: {"time_ms":1707489262558,"events":[{"channel":"my-channel","name":"subscription_count","subscription_count":1}]}  
[2024-02-09 14:34:25] local.INFO: {"time_ms":1707489263859,"events":[{"channel":"my-channel","name":"subscription_count","subscription_count":2}]}  

What would be an API to send a message from the server to the client in response to the command (smth like this->$transmit(...))?

There's no need. A single call to the broadcast() helper inside Laravel will do the job.
It works this way because a potential AnyCableBroadcaster adapter will need to extend the base abstract Illuminate\Broadcasting\Broadcasters\Broadcaster class which implements the Illuminate\Contracts\Broadcasting\Broadcaster interface that contains a broadcast() method, so it's all handled there.

It's as simple as calling it like

broadcast(new ChatMessage($message));

Regarding the client-side part, the problem with Laravel Echo is the way it's tied to the Pub/Sub architecture, so you can't actually encapsulate the Channel.perform() method inside Echo's abstract Channel class because there's no signature for a method that does client-to-server messaging.
But still, we can create an anycable connector for Echo can be done, but the process of sending data to from client to server needs to be done by accessing the underlying connector attribute. I'm talking about a syntax that's similar to Echo.connector.perform().
We can fork the laravel/echo repository and add all classes related to AnyCable, and then do a pull request and see if they accept this idea. In case they don't accept the pull request, we can just rename the package to something as anycable/echo-client and dispose everything related to Socket.IO and Pusher, and keep only files that encapsulates anycable-client. This shouldn't be a big problem in legal terms since the original laravel/echo package is licensed under MIT license.