@uns-kit/api 3.0.38 → 3.0.39

package/dist/app.d.ts

@@ -1,7 +1,7 @@
 /**
  * Module dependencies.
  */
-import { type Router } from "express";
+import { type Response, type Router } from "express";
 import * as http from "http";
 type MountConfig = {
     apiBasePrefix?: string;
@@ -12,8 +12,16 @@ export default class App {
     private expressApplication;
     private ownershipGate;
     private readonly acceptedRequests;
+    private readonly requestWork;
     private requestFailed;
     setOwnershipGate(gate: () => boolean): void;
+    /**
+     * Declare application-owned read-only work before its first asynchronous step.
+     * HTTP method names are not proof of safety: only use this for work without
+     * external effects. A disconnected reader still waits for actual work to settle.
+     * This does not authenticate, cancel, retry or send the response.
+     */
+    runReadOnlyRequest<T>(res: Response, operation: () => T | Promise<T>): Promise<T>;
     drainRequests(): Promise<void>;
     stop(): Promise<void>;
     server: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;

package/dist/app.js

@@ -30,8 +30,36 @@ export default class App {
     expressApplication;
     ownershipGate;
     acceptedRequests = new Set();
+    requestWork = new WeakMap();
     requestFailed = false;
     setOwnershipGate(gate) { this.ownershipGate = gate; }
+    /**
+     * Declare application-owned read-only work before its first asynchronous step.
+     * HTTP method names are not proof of safety: only use this for work without
+     * external effects. A disconnected reader still waits for actual work to settle.
+     * This does not authenticate, cancel, retry or send the response.
+     */
+    async runReadOnlyRequest(res, operation) {
+        const request = this.requestWork.get(res);
+        if (!request && this.ownershipGate)
+            throw new Error("HTTP request was not admitted by this runtime");
+        if (request) {
+            if (request.transportEnded || request.readOnly)
+                throw new Error("HTTP work must be declared once before the response ends");
+            request.readOnly = true;
+            request.workSettled = false;
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            if (request) {
+                request.workSettled = true;
+                if (request.transportEnded)
+                    request.complete();
+            }
+        }
+    }
     async drainRequests() {
         while (this.acceptedRequests.size)
             await Promise.all([...this.acceptedRequests]);
@@ -71,13 +99,20 @@ export default class App {
             let finish;
             const accepted = new Promise(resolve => { finish = resolve; });
             this.acceptedRequests.add(accepted);
-            res.once("finish", () => { this.acceptedRequests.delete(accepted); finish(); });
-            res.once("close", () => {
-                if (!res.writableFinished)
+            const request = {
+                transportEnded: false, readOnly: false, workSettled: true,
+                complete: () => { this.acceptedRequests.delete(accepted); finish(); },
+            };
+            this.requestWork.set(res, request);
+            const endTransport = () => {
+                request.transportEnded = true;
+                if (!res.writableFinished && !request.readOnly)
                     this.requestFailed = true;
-                this.acceptedRequests.delete(accepted);
-                finish();
-            });
+                if (request.workSettled)
+                    request.complete();
+            };
+            res.once("finish", endTransport);
+            res.once("close", endTransport);
             next();
         });
         this.processName = processName;

package/dist/uns-api-proxy.d.ts

@@ -1,3 +1,4 @@
+import { type Response } from "express";
 import { UnsAttribute } from "@uns-kit/core/uns/uns-interfaces.js";
 import UnsProxy from "@uns-kit/core/uns/uns-proxy.js";
 import { UnsTopics } from "@uns-kit/core/uns/uns-topics.js";
@@ -23,6 +24,8 @@ export default class UnsApiProxy extends UnsProxy {
     constructor(processName: string, instanceName: string, options: IApiProxyOptions);
     setOwnershipGate(gate: () => boolean): void;
     drainRequests(): Promise<void>;
+    /** Track an explicitly read-only handler through completion, including client disconnects. */
+    runReadOnlyRequest<T>(res: Response, operation: () => T | Promise<T>): Promise<T>;
     getProcessName(): string;
     private getPublishedApiHost;
     /**

package/dist/uns-api-proxy.js

@@ -94,6 +94,10 @@ export default class UnsApiProxy extends UnsProxy {
     }
     setOwnershipGate(gate) { this.app.setOwnershipGate(gate); }
     async drainRequests() { await this.app.drainRequests(); }
+    /** Track an explicitly read-only handler through completion, including client disconnects. */
+    async runReadOnlyRequest(res, operation) {
+        return this.app.runReadOnlyRequest(res, operation);
+    }
     getProcessName() {
         return this.processName;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uns-kit/api",
-  "version": "3.0.38",
+  "version": "3.0.39",
   "description": "Express-powered API gateway plugin for UnsProxyProcess with JWT/JWKS support.",
   "type": "module",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "multer": "^2.2.0",
     "hyparquet-writer": "^0.16.5",
     "uuid": "^14.0.1",
-    "@uns-kit/core": "3.0.38"
+    "@uns-kit/core": "3.0.39"
   },
   "devDependencies": {
     "@types/cookie-parser": "^1.4.10",