@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/dist/gateway/release-admission.js

@@ -0,0 +1,259 @@
+import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+const RELEASE_FIELD = '__sequence_release';
+const RELEASE_HEADER = 'x-sequence-artifact-release';
+const FRAMEWORK_BUILD_HEADER = 'x-deployment-id';
+const MAX_PREFIX_BYTES = 64 * 1024;
+const MAX_RELEASE_BYTES = 255;
+const RELEASE_ID = /^[a-zA-Z0-9_-]{1,255}$/;
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+export class ReleaseAdmissionError extends Error {
+    reason;
+    status = 409;
+    code = 'update-required';
+    constructor(reason = 'missing-release') {
+        super('Reload the application before submitting this request. The request was not executed.');
+        this.reason = reason;
+        this.name = 'ReleaseAdmissionError';
+    }
+}
+function parseUrlEncoded({ prefix, ended }) {
+    const separator = prefix.indexOf(0x26);
+    if (separator < 0 && !ended)
+        return undefined;
+    const first = prefix.subarray(0, separator < 0 ? prefix.length : separator).toString('utf8');
+    const equals = first.indexOf('=');
+    if (equals < 0)
+        throw new ReleaseAdmissionError('invalid-form');
+    try {
+        const name = decodeURIComponent(first.slice(0, equals).replace(/\+/g, ' '));
+        const release = decodeURIComponent(first.slice(equals + 1).replace(/\+/g, ' '));
+        if (name !== RELEASE_FIELD || Buffer.byteLength(release) > MAX_RELEASE_BYTES || !RELEASE_ID.test(release)) {
+            throw new ReleaseAdmissionError('invalid-form');
+        }
+        return release;
+    }
+    catch {
+        throw new ReleaseAdmissionError('invalid-form');
+    }
+}
+function multipartParser({ boundary }) {
+    const opening = Buffer.from(`--${boundary}\r\n`);
+    const delimiter = Buffer.from(`\r\n--${boundary}`);
+    return ({ prefix, ended }) => {
+        if (!prefix.subarray(0, Math.min(prefix.length, opening.length)).equals(opening.subarray(0, Math.min(prefix.length, opening.length)))) {
+            throw new ReleaseAdmissionError('invalid-form');
+        }
+        if (prefix.length < opening.length) {
+            if (ended)
+                throw new ReleaseAdmissionError('invalid-form');
+            return undefined;
+        }
+        const headerEnd = prefix.indexOf('\r\n\r\n', opening.length);
+        if (headerEnd < 0) {
+            if (ended)
+                throw new ReleaseAdmissionError('invalid-form');
+            return undefined;
+        }
+        const headers = new Map();
+        for (const line of prefix.subarray(opening.length, headerEnd).toString('latin1').split('\r\n')) {
+            const colon = line.indexOf(':');
+            if (colon <= 0)
+                throw new ReleaseAdmissionError('invalid-form');
+            const name = line.slice(0, colon).toLowerCase();
+            const value = line.slice(colon + 1).trim();
+            if (!['content-disposition', 'content-type'].includes(name) || headers.has(name)) {
+                throw new ReleaseAdmissionError('invalid-form');
+            }
+            headers.set(name, value);
+        }
+        const disposition = headers.get('content-disposition')?.split(';').map((part) => part.trim());
+        if (!disposition || disposition.length !== 2 || disposition[0].toLowerCase() !== 'form-data') {
+            throw new ReleaseAdmissionError('invalid-form');
+        }
+        const field = disposition[1];
+        const equals = field.indexOf('=');
+        if (equals < 0 || field.slice(0, equals).toLowerCase() !== 'name' ||
+            ![RELEASE_FIELD, `"${RELEASE_FIELD}"`].includes(field.slice(equals + 1))) {
+            throw new ReleaseAdmissionError('invalid-form');
+        }
+        const contentType = headers.get('content-type');
+        if (contentType && !/^text\/plain(?:\s*;\s*charset=(?:utf-8|"utf-8"))?$/i.test(contentType)) {
+            throw new ReleaseAdmissionError('invalid-form');
+        }
+        const valueStart = headerEnd + 4;
+        const valueEnd = prefix.indexOf(delimiter, valueStart);
+        if (valueEnd < 0) {
+            if (ended || prefix.length - valueStart > MAX_RELEASE_BYTES + delimiter.length - 1) {
+                throw new ReleaseAdmissionError('invalid-form');
+            }
+            return undefined;
+        }
+        if (valueEnd - valueStart > MAX_RELEASE_BYTES)
+            throw new ReleaseAdmissionError('invalid-form');
+        const suffixOffset = valueEnd + delimiter.length;
+        if (prefix.length < suffixOffset + 2) {
+            if (ended)
+                throw new ReleaseAdmissionError('invalid-form');
+            return undefined;
+        }
+        const suffix = prefix.subarray(suffixOffset, suffixOffset + 2).toString('ascii');
+        if (suffix !== '\r\n' && suffix !== '--')
+            throw new ReleaseAdmissionError('invalid-form');
+        if (suffix === '--') {
+            const closingEnd = suffixOffset + 2;
+            if (prefix.length < closingEnd + 2) {
+                if (!ended)
+                    return undefined;
+                if (prefix.length !== closingEnd)
+                    throw new ReleaseAdmissionError('invalid-form');
+            }
+            else if (!prefix.subarray(closingEnd, closingEnd + 2).equals(Buffer.from('\r\n'))) {
+                throw new ReleaseAdmissionError('invalid-form');
+            }
+        }
+        const release = prefix.subarray(valueStart, valueEnd).toString('utf8');
+        if (!RELEASE_ID.test(release))
+            throw new ReleaseAdmissionError('invalid-form');
+        return release;
+    };
+}
+function getFormParser({ contentType }) {
+    if (typeof contentType !== 'string')
+        throw new ReleaseAdmissionError('missing-release');
+    const [mediaType, ...parameters] = contentType.split(';').map((part) => part.trim());
+    if (mediaType.toLowerCase() === 'application/x-www-form-urlencoded')
+        return parseUrlEncoded;
+    if (mediaType.toLowerCase() !== 'multipart/form-data')
+        throw new ReleaseAdmissionError('missing-release');
+    const boundaries = parameters.filter((parameter) => parameter.slice(0, parameter.indexOf('=')).toLowerCase() === 'boundary');
+    if (boundaries.length !== 1)
+        throw new ReleaseAdmissionError('invalid-form');
+    const raw = boundaries[0].slice(boundaries[0].indexOf('=') + 1);
+    const boundary = raw.startsWith('"') && raw.endsWith('"') ? raw.slice(1, -1) : raw;
+    if (!/^[0-9A-Za-z'()+_,./:=? -]{1,70}$/.test(boundary) || boundary.endsWith(' ') ||
+        (!raw.startsWith('"') && boundary.includes(' '))) {
+        throw new ReleaseAdmissionError('invalid-form');
+    }
+    return multipartParser({ boundary });
+}
+function checkRelease({ release, expectedDeploymentId }) {
+    if (!RELEASE_ID.test(release) || release !== expectedDeploymentId)
+        throw new ReleaseAdmissionError('stale-release');
+}
+function readReleaseHeader({ request, name }) {
+    const value = request.headers[name];
+    // Inspect raw headers too: Node may discard rather than join duplicate values.
+    const count = request.rawHeaders.filter((_, index) => index % 2 === 0 && request.rawHeaders[index].toLowerCase() === name).length;
+    if (count > 1)
+        throw new ReleaseAdmissionError('conflicting-release');
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || !RELEASE_ID.test(value))
+        throw new ReleaseAdmissionError('conflicting-release');
+    return value;
+}
+/** Framework hints identify compiled assets, never the Atlas activation authorizing a mutation. */
+function validateFrameworkHints({ request, expectedFrameworkBuildId }) {
+    const header = readReleaseHeader({ request, name: FRAMEWORK_BUILD_HEADER });
+    let query;
+    try {
+        query = new URL(request.url ?? '/', 'http://release.invalid').searchParams.getAll('dpl');
+    }
+    catch {
+        throw new ReleaseAdmissionError('conflicting-release');
+    }
+    if (!artifactNextFrameworkBuildIdSchema.safeParse(expectedFrameworkBuildId).success ||
+        (header !== undefined && !artifactNextFrameworkBuildIdSchema.safeParse(header).success) ||
+        query.length > 1 || (query.length === 1 && !artifactNextFrameworkBuildIdSchema.safeParse(query[0]).success)) {
+        throw new ReleaseAdmissionError('conflicting-release');
+    }
+    if (header !== undefined && query.length === 1 && header !== query[0]) {
+        throw new ReleaseAdmissionError('conflicting-release');
+    }
+    const frameworkBuildId = header ?? query[0];
+    if (frameworkBuildId !== undefined && frameworkBuildId !== expectedFrameworkBuildId) {
+        throw new ReleaseAdmissionError('stale-release');
+    }
+}
+function bytes({ value }) {
+    if (!(value instanceof Uint8Array))
+        throw new ReleaseAdmissionError('invalid-form');
+    return value;
+}
+/**
+ * Admit a mutation against the release that rendered its document. No request is
+ * forwarded until admission succeeds. An admitted form exposes one continuation
+ * over the original iterator, including every byte inspected here.
+ */
+export async function admitHostedMutation({ request, expectedDeploymentId, expectedFrameworkBuildId, active, published }) {
+    const method = (request.method ?? 'GET').toUpperCase();
+    validateFrameworkHints({ request, expectedFrameworkBuildId });
+    if (READ_METHODS.has(method))
+        return {};
+    if (published && !active)
+        throw new ReleaseAdmissionError('inactive-release');
+    const release = readReleaseHeader({ request, name: RELEASE_HEADER });
+    if (release !== undefined) {
+        checkRelease({ release, expectedDeploymentId });
+        return {};
+    }
+    if (method !== 'POST')
+        throw new ReleaseAdmissionError('missing-release');
+    const parse = getFormParser({ contentType: request.headers['content-type'] });
+    // A normal for-await break destroys IncomingMessage. Retain this one iterator
+    // while peeking, then hand its continuation to the proxy without a second read.
+    const iterator = request.iterator({ destroyOnReturn: false });
+    const buffered = [];
+    const prefixBuffer = Buffer.alloc(MAX_PREFIX_BYTES);
+    let prefixLength = 0;
+    let ended = false;
+    try {
+        while (true) {
+            const release = parse({ prefix: prefixBuffer.subarray(0, prefixLength), ended });
+            if (release !== undefined) {
+                checkRelease({ release, expectedDeploymentId });
+                break;
+            }
+            if (ended)
+                throw new ReleaseAdmissionError('invalid-form');
+            if (prefixLength >= MAX_PREFIX_BYTES)
+                throw new ReleaseAdmissionError('prefix-limit');
+            const next = await iterator.next();
+            ended = next.done === true;
+            if (!ended) {
+                const chunk = bytes({ value: next.value });
+                buffered.push(chunk);
+                // Inspect at most 64 KiB even when a transport read returns a larger
+                // chunk. Keep that original chunk for lossless, zero-copy forwarding.
+                const inspected = chunk.subarray(0, MAX_PREFIX_BYTES - prefixLength);
+                prefixBuffer.set(inspected, prefixLength);
+                prefixLength += inspected.length;
+            }
+        }
+    }
+    catch (error) {
+        await iterator.return?.();
+        throw error;
+    }
+    async function* continuation() {
+        try {
+            for (const chunk of buffered)
+                yield chunk;
+            if (ended)
+                return;
+            while (true) {
+                const next = await iterator.next();
+                if (next.done)
+                    return;
+                yield bytes({ value: next.value });
+            }
+        }
+        finally {
+            // The transport owns abort/connection-close behavior. Returning this
+            // non-destructive iterator releases its listeners without losing a 409
+            // or upstream-error response by prematurely destroying the client socket.
+            await iterator.return?.();
+        }
+    }
+    return { body: continuation() };
+}

package/dist/gateway/server.d.ts

@@ -0,0 +1,38 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type TunnelLease, type TunnelBrokerOptions } from '../tunnel/index.js';
+import { ArtifactGatewayControl } from './control.js';
+import { type ArtifactRequestAdmission } from './admission.js';
+import { type GatewayControlAdmission } from './control-admission.js';
+export interface ArtifactGatewayOptions {
+    control: ArtifactGatewayControl;
+    runtimeDomain: string;
+    parentOrigin: string;
+    gatewayOrigin: string;
+    sessionKey: string;
+    contextPrivateKey: string;
+    contextKeyId: string;
+    /** Unique per process, never a shared Cloud Run revision name. */
+    nodeId: string;
+    routing: TunnelBrokerOptions['routing'];
+    relay?: TunnelBrokerOptions['relay'];
+    resolveLease?: TunnelBrokerOptions['resolveLease'];
+    renewLease?: (lease: TunnelLease) => Promise<boolean>;
+    ready?: () => boolean;
+    admission?: Pick<ArtifactRequestAdmission, 'acquire'>;
+    /** Rate limits `/_sequence/session` and `/_sequence/tunnel` before they reach Atlas. Without it
+     * both endpoints fail closed. */
+    controlAdmission?: Pick<GatewayControlAdmission, 'admit'>;
+    /** Reuse of a positive Atlas authorization (default GATEWAY_AUTHORIZATION_TTL_MS; 0 disables). */
+    authorizationCacheTtlMs?: number;
+    onError?: (event: {
+        kind: string;
+        requestId?: string;
+        count?: number;
+    }) => void;
+}
+export declare function createArtifactGateway(options: ArtifactGatewayOptions): {
+    server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
+    /** Observations recorded but not yet confirmed by Atlas: what a forced exit would lose. */
+    readonly pendingUsage: number;
+    drain(): Promise<void>;
+};