@kirschbaum-development/sst-laravel 0.3.1 → 0.3.2

package/README.md

@@ -88,6 +88,44 @@ const app = new LaravelService('MyLaravelApp', {
 
 Check all the `web` options [here](https://github.com/kirschbaum-development/sst-laravel/blob/main/docs/api.md#web).
 
+### Reverb
+
+You can deploy a dedicated Laravel Reverb service for WebSocket traffic. Reverb runs as a worker-style container using `php artisan reverb:start`, but SST Laravel also attaches a load balancer so you can give it its own public domain.
+
+```js
+const app = new LaravelService('MyLaravelApp', {
+  web: {
+    domain: 'app.example.com',
+  },
+
+  reverb: {
+    domain: {
+      dns: sst.cloudflare.dns(),
+      name: 'ws.example.com',
+    },
+  },
+});
+
+return {
+  url: app.url,
+  reverbUrl: app.reverbUrl,
+};
+```
+
+When `reverb.domain` is configured, SST Laravel automatically injects the Reverb server variables:
+
+```env
+REVERB_SERVER_HOST=0.0.0.0
+REVERB_SERVER_PORT=8080
+REVERB_HOST=ws.example.com
+REVERB_PORT=443
+REVERB_SCHEME=https
+```
+
+If you enable horizontal scaling for Reverb, make sure your Laravel application is configured for Reverb scaling with Redis.
+
+Check all the `reverb` options [here](https://github.com/kirschbaum-development/sst-laravel/blob/main/docs/api.md#reverb).
+
 ### Workers
 
 Beyond HTTP requests, you can set up one or more `workers` for your Laravel application. Workers are meant to run background commands like Laravel Horizon, the Laravel Scheduler or any background command you may need to run.
@@ -407,6 +445,7 @@ This will list all running tasks in your cluster and let you choose which one to
 ```bash
 npx sst-laravel ssh web --stage production
 npx sst-laravel ssh worker --stage production
+npx sst-laravel ssh reverb --stage production
 ```
 
 If you are naming your workers differently, you can specify the worker name:
@@ -423,6 +462,7 @@ You can view the logs for your application using the `sst-laravel logs` command.
 ```bash
 npx sst-laravel logs {service} --stage production
 npx sst-laravel logs web --stage production
+npx sst-laravel logs reverb --stage production
 npx sst-laravel logs worker --stage production
 ```
 

package/docs/api.md

@@ -97,6 +97,9 @@ new LaravelService("Laravel", {
   web: {
     domain: "example.com"
   },
+  reverb: {
+    domain: "ws.example.com"
+  },
   config: {
     environment: {
       secrets: env
@@ -348,6 +351,103 @@ workers: [
 - **Type:** `ServiceArgs["permissions"]`
 - **Description:** IAM permissions specific to this worker.
 
+### `reverb`
+- **Type:** `boolean | LaravelReverbArgs`
+- **Default:** `false`
+- **Description:** Configuration for a dedicated Laravel Reverb service. When enabled, SST Laravel creates a worker-style service that runs `php artisan reverb:start` and exposes it through a load balancer.
+
+**Example:**
+```typescript
+reverb: {
+  domain: "ws.example.com",
+  scaling: {
+    min: 1,
+    max: 2
+  }
+}
+```
+
+You can also enable Reverb with defaults:
+
+```typescript
+reverb: true
+```
+
+#### `reverb.domain`
+- **Type:** `Input<string | { name: Input<string>; cert?: Input<string>; dns?: Input<false | Dns> }>`
+- **Description:** Custom domain for the Reverb service. If provided, SST Laravel routes HTTP and HTTPS traffic to Reverb's internal listener on port 8080 by default.
+
+**Example (with custom DNS provider):**
+```typescript
+reverb: {
+  domain: {
+    name: "ws.example.com",
+    dns: sst.cloudflare.dns()
+  }
+}
+```
+
+When `reverb.domain` is configured, SST Laravel auto-injects:
+
+```env
+REVERB_SERVER_HOST=0.0.0.0
+REVERB_SERVER_PORT=8080
+REVERB_HOST=ws.example.com
+REVERB_PORT=443
+REVERB_SCHEME=https
+```
+
+#### `reverb.host`
+- **Type:** `string`
+- **Default:** `"0.0.0.0"`
+- **Description:** Host the Reverb server listens on inside the container.
+
+#### `reverb.port`
+- **Type:** `number`
+- **Default:** `8080`
+- **Description:** Port the Reverb server listens on inside the container. The default load balancer forwards traffic to this port.
+
+#### `reverb.command`
+- **Type:** `string`
+- **Default:** `"php artisan reverb:start"`
+- **Description:** Command used to start the Reverb service.
+
+#### `reverb.architecture`
+- **Type:** `ServiceArgs["architecture"]`
+- **Description:** The CPU architecture for the Reverb service.
+
+#### `reverb.cpu`
+- **Type:** `ServiceArgs["cpu"]`
+- **Description:** CPU units for the Reverb service.
+
+#### `reverb.memory`
+- **Type:** `ServiceArgs["memory"]`
+- **Description:** Memory allocation for the Reverb service.
+
+#### `reverb.storage`
+- **Type:** `ServiceArgs["storage"]`
+- **Description:** Storage configuration for the Reverb service.
+
+#### `reverb.scaling`
+- **Type:** `ServiceArgs["scaling"]`
+- **Description:** Auto-scaling configuration for the Reverb service. Horizontal Reverb scaling requires Redis and `REVERB_SCALING_ENABLED=true` in your Laravel environment.
+
+#### `reverb.logging`
+- **Type:** `ServiceArgs["logging"]`
+- **Description:** Logging configuration for the Reverb service.
+
+#### `reverb.health`
+- **Type:** `ServiceArgs["health"]`
+- **Description:** ECS health check configuration for the Reverb service.
+
+#### `reverb.executionRole`
+- **Type:** `ServiceArgs["executionRole"]`
+- **Description:** Execution role for the Reverb service.
+
+#### `reverb.permissions`
+- **Type:** `ServiceArgs["permissions"]`
+- **Description:** IAM permissions specific to the Reverb service.
+
 ### `config`
 - **Type:** `object`
 - **Description:** Config settings.
@@ -449,6 +549,16 @@ const app = new LaravelService("MyApp", { ... });
 console.log(app.url); // https://example.com or https://xyz.elb.amazonaws.com
 ```
 
+### `reverbUrl`
+- **Type:** `Output<string>`
+- **Description:** The URL of the Reverb service. If `reverb.domain` is set, returns the custom domain URL. Otherwise, returns the auto-generated load balancer URL.
+
+**Example:**
+```typescript
+const app = new LaravelService("MyApp", { ... });
+console.log(app.reverbUrl); // https://ws.example.com or https://xyz.elb.amazonaws.com
+```
+
 ## Complete Example
 
 ```typescript
@@ -477,6 +587,14 @@ const app = new LaravelService("MyApp", {
       max: 10
     }
   },
+
+  reverb: {
+    domain: "ws.example.com",
+    scaling: {
+      min: 1,
+      max: 2
+    }
+  },
   
   workers: [
     {
@@ -510,7 +628,8 @@ const app = new LaravelService("MyApp", {
 });
 
 return {
-  url: app.url
+  url: app.url,
+  reverbUrl: app.reverbUrl
 };
 ```
 
@@ -537,6 +656,10 @@ const app = new LaravelService("MyApp", {
       max: 10
     }
   },
+
+  reverb: {
+    domain: "ws.example.com"
+  },
   
   workers: [
     {
@@ -565,6 +688,7 @@ const app = new LaravelService("MyApp", {
 
 return {
   url: app.url,
+  reverbUrl: app.reverbUrl,
   secretsPath: env.path
 };
 ```

package/laravel-sst.ts

@@ -25,6 +25,7 @@ import {
 import { RemoteEnvVault, RemoteEnvVaultArgs } from './src/laravel-env-manager';
 import { getPackagePath } from './src/config';
 import { RemoteEnvFile } from './src/remote-env-file';
+import { buildReverbEnvironmentVariables } from './src/reverb';
 import { getSecretsFingerprint } from './src/secrets-manager';
 
 // Re-export RemoteEnvVault for external use
@@ -44,6 +45,50 @@ enum ImageType {
     Cli = 'cli',
 }
 
+export type LaravelDomain = Input<
+    | string
+    | {
+          /**
+           * Domain name. You are able to use variables from the SST config file here.
+           *
+           * @example
+           * ```js
+           * domain: {
+           *   name: `${$app.stage}.example.com`,
+           * }
+           * ```
+           */
+          name: Input<string>;
+
+          /**
+           * Certificate ARN. Use this in case you are manually setting up the SSL certificate.
+           * This is usually needed when your DNS is not in the same AWS account or is outside of AWS.
+           *
+           * @example
+           * ```js
+           * domain: {
+           *   cert: 'arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012',
+           * }
+           * ```
+           */
+          cert?: Input<string>;
+
+          /**
+           * SST DNS configuration. You can use this configuration if your DNS is in Cloudflare or another AWS account.
+           *
+           * @see https://sst.dev/docs/component/cloudflare/dns/
+           * @see https://sst.dev/docs/component/aws/dns/
+           * @example
+           * ```js
+           * domain: {
+           *   dns: sst.cloudflare.dns(),
+           * }
+           * ```
+           */
+          dns?: Input<false | (Dns & {})>;
+      }
+>;
+
 export interface LaravelServiceArgs {
     architecture?: ServiceArgs['architecture'];
     cpu?: ServiceArgs['cpu'];
@@ -91,49 +136,35 @@ export interface LaravelWebArgs extends LaravelServiceArgs {
     /**
      * Custom domain for the web layer. (if you don't provide a domain name, you will be able to use the load balancer domain for testing (http only))
      */
-    domain?: Input<
-        | string
-        | {
-              /**
-               * Domain name. You are able to use variables from the SST config file here.
-               *
-               * @example
-               * ```js
-               * domain: {
-               *   name: `${$app.stage}.example.com`,
-               * }
-               * ```
-               */
-              name: Input<string>;
-
-              /**
-               * Certificate ARN. Use this in case you are manually setting up the SSL certificate.
-               * This is usually needed when your DNS is not in the same AWS account or is outside of AWS.
-               *
-               * @example
-               * ```js
-               * domain: {
-               *   cert: 'arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012',
-               * }
-               * ```
-               */
-              cert?: Input<string>;
-
-              /**
-               * SST DNS configuration. You can use this configuration if your DNS is in Cloudflare or another AWS account.
-               *
-               * @see https://sst.dev/docs/component/cloudflare/dns/
-               * @see https://sst.dev/docs/component/aws/dns/
-               * @example
-               * ```js
-               * domain: {
-               *   dns: sst.cloudflare.dns(),
-               * }
-               * ```
-               */
-              dns?: Input<false | (Dns & {})>;
-          }
-    >;
+    domain?: LaravelDomain;
+}
+
+export interface LaravelReverbArgs extends LaravelServiceArgs {
+    /**
+     * Custom domain for the Reverb service. When provided, Reverb requests are routed over HTTPS to the Reverb server running on port 8080 by default.
+     */
+    domain?: LaravelDomain;
+
+    /**
+     * Host the Reverb server listens on inside the container.
+     *
+     * @default `0.0.0.0`
+     */
+    host?: string;
+
+    /**
+     * Port the Reverb server listens on inside the container.
+     *
+     * @default `8080`
+     */
+    port?: number;
+
+    /**
+     * Command used to start Reverb.
+     *
+     * @default `php artisan reverb:start`
+     */
+    command?: string;
 }
 
 export interface LaravelWorkerConfig extends LaravelServiceArgs {
@@ -185,6 +216,11 @@ export interface LaravelArgs extends ClusterArgs {
      */
     workers?: LaravelWorkerConfig[];
 
+    /**
+     * If enabled, a public worker-style container will be created to run Laravel Reverb.
+     */
+    reverb?: boolean | LaravelReverbArgs;
+
     /**
      * Config settings.
      */
@@ -292,6 +328,7 @@ export class LaravelService extends Component {
         const sitePath = args.path ?? '.';
         const absSitePath = path.resolve(sitePath.toString());
         const nodeModulePath = getPackagePath();
+        const reverbConfig = normalizeReverbConfig(args.reverb);
 
         // Determine the path where our plugin will save build files.
         // SST sets __dirname to the .sst/platform directory.
@@ -375,7 +412,9 @@ export class LaravelService extends Component {
                             ? args.web.loadBalancer
                             : {
                                   domain: args.web?.domain,
-                                  ports: getDefaultPublicPorts(),
+                                  ports: getDefaultPublicPorts(
+                                      args.web?.domain,
+                                  ),
                               },
 
                     dev: {
@@ -472,6 +511,8 @@ export class LaravelService extends Component {
             workerConfig: LaravelWorkerConfig,
             serviceName: string,
             workerBuildPath: string,
+            serviceKey = serviceName,
+            devCommand = `php ${sitePath}/artisan horizon`,
         ) => {
             createWorkerTasks(workerConfig, workerBuildPath);
 
@@ -482,7 +523,7 @@ export class LaravelService extends Component {
                 CUSTOM_CONF_PATH: workerBuildPath.replace(absSitePath, ''),
             };
 
-            this.services[serviceName] = new sst.aws.Service(
+            this.services[serviceKey] = new sst.aws.Service(
                 serviceName,
                 {
                     cluster,
@@ -492,9 +533,10 @@ export class LaravelService extends Component {
                     image: getImage(ImageType.Worker, imgBuildArgs),
                     scaling: workerConfig.scaling,
                     environment: getEnvironmentVariables(),
+                    loadBalancer: workerConfig.loadBalancer,
 
                     dev: {
-                        command: `php ${sitePath}/artisan horizon`,
+                        command: devCommand,
                     },
 
                     transform: {
@@ -524,6 +566,44 @@ export class LaravelService extends Component {
             );
         };
 
+        function addReverbService() {
+            if (!reverbConfig) {
+                return;
+            }
+
+            const reverbPort: Port = `${reverbConfig.port}/http`;
+            const reverbWorkerConfig: LaravelWorkerConfig = {
+                ...reverbConfig,
+                name: 'reverb',
+                loadBalancer: reverbConfig.loadBalancer ?? {
+                    domain: reverbConfig.domain,
+                    ports: getDefaultPublicPorts(
+                        reverbConfig.domain,
+                        reverbConfig.port,
+                    ),
+                    health: {
+                        [reverbPort]: {
+                            path: '/apps',
+                            successCodes: '200-499',
+                        },
+                    },
+                },
+                tasks: {
+                    'laravel-reverb': {
+                        command: reverbConfig.command,
+                    },
+                },
+            };
+
+            createWorkerService(
+                reverbWorkerConfig,
+                `${name}-Reverb`,
+                path.resolve(pluginBuildPath, 'worker-reverb'),
+                'reverb',
+                `php ${sitePath}/artisan reverb:start`,
+            );
+        }
+
         function addWorkerServices() {
             args.workers?.forEach((workerConfig, index) => {
                 const workerName = workerConfig.name || `worker-${index + 1}`;
@@ -548,6 +628,10 @@ export class LaravelService extends Component {
             addWorkerServices();
         }
 
+        if (reverbConfig) {
+            addReverbService();
+        }
+
         function normalizeClusterVpc(
             vpc: LaravelArgs['vpc'],
         ): LaravelArgs['vpc'] {
@@ -576,13 +660,16 @@ export class LaravelService extends Component {
             };
         }
 
-        function getDefaultPublicPorts(): Ports {
+        function getDefaultPublicPorts(
+            domain?: LaravelDomain,
+            forwardPortNumber = 8080,
+        ): Ports {
             let ports;
-            const forwardPort: Port = '8080/http';
+            const forwardPort: Port = `${forwardPortNumber}/http`;
             const portHttp: Port = '80/http';
             const portHttps: Port = '443/https';
 
-            if (args.web?.domain) {
+            if (domain) {
                 ports = [
                     { listen: portHttp, forward: forwardPort },
                     { listen: portHttps, forward: forwardPort },
@@ -671,7 +758,12 @@ export class LaravelService extends Component {
         function getEnvironmentVariables() {
             const env = args.config?.environment?.vars || {};
 
-            return env;
+            return {
+                ...(shouldAutoInjectEnvironment()
+                    ? getReverbEnvironmentVariables()
+                    : {}),
+                ...env,
+            };
         }
 
         function getLinkedEnvironmentData() {
@@ -712,6 +804,7 @@ export class LaravelService extends Component {
                 linkedEnvironment: {
                     ...applyLinkedResourcesEnv(resources),
                     ...customEnv,
+                    ...getReverbEnvironmentVariables(),
                 },
                 linkedSecrets: extractSecrets(resources).map((secret) => ({
                     name: secret.name,
@@ -861,6 +954,82 @@ export class LaravelService extends Component {
             return undefined;
         }
 
+        function getReverbEnvironmentVariables() {
+            if (!reverbConfig) {
+                return {};
+            }
+
+            const publicHost = getDomainName(reverbConfig.domain);
+            const serverVariables = buildReverbEnvironmentVariables({
+                serverHost: reverbConfig.host,
+                serverPort: reverbConfig.port,
+            });
+
+            if (!publicHost) {
+                return serverVariables;
+            }
+
+            if (typeof publicHost === 'string') {
+                return buildReverbEnvironmentVariables({
+                    publicHost,
+                    serverHost: reverbConfig.host,
+                    serverPort: reverbConfig.port,
+                });
+            }
+
+            return {
+                ...serverVariables,
+                REVERB_HOST: publicHost,
+                REVERB_PORT: '443',
+                REVERB_SCHEME: 'https',
+            };
+        }
+
+        function shouldAutoInjectEnvironment(): boolean {
+            return args.config?.environment?.autoInject !== false;
+        }
+
+        function getDomainName(
+            domain?: LaravelDomain,
+        ): PulumiInput<string | undefined> | undefined {
+            if (!domain) {
+                return undefined;
+            }
+
+            if (typeof domain === 'string') {
+                return domain;
+            }
+
+            if (typeof domain === 'object' && 'name' in domain) {
+                return output((domain as { name: Input<string> }).name).apply(
+                    (domainName) => domainName || undefined,
+                );
+            }
+
+            return undefined;
+        }
+
+        function normalizeReverbConfig(
+            config?: boolean | LaravelReverbArgs,
+        ): (LaravelReverbArgs & {
+            command: string;
+            host: string;
+            port: number;
+        }) | undefined {
+            if (!config) {
+                return undefined;
+            }
+
+            const reverb = typeof config === 'boolean' ? {} : config;
+
+            return {
+                ...reverb,
+                command: reverb.command ?? 'php artisan reverb:start',
+                host: reverb.host ?? '0.0.0.0',
+                port: reverb.port ?? 8080,
+            };
+        }
+
         function prepareDeploymentScript() {
             const deployDir = path.resolve(pluginBuildPath, 'deploy');
             const dst = path.resolve(deployDir, '60-deploy.sh');
@@ -896,6 +1065,16 @@ export class LaravelService extends Component {
         return this.services['web'].url;
     }
 
+    /**
+     * The URL of the Reverb service.
+     *
+     * If `reverb.domain` is set, this is the URL with the custom domain.
+     * Otherwise, it's the auto-generated load balancer URL.
+     */
+    public get reverbUrl() {
+        return this.services['reverb'].url;
+    }
+
     /**
      * The messages from the service.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirschbaum-development/sst-laravel",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "description": "An unofficial extension of SST to deploy containerized Laravel applications to AWS Fargate.",
   "main": "laravel-sst.ts",

package/src/reverb.ts

@@ -0,0 +1,26 @@
+export interface ReverbEnvironmentOptions {
+  serverHost?: string;
+  serverPort?: number;
+  publicHost?: string;
+  publicPort?: number;
+  publicScheme?: string;
+}
+
+export function buildReverbEnvironmentVariables(
+  options: ReverbEnvironmentOptions = {},
+): Record<string, string> {
+  const vars: Record<string, string> = {
+    REVERB_SERVER_HOST: options.serverHost ?? '0.0.0.0',
+    REVERB_SERVER_PORT: (options.serverPort ?? 8080).toString(),
+  };
+
+  if (!options.publicHost) {
+    return vars;
+  }
+
+  vars.REVERB_HOST = options.publicHost;
+  vars.REVERB_PORT = (options.publicPort ?? 443).toString();
+  vars.REVERB_SCHEME = options.publicScheme ?? 'https';
+
+  return vars;
+}

package/templates/sst.config.run.template

@@ -46,6 +46,15 @@
         }
       },
 
+      // this configuration will create a dedicated Reverb container for WebSocket traffic
+      // reverb: {
+      //   domain: {
+      //     name: $app.stage === "production"
+      //       ? "ws.example.com"
+      //       : `ws.${$app.stage}.example.com`,
+      //   },
+      // },
+
       // this configuration will create one worker container, which will run horizon and the laravel scheduler as background jobs
       workers: [
         {
@@ -57,4 +66,5 @@
 
     return {
       url: app.url,
+      // reverbUrl: app.reverbUrl,
     };