@sequenceholdings/artifact-studio 0.7.1 → 0.8.1

package/dist/tunnel/broker.js

@@ -1,6 +1,7 @@
 import { WebSocketServer } from 'ws';
 import { TunnelPeer, tunnelLimits } from './peer.js';
 import { assertSafeRequest, encodeTunnelFrame, isSharedCacheDirective, normalizePublicOrigin, sanitizeRequestHeaders, sanitizeResponseHeaders, SHARED_CACHE_REFUSAL, TUNNEL_PROTOCOL } from './protocol.js';
+import { appendArtifactAuthenticationHeader } from '../server/request-authentication.js';
 import { forwardWebSocketMessages, MessageBudget, permittedCloseCode, sendWebSocket, WebSocketMessage, writeChunk } from './io.js';
 import { declaredLength, isExternalFailure } from './external.js';
 const UPGRADE_REASONS = { 403: 'Forbidden', 429: 'Too Many Requests', 503: 'Service Unavailable' };
@@ -65,6 +66,10 @@ export class ArtifactTunnelBroker {
     pendingConnections = new Map();
     ownerTimers = new Set();
     closing = false;
+    draining = false;
+    drainWaiters = new Set();
+    pendingReceipts = new Set();
+    relayClosed;
     constructor(options) {
         this.options = options;
         if (!options.nodeId || !options.routing || !options.authorizeTunnel || !options.authorizeRequest || !options.validateLease) {
@@ -80,7 +85,7 @@ export class ArtifactTunnelBroker {
         let lease = null;
         let claimed = false;
         try {
-            if (this.closing) {
+            if (this.draining || this.closing) {
                 rejectUpgrade(socket, 503);
                 return;
             }
@@ -99,19 +104,28 @@ export class ArtifactTunnelBroker {
                 rejectUpgrade(socket, 403);
                 return;
             }
+            if (this.draining || this.closing) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
             claimed = await this.options.routing.claim(lease, this.options.nodeId);
             const owner = await this.options.routing.lookup(lease.sessionId);
             if (!claimed || owner?.nodeId !== this.options.nodeId || owner.epoch !== lease.epoch || socket.destroyed) {
                 rejectUpgrade(socket, 403);
                 return;
             }
+            if (this.draining || this.closing) {
+                await this.options.routing.release(lease.sessionId, lease.epoch, this.options.nodeId).catch(() => undefined);
+                rejectUpgrade(socket, 503);
+                return;
+            }
             const authorizedLease = lease;
             this.tunnels.handleUpgrade(request, socket, head, (websocket) => {
                 const ready = () => websocket.send(encodeTunnelFrame({ type: 'ready', id: authorizedLease.sessionId, epoch: authorizedLease.epoch }));
                 websocket.once('close', () => this.options.onTunnelClosed?.(authorizedLease));
                 if (this.options.relay) {
                     void this.options.relay.attach(authorizedLease, websocket).then(() => {
-                        if (this.closing) {
+                        if (this.draining || this.closing) {
                             websocket.terminate();
                             return;
                         }
@@ -283,7 +297,15 @@ export class ArtifactTunnelBroker {
     async handleWebSocketUpgrade(request, socket, head, sessionId) {
         socket.pause();
         try {
+            if (this.draining || this.closing) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
             const authorized = await this.authorize(request, sessionId);
+            if (this.draining || this.closing) {
+                rejectUpgrade(socket, 503);
+                return;
+            }
             if (!authorized) {
                 rejectUpgrade(socket, 403);
                 return;
@@ -317,12 +339,9 @@ export class ArtifactTunnelBroker {
             return null;
         if (!['GET', 'HEAD', 'OPTIONS'].includes(request.method ?? 'GET') && request.headers.origin !== origin)
             return null;
-        const headers = sanitizeRequestHeaders(request.headers, origin);
-        if (authorization.requestContext) {
-            if (/[\r\n]/.test(authorization.requestContext))
-                return null;
-            headers['x-sequence-artifact-context'] = authorization.requestContext;
-        }
+        const headers = this.requestHeaders({ request, origin, authorization });
+        if (!headers)
+            return null;
         let connection = this.connections.get(sessionId);
         if (this.options.relay && this.options.resolveLease) {
             const lease = await this.options.resolveLease(sessionId);
@@ -341,6 +360,21 @@ export class ArtifactTunnelBroker {
             return null;
         return { connection, headers };
     }
+    requestHeaders({ request, origin, authorization }) {
+        const headers = sanitizeRequestHeaders(request.headers, origin);
+        if (authorization.requestContext) {
+            if (/[\r\n]/.test(authorization.requestContext))
+                return null;
+            headers['x-sequence-artifact-context'] = authorization.requestContext;
+        }
+        try {
+            appendArtifactAuthenticationHeader({ headers, token: authorization.requestAuthentication, contextToken: authorization.requestContext });
+        }
+        catch {
+            return null;
+        }
+        return headers;
+    }
     /**
      * The live tunnel for an external request: the session's current lease, for the granted project
      * and environment, still valid. Null otherwise. No browser owner is compared: Atlas's grant
@@ -459,7 +493,22 @@ export class ArtifactTunnelBroker {
             return;
         }
         if (frame.type === 'end') {
+            if (!this.options.relay) {
+                this.finish(connection, frame.id);
+                return;
+            }
+            // The existing cancel frame releases an already-completed stream. Redis owners that
+            // negotiated receipts retain the route until this proves the final response was consumed.
+            const receipt = connection.peer.send({ type: 'cancel', id: frame.id }).catch(() => connection.peer.close());
+            this.pendingReceipts.add(receipt);
             this.finish(connection, frame.id);
+            try {
+                await receipt;
+            }
+            finally {
+                this.pendingReceipts.delete(receipt);
+                this.notifyDrained();
+            }
             return;
         }
         if (frame.type === 'cancel') {
@@ -575,6 +624,7 @@ export class ArtifactTunnelBroker {
             stream.socket.close(status ? 1011 : 1000);
         else if (stream.upgrade)
             rejectUpgrade(stream.upgrade.socket, status ?? 503);
+        this.notifyDrained();
     }
     abort(connection, id, status = 502) {
         if (!connection.streams.has(id))
@@ -582,20 +632,54 @@ export class ArtifactTunnelBroker {
         this.finish(connection, id, status);
         void connection.peer.send({ type: 'cancel', id }).catch(() => undefined);
     }
-    /** Immediate revocation and graceful service shutdown hook. */
+    /** Stop new upgrades and remote-owner admission while admitted HTTP handlers finish. */
+    beginDrain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        this.options.relay?.beginDrain?.();
+        for (const connection of this.connections.values()) {
+            for (const [id, stream] of connection.streams)
+                if (stream.upgrade)
+                    this.abort(connection, id, 503);
+        }
+    }
+    notifyDrained() {
+        if (!this.drainWaiters.size || this.pendingReceipts.size)
+            return;
+        for (const connection of this.connections.values())
+            if (connection.streams.size)
+                return;
+        for (const resolve of this.drainWaiters)
+            resolve();
+        this.drainWaiters.clear();
+    }
+    /** The gateway first joins admitted handlers and response accounting. Its outer deadline
+     * bounds finite streams; lease validation and revocation remain active until cleanup. */
+    async drain() {
+        this.beginDrain();
+        await new Promise((resolve) => { this.drainWaiters.add(resolve); this.notifyDrained(); });
+        await this.options.relay?.drain?.();
+        this.close();
+        await this.relayClosed;
+    }
+    /** Immediate security revocation, never a graceful drain. */
     disconnect(sessionId) {
         this.connections.get(sessionId)?.peer.close();
         this.options.relay?.disconnect(sessionId);
     }
     close() {
+        if (this.closing)
+            return;
         this.closing = true;
+        this.draining = true;
         for (const timer of this.ownerTimers)
             clearInterval(timer);
         this.ownerTimers.clear();
         for (const connection of this.connections.values())
             connection.peer.close();
         this.tunnels.close();
-        void this.options.relay?.close().catch(() => undefined);
+        this.relayClosed = this.options.relay?.close().catch(() => undefined);
     }
 }
 /** For one-process local development/tests only. Production must provide a shared

package/dist/tunnel/client.js

@@ -6,6 +6,7 @@ import { forwardWebSocketMessages, MessageBudget, permittedCloseCode, sendWebSoc
 import { declaredLength } from './external.js';
 import { isLoopbackHostname } from '../loopback.js';
 import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX } from '../server/internal/signed-token.js';
+import { ARTIFACT_REQUEST_AUTHENTICATION_HEADER, assertArtifactRequestHeaderBudget, validatedArtifactAuthenticationHeader } from '../server/request-authentication.js';
 /** One connection/epoch only. The caller obtains a fresh lease to reconnect;
  * no HTTP request or mutation is ever retained or replayed. */
 export async function connectLocalTunnel(options) {
@@ -59,6 +60,11 @@ export async function connectLocalTunnel(options) {
             const context = frame.headers['x-sequence-artifact-context'];
             if (typeof context === 'string')
                 headers['x-sequence-artifact-context'] = context;
+            // This frame came from the authenticated gateway connection, not a browser header map.
+            const authentication = validatedArtifactAuthenticationHeader({ token: frame.headers[ARTIFACT_REQUEST_AUTHENTICATION_HEADER], contextToken: context });
+            if (authentication !== undefined)
+                headers[ARTIFACT_REQUEST_AUTHENTICATION_HEADER] = authentication;
+            assertArtifactRequestHeaderBudget({ headers });
             const timer = setTimeout(() => { void fail(frame.id); }, limits.requestTimeoutMs);
             timer.unref();
             const forward = { message: new WebSocketMessage(limits.maxWebSocketMessageBytes, messageBudget), bytes: 0, timer };

package/dist/tunnel/redis-types.d.ts

@@ -40,12 +40,16 @@ export type Remote = {
     nodeId: string;
     connection: string;
     lastSeen: number;
+    receipts?: boolean;
 };
 export type Attached = {
     lease: TunnelLease;
     socket: TunnelSocket;
     remotes: Map<string, Remote>;
-    streams: Map<string, Remote>;
+    streams: Map<string, Remote & {
+        websocket: boolean;
+        ended: boolean;
+    }>;
     timer: NodeJS.Timeout;
     queuedBytes: number;
     receiving: Promise<void>;

package/dist/tunnel/redis.d.ts

@@ -12,6 +12,10 @@ export declare class RedisTunnelRelay implements TunnelRelay {
     private readonly options;
     private started;
     private closed;
+    private draining;
+    private drainSealed;
+    private drainWork;
+    private readonly drainWaiters;
     private readonly attached;
     private readonly connected;
     private readonly frames;
@@ -52,5 +56,13 @@ export declare class RedisTunnelRelay implements TunnelRelay {
     private closeOwner;
     private closeConnection;
     disconnect(sessionId: string): void;
+    /** Reject new remote requests, but allow same-node work already admitted by the HTTP
+     * gateway until drain() seals it. Security checks and ownership timers stay live. */
+    beginDrain(): void;
+    private notifyDrained;
+    /** Updated requesters acknowledge consumed final responses with cancel. Keep those bounded
+     * routes even before drain starts to cover an end-vs-shutdown race. Legacy requesters retain
+     * the previous publish-only completion behavior; they never acquire a new receipt wait. */
+    drain(): Promise<void>;
     close(): Promise<void>;
 }

package/dist/tunnel/redis.js

@@ -4,6 +4,9 @@ import { redisIdentifier as identifier, redisNamespaceSchema as namespaceSchema,
 import { RelaySocket } from './redis-socket.js';
 import { deriveRelayFrameKey, RelayFrameAuthenticator } from './redis-auth.js';
 export { RedisTunnelOwnership } from './redis-ownership.js';
+// Broker stream IDs are UUIDs. This authenticated, otherwise-unused ACK is ignored by old
+// owners and never forwarded to the developer. It negotiates cancel-as-completion-receipt.
+const DRAIN_CAPABILITY_ID = 'relay-drain-v1';
 /** Internal Redis channels contain authorized application traffic. Deploy them
  * on the environment's private, authenticated Redis and disable command replay.
  * Every message is authenticated with a gateway-only key: other Redis clients
@@ -12,6 +15,10 @@ export class RedisTunnelRelay {
     options;
     started = false;
     closed = false;
+    draining = false;
+    drainSealed = false;
+    drainWork = Promise.resolve();
+    drainWaiters = new Set();
     attached = new Map();
     connected = new Map();
     frames;
@@ -165,10 +172,14 @@ export class RedisTunnelRelay {
     }
     async attachOwned(input, socket) {
         this.assertStarted();
+        if (this.draining)
+            throw new Error('Tunnel relay is draining');
         const lease = await this.verifiedLease(input);
         if (!(await this.current(lease, this.options.nodeId)) || socket.readyState !== 1)
             throw new Error('Tunnel is owned by another node');
         this.assertStarted();
+        if (this.draining)
+            throw new Error('Tunnel relay is draining');
         const previous = this.attached.get(lease.sessionId);
         if (previous && previous.lease.epoch >= lease.epoch)
             throw new Error('Duplicate tunnel owner');
@@ -242,6 +253,10 @@ export class RedisTunnelRelay {
         }
         const remote = owner.remotes.get(message.connection);
         if (message.type === 'open') {
+            if (this.draining && (this.drainSealed || message.source !== this.options.nodeId)) {
+                await this.publish(message.source, this.envelope(owner.lease, message.connection, 'close', 'requester'));
+                return;
+            }
             if (remote || owner.remotes.size >= DEFAULT_TUNNEL_LIMITS.maxStreams)
                 throw new Error('Duplicate or excessive tunnel connections');
             owner.remotes.set(message.connection, { nodeId: message.source, connection: message.connection, lastSeen: Date.now() });
@@ -272,6 +287,11 @@ export class RedisTunnelRelay {
         if (message.type === 'ready') {
             if (connection.socket.readyState !== 0)
                 throw new Error('Duplicate tunnel ready');
+            // Publish before exposing the socket, preserving marker-before-request ordering even
+            // when this node is also the owner. Old owners ignore ACKs for unknown stream IDs.
+            await this.publish(connection.ownerNode, this.envelope(connection.lease, message.connection, 'frame', 'owner', JSON.stringify({ type: 'ack', id: DRAIN_CAPABILITY_ID, bytes: 1 })));
+            if (this.connected.get(message.connection) !== connection || connection.socket.readyState !== 0)
+                return;
             clearTimeout(connection.timer);
             connection.socket.readyState = 1;
             connection.resolve(connection.socket);
@@ -287,6 +307,11 @@ export class RedisTunnelRelay {
         const frame = parseTunnelFrame(raw);
         if (frame.type === 'ready' || frame.type === 'response' || frame.type === 'ws-open')
             throw new Error('Invalid requester frame direction');
+        if (frame.id === DRAIN_CAPABILITY_ID) {
+            if (frame.type === 'ack' && frame.bytes === 1)
+                remote.receipts = true;
+            return;
+        }
         const route = owner.streams.get(frame.id);
         if (frame.type === 'request') {
             if (route || owner.streams.size >= DEFAULT_TUNNEL_LIMITS.maxStreams) {
@@ -294,13 +319,37 @@ export class RedisTunnelRelay {
                 await this.publish(remote.nodeId, this.envelope(owner.lease, remote.connection, 'close', 'requester'));
                 return;
             }
-            owner.streams.set(frame.id, remote);
+            const refused = this.draining && (this.drainSealed || remote.nodeId !== this.options.nodeId || frame.websocket);
+            if (refused && frame.websocket) {
+                // Upgrades cannot consume HTTP response frames. Cancel only this stream; no
+                // route or completion receipt is needed because it never reached the developer.
+                await this.publish(remote.nodeId, this.envelope(owner.lease, remote.connection, 'frame', 'requester', JSON.stringify({ type: 'cancel', id: frame.id })));
+                return;
+            }
+            owner.streams.set(frame.id, { ...remote, websocket: frame.websocket, ended: refused });
+            if (refused) {
+                await this.publish(remote.nodeId, this.envelope(owner.lease, remote.connection, 'frame', 'requester', JSON.stringify({ type: 'response', id: frame.id, status: 503, headers: { 'cache-control': 'no-store' } })));
+                await this.publish(remote.nodeId, this.envelope(owner.lease, remote.connection, 'frame', 'requester', JSON.stringify({ type: 'end', id: frame.id })));
+                if (!remote.receipts)
+                    owner.streams.delete(frame.id);
+                this.notifyDrained();
+                return;
+            }
         }
         else if (!route || route.connection !== remote.connection || route.nodeId !== remote.nodeId)
             return;
-        if (frame.type === 'cancel' || frame.type === 'ws-close')
-            owner.streams.delete(frame.id);
+        if (route?.ended) {
+            if (frame.type === 'cancel' || frame.type === 'ws-close') {
+                owner.streams.delete(frame.id);
+                this.notifyDrained();
+            }
+            return;
+        }
         await this.writeDeveloper(owner, raw);
+        if (frame.type === 'cancel' || frame.type === 'ws-close') {
+            owner.streams.delete(frame.id);
+            this.notifyDrained();
+        }
     }
     writeDeveloper(owner, raw) {
         if (owner.stopped || owner.socket.readyState !== 1 || owner.socket.bufferedAmount + Buffer.byteLength(raw) > DEFAULT_TUNNEL_LIMITS.maxBufferedBytes) {
@@ -336,9 +385,15 @@ export class RedisTunnelRelay {
             const remote = owner.streams.get(frame.id);
             if (!remote)
                 return;
+            if (remote.ended)
+                return;
+            const retainReceipt = frame.type === 'end' && !remote.websocket && remote.receipts;
+            if (retainReceipt)
+                remote.ended = true;
             await this.publish(remote.nodeId, this.envelope(owner.lease, remote.connection, 'frame', 'requester', raw));
-            if (frame.type === 'end' || frame.type === 'cancel' || frame.type === 'ws-close')
+            if (!retainReceipt && (frame.type === 'end' || frame.type === 'cancel' || frame.type === 'ws-close'))
                 owner.streams.delete(frame.id);
+            this.notifyDrained();
         }).catch(() => this.closeOwner(owner)).finally(() => { owner.queuedBytes -= bytes; });
     }
     closeRemote(owner, remote) {
@@ -349,6 +404,7 @@ export class RedisTunnelRelay {
             owner.streams.delete(id);
             void this.writeDeveloper(owner, JSON.stringify({ type: 'cancel', id })).catch(() => this.closeOwner(owner));
         }
+        this.notifyDrained();
     }
     closeOwner(owner) {
         if (owner.stopped)
@@ -362,6 +418,7 @@ export class RedisTunnelRelay {
             void this.publish(remote.nodeId, this.envelope(owner.lease, remote.connection, 'close', 'requester')).catch(() => undefined);
         owner.remotes.clear();
         owner.streams.clear();
+        this.notifyDrained();
         void this.options.ownership.release(owner.lease.sessionId, owner.lease.epoch, this.options.nodeId).catch(() => undefined);
     }
     closeConnection(id, connection) {
@@ -387,6 +444,47 @@ export class RedisTunnelRelay {
                     return this.publish(remote.nodeId, { type: 'revoke', destination: 'owner', source: this.options.nodeId, connection: randomUUID(), sessionId, epoch: remote.epoch });
             }).catch(() => undefined);
     }
+    /** Reject new remote requests, but allow same-node work already admitted by the HTTP
+     * gateway until drain() seals it. Security checks and ownership timers stay live. */
+    beginDrain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        const cancellations = [];
+        for (const owner of this.attached.values())
+            for (const [id, route] of owner.streams) {
+                if (!route.websocket)
+                    continue;
+                route.ended = true;
+                const frame = JSON.stringify({ type: 'cancel', id });
+                cancellations.push(Promise.all([
+                    this.writeDeveloper(owner, frame),
+                    this.publish(route.nodeId, this.envelope(owner.lease, route.connection, 'frame', 'requester', frame)),
+                ]).then(() => { owner.streams.delete(id); this.notifyDrained(); }).catch(() => this.closeOwner(owner)));
+            }
+        this.drainWork = Promise.all(cancellations).then(() => undefined);
+    }
+    notifyDrained() {
+        if (!this.drainWaiters.size)
+            return;
+        for (const owner of this.attached.values())
+            if (owner.streams.size)
+                return;
+        for (const resolve of this.drainWaiters)
+            resolve();
+        this.drainWaiters.clear();
+    }
+    /** Updated requesters acknowledge consumed final responses with cancel. Keep those bounded
+     * routes even before drain starts to cover an end-vs-shutdown race. Legacy requesters retain
+     * the previous publish-only completion behavior; they never acquire a new receipt wait. */
+    async drain() {
+        this.beginDrain();
+        this.drainSealed = true;
+        await this.receiving;
+        await this.drainWork;
+        await new Promise((resolve) => { this.drainWaiters.add(resolve); this.notifyDrained(); });
+        await this.publishing;
+    }
     async close() {
         if (this.closed)
             return;

package/dist/tunnel/transport.d.ts

@@ -13,5 +13,8 @@ export interface TunnelRelay {
     attach(lease: TunnelLease, socket: TunnelSocket): Promise<void>;
     connect(lease: TunnelLease): Promise<TunnelSocket>;
     disconnect(sessionId: string): void;
+    /** Optional for custom adapters; built-in Redis retains owned finite streams during drain. */
+    beginDrain?(): void;
+    drain?(): Promise<void>;
     close(): Promise<void>;
 }

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "SDK types and CLI library for building Artifact Studio apps. Driven via `seq-studio artifact <sub>` (@sequenceholdings/studio-cli), which runs the `./cli` runCli export.",
   "type": "module",
   "exports": {
@@ -169,7 +169,7 @@
     "parse5": "7.3.0",
     "@sequenceholdings/lattice-form-renderer": "0.2.0",
     "@sequenceholdings/storage": "0.1.1",
-    "@sequenceholdings/orm": "2.6.1"
+    "@sequenceholdings/orm": "2.6.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/templates/react-vite/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@sequenceholdings/artifact-studio": "^0.7.0",
+    "@sequenceholdings/artifact-studio": "^0.8.0",
     "@sequenceholdings/atlas-ui": "^3.1.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",