@zlink-systems/framework 0.29.1 → 0.30.1

package/src/runtime/foundation/service-wire-m6a-codec.ts

@@ -8,6 +8,7 @@ import {
 } from './service-topology-registry';
 import {
   SERVICE_WIRE_PREFIX_SIZE,
+  SERVICE_WIRE_TEXT8_MAX_BYTES,
   decodeCanonicalServiceWireText,
   encodeCanonicalServiceWireText
 } from './service-wire-binary-primitives';
@@ -70,8 +71,7 @@ export function encodeNodeRequestHeader(correlation: bigint): Buffer {
   return withU64(prefix(M6aServiceWireCommand.nodeRequest), correlation, 'correlation');
 }
 
-export function decodeNodeRequestHeader(frame: Uint8Array): bigint {
-  const header = decodeHeader(frame);
+export function decodeNodeRequestHeader(frame: Uint8Array, header = decodeHeader(frame)): bigint {
   if (
     header.command !== M6aServiceWireCommand.nodeRequest ||
     header.flags !== 0 ||
@@ -86,8 +86,7 @@ export function encodeChannelSendHeader(channelName: string): Buffer {
   return concat(prefix(M6aServiceWireCommand.channelSend), encodeText8(channelName, 'channelName'));
 }
 
-export function decodeChannelSendHeader(frame: Uint8Array): string {
-  const header = decodeHeader(frame);
+export function decodeChannelSendHeader(frame: Uint8Array, header = decodeHeader(frame)): string {
   if (header.command !== M6aServiceWireCommand.channelSend || header.flags !== 0) {
     fail('Invalid channelSend header.');
   }
@@ -104,11 +103,13 @@ export function encodeChannelRequestHeader(correlation: bigint, channelName: str
   );
 }
 
-export function decodeChannelRequestHeader(frame: Uint8Array): {
+export function decodeChannelRequestHeader(
+  frame: Uint8Array,
+  header = decodeHeader(frame)
+): {
   readonly correlation: bigint;
   readonly channelName: string;
 } {
-  const header = decodeHeader(frame);
   if (header.command !== M6aServiceWireCommand.channelRequest || header.flags !== 0) {
     fail('Invalid channelRequest header.');
   }
@@ -165,24 +166,12 @@ export function decodeReplyHeader(frame: Uint8Array): ServiceReplyHeader {
 }
 
 export function encodeApplicationPayload(payload: ServiceApplicationPayload): Buffer {
-  const packetName = encodeText8(payload.packetName, 'packetName');
-  const contentType = encodeText8(payload.contentType, 'contentType');
-  if (payload.payload.byteLength > MAX_U32) fail('Application payload exceeds u32.');
-  const bodyLength =
-    packetName.byteLength + contentType.byteLength + 4 + payload.payload.byteLength;
-  if (bodyLength > MAX_U32) fail('Application payload body exceeds u32.');
-  const result = Buffer.alloc(5 + bodyLength);
-  result[0] = APPLICATION_PAYLOAD_VERSION;
-  result.writeUInt32BE(bodyLength, 1);
-  let offset = 5;
-  offset += packetName.copy(result, offset);
-  offset += contentType.copy(result, offset);
-  result.writeUInt32BE(payload.payload.byteLength, offset);
-  offset += 4;
-  Buffer.from(payload.payload.buffer, payload.payload.byteOffset, payload.payload.byteLength).copy(
-    result,
-    offset
+  const result = allocateApplicationPayload(
+    payload.packetName,
+    payload.contentType,
+    payload.payload.byteLength
   );
+  result.set(payload.payload, result.byteLength - payload.payload.byteLength);
   return result;
 }
 
@@ -198,35 +187,65 @@ export function encodeMultipartApplicationPayload(
 ): Buffer {
   if (parts.length === 0) fail('Multipart payload must contain at least one part.');
   if (parts.length > MAX_U32) fail('Multipart part count exceeds u32.');
-  const packetNameBytes = encodeText8(packetName, 'packetName');
-  const contentTypeBytes = encodeText8(contentType, 'contentType');
   let multipartLength = 4;
   for (const part of parts) {
     if (part.byteLength > MAX_U32) fail('Multipart part exceeds u32.');
     multipartLength += 4 + part.byteLength;
     if (multipartLength > MAX_U32) fail('Multipart payload exceeds u32.');
   }
-  const bodyLength = packetNameBytes.byteLength + contentTypeBytes.byteLength + 4 + multipartLength;
-  if (bodyLength > MAX_U32) fail('Application payload body exceeds u32.');
-  const result = Buffer.alloc(5 + bodyLength);
-  result[0] = APPLICATION_PAYLOAD_VERSION;
-  result.writeUInt32BE(bodyLength, 1);
-  let offset = 5;
-  offset += packetNameBytes.copy(result, offset);
-  offset += contentTypeBytes.copy(result, offset);
-  result.writeUInt32BE(multipartLength, offset);
-  offset += 4;
+  const result = allocateApplicationPayload(packetName, contentType, multipartLength);
+  let offset = result.byteLength - multipartLength;
   result.writeUInt32BE(parts.length, offset);
   offset += 4;
   for (const part of parts) {
     result.writeUInt32BE(part.byteLength, offset);
     offset += 4;
-    Buffer.from(part.buffer, part.byteOffset, part.byteLength).copy(result, offset);
+    result.set(part, offset);
     offset += part.byteLength;
   }
   return result;
 }
 
+function allocateApplicationPayload(
+  packetName: string,
+  contentType: string,
+  payloadLength: number
+): Buffer {
+  const packetNameBytes = encodeCanonicalServiceWireText(
+    packetName,
+    'packetName',
+    SERVICE_WIRE_TEXT8_MAX_BYTES,
+    fail
+  );
+  const contentTypeBytes = encodeCanonicalServiceWireText(
+    contentType,
+    'contentType',
+    SERVICE_WIRE_TEXT8_MAX_BYTES,
+    fail
+  );
+  if (payloadLength > MAX_U32) fail('Application payload exceeds u32.');
+  const frameLength =
+    APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES +
+    packetNameBytes.byteLength +
+    contentTypeBytes.byteLength +
+    payloadLength;
+  const prefixLength = 1 + APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES;
+  const bodyLength = frameLength - prefixLength;
+  if (bodyLength > MAX_U32) fail('Application payload body exceeds u32.');
+  const result = Buffer.alloc(frameLength);
+  result[0] = APPLICATION_PAYLOAD_VERSION;
+  result.writeUInt32BE(bodyLength, 1);
+  let offset = prefixLength;
+  result[offset++] = packetNameBytes.byteLength;
+  result.set(packetNameBytes, offset);
+  offset += packetNameBytes.byteLength;
+  result[offset++] = contentTypeBytes.byteLength;
+  result.set(contentTypeBytes, offset);
+  offset += contentTypeBytes.byteLength;
+  result.writeUInt32BE(payloadLength, offset);
+  return result;
+}
+
 export function decodeApplicationPayload(frame: Uint8Array): ServiceApplicationPayload {
   const decoded = decodeApplicationPayloadView(frame);
   return {
@@ -487,7 +506,7 @@ function encodeU64(value: bigint): Buffer {
 }
 
 function encodeText8(value: string, field: string): Buffer {
-  const bytes = encodeCanonicalServiceWireText(value, field, 0xff, fail);
+  const bytes = encodeCanonicalServiceWireText(value, field, SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
   return concat(Buffer.of(bytes.byteLength), bytes);
 }
 
@@ -501,7 +520,7 @@ function tlv(id: number, value: Buffer): Buffer {
 }
 
 function concat(...parts: readonly Uint8Array[]): Buffer {
-  return Buffer.concat(parts.map((part) => Buffer.from(part)));
+  return Buffer.concat(parts);
 }
 
 function readNonZeroU64(bytes: Buffer, offset: number, field: string): bigint {

package/src/runtime/handlers/handler-instance-scope.ts

@@ -9,13 +9,10 @@ export interface ZLinkHandlerInstanceScope {
 }
 
 interface ZLinkHandlerInstanceScopeFactory {
+  prepare?(type: Type): void | (() => unknown);
   create(context?: ZLinkMessageContext): ZLinkHandlerInstanceScope;
 }
 
-interface ActiveHandlerScope {
-  readonly scope: ZLinkHandlerInstanceScope;
-}
-
 interface Deferred<T> {
   readonly promise: Promise<T>;
   readonly resolve: (value: T) => void;
@@ -29,12 +26,37 @@ interface LifecycleScopeDisposal {
 }
 
 const HANDLER_SCOPE_FACTORY = Symbol.for('@zlink-systems/framework.handler-instance-scope-factory');
-const activeHandlerScope = new AsyncLocalStorage<ActiveHandlerScope>();
+const activeHandlerScope = new AsyncLocalStorage<ZLinkHandlerInstanceScope>();
 const activeLifecycleScope = new AsyncLocalStorage<LifecycleHandlerInstanceScope>();
 const detachedLifecycleResource = new AsyncResource('zlink:handler-instance-scope');
 const dispatchScopes = new WeakMap<object, ZLinkHandlerInstanceScope>();
 const lifecycleScopes = new WeakMap<object, LifecycleHandlerInstanceScope>();
 
+export function registerHandlerInstanceScopeFactory(
+  providerResolver: ZLinkProviderResolver,
+  factory: ZLinkHandlerInstanceScopeFactory
+): void {
+  Object.defineProperty(providerResolver, HANDLER_SCOPE_FACTORY, {
+    value: factory,
+    enumerable: false
+  });
+}
+
+export function prepareHandlerInstance<T>(
+  providerResolver: ZLinkProviderResolver | undefined,
+  type: Type<T>
+): (() => T) | undefined {
+  if (providerResolver === undefined) return () => new type();
+  const factory = (providerResolver as unknown as Record<PropertyKey, unknown>)[
+    HANDLER_SCOPE_FACTORY
+  ];
+  if (isHandlerInstanceScopeFactory(factory)) {
+    const activate = factory.prepare?.(type);
+    if (activate !== undefined) return activate as () => T;
+  }
+  return undefined;
+}
+
 export async function runInHandlerInstanceScope<T>(
   providerResolver: ZLinkProviderResolver | undefined,
   context: ZLinkMessageContext | undefined,
@@ -42,7 +64,7 @@ export async function runInHandlerInstanceScope<T>(
 ): Promise<T> {
   const active = activeHandlerScope.getStore();
   if (active !== undefined) {
-    return callback(active.scope);
+    return callback(active);
   }
   if (context !== undefined) {
     const existing = dispatchScopes.get(context);
@@ -56,7 +78,7 @@ export async function runInHandlerInstanceScope<T>(
     dispatchScopes.set(context, scope);
   }
   try {
-    return await activeHandlerScope.run({ scope }, () => callback(scope));
+    return await activeHandlerScope.run(scope, () => callback(scope));
   } finally {
     if (context !== undefined && dispatchScopes.get(context) === scope) {
       dispatchScopes.delete(context);
@@ -144,14 +166,15 @@ class DefaultHandlerInstanceScope implements ZLinkHandlerInstanceScope {
     if (existing !== undefined) return existing;
     const activation = createDeferred<unknown>();
     this.instances.set(type, activation.promise);
-    void this.activate(type, activation);
+    this.activate(type, activation);
     return activation.promise as Promise<T>;
   }
 
   async dispose(): Promise<void> {
     if (this.disposed) return;
     this.disposed = true;
-    await Promise.allSettled(this.instances.values());
+    if (this.owned.length !== this.instances.size)
+      await Promise.allSettled(this.instances.values());
     try {
       await disposeOwnedInstances(this.owned);
     } finally {
@@ -159,21 +182,43 @@ class DefaultHandlerInstanceScope implements ZLinkHandlerInstanceScope {
       this.instances.clear();
     }
   }
-  private async activate<T>(type: Type<T>, activation: Deferred<unknown>): Promise<void> {
-    let instance: T;
+  private activate<T>(type: Type<T>, activation: Deferred<unknown>): void {
     try {
       const created = this.providerResolver?.create?.(type);
-      instance = created === undefined ? new type() : await created;
+      if (created === undefined) {
+        this.completeActivation(new type(), activation);
+      } else {
+        void this.activatePending(created, activation);
+      }
     } catch (error) {
       activation.reject(error);
-      return;
     }
+  }
 
+  private async activatePending<T>(
+    created: T | Promise<T>,
+    activation: Deferred<unknown>
+  ): Promise<void> {
+    try {
+      this.completeActivation(await created, activation);
+    } catch (error) {
+      activation.reject(error);
+    }
+  }
+
+  private completeActivation(instance: unknown, activation: Deferred<unknown>): void {
     if (!this.disposed) {
       this.owned.push(instance);
       activation.resolve(instance);
       return;
     }
+    void this.disposeLateActivation(instance, activation);
+  }
+
+  private async disposeLateActivation(
+    instance: unknown,
+    activation: Deferred<unknown>
+  ): Promise<void> {
     try {
       await disposeOwnedInstance(instance);
       activation.reject(new Error('Handler instance scope was disposed during activation.'));
@@ -306,6 +351,11 @@ function startOutsideLifecycleInvocation<T>(work: () => T): T {
 }
 
 export async function disposeOwnedInstance(instance: unknown): Promise<void> {
+  const cleanup = handlerInstanceCleanup(instance);
+  if (cleanup !== undefined) await cleanup.call(instance);
+}
+
+export function handlerInstanceCleanup(instance: unknown): (() => unknown) | undefined {
   if (instance === null || instance === undefined) return;
   const value = instance as {
     dispose?: () => unknown;
@@ -313,12 +363,13 @@ export async function disposeOwnedInstance(instance: unknown): Promise<void> {
     onModuleDestroy?: () => unknown;
   };
   if (typeof value.dispose === 'function') {
-    await value.dispose();
+    return value.dispose;
   } else if (typeof value.close === 'function') {
-    await value.close();
+    return value.close;
   } else if (typeof value.onModuleDestroy === 'function') {
-    await value.onModuleDestroy();
+    return value.onModuleDestroy;
   }
+  return undefined;
 }
 
 export async function disposeOwnedInstances(instances: readonly unknown[]): Promise<void> {

package/src/runtime/host/actor-packet-relay.ts

@@ -303,6 +303,7 @@ export class ZLinkActorPacketRelay {
         const dispatch =
           state?.spotId === undefined
             ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(
+                'remote',
                 relay.actorId,
                 [header, body],
                 false,
@@ -310,6 +311,7 @@ export class ZLinkActorPacketRelay {
                 fallbackActorRef
               )
             : this.requireSpotManager().dispatchRoutedActorPacket(
+                'remote',
                 state.spotId,
                 relay.actorId,
                 [header, body],
@@ -356,6 +358,7 @@ export class ZLinkActorPacketRelay {
         const dispatch =
           state?.spotId === undefined
             ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(
+                'remote',
                 relay.actorId,
                 [header, body],
                 false,
@@ -363,6 +366,7 @@ export class ZLinkActorPacketRelay {
                 fallbackActorRef
               )
             : this.requireSpotManager().dispatchRoutedActorPacket(
+                'remote',
                 state.spotId,
                 relay.actorId,
                 [header, body],
@@ -423,6 +427,7 @@ export class ZLinkActorPacketRelay {
       const response =
         state?.spotId === undefined
           ? await this.requireSpotNodeRuntime().dispatchEntryActorPacket(
+              'remote',
               relay.actorId,
               [header, body],
               relay.returnResponse === true,
@@ -430,6 +435,7 @@ export class ZLinkActorPacketRelay {
               fallbackActorRef
             )
           : await this.requireSpotManager().dispatchRoutedActorPacket(
+              'remote',
               state.spotId,
               relay.actorId,
               [header, body],
@@ -892,6 +898,7 @@ export class ZLinkActorPacketRelay {
       this.options.detachedTaskRunner.runDetached('local actor packet relay', async () => {
         try {
           const response = await this.requireSpotManager().dispatchRoutedActorPacket(
+            'local',
             spotId,
             actor.actorId,
             [header, body],

package/src/runtime/host/actor-runtime-options-factory.ts

@@ -276,16 +276,28 @@ export class ZLinkActorRuntimeOptionsFactory {
       staleActorRefPredicate: (meshName, actor) =>
         this.actorBelongsToMesh(meshName, actor.actorId) &&
         this.options.actorHandoff.isKnownStale(actor),
-      handoffCapture: (meshName, actorId, parts, returnResponse, actor, deadlineUnixMs) =>
+      handoffCapture: (
+        meshName,
+        actorId,
+        parts,
+        returnResponse,
+        actor,
+        deadlineUnixMs,
+        onAdmitted
+      ) =>
         this.actorBelongsToMesh(meshName, actorId) &&
         !this.options.actorHandoff.isProvisional(actorId)
           ? this.options.actorHandoff.capture(
+              'local',
               actorId,
               parts,
               returnResponse,
               undefined,
               actor,
-              deadlineUnixMs
+              deadlineUnixMs,
+              undefined,
+              undefined,
+              onAdmitted
             )
           : undefined,
       sendErrorReporter: this.options.reportPostCommitError