@kirschbaum-development/sst-laravel 0.3.3 → 0.3.5

package/README.md

@@ -88,6 +88,36 @@ const app = new LaravelService('MyLaravelApp', {
 
 Check all the `web` options [here](https://github.com/kirschbaum-development/sst-laravel/blob/main/docs/api.md#web).
 
+#### Load balancer health check
+
+Laravel ships a built-in `/up` health endpoint. Point the load balancer at it via `web.healthCheck` — a shortcut over `loadBalancer.health` that targets the default forward port for you:
+
+```js
+const app = new LaravelService('MyLaravelApp', {
+  web: {
+    domain: { name: 'app.example.com' },
+    healthCheck: { path: '/up' },
+  },
+});
+```
+
+All [`loadBalancer.health` options](https://sst.dev/docs/component/aws/service/#loadbalancer-health) are supported (`interval`, `timeout`, `healthyThreshold`, `unhealthyThreshold`, `successCodes`). If you set `web.loadBalancer` explicitly, `healthCheck` is ignored — configure `loadBalancer.health` directly there.
+
+#### HTTP to HTTPS redirect
+
+When you configure a `domain` (which provisions an SSL certificate and an HTTPS listener), HTTP (port 80) traffic is redirected to HTTPS (port 443) by default. To keep forwarding HTTP traffic straight to your application instead, set `httpsRedirect: false`:
+
+```js
+const app = new LaravelService('MyLaravelApp', {
+  web: {
+    domain: { name: 'app.example.com' },
+    httpsRedirect: false,
+  },
+});
+```
+
+This has no effect when no `domain` is set, or when you provide an explicit `web.loadBalancer` (configure `loadBalancer.ports` yourself in that case).
+
 ### 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.

package/docs/api.md

@@ -259,7 +259,38 @@ web: {
 
 #### `web.health`
 - **Type:** `ServiceArgs["health"]`
-- **Description:** Health check configuration for the web service.
+- **Description:** ECS container-level health check for the web service. Distinct from `web.healthCheck` (load balancer).
+
+#### `web.healthCheck`
+- **Type:** `Input<LaravelHealthCheck>`
+- **Description:** Load balancer health check applied to the default forward port (`8080/http`). Shorthand so you don't have to override the full `loadBalancer` config just to set a path. Ignored when `loadBalancer` is provided — configure `loadBalancer.health` directly in that case.
+
+**Example:**
+```typescript
+web: {
+  domain: { name: 'app.example.com' },
+  healthCheck: {
+    path: '/up',
+    successCodes: '200',
+    interval: '30 seconds',
+    healthyThreshold: 2,
+    unhealthyThreshold: 3,
+  },
+}
+```
+
+#### `web.httpsRedirect`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** When a `domain` is configured, redirect HTTP (port 80) traffic to the HTTPS (port 443) listener instead of forwarding it straight to the application. Set to `false` to keep forwarding HTTP traffic to the app. Has no effect when no `domain` is set (there is no HTTPS listener to redirect to) or when an explicit `loadBalancer` is provided.
+
+**Example:**
+```typescript
+web: {
+  domain: { name: 'app.example.com' },
+  httpsRedirect: false,
+}
+```
 
 #### `web.executionRole`
 - **Type:** `ServiceArgs["executionRole"]`

package/laravel-sst.ts

@@ -27,18 +27,11 @@ import { getPackagePath } from './src/config';
 import { RemoteEnvFile } from './src/remote-env-file';
 import { buildReverbEnvironmentVariables } from './src/reverb';
 import { getSecretsFingerprint } from './src/secrets-manager';
+import { buildDefaultPublicPorts, Port } from './src/load-balancer';
 
 // Re-export RemoteEnvVault for external use
 export { RemoteEnvVault, RemoteEnvVaultArgs };
 
-// duplicate from cluster.ts
-type Port = `${number}/${'http' | 'https' | 'tcp' | 'udp' | 'tcp_udp' | 'tls'}`;
-
-type Ports = {
-    listen: Port;
-    forward: Port;
-}[];
-
 enum ImageType {
     Web = 'web',
     Worker = 'worker',
@@ -132,11 +125,93 @@ export interface LaravelServiceArgs {
     >;
 }
 
+/**
+ * Shorthand for the load balancer health check applied to the default forward
+ * port. Mirrors the inner shape of SST's `loadBalancer.health` entry, minus the
+ * per-port keying which the package fills in for you.
+ *
+ * Not used when {@link LaravelWebArgs.loadBalancer} is provided — in that case
+ * configure `loadBalancer.health` directly.
+ */
+export interface LaravelHealthCheck {
+    /**
+     * The URL path the load balancer pings for health checks.
+     * @default `"/"`
+     */
+    path?: Input<string>;
+    /**
+     * Time between health check requests. Between `5 seconds` and `300 seconds`.
+     * @default `"30 seconds"`
+     */
+    interval?: Input<`${number} ${'second' | 'seconds' | 'minute' | 'minutes'}`>;
+    /**
+     * Per-request timeout. Between `2 seconds` and `120 seconds`.
+     * @default `"5 seconds"`
+     */
+    timeout?: Input<`${number} ${'second' | 'seconds' | 'minute' | 'minutes'}`>;
+    /**
+     * Consecutive successes required to mark a target healthy. Between 2 and 10.
+     * @default `5`
+     */
+    healthyThreshold?: Input<number>;
+    /**
+     * Consecutive failures required to mark a target unhealthy. Between 2 and 10.
+     * @default `2`
+     */
+    unhealthyThreshold?: Input<number>;
+    /**
+     * HTTP response codes treated as successful (e.g. `"200"`, `"200-299"`).
+     * @default `"200"`
+     */
+    successCodes?: Input<string>;
+}
+
 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?: LaravelDomain;
+
+    /**
+     * Load balancer health check for the web service. The package wires this
+     * to the default forward port (`8080/http`), so you only specify the
+     * check itself — not the per-port key.
+     *
+     * Distinct from {@link LaravelServiceArgs.health}, which is the ECS
+     * container-level health check.
+     *
+     * Ignored when `loadBalancer` is set — configure `loadBalancer.health`
+     * yourself in that case.
+     *
+     * @example
+     * ```js
+     * web: {
+     *   healthCheck: { path: '/up' },
+     * }
+     * ```
+     */
+    healthCheck?: Input<LaravelHealthCheck>;
+
+    /**
+     * When a `domain` is configured, redirect HTTP (port 80) traffic to the
+     * HTTPS (port 443) listener instead of forwarding it straight to the
+     * application. Set to `false` to keep forwarding HTTP traffic to the app.
+     *
+     * Has no effect when no `domain` is set (there is no HTTPS listener to
+     * redirect to) or when an explicit `loadBalancer` is provided (configure
+     * `loadBalancer.ports` yourself in that case).
+     *
+     * @default `true`
+     *
+     * @example
+     * ```js
+     * web: {
+     *   domain: 'example.com',
+     *   httpsRedirect: false,
+     * }
+     * ```
+     */
+    httpsRedirect?: boolean;
 }
 
 export interface LaravelReverbArgs extends LaravelServiceArgs {
@@ -412,9 +487,18 @@ export class LaravelService extends Component {
                             ? args.web.loadBalancer
                             : {
                                   domain: args.web?.domain,
-                                  ports: getDefaultPublicPorts(
-                                      args.web?.domain,
-                                  ),
+                                  ports: buildDefaultPublicPorts({
+                                      hasDomain: Boolean(args.web?.domain),
+                                      httpsRedirect:
+                                          args.web?.httpsRedirect ?? true,
+                                  }),
+                                  ...(args.web?.healthCheck
+                                      ? {
+                                            health: {
+                                                '8080/http': args.web.healthCheck,
+                                            },
+                                        }
+                                      : {}),
                               },
 
                     dev: {
@@ -577,10 +661,10 @@ export class LaravelService extends Component {
                 name: 'reverb',
                 loadBalancer: reverbConfig.loadBalancer ?? {
                     domain: reverbConfig.domain,
-                    ports: getDefaultPublicPorts(
-                        reverbConfig.domain,
-                        reverbConfig.port,
-                    ),
+                    ports: buildDefaultPublicPorts({
+                        hasDomain: Boolean(reverbConfig.domain),
+                        forwardPort: reverbConfig.port,
+                    }),
                     health: {
                         [reverbPort]: {
                             path: '/apps',
@@ -660,27 +744,6 @@ export class LaravelService extends Component {
             };
         }
 
-        function getDefaultPublicPorts(
-            domain?: LaravelDomain,
-            forwardPortNumber = 8080,
-        ): Ports {
-            let ports;
-            const forwardPort: Port = `${forwardPortNumber}/http`;
-            const portHttp: Port = '80/http';
-            const portHttps: Port = '443/https';
-
-            if (domain) {
-                ports = [
-                    { listen: portHttp, forward: forwardPort },
-                    { listen: portHttps, forward: forwardPort },
-                ];
-            } else {
-                ports = [{ listen: portHttp, forward: forwardPort }];
-            }
-
-            return ports;
-        }
-
         // TODO: We have to test if it works when a custom image is provided in sst.config.js
         function getImage(imgType: ImageType, extraArgs: object = {}) {
             const img = getDefaultImage(imgType, extraArgs);

package/package.json

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

package/src/load-balancer.ts

@@ -0,0 +1,60 @@
+export type Port = `${number}/${'http' | 'https' | 'tcp' | 'udp' | 'tcp_udp' | 'tls'}`;
+
+export type Ports = {
+  listen: Port;
+  forward?: Port;
+  redirect?: Port;
+}[];
+
+export interface DefaultPublicPortsOptions {
+  /**
+   * Whether a custom domain (and therefore an HTTPS listener) is configured.
+   */
+  hasDomain: boolean;
+
+  /**
+   * Container port the load balancer forwards application traffic to.
+   *
+   * @default 8080
+   */
+  forwardPort?: number;
+
+  /**
+   * When a domain is configured, redirect the HTTP (port 80) listener to the
+   * HTTPS (port 443) listener instead of forwarding it to the application.
+   * Ignored when no domain is configured, since there is no HTTPS listener to
+   * redirect to.
+   *
+   * @default true
+   */
+  httpsRedirect?: boolean;
+}
+
+/**
+ * Builds the default load balancer port mapping for a public service.
+ *
+ * Without a domain, only an HTTP listener is created (forwarding to the app).
+ * With a domain, both HTTP and HTTPS listeners are created; the HTTP listener
+ * redirects to HTTPS by default, or forwards to the app when
+ * `httpsRedirect` is disabled.
+ */
+export function buildDefaultPublicPorts({
+  hasDomain,
+  forwardPort = 8080,
+  httpsRedirect = true,
+}: DefaultPublicPortsOptions): Ports {
+  const forward: Port = `${forwardPort}/http`;
+  const portHttp: Port = '80/http';
+  const portHttps: Port = '443/https';
+
+  if (!hasDomain) {
+    return [{ listen: portHttp, forward }];
+  }
+
+  return [
+    httpsRedirect
+      ? { listen: portHttp, redirect: portHttps }
+      : { listen: portHttp, forward },
+    { listen: portHttps, forward },
+  ];
+}