@kirschbaum-development/sst-laravel 0.3.3 → 0.3.4

package/README.md

@@ -88,6 +88,21 @@ 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.
+
 ### 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,25 @@ 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.executionRole`
 - **Type:** `ServiceArgs["executionRole"]`

package/laravel-sst.ts

@@ -132,11 +132,72 @@ 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>;
 }
 
 export interface LaravelReverbArgs extends LaravelServiceArgs {
@@ -415,6 +476,13 @@ export class LaravelService extends Component {
                                   ports: getDefaultPublicPorts(
                                       args.web?.domain,
                                   ),
+                                  ...(args.web?.healthCheck
+                                      ? {
+                                            health: {
+                                                '8080/http': args.web.healthCheck,
+                                            },
+                                        }
+                                      : {}),
                               },
 
                     dev: {

package/package.json

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