@zlink-systems/framework 0.11.0 → 0.13.0

package/dist/runtime/channels/channel-envelope.js

@@ -40,22 +40,7 @@ function encodeChannelEnvelopeParts(kind, channelName, packetName, payload, time
     const encoded = encodePayload(payload, (0, channel_framework_packets_1.codecsForFrameworkPacket)(messageName, codecs), messageName, 'payload');
     const flow = createFlow ? (0, flow_context_1.currentOrCreateFlow)('Application') : undefined;
     const envelopeCorrelationId = correlationIdForOutboundKind(kind, correlationId);
-    const header = {
-        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
-        kind,
-        channelName,
-        messageName,
-        contentType: encoded.contentType,
-        correlationId: envelopeCorrelationId,
-        deadline: timeoutMs === undefined ? null : new Date(Date.now() + timeoutMs).toISOString(),
-        topic: topic ?? null,
-        errorCode: null,
-        errorMessage: null,
-        metadata: applicationMetadataRecord(metadata),
-        flowId: flow?.flowId,
-        flowOrigin: flow?.flowOrigin
-    };
-    return [encodeChannelHeader(header), encoded.message];
+    return [encodeChannelHeader(kind, channelName, messageName, encoded.contentType, envelopeCorrelationId, timeoutMs === undefined ? null : new Date(Date.now() + timeoutMs).toISOString(), topic ?? null, null, null, undefined, applicationMetadataRecord(metadata), flow?.flowId, flow?.flowOrigin), encoded.message];
 }
 /**
  * Encodes an outbound channel envelope with a deadline that was established
@@ -71,60 +56,17 @@ function encodeChannelEnvelopePartsAtDeadline(kind, channelName, packetName, pay
     const encoded = encodePayload(payload, (0, channel_framework_packets_1.codecsForFrameworkPacket)(messageName, codecs), messageName, 'payload');
     const flow = createFlow ? (0, flow_context_1.currentOrCreateFlow)('Application') : undefined;
     const envelopeCorrelationId = correlationIdForOutboundKind(kind, correlationId);
-    const header = {
-        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
-        kind,
-        channelName,
-        messageName,
-        contentType: encoded.contentType,
-        correlationId: envelopeCorrelationId,
-        deadline: new Date(deadlineUnixMs).toISOString(),
-        topic: topic ?? null,
-        errorCode: null,
-        errorMessage: null,
-        metadata: applicationMetadataRecord(metadata),
-        flowId: flow?.flowId,
-        flowOrigin: flow?.flowOrigin
-    };
-    return [encodeChannelHeader(header), encoded.message];
+    return [encodeChannelHeader(kind, channelName, messageName, encoded.contentType, envelopeCorrelationId, new Date(deadlineUnixMs).toISOString(), topic ?? null, null, null, undefined, applicationMetadataRecord(metadata), flow?.flowId, flow?.flowOrigin), encoded.message];
 }
 function encodeChannelPublishEnvelopeParts(channelName, topic, packetName, payload, codecs, createFlow = true, metadata = EMPTY_OUTBOUND_METADATA) {
     const messageName = (0, packet_name_1.resolveFrameworkPacketName)(payload, packetName, 'Channel');
     const encoded = encodePayload(payload, (0, channel_framework_packets_1.codecsForFrameworkPacket)(messageName, codecs), messageName, 'payload');
     const flow = createFlow ? (0, flow_context_1.currentOrCreateFlow)('Application') : undefined;
-    const header = {
-        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
-        kind: 4 /* ZLinkChannelMessageKind.Publish */,
-        channelName,
-        messageName,
-        contentType: encoded.contentType,
-        correlationId: null,
-        deadline: null,
-        topic,
-        errorCode: null,
-        errorMessage: null,
-        metadata: applicationMetadataRecord(metadata),
-        flowId: flow?.flowId,
-        flowOrigin: flow?.flowOrigin
-    };
-    return [encodeChannelHeader(header), encoded.message];
+    return [encodeChannelHeader(4 /* ZLinkChannelMessageKind.Publish */, channelName, messageName, encoded.contentType, null, null, topic, null, null, undefined, applicationMetadataRecord(metadata), flow?.flowId, flow?.flowOrigin), encoded.message];
 }
 function encodeChannelReplyParts(request, payload, codecs) {
     const encoded = encodePayload(payload ?? Buffer.alloc(0), (0, channel_framework_packets_1.codecsForFrameworkPacket)(request.messageName, codecs), request.messageName, 'reply');
-    const header = {
-        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
-        kind: 2 /* ZLinkChannelMessageKind.Response */,
-        channelName: request.channelName,
-        messageName: request.messageName,
-        contentType: encoded.contentType,
-        correlationId: request.correlationId,
-        deadline: null,
-        topic: null,
-        metadata: {},
-        flowId: request.flowId,
-        flowOrigin: request.flowOrigin
-    };
-    return [encodeChannelHeader(header), encoded.message];
+    return [encodeChannelHeader(2 /* ZLinkChannelMessageKind.Response */, request.channelName, request.messageName, encoded.contentType, request.correlationId, null, null, undefined, undefined, undefined, EMPTY_APPLICATION_METADATA, request.flowId, request.flowOrigin), encoded.message];
 }
 /**
  * Reply metadata marker for errors the framework generated itself (never for
@@ -147,13 +89,12 @@ const ERROR_KIND_WIRE_NAMES = [
     'not_configured', // 3
     'rejected', // 4
     'unavailable', // 5
-    'capacity_exceeded', // 6
-    'deadline_exceeded', // 7
-    'shutting_down', // 8
-    'protocol_error', // 9
-    'invalid_operation', // 10
-    'data_lost', // 11
-    'internal_failure' // 12
+    'deadline_exceeded', // 6
+    'shutting_down', // 7
+    'protocol_error', // 8
+    'invalid_operation', // 9
+    'data_lost', // 10
+    'internal_failure' // 11
 ];
 const ERROR_KIND_BY_WIRE_NAME = new Map(ERROR_KIND_WIRE_NAMES.map((name, kind) => [name, kind]));
 function channelErrorCodeName(kind) {
@@ -164,22 +105,7 @@ function encodeChannelErrorReplyParts(request, error, metadata = {}) {
         ? error.kind
         : contracts_1.ZLinkFrameworkErrorKind.InternalFailure);
     const errorMessage = error instanceof Error ? error.message : String(error);
-    const header = {
-        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
-        kind: 5 /* ZLinkChannelMessageKind.Error */,
-        channelName: request.channelName,
-        messageName: request.messageName,
-        contentType: exports.JSON_CONTENT_TYPE,
-        correlationId: request.correlationId,
-        deadline: null,
-        topic: null,
-        errorCode,
-        errorMessage,
-        metadata,
-        flowId: request.flowId,
-        flowOrigin: request.flowOrigin
-    };
-    return [encodeChannelHeader(header), encodeJsonBytes(null)];
+    return [encodeChannelHeader(5 /* ZLinkChannelMessageKind.Error */, request.channelName, request.messageName, exports.JSON_CONTENT_TYPE, request.correlationId, null, null, errorCode, errorMessage, undefined, metadata, request.flowId, request.flowOrigin), encodeJsonBytes(null)];
 }
 function decodeChannelReply(parts, codecs) {
     const header = decodeChannelHeader(parts);
@@ -335,25 +261,145 @@ function isMessage(value) {
 function encodeJsonBytes(value, schema) {
     return Buffer.from((0, framework_json_v1_1.stringifyFrameworkJsonV1)(value, schema));
 }
-function encodeChannelHeader(header) {
-    //  Explicit construction: this runs for every outbound envelope, so avoid a
-    //  per-message spread of the whole header.
-    return encodeJsonBytes({
-        formatMarker: header.formatMarker,
-        kind: header.kind,
-        channelName: header.channelName,
-        messageName: header.messageName,
-        contentType: header.contentType,
-        correlationId: header.correlationId,
-        deadline: header.deadline,
-        topic: header.topic,
-        errorCode: header.errorCode,
-        errorMessage: header.errorMessage,
-        source: header.source,
-        metadata: header.metadata,
-        flowId: header.flowId,
-        flowOrigin: header.flowOrigin === undefined ? undefined : encodeFlowOrigin(header.flowOrigin)
-    });
+function encodeChannelHeader(kind, channelName, messageName, contentType, correlationId, deadline, topic, errorCode, errorMessage, source, metadata, flowId, flowOrigin) {
+    // The wire has a fixed field order. Measure escaped UTF-8 first, then write
+    // each field once into the only header Buffer: no header object, whole JSON
+    // string, or post-encode byte copy exists on the outbound path.
+    const measure = new ChannelHeaderWriter();
+    writeChannelHeader(measure, kind, channelName, messageName, contentType, correlationId, deadline, topic, errorCode, errorMessage, source, metadata, flowId, flowOrigin);
+    const result = Buffer.alloc(measure.byteLength);
+    const writer = new ChannelHeaderWriter(result);
+    writeChannelHeader(writer, kind, channelName, messageName, contentType, correlationId, deadline, topic, errorCode, errorMessage, source, metadata, flowId, flowOrigin);
+    return result;
+}
+function writeChannelHeader(writer, kind, channelName, messageName, contentType, correlationId, deadline, topic, errorCode, errorMessage, source, metadata, flowId, flowOrigin) {
+    writer.append('{"formatMarker":');
+    writer.append(String(exports.ZLINK_CHANNEL_FORMAT_MARKER));
+    writer.append(',"kind":');
+    writer.append(String(kind));
+    writer.append(',"channelName":');
+    writer.string(channelName);
+    writer.append(',"messageName":');
+    writer.string(messageName);
+    writer.append(',"contentType":');
+    writer.string(contentType);
+    writer.append(',"correlationId":');
+    writer.nullableString(correlationId);
+    writer.append(',"deadline":');
+    writer.nullableString(deadline);
+    writer.append(',"topic":');
+    writer.nullableString(topic);
+    if (errorCode !== undefined) {
+        writer.append(',"errorCode":');
+        writer.nullableString(errorCode);
+    }
+    if (errorMessage !== undefined) {
+        writer.append(',"errorMessage":');
+        writer.nullableString(errorMessage);
+    }
+    if (source !== undefined) {
+        writer.append(',"source":');
+        writer.nullableString(source);
+    }
+    writer.append(',"metadata":{');
+    let first = true;
+    for (const name in metadata) {
+        if (!Object.prototype.hasOwnProperty.call(metadata, name))
+            continue;
+        if (!first)
+            writer.append(',');
+        first = false;
+        writer.string(name);
+        writer.append(':');
+        writer.string(metadata[name]);
+    }
+    writer.append('}');
+    if (flowId !== undefined) {
+        writer.append(',"flowId":');
+        writer.string(flowId);
+    }
+    if (flowOrigin !== undefined) {
+        writer.append(',"flowOrigin":');
+        writer.append(String(encodeFlowOrigin(flowOrigin)));
+    }
+    writer.append('}');
+}
+class ChannelHeaderWriter {
+    output;
+    offset = 0;
+    constructor(output) {
+        this.output = output;
+    }
+    get byteLength() {
+        return this.offset;
+    }
+    append(value) {
+        if (this.output === undefined) {
+            this.offset += Buffer.byteLength(value);
+            return;
+        }
+        this.offset += this.output.write(value, this.offset, 'utf8');
+    }
+    nullableString(value) {
+        if (value === null)
+            this.append('null');
+        else
+            this.string(value);
+    }
+    string(value) {
+        this.append('"');
+        let start = 0;
+        for (let index = 0; index < value.length; index += 1) {
+            const code = value.charCodeAt(index);
+            let escaped;
+            switch (code) {
+                case 0x08:
+                    escaped = '\\b';
+                    break;
+                case 0x09:
+                    escaped = '\\t';
+                    break;
+                case 0x0a:
+                    escaped = '\\n';
+                    break;
+                case 0x0c:
+                    escaped = '\\f';
+                    break;
+                case 0x0d:
+                    escaped = '\\r';
+                    break;
+                case 0x22:
+                    escaped = '\\"';
+                    break;
+                case 0x5c:
+                    escaped = '\\\\';
+                    break;
+                default:
+                    if (code < 0x20) {
+                        escaped = `\\u00${code.toString(16).padStart(2, '0')}`;
+                    }
+                    else if (code >= 0xd800 && code <= 0xdbff) {
+                        const next = value.charCodeAt(index + 1);
+                        if (next >= 0xdc00 && next <= 0xdfff) {
+                            index += 1;
+                        }
+                        else {
+                            escaped = `\\u${code.toString(16)}`;
+                        }
+                    }
+                    else if (code >= 0xdc00 && code <= 0xdfff) {
+                        escaped = `\\u${code.toString(16)}`;
+                    }
+            }
+            if (escaped === undefined)
+                continue;
+            this.append(value.slice(start, index));
+            this.append(escaped);
+            start = index + 1;
+        }
+        this.append(value.slice(start));
+        this.append('"');
+    }
 }
 function encodeFlowOrigin(origin) {
     switch (origin) {
@@ -367,13 +413,173 @@ function decodeChannelHeader(parts, flowEnabled = true) {
     if (parts.length === 0) {
         throw new configuration_1.ZLinkConfigurationException('Channel envelope header part is missing.');
     }
-    return validateChannelHeader(parseWireJson(parts[0].data().toString()), flowEnabled);
+    return validateChannelHeader(parseChannelHeaderBytes(parts[0].data()), flowEnabled);
 }
 function parseWireJson(payload, schema) {
     return (0, framework_json_v1_1.parseFrameworkJsonV1)(payload, {
         rejectPropertyName: isPrototypeKey
     }, schema);
 }
+function parseChannelHeaderBytes(payload) {
+    return tryParseCanonicalChannelHeader(payload) ?? parseWireJson(payload.toString());
+}
+/**
+ * Accept the byte layout emitted by writeChannelHeader without materializing
+ * the enclosing JSON text. Any variation falls through to the established
+ * framework-json-v1 parser, which remains the sole authority for JSON
+ * failures, unknown properties, and prototype-key rejection.
+ */
+function tryParseCanonicalChannelHeader(payload) {
+    const reader = new CanonicalChannelHeaderReader(payload);
+    if (!reader.consume('{"formatMarker":242,"kind":'))
+        return undefined;
+    const kind = reader.readSingleDigit();
+    if (kind === undefined || !reader.consume(',"channelName":'))
+        return undefined;
+    const channelName = reader.readString();
+    if (channelName === undefined || !reader.consume(',"messageName":'))
+        return undefined;
+    const messageName = reader.readString();
+    if (messageName === undefined || !reader.consume(',"contentType":'))
+        return undefined;
+    const contentType = reader.readString();
+    if (contentType === undefined || !reader.consume(',"correlationId":'))
+        return undefined;
+    const correlationId = reader.readNullableString();
+    if (correlationId === undefined || !reader.consume(',"deadline":'))
+        return undefined;
+    const deadline = reader.readNullableString();
+    if (deadline === undefined || !reader.consume(',"topic":'))
+        return undefined;
+    const topic = reader.readNullableString();
+    if (topic === undefined)
+        return undefined;
+    const header = {
+        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
+        kind,
+        channelName,
+        messageName,
+        contentType,
+        correlationId: correlationId === NULL_JSON_STRING ? null : correlationId,
+        deadline: deadline === NULL_JSON_STRING ? null : deadline,
+        topic: topic === NULL_JSON_STRING ? null : topic
+    };
+    if (!reader.readOptionalNullableString('errorCode', header))
+        return undefined;
+    if (!reader.readOptionalNullableString('errorMessage', header))
+        return undefined;
+    if (!reader.readOptionalNullableString('source', header))
+        return undefined;
+    if (!reader.consume(',"metadata":{}'))
+        return undefined;
+    header.metadata = {};
+    if (!reader.readOptionalString('flowId', header))
+        return undefined;
+    if (!reader.readOptionalSingleDigit('flowOrigin', header))
+        return undefined;
+    return reader.consume('}') && reader.atEnd() ? header : undefined;
+}
+const NULL_JSON_STRING = Symbol('null JSON string');
+class CanonicalChannelHeaderReader {
+    bytes;
+    index = 0;
+    constructor(bytes) {
+        this.bytes = bytes;
+    }
+    atEnd() {
+        return this.index === this.bytes.length;
+    }
+    consume(value) {
+        if (this.index + value.length > this.bytes.length)
+            return false;
+        for (let offset = 0; offset < value.length; offset += 1) {
+            if (this.bytes[this.index + offset] !== value.charCodeAt(offset))
+                return false;
+        }
+        this.index += value.length;
+        return true;
+    }
+    readSingleDigit() {
+        if (this.index === this.bytes.length)
+            return undefined;
+        const value = this.bytes[this.index];
+        if (value < 0x30 || value > 0x39)
+            return undefined;
+        this.index += 1;
+        return value - 0x30;
+    }
+    readString() {
+        if (this.bytes[this.index] !== 0x22)
+            return undefined;
+        const start = this.index;
+        this.index += 1;
+        while (this.index < this.bytes.length) {
+            const value = this.bytes[this.index++];
+            if (value === 0x22) {
+                return JSON.parse(this.bytes.toString('utf8', start, this.index));
+            }
+            if (value < 0x20)
+                return undefined;
+            if (value !== 0x5c)
+                continue;
+            if (this.index === this.bytes.length)
+                return undefined;
+            const escaped = this.bytes[this.index++];
+            if (escaped === 0x75) {
+                for (let count = 0; count < 4; count += 1) {
+                    if (this.index === this.bytes.length)
+                        return undefined;
+                    const digit = this.bytes[this.index++];
+                    if (!isHexDigit(digit))
+                        return undefined;
+                }
+            }
+            else if (escaped !== 0x22 && escaped !== 0x5c && escaped !== 0x2f
+                && escaped !== 0x62 && escaped !== 0x66 && escaped !== 0x6e
+                && escaped !== 0x72 && escaped !== 0x74) {
+                return undefined;
+            }
+        }
+        return undefined;
+    }
+    readNullableString() {
+        if (this.consume('null'))
+            return NULL_JSON_STRING;
+        return this.readString();
+    }
+    readOptionalNullableString(name, target) {
+        if (!this.consume(`,\"${name}\":`))
+            return true;
+        const value = this.readNullableString();
+        if (value === undefined)
+            return false;
+        target[name] = value === NULL_JSON_STRING ? null : value;
+        return true;
+    }
+    readOptionalString(name, target) {
+        if (!this.consume(`,\"${name}\":`))
+            return true;
+        const value = this.readString();
+        if (value === undefined)
+            return false;
+        target[name] = value;
+        return true;
+    }
+    readOptionalSingleDigit(name, target) {
+        if (!this.consume(`,\"${name}\":`))
+            return true;
+        const value = this.readSingleDigit();
+        if (value === undefined)
+            return false;
+        target[name] = value;
+        return true;
+    }
+}
+function isHexDigit(value) {
+    return (value >= 0x30 && value <= 0x39)
+        || (value >= 0x41 && value <= 0x46)
+        || (value >= 0x61 && value <= 0x66);
+}
 function schemaForInboundChannelEnvelope(header) {
     const contract = (0, Attributes_1.readZLinkPacketJsonContract)(header.messageName);
     return header.kind === 2 /* ZLinkChannelMessageKind.Response */ ? contract?.reply : contract?.payload;
@@ -401,22 +607,19 @@ function validateChannelHeader(value, flowEnabled = true) {
     }
     const correlationId = requireNullableString(header.correlationId, 'correlationId');
     validateCorrelationForKind(kind, correlationId);
-    return {
-        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
-        kind,
-        channelName: requireString(header.channelName, 'channelName'),
-        messageName: requireString(header.messageName, 'messageName'),
-        contentType,
-        correlationId,
-        deadline: requireNullableString(header.deadline, 'deadline'),
-        topic: requireNullableString(header.topic, 'topic'),
-        errorCode: header.errorCode === undefined ? null : requireNullableString(header.errorCode, 'errorCode'),
-        errorMessage: header.errorMessage === undefined ? null : requireNullableString(header.errorMessage, 'errorMessage'),
-        source: header.source === undefined ? undefined : requireNullableString(header.source, 'source'),
-        metadata: requireApplicationMetadata(header.metadata),
-        flowId,
-        flowOrigin
-    };
+    requireString(header.channelName, 'channelName');
+    requireString(header.messageName, 'messageName');
+    requireNullableString(header.deadline, 'deadline');
+    requireNullableString(header.topic, 'topic');
+    // Parsing already gives this receive operation an owned object. Validate
+    // and normalize it here instead of allocating a second header per record.
+    header.errorCode = header.errorCode === undefined ? null : requireNullableString(header.errorCode, 'errorCode');
+    header.errorMessage = header.errorMessage === undefined ? null : requireNullableString(header.errorMessage, 'errorMessage');
+    header.source = header.source === undefined ? undefined : requireNullableString(header.source, 'source');
+    header.metadata = requireApplicationMetadata(header.metadata);
+    header.flowId = flowId;
+    header.flowOrigin = flowOrigin;
+    return header;
 }
 function correlationIdForOutboundKind(kind, correlationId) {
     if (kind === 1 /* ZLinkChannelMessageKind.Request */) {

package/dist/runtime/channels/channel-multipart.d.ts

@@ -6,8 +6,15 @@ export interface ZLinkMultipartOperation<TNext> {
 export interface ZLinkMultipartSubmitOperation extends ZLinkMultipartOperation<ZLinkMultipartSubmitOperation> {
     submit(): unknown;
 }
+/**
+ * Binding submit()은 제출 스냅샷을 돌려준다. admission을 기다리려면 `.admitted`를
+ * await 한다. binding 타입과 구조적으로 호환되므로 import 하지 않는다.
+ */
+export interface ZLinkMultipartSubmission {
+    readonly admitted: Promise<void>;
+}
 export interface ZLinkMultipartAsyncSubmitOperation extends ZLinkMultipartOperation<ZLinkMultipartAsyncSubmitOperation> {
-    submit(): Promise<void>;
+    submit(): ZLinkMultipartSubmission;
 }
 export type ZLinkMultipartReplyOperation = ZLinkMultipartSubmitOperation;
 export declare function appendParts<TNext extends ZLinkMultipartOperation<TNext>>(operation: ZLinkMultipartOperation<TNext>, parts: readonly MessageLike[]): TNext;

package/dist/runtime/channels/channel-outbound-operations.js

@@ -331,8 +331,6 @@ function requestTerminalResult(error, signal) {
     if (error instanceof contracts_1.ZLinkFrameworkException) {
         if (error.kind === contracts_1.ZLinkFrameworkErrorKind.ShuttingDown)
             return 'shutdown';
-        if (error.kind === contracts_1.ZLinkFrameworkErrorKind.CapacityExceeded)
-            return 'backpressured';
     }
     return 'failed';
 }

package/dist/runtime/channels/channel-receive-loops.d.ts

@@ -1,6 +1,7 @@
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
 import type { ZLinkBackendRouterSocket, ZLinkBackendSpotRouteBridge, ZLinkBackendSubscriberSocket, ZLinkBackendReadablePoller, ZLinkChannelBackendAdapter } from '../backend/contracts';
+import type { ZLinkMultipartAsyncSubmitOperation } from './channel-multipart';
 import type { ZLinkChannelEnvelopeHeader } from './channel-envelope';
 import { type ZLinkReceiveTaskErrorReporter } from './channel-receive-task-tracker';
 import { ApplicationJobQueue } from '../host/application-job-queue';
@@ -10,9 +11,6 @@ interface ZLinkMultipartOperation<TNext> {
 interface ZLinkMultipartSubmitOperation extends ZLinkMultipartOperation<ZLinkMultipartSubmitOperation> {
     submit(): unknown;
 }
-interface ZLinkMultipartAsyncSubmitOperation extends ZLinkMultipartOperation<ZLinkMultipartAsyncSubmitOperation> {
-    submit(): Promise<void>;
-}
 type ZLinkMultipartReplyOperation = ZLinkMultipartSubmitOperation;
 interface ZLinkChannelRequestDispatchLoop {
     /** Spec 27 §4: with tracing Off, inbound flow fields are neither validated nor carried forward. */