laravel-echo-api-gateway 0.5.8 → 0.5.9

package/.eslintrc.js

@@ -12,5 +12,6 @@ module.exports = {
         "@typescript-eslint/ban-types": "off",
         "@typescript-eslint/no-explicit-any": "off",
         "prefer-const": "off",
+        "@typescript-eslint/no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
     },
 };

package/.github/workflows/ci.yml

@@ -8,10 +8,25 @@ jobs:
   pest:
     runs-on: ubuntu-latest
     strategy:
-      fail-fast: true
+      fail-fast: false
       matrix:
-        php: ['8.1']
-    name: Pest - PHP ${{ matrix.php }}
+        include:
+          - php: '8.1'
+            laravel: '^10.0'
+            testbench: '^8.0'
+          - php: '8.2'
+            laravel: '^11.0'
+            testbench: '^9.0'
+          - php: '8.3'
+            laravel: '^12.0'
+            testbench: '^10.0'
+          - php: '8.4'
+            laravel: '^12.0'
+            testbench: '^10.0'
+          - php: '8.5'
+            laravel: '^13.0'
+            testbench: '^11.0'
+    name: Pest - PHP ${{ matrix.php }} - Laravel ${{ matrix.laravel }}
     steps:
       - uses: actions/checkout@v4
       - uses: shivammathur/setup-php@v2
@@ -19,35 +34,35 @@ jobs:
           php-version: ${{ matrix.php }}
           extensions: dom, mbstring, soap, bcmath, pdo_sqlite, intl
           coverage: pcov
-      - uses: ramsey/composer-install@v1
-        with:
-          composer-options: "--prefer-dist --optimize-autoloader --ignore-platform-reqs"
+      - name: Install dependencies
+        run: |
+          composer update --no-interaction --prefer-dist --with-all-dependencies \
+            --with "laravel/framework:${{ matrix.laravel }}" \
+            --with "orchestra/testbench:${{ matrix.testbench }}"
       - name: Run PestPHP
-        run: vendor/bin/pest --coverage --coverage-clover test-results/pest.xml
+        run: vendor/bin/pest --coverage-clover test-results/pest.xml
         env:
           AWS_ACCESS_KEY_ID: fake
           AWS_SECRET_ACCESS_KEY: fake
           AWS_SESSION_TOKEN: fake
       - name: Upload coverage to Codecov
         if: always()
-        uses: codecov/codecov-action@v2
+        uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           flags: pest-${{ matrix.php }}
-          file: test-results/pest.xml
+          files: test-results/pest.xml
 
   larastan:
     runs-on: ubuntu-latest
     name: Larastan
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: shivammathur/setup-php@v2
         with:
-          php-version: ${{ matrix.php }}
+          php-version: '8.4'
           extensions: soap, bcmath, pdo_sqlite, intl
-      - uses: ramsey/composer-install@v1
-        with:
-          composer-options: "--prefer-dist --optimize-autoloader --ignore-platform-reqs"
+      - uses: ramsey/composer-install@v3
       - name: Run Larastan
         run: vendor/bin/phpstan analyse --no-progress
 
@@ -55,49 +70,38 @@ jobs:
     runs-on: ubuntu-latest
     name: ESLint
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
       - name: Install dependencies
-        run: npm install
+        run: npm ci
       - name: Run ESLint
         run: npm run lint
 
   jest:
     runs-on: ubuntu-latest
-    name: Jest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: ['18', '20', '22']
+    # The suite runs every test against laravel-echo v1 (aliased as laravel-echo-v1) and v2.
+    name: Jest - Node ${{ matrix.node }}
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: '15'
+          node-version: ${{ matrix.node }}
       - name: Install dependencies
-        run: npm install
+        run: npm ci
+      - name: Build
+        run: npm run build
       - name: Run Jest
-        run: npm run test --coverage --coverageDirectory=test-results/jest
+        run: npm test -- --coverage --coverageDirectory=test-results/jest
       - name: Upload coverage to Codecov
         if: always()
-        uses: codecov/codecov-action@v1
+        uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           flags: jest
-          file: test-results/jest/clover.xml
-#  phpcs:
-#    runs-on: ubuntu-latest
-#    name: PHP Style Fixer
-#    steps:
-#      - uses: actions/checkout@v2
-#      - uses: shivammathur/setup-php@v2
-#        with:
-#          php-version: '7.4'
-#          extensions: soap, bcmath, pdo_sqlite
-#      - name: Get Composer Cache Directory
-#        id: composer-cache
-#        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
-#      - uses: actions/cache@v2
-#        with:
-#          path: ${{ steps.composer-cache.outputs.dir }}
-#          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
-#          restore-keys: ${{ runner.os }}-composer-
-#      - name: Install Composer dependencies
-#        run: composer install --no-interaction --no-progress  --prefer-dist --optimize-autoloader --ignore-platform-reqs
-#      - name: Run PHP-CS-Fixer
-#        run: vendor/bin/php-cs-fixer fix --dry-run --diff --allow-risky=yes
+          files: test-results/jest/clover.xml

package/README.md

@@ -18,10 +18,11 @@ though the latter one involves some manual set-up.
 In order to use this package, your project needs to meet the following criteria:
 
 - PHP 8.x
-- Laravel 6 to 12
+- Laravel 6 to 13
 - Uses either [bref](https://bref.sh) or [Laravel Vapor](https://vapor.laravel.com) to deploy to AWS
 - Has a working queue
-- Uses Laravel Mix or any other tool to bundle your assets
+- Uses [laravel-echo](https://github.com/laravel/echo) v1.10+ or v2 on the client
+- Uses Vite, Laravel Mix or any other tool to bundle your assets (or Node.js 18+ for non-browser clients)
 
 ## Installation
 
@@ -32,11 +33,11 @@ First we have to install both the composer and npm package:
 ```shell
 composer require georgeboot/laravel-echo-api-gateway
 
-yarn add laravel-echo-api-gateway
-# or
-npm install --save-dev laravel-echo-api-gateway
+npm install --save-dev laravel-echo laravel-echo-api-gateway
 ```
 
+`laravel-echo` is a peer dependency: the package works with the version your app already uses (v1.10+ or v2).
+
 ### Platform-specific instructions
 
 #### A. When using Bref
@@ -51,8 +52,7 @@ functions:
     # Add this function
     websocket:
         handler: handlers/websocket.php
-        layers:
-            - ${bref:layer.php-80}
+        runtime: php-83
         events:
             - websocket: $disconnect
             - websocket: $default
@@ -122,6 +122,8 @@ provider:
         LARAVEL_ECHO_API_GATEWAY_DYNAMODB_TABLE: !Ref ConnectionsTable
         LARAVEL_ECHO_API_GATEWAY_API_ID: !Ref WebsocketsApi
         LARAVEL_ECHO_API_GATEWAY_API_STAGE: "${self:provider.stage}"
+        # Optional, see "Signing secret" below
+        LARAVEL_ECHO_API_GATEWAY_SECRET: ${ssm:/my-app/echo-api-gateway-secret}
 ```
 
 Next, create the PHP handler file in `handlers/websocket.php`
@@ -180,38 +182,112 @@ BROADCAST_DRIVER=laravel-echo-api-gateway
 LARAVEL_ECHO_API_GATEWAY_DYNAMODB_TABLE=the-table-name-you-entered-when-creating-it
 LARAVEL_ECHO_API_GATEWAY_API_ID=your-websocket-api-id
 LARAVEL_ECHO_API_GATEWAY_API_STAGE=your-api-stage-name
+# Optional, see "Signing secret" below
+LARAVEL_ECHO_API_GATEWAY_SECRET=a-long-random-string
 ```
 
+### Signing secret
+
+Private and presence channels are authorized by your app (`/broadcasting/auth`), which signs the socket id and channel
+name. The websocket handler verifies that signature before subscribing the connection. By default both use your
+`APP_KEY`. If the websocket handler runs as a separate app, set the same `LARAVEL_ECHO_API_GATEWAY_SECRET` on both
+instead of sharing your `APP_KEY`.
+
 ### Generate front-end code
 
 Add to your javascript file:
 
 ```js
 import Echo from 'laravel-echo';
-import {broadcaster} from 'laravel-echo-api-gateway';
+import { Connector } from 'laravel-echo-api-gateway';
 
 window.Echo = new Echo({
-    broadcaster,
+    broadcaster: Connector,
     // replace the placeholders
-    host: 'wss://{api-ip}.execute-api.{region}.amazonaws.com/{stage}',
+    host: 'wss://{api-id}.execute-api.{region}.amazonaws.com/{stage}',
     authEndpoint: '{auth-url}/broadcasting/auth', // Optional: Use if you have a separate authentication endpoint
     bearerToken: '{token}', // Optional: Use if you need a Bearer Token for authentication
 });
 ```
 
-You can also enable console output by passing a `debug: true` otpion to your window.Echo intializer : 
+The `broadcaster` export from previous versions keeps working: `new Echo({ broadcaster, ... })`.
+
+With TypeScript and laravel-echo v2, its typings do not accept custom connector classes yet, so cast the option:
+`broadcaster: Connector as any`.
+
+#### Using `@laravel/echo-react` or `@laravel/echo-vue`
+
+```ts
+import { configureEcho } from '@laravel/echo-react';
+import { Connector } from 'laravel-echo-api-gateway';
+
+configureEcho({
+    broadcaster: Connector as any,
+    host: import.meta.env.VITE_ECHO_API_GATEWAY_HOST,
+});
+```
+
+#### Using it outside the browser (Node.js, Electron)
+
+The connector only needs the global `WebSocket` and `fetch`, available in Node.js 22+ (or 18+ with a `WebSocket`
+polyfill such as [ws](https://github.com/websockets/ws) assigned to `globalThis.WebSocket`).
+
+To authorize private channels with your own logic, pass a custom handler. It receives the socket id and channel name
+and must call back with the response of your `/broadcasting/auth` endpoint:
+
 ```js
-import Echo from 'laravel-echo';
-import {broadcaster} from 'laravel-echo-api-gateway';
+const echo = new Echo({
+    broadcaster: Connector,
+    host: 'wss://{api-id}.execute-api.{region}.amazonaws.com/{stage}',
+    channelAuthorization: {
+        customHandler: ({ socketId, channelName }, callback) => {
+            fetch('https://my-app.test/api/broadcasting/auth', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+                body: JSON.stringify({ socket_id: socketId, channel_name: channelName }),
+            })
+                .then((response) => response.json())
+                .then((data) => callback(null, data))
+                .catch((error) => callback(error, null));
+        },
+    },
+});
+```
+
+You can also pass `channelAuthorization: { endpoint, headers }` to only change the endpoint or add headers.
+Authorization failures and rejected subscriptions are reported to `channel.error(callback)`.
+
+#### Options
 
+| Option | Default | Description |
+| --- | --- | --- |
+| `host` | | The websocket URL of your API Gateway stage. |
+| `authEndpoint` | `/broadcasting/auth` | Endpoint used to authorize private and presence channels. |
+| `bearerToken` | | Sent as `Authorization: Bearer ...` to the auth endpoint. |
+| `auth.headers` | `{}` | Extra headers sent to the auth endpoint. |
+| `channelAuthorization` | | `{ endpoint, headers, customHandler }`, see above. |
+| `pingInterval` | `60000` | Milliseconds between keep-alive pings. API Gateway closes idle connections after 10 minutes. |
+| `reconnectDelay` | `1000` | Milliseconds before the first reconnect attempt. Later attempts back off exponentially. |
+| `maxReconnectDelay` | `30000` | Upper bound for the reconnect delay. |
+| `debug` | `false` | Log connection activity to the console. |
+
+API Gateway closes every websocket connection after 2 hours. The connector reconnects automatically and subscribes
+again to every channel you joined, so your listeners keep receiving events.
+
+You can also enable console output by passing a `debug: true` option to your Echo initializer:
+
+```js
 window.Echo = new Echo({
-    broadcaster,
-    // replace the placeholders
-    host: 'wss://{api-ip}.execute-api.{region}.amazonaws.com/{stage}',
+    broadcaster: Connector,
+    host: 'wss://{api-id}.execute-api.{region}.amazonaws.com/{stage}',
     debug: true
 });
 ```
 
+Lastly, build your assets (for example with Vite or Laravel Mix). After this step, you should be up and running.
 
+### Limitations
 
-Lastly, you have to generate your assets by running Laravel Mix. After this step, you should be up and running.
+- Presence channels can be joined, but member tracking (`here`, `joining`, `leaving`) is not implemented yet.
+- Client events (whispers) can only be sent by connections subscribed to the private or presence channel, like Pusher.
+- Encrypted private channels are not supported.

package/dist/Channel.d.ts

@@ -0,0 +1,89 @@
+import { EventFormatter } from "./EventFormatter";
+import { Websocket } from "./Websocket";
+import type { Options } from "./Websocket";
+/**
+ * A channel on the API Gateway websocket. It implements the public, private and presence channel
+ * interfaces of laravel-echo (v1 and v2) without extending its internal classes.
+ */
+export declare class Channel {
+    /**
+     * The websocket connection.
+     */
+    socket: Websocket;
+    /**
+     * The name of the channel.
+     */
+    name: string;
+    /**
+     * Channel options.
+     */
+    options: Options;
+    /**
+     * The event formatter.
+     */
+    eventFormatter: EventFormatter;
+    /**
+     * Create a new class instance.
+     */
+    constructor(socket: Websocket, name: string, options: Options);
+    /**
+     * Subscribe to the channel.
+     */
+    subscribe(): void;
+    /**
+     * Unsubscribe from the channel.
+     */
+    unsubscribe(): void;
+    /**
+     * Listen for an event on the channel instance.
+     */
+    listen(event: string, callback: Function): this;
+    /**
+     * Stop listening for an event on the channel instance. Without a callback, every listener of the event is removed.
+     */
+    stopListening(event: string, callback?: Function): this;
+    /**
+     * Listen for a whisper event on the channel instance.
+     */
+    listenForWhisper(event: string, callback: Function): this;
+    /**
+     * Stop listening for a whisper event on the channel instance.
+     */
+    stopListeningForWhisper(event: string, callback?: Function): this;
+    /**
+     * Listen for an event on the channel instance.
+     */
+    notification(callback: Function): this;
+    /**
+     * Stop listening for notification events on the channel instance.
+     */
+    stopListeningForNotification(callback?: Function): this;
+    /**
+     * Register a callback to be called anytime a subscription succeeds.
+     */
+    subscribed(callback: Function): this;
+    /**
+     * Register a callback to be called anytime a subscription or authorization error occurs.
+     */
+    error(callback: Function): this;
+    /**
+     * Bind a channel to an event.
+     */
+    on(event: string, callback: Function): this;
+    /**
+     * Send a client event to the other members of the channel.
+     */
+    whisper(event: string, data: unknown): this;
+    /**
+     * Presence channels are not supported yet: member tracking is not implemented on the server.
+     */
+    here(_callback: Function): this;
+    /**
+     * Presence channels are not supported yet: member tracking is not implemented on the server.
+     */
+    joining(_callback: Function): this;
+    /**
+     * Presence channels are not supported yet: member tracking is not implemented on the server.
+     */
+    leaving(_callback: Function): this;
+}

package/dist/Connector.d.ts

@@ -0,0 +1,92 @@
+import { Websocket } from "./Websocket";
+import type { Options } from "./Websocket";
+import { Channel } from "./Channel";
+export { Channel };
+export { EventFormatter } from "./EventFormatter";
+export type { AuthorizationData, AuthorizationError, ChannelAuthorization, Options } from "./Websocket";
+/**
+ * Laravel Echo connector for API Gateway websockets.
+ *
+ * It does not extend laravel-echo's internal classes, so it works with laravel-echo v1 and v2:
+ * both create custom connectors with `new options.broadcaster(options)`.
+ */
+export declare class Connector {
+    /**
+     * Default connector options, matching laravel-echo's defaults.
+     */
+    static readonly _defaultOptions: {
+        auth: {
+            headers: {};
+        };
+        authEndpoint: string;
+        csrfToken: any;
+        bearerToken: any;
+        host: any;
+        namespace: string;
+    };
+    /**
+     * Connector options.
+     */
+    options: Options;
+    socket: Websocket;
+    /**
+     * All of the subscribed channel names.
+     */
+    channels: {
+        [name: string]: Channel;
+    };
+    /**
+     * Create a new class instance. Without a host no connection is opened, which keeps
+     * laravel-echo v2's `new broadcaster()` capability check free of side effects.
+     */
+    constructor(options?: Options);
+    /**
+     * Merge the custom options with the defaults and add the CSRF and bearer token headers.
+     */
+    protected setOptions(options: Options): void;
+    /**
+     * Extract the CSRF token from the page.
+     */
+    protected csrfToken(): string | null;
+    /**
+     * Create a fresh websocket connection.
+     */
+    connect(): void;
+    /**
+     * Listen for an event on a channel instance.
+     */
+    listen(name: string, event: string, callback: Function): Channel;
+    /**
+     * Get a channel instance by name.
+     */
+    channel(name: string): Channel;
+    /**
+     * Get a private channel instance by name.
+     */
+    privateChannel(name: string): Channel;
+    /**
+     * Get a presence channel instance by name.
+     */
+    presenceChannel(name: string): Channel;
+    /**
+     * Leave the given channel, as well as its private and presence variants.
+     */
+    leave(name: string): void;
+    /**
+     * Leave the given channel.
+     */
+    leaveChannel(name: string): void;
+    /**
+     * Get the socket ID for the connection.
+     */
+    socketId(): string | undefined;
+    /**
+     * Disconnect socket connection.
+     */
+    disconnect(): void;
+}
+/**
+ * Kept for backwards compatibility: `new Echo({ broadcaster })`. A function declaration (not an arrow
+ * function) so laravel-echo can call it with `new`.
+ */
+export declare function broadcaster(options?: Options): Connector;

package/dist/EventFormatter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Formats event names the same way laravel-echo does, so `listen('OrderCreated')` matches
+ * `App\Events\OrderCreated` and `listen('.custom-name')` matches `custom-name`.
+ */
+export declare class EventFormatter {
+    private namespace;
+    constructor(namespace: string | false);
+    format(event: string): string;
+    setNamespace(namespace: string | false): void;
+}

package/dist/Websocket.d.ts

@@ -0,0 +1,78 @@
+import type { Channel } from "./Channel";
+export type ChannelAuthorizationCallback = (error: unknown, data: AuthorizationData | null) => void;
+export type ChannelAuthorization = {
+    endpoint?: string;
+    headers?: Record<string, string>;
+    customHandler?: (params: {
+        socketId: string;
+        channelName: string;
+    }, callback: ChannelAuthorizationCallback) => void;
+};
+export type Options = {
+    host?: string;
+    authEndpoint?: string;
+    auth?: {
+        headers: Record<string, string>;
+    };
+    channelAuthorization?: ChannelAuthorization;
+    bearerToken?: string | null;
+    csrfToken?: string | null;
+    namespace?: string | false;
+    debug?: boolean;
+    /** Milliseconds between keep-alive pings. API Gateway closes idle connections after 10 minutes. */
+    pingInterval?: number;
+    /** Milliseconds to wait before the first reconnect attempt. Later attempts back off exponentially. */
+    reconnectDelay?: number;
+    /** Upper bound for the reconnect delay, in milliseconds. */
+    maxReconnectDelay?: number;
+    [key: string]: any;
+};
+export type MessageBody = {
+    event: string;
+    channel?: string;
+    data?: any;
+};
+export type AuthorizationData = {
+    auth: string;
+    channel_data?: string;
+};
+export type AuthorizationError = {
+    type: 'AuthError';
+    status: number | null;
+    error: unknown;
+};
+export declare class Websocket {
+    options: Options;
+    websocket: WebSocket | undefined;
+    private buffer;
+    /**
+     * Every channel that should be subscribed, re-subscribed each time a new connection is identified.
+     */
+    private channels;
+    private listeners;
+    private socketId;
+    private closing;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private pingTimer;
+    constructor(options: Options);
+    private connect;
+    private scheduleReconnect;
+    private startPing;
+    private stopPing;
+    private handleMessage;
+    private dispatch;
+    protected parseMessage(body: string): MessageBody | undefined;
+    getSocketId(): string | undefined;
+    private socketIsReady;
+    send(message: MessageBody): void;
+    close(): void;
+    subscribe(channel: Channel): void;
+    private actuallySubscribe;
+    private authorize;
+    private authorizationError;
+    unsubscribe(channel: Channel): void;
+    bind(channel: Channel, event: string, callback: Function): void;
+    unbind(channel: Channel, event: string, callback?: Function): void;
+    private debug;
+}