@luckystack/server 0.7.5 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-07-27
+
+### Added
+
+- Routed GET API calls can carry a lossless typed payload through the reserved `__luckystack_data` query value while public key-per-query callers remain compatible.
+
+## [0.7.6] - 2026-07-23
+
+### Fixed
+
+- A successfully listening server now refreshes its boot-UUID TTL every third
+  of the configured lifetime and stops the heartbeat during shutdown. Healthy
+  long-running servers therefore no longer become not-ready after one hour.
+
 ## [0.7.4] - 2026-07-22
 
 ### Fixed

package/CLAUDE.md

@@ -25,7 +25,7 @@ One-call server bootstrap for a LuckyStack project. Wires together a raw Node.js
 
 | Function / Export | One-liner | Deep doc |
 |---|---|---|
-| `createLuckyStackServer(options)` | Lower-level factory that returns `{ httpServer, ioServer, listen, stop, close }`. Wires HTTP + Socket.io + framework routes; installs a persistent `httpServer.on('error')` listener and (in prod) SIGTERM/SIGINT → graceful `stop()`. | -> docs/create-server.md |
+| `createLuckyStackServer(options)` | Lower-level factory that returns `{ httpServer, ioServer, listen, stop, close }`. Wires HTTP + Socket.io + framework routes; after a successful listen starts the boot-UUID TTL heartbeat, and stops it during shutdown. Installs a persistent `httpServer.on('error')` listener and (in prod) SIGTERM/SIGINT → graceful `stop()`. | -> docs/create-server.md |
 | `RunningLuckyStackServer.stop(options?)` / `.close(options?)` | Graceful shutdown (MIS-016). Stops accepting new connections, dispatches the core `preServerStop` hook, flushes error-trackers (bounded by a per-step timeout race), then closes io + http + the Redis-adapter pub/sub clients. Each step isolated + time-bounded so one hanging step can't stall shutdown. Idempotent. `options`: `{ reason?, timeoutMs? }` (default `timeoutMs` 10000). | -> docs/create-server.md |
 | `bootstrapLuckyStack(options)` | High-level entry: auto-imports `luckystack/<pkg>/*.ts` overlay in topological order, then delegates to `createLuckyStackServer`. An overlay file that fails to import (classic: it imports a package removed via `luckystack remove`) aborts boot with an ACTIONABLE error naming the file, instead of a raw ERR_MODULE_NOT_FOUND. | -> docs/create-server.md |
 | `OVERLAY_ORDER` (exported const) | The canonical overlay walk order (`core, deploy, login, email, sentry, presence, cron, docs-ui, server`). Exported so the consumer's `scripts/bundleServer.mjs` imports it at build time — a hardcoded bundler copy once silently dropped the cron slot from prod; `overlayOrderParity.test.ts` pins the bundlers' fallback lists to this. | -> docs/create-server.md |

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 
 // src/createServer.ts
 import http from "http";
-import { registerBindAddress, registerBoundAddress, writeBootUuid, getLogger as getLogger13, getProjectConfig as getProjectConfig15, tryCatch as tryCatch10, tryCatchSync as tryCatchSync2, resolveEnvKey as resolveEnvKey5, dispatchHook as dispatchHook8 } from "@luckystack/core";
+import { registerBindAddress, registerBoundAddress, writeBootUuid, startBootUuidHeartbeat, getLogger as getLogger13, getProjectConfig as getProjectConfig15, tryCatch as tryCatch10, tryCatchSync as tryCatchSync3, resolveEnvKey as resolveEnvKey5, dispatchHook as dispatchHook8 } from "@luckystack/core";
 
 // src/httpHandler.ts
 import { randomUUID } from "crypto";
@@ -24,7 +24,7 @@ import {
   normalizeOrigin,
   readSession as readSession3,
   tryCatch as tryCatch7,
-  tryCatchSync
+  tryCatchSync as tryCatchSync2
 } from "@luckystack/core";
 
 // src/logSanitize.ts
@@ -921,7 +921,8 @@ import {
   dispatchHook as dispatchHook3,
   extractTokenFromRequest,
   getLogger as getLogger4,
-  tryCatch as tryCatch4
+  tryCatch as tryCatch4,
+  tryCatchSync
 } from "@luckystack/core";
 import { handleHttpApiRequest } from "@luckystack/api";
 
@@ -1038,8 +1039,25 @@ var handleApiRoute = async ({
       res.end(JSON.stringify(response));
       return true;
     }
-    const apiData = typeof params === "object" ? { ...params } : {};
+    let apiData = typeof params === "object" ? { ...params } : {};
     delete apiData.stream;
+    const routedData = apiData.__luckystack_data;
+    if (typeof routedData === "string") {
+      const [parseError, parsed] = tryCatchSync(() => JSON.parse(routedData));
+      if (parseError || parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        const response = {
+          status: "error",
+          httpStatus: 400,
+          message: "api.invalidRequestFormat",
+          errorCode: "api.invalidRequestFormat"
+        };
+        res.setHeader("Content-Type", "application/json");
+        res.writeHead(400);
+        res.end(JSON.stringify(response));
+        return true;
+      }
+      apiData = { ...parsed };
+    }
     const requesterIp = resolveRequesterIp(req);
     const result = await handleHttpApiRequest({
       name: apiName,
@@ -1390,7 +1408,7 @@ var setSecurityHeaders = (req, res, origin) => {
   res.setHeader("X-Content-Type-Options", securityHeaders.contentTypeOptions);
   const builder = getSecurityHeadersBuilder();
   if (builder) {
-    const [error] = tryCatchSync(() => {
+    const [error] = tryCatchSync2(() => {
       const custom = builder(req);
       if (custom) {
         for (const [name, value] of Object.entries(custom)) {
@@ -1509,7 +1527,7 @@ var handleHttpRequestInner = async (req, res, options) => {
   );
   const url = req.url ?? "/";
   const [routePathRaw, queryStringRaw] = url.split("?");
-  const [decodeError, decodedPath] = tryCatchSync(() => decodeURIComponent(routePathRaw ?? "/"));
+  const [decodeError, decodedPath] = tryCatchSync2(() => decodeURIComponent(routePathRaw ?? "/"));
   if (decodeError || decodedPath === null) {
     res.statusCode = 400;
     res.setHeader("Content-Type", "text/plain");
@@ -2398,8 +2416,8 @@ var listenLuckyStackServer = (httpServer, ip, port, callback) => new Promise((re
         process.once("exit", clearDevServerInfo);
       }
       if (attemptPort !== startPort && !production) {
-        const configuredCallbackBase = tryCatchSync2(() => getProjectConfig15().oauthCallbackBase)[1] ?? "";
-        const callbackPort = tryCatchSync2(() => {
+        const configuredCallbackBase = tryCatchSync3(() => getProjectConfig15().oauthCallbackBase)[1] ?? "";
+        const callbackPort = tryCatchSync3(() => {
           const callbackUrl = new URL(configuredCallbackBase);
           return callbackUrl.port || (callbackUrl.protocol === "https:" ? "443" : "80");
         })[1] ?? "";
@@ -2460,9 +2478,15 @@ var createLuckyStackServer = async (options = {}) => {
   const { io: ioServer, adapterClients } = loadSocket(httpServer, {
     maxHttpBufferSize: options.maxHttpBufferSize
   });
-  const listen = (callback) => listenLuckyStackServer(httpServer, ip, port, callback);
+  let bootUuidHeartbeat = null;
+  const listen = async (callback) => {
+    const listeningServer = await listenLuckyStackServer(httpServer, ip, port, callback);
+    bootUuidHeartbeat ??= startBootUuidHeartbeat();
+    return listeningServer;
+  };
   let shutdownPromise = null;
   const stop = (stopOptions = {}) => {
+    bootUuidHeartbeat?.stop();
     shutdownPromise ??= runGracefulShutdown({ httpServer, ioServer, adapterClients }, stopOptions);
     return shutdownPromise;
   };