@zlink-systems/framework 0.10.0

package/src/runtime/streams/native-fallback-bound-session.ts

@@ -0,0 +1,321 @@
+import {
+  createInternalFrameworkException,
+  ZLinkFrameworkInternalErrorKind
+} from '../framework-errors-internal';
+import type { ActorRef, ZLinkBoundSession, ZLinkBoundSessionSendCall } from '../../contracts';
+import { ZLinkSpotKind } from '../../contracts';
+import {
+  requireOneWayCompletion,
+  throwAlreadySubmitted,
+  ZLinkSubmitStatus,
+  type ZLinkSubmitResult
+} from '../messaging/submission-result';
+import {
+  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
+  ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
+  ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET,
+  type ZLinkActorRoutedJoinTransport,
+  type ZLinkRemoteActorPacketTarget,
+  type ZLinkRemoteBoundSessionTarget
+} from '../actors';
+import {
+  encodeRemoteActorPacketRelayPayload,
+  encodeRemoteActorPacketTarget
+} from '../actors/actor-packet-relay-wire';
+import { encodeRemoteBoundSessionSendPayload } from '../actors/bound-session-wire';
+import { tryRequestRoutedJson } from '../actors/actor-routed-json-request';
+import {
+  ZLinkStreamCodec,
+  ZLinkStreamHeaderFlags,
+  ZLinkStreamMessageKind,
+  encodeStreamHeader,
+  type ZLinkStreamFrameHeader
+} from './protocol';
+import type { ZLinkNativeFallbackBoundSessionPort } from './stream-binding-runtime-ports';
+import { throwIfAborted } from '../abort';
+import type { ZLinkBackendActorSessionNode } from '../backend';
+import { resolveFrameworkPacketName } from '../messaging/packet-name';
+import { currentOrCreateFlow, runWithOutboundFlow } from '../diagnostics/flow-context';
+
+export interface ZLinkNativeFallbackBoundSessionOptions {
+  readonly runtime: ZLinkNativeFallbackBoundSessionPort;
+  readonly routedTransport: ZLinkActorRoutedJoinTransport;
+  readonly actorRefProvider: () => ActorRef | undefined;
+  readonly nativeActorNodeProvider: () => ZLinkBackendActorSessionNode | undefined;
+  readonly localActorProvider?: () => boolean;
+  readonly remoteBoundSessionTargetProvider: () => ZLinkRemoteBoundSessionTarget | undefined;
+  readonly remoteActorPacketTargetProvider: () => ZLinkRemoteActorPacketTarget | undefined;
+  readonly requestTimeoutMs?: number;
+  readonly actorId: string;
+  readonly onSend?: (actorId: string, packetName: string) => void;
+  readonly reportError: (error: unknown) => void;
+  readonly flowCreationEnabled?: () => boolean;
+}
+
+export class ZLinkNativeFallbackBoundSession implements ZLinkBoundSession {
+  constructor(private readonly options: ZLinkNativeFallbackBoundSessionOptions) {}
+
+  send(message: unknown): ZLinkBoundSessionSendCall {
+    return new ZLinkNativeFallbackBoundSessionSendCall(this.options, message);
+  }
+
+  async disconnect(signal?: AbortSignal): Promise<void> {
+    const remoteTarget = this.options.remoteBoundSessionTargetProvider();
+    if (remoteTarget !== undefined) {
+      const spotKind: ZLinkSpotKind | undefined =
+        'spotKind' in remoteTarget ? remoteTarget.spotKind as ZLinkSpotKind | undefined : undefined;
+      const payload = encodeRemoteActorPacketRelayPayload({
+        actorId: this.options.actorId,
+        routerChannelId: remoteTarget.routerChannelId,
+        header: encodeStreamHeader(disconnectedFrameHeader()),
+        payload: Buffer.alloc(0)
+      });
+      const target = {
+        routerChannelId: remoteTarget.routerChannelId,
+        targetNodeRid: remoteTarget.targetNodeRid,
+        spotId: remoteTarget.spotId,
+        spotKind: spotKind ?? ZLinkSpotKind.Entry
+      };
+      if (await tryRequestRoutedJson(
+        this.options.routedTransport,
+        target,
+        payload,
+        { timeoutMs: this.options.requestTimeoutMs, signal }
+      )) {
+        return;
+      }
+      await this.options.routedTransport.sendToSpot(
+        target,
+        payload,
+        { packetName: ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, signal }
+      );
+      return;
+    }
+    const actorRef = this.options.actorRefProvider();
+    const node = this.options.nativeActorNodeProvider();
+    if (
+      actorRef !== undefined
+      && node !== undefined
+      && currentBindingGeneration(actorRef) !== undefined
+    ) {
+      await this.options.runtime.disconnectNativeBoundSession(node, actorRef, signal);
+      return;
+    }
+    await this.options.runtime.disconnectBoundSession(this.options.actorId, signal);
+  }
+}
+
+class ZLinkNativeFallbackBoundSessionSendCall implements ZLinkBoundSessionSendCall {
+  private selectedPacketName: string | undefined;
+  private readonly selectedMetadata = new Map<string, string>();
+  private executed = false;
+
+  constructor(
+    private readonly options: ZLinkNativeFallbackBoundSessionOptions,
+    private readonly message: unknown
+  ) {}
+
+  metadata(key: string, value: string): this {
+    this.selectedMetadata.set(key, value);
+    return this;
+  }
+
+  packetName(packetName: string): this {
+    this.selectedPacketName = packetName;
+    return this;
+  }
+
+  async submit(signal?: AbortSignal): Promise<void> {
+    if (this.executed) {
+      throwAlreadySubmitted('Bound session send call');
+    }
+    const packetName = resolveFrameworkPacketName(this.message, this.selectedPacketName, 'Bound session');
+    this.executed = true;
+    throwIfAborted(signal);
+    const result = await this.execute(packetName, signal);
+    requireOneWayCompletion(
+      result,
+      'Bound session send',
+      ZLinkFrameworkInternalErrorKind.ActorSessionNotBound
+    );
+  }
+
+  private execute(packetName: string, signal?: AbortSignal): Promise<ZLinkSubmitResult> {
+    // Call-scoped flow (spec 27 §4): the relay JSON flow pair and any nested
+    // routed-transport envelope share one ambient flow that does not outlive
+    // this submit call.
+    return runWithOutboundFlow(
+      this.options.flowCreationEnabled?.() ?? true,
+      () => this.executeScoped(packetName, signal)
+    );
+  }
+
+  private async executeScoped(packetName: string, signal?: AbortSignal): Promise<ZLinkSubmitResult> {
+    const localActor = this.options.localActorProvider?.() === true;
+    const remoteTarget = this.options.remoteBoundSessionTargetProvider();
+    const sealedRemoteTarget = remoteTarget?.relocationSealId !== undefined;
+    let nativeAttempted = false;
+    if (localActor && !sealedRemoteTarget) {
+      const result = await this.options.runtime.submitLocalBoundSession(
+        this.options.actorId,
+        this.message,
+        packetName,
+        this.selectedMetadata,
+        signal
+      );
+      if (result.status !== ZLinkSubmitStatus.TargetNotFound) {
+        this.traceSubmitted(result, packetName);
+        return result;
+      }
+
+      // A local Actor with a concrete native owner has a direct binding path.
+      // Use that path before a routed transfer target. The transfer target is
+      // retained for actors whose current owner is remote or whose native
+      // binding is no longer available.
+      const actorRef = this.options.actorRefProvider();
+      const node = this.options.nativeActorNodeProvider();
+      const bindingGeneration = currentBindingGeneration(actorRef);
+      if (
+        actorRef !== undefined
+        && node !== undefined
+        && bindingGeneration !== undefined
+      ) {
+        nativeAttempted = true;
+        const result = await this.options.runtime.sendNativeBoundSession(
+          node,
+          actorRef,
+          this.message,
+          packetName,
+          this.selectedMetadata,
+          signal
+        );
+        if (result.status !== ZLinkSubmitStatus.TargetNotFound) {
+          this.traceSubmitted(result, packetName);
+          return result;
+        }
+        if (remoteTarget === undefined) {
+          return result;
+        }
+      }
+    }
+    if (remoteTarget !== undefined) {
+      const actorRef = this.options.actorRefProvider();
+      const ownershipGeneration = (actorRef as (ActorRef & { ownershipGeneration?: bigint }) | undefined)
+        ?.ownershipGeneration;
+      const payload = encodeRemoteBoundSessionSendPayload({
+        actorId: this.options.actorId,
+        actorMeshName: actorRef?.meshName,
+        actorNodeRid: actorRef === undefined ? undefined : String(actorRef.nodeRid),
+        actorNodeRidHex: (actorRef?.nodeRid as { toHex?: () => string } | undefined)?.toHex?.(),
+        actorGeneration: actorRef?.objectGeneration.toString(),
+        actorOwnershipGeneration: ownershipGeneration?.toString(),
+        relocationSealId: remoteTarget.relocationSealId,
+        message: this.message,
+        boundPacketName: packetName,
+        metadata: this.selectedMetadata,
+        actorPacketTarget: encodeRemoteActorPacketTarget(
+          this.options.remoteActorPacketTargetProvider()
+        ),
+        ...((this.options.flowCreationEnabled?.() ?? true)
+          ? currentOrCreateFlow('Application')
+          : undefined)
+      });
+      const submit = this.options.routedTransport.submitInfrastructure
+        ?? this.options.routedTransport.submit;
+      const result = submit === undefined
+        ? await this.options.routedTransport.sendToSpot(
+            {
+              routerChannelId: remoteTarget.routerChannelId,
+              targetNodeRid: remoteTarget.targetNodeRid,
+              spotId: remoteTarget.spotId,
+              spotKind: ZLinkSpotKind.Entry
+            },
+            payload,
+            { packetName: ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET, signal }
+          )
+        : await submit.call(
+            this.options.routedTransport,
+            remoteTarget.routerChannelId,
+            String(remoteTarget.targetNodeRid),
+            ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET,
+            payload,
+            signal
+          );
+      this.traceSubmitted(result, packetName);
+      return result;
+    }
+    const localResult = await this.options.runtime.submitLocalBoundSession(
+      this.options.actorId,
+      this.message,
+      packetName,
+      this.selectedMetadata,
+      signal
+    );
+    if (localResult.status !== ZLinkSubmitStatus.TargetNotFound) {
+      this.traceSubmitted(localResult, packetName);
+      return localResult;
+    }
+    const actorRef = this.options.actorRefProvider();
+    const node = this.options.nativeActorNodeProvider();
+    const bindingGeneration = currentBindingGeneration(actorRef);
+    if (
+      !nativeAttempted
+      && actorRef !== undefined
+      && node !== undefined
+      && bindingGeneration !== undefined
+    ) {
+      const result = await this.options.runtime.sendNativeBoundSession(
+        node,
+        actorRef,
+        this.message,
+        packetName,
+        this.selectedMetadata,
+        signal
+      );
+      this.traceSubmitted(result, packetName);
+      return result;
+    }
+    if (localActor) {
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.ActorSessionNotBound,
+        `No current session binding exists for actor '${this.options.actorId}'.`,
+        true
+      );
+    }
+    const result = await this.options.runtime.sendBoundSession(
+      this.options.actorId,
+      this.message,
+      packetName,
+      this.selectedMetadata,
+      signal
+    );
+    this.traceSubmitted(result, packetName);
+    return result;
+  }
+
+  private traceSubmitted(result: ZLinkSubmitResult, packetName: string): void {
+    if (result.status === ZLinkSubmitStatus.Submitted) {
+      this.options.onSend?.(this.options.actorId, packetName);
+    }
+  }
+}
+
+function currentBindingGeneration(actorRef: ActorRef | undefined): bigint | undefined {
+  const generation = (actorRef as (ActorRef & { readonly bindingGeneration?: bigint }) | undefined)
+    ?.bindingGeneration;
+  return positiveBindingGeneration(generation);
+}
+
+function positiveBindingGeneration(generation: bigint | undefined): bigint | undefined {
+  return generation !== undefined && generation > 0n ? generation : undefined;
+}
+
+function disconnectedFrameHeader(): ZLinkStreamFrameHeader {
+  return {
+    kind: ZLinkStreamMessageKind.Send,
+    codec: ZLinkStreamCodec.Raw,
+    flags: ZLinkStreamHeaderFlags.None,
+    name: ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
+    metadata: new Map()
+  };
+}

package/src/runtime/streams/protocol.ts

@@ -0,0 +1,291 @@
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkFlowOrigin } from '../../contracts';
+import { resolveFrameworkPacketName } from '../messaging/packet-name';
+import {
+  decodeStreamWireFrame,
+  decodeStreamWireHeader,
+  encodeStreamWireFrame,
+  encodeStreamWireHeader,
+  lz4PickleUncompressed,
+  lz4UnpicklePayload,
+  tryDecodeStreamWireFrame,
+  utf8Encode
+} from '@zlink-systems/stream-wire';
+import { throwAlreadySubmitted } from '../messaging/submission-result';
+
+export { utf8Decode, utf8Encode } from '@zlink-systems/stream-wire';
+
+const defaultMaxDecompressedPayloadSize = 64 * 1024;
+const actorRequestDeadlineMetadataKey = '$zlink.actor-request-deadline-unix-ms';
+//  Shared empty metadata for the dominant no-metadata frame; ReadonlyMap
+//  keeps every consumer from mutating it.
+const EMPTY_STREAM_METADATA: ReadonlyMap<string, string> = new Map();
+
+export enum ZLinkStreamCodec {
+  Raw = 0,
+  Json = 1,
+  MessagePack = 2,
+  Protobuf = 3
+}
+
+export function streamCodecContentType(codec: ZLinkStreamCodec): string {
+  switch (codec) {
+    case ZLinkStreamCodec.Json: return 'application/json';
+    case ZLinkStreamCodec.MessagePack: return 'application/x-msgpack';
+    case ZLinkStreamCodec.Protobuf: return 'application/x-protobuf';
+    case ZLinkStreamCodec.Raw: return 'application/octet-stream';
+  }
+  throw new TypeError(`Unsupported STREAM codec '${codec}'.`);
+}
+
+export function streamCodecForContentType(contentType: string): ZLinkStreamCodec {
+  switch (contentType) {
+    case 'application/json': return ZLinkStreamCodec.Json;
+    case 'application/x-msgpack': return ZLinkStreamCodec.MessagePack;
+    case 'application/x-protobuf': return ZLinkStreamCodec.Protobuf;
+    case 'application/octet-stream': return ZLinkStreamCodec.Raw;
+  }
+  throw new TypeError(`Unsupported STREAM content type '${contentType}'.`);
+}
+
+export enum ZLinkStreamMessageKind {
+  Send = 1,
+  Request = 2,
+  Response = 3,
+  Error = 4,
+  Control = 5
+}
+
+export enum ZLinkStreamHeaderFlags {
+  None = 0,
+  HasRequestSeq = 0x01,
+  HasMetadata = 0x02,
+  PayloadCompressed = 0x04,
+  HasCorrelationId = 0x08,
+  HasFlowId = 0x10
+}
+
+export enum ZLinkStreamCloseReasonCode {
+  ClientClose = 1,
+  IdleTimeout = 2,
+  HeartbeatTimeout = 3,
+  ServerDrain = 4,
+  ProtocolError = 5,
+  TransportError = 6
+}
+
+export const ZLINK_STREAM_HEARTBEAT_PING = '$zlink.heartbeat.ping';
+export const ZLINK_STREAM_HEARTBEAT_PONG = '$zlink.heartbeat.pong';
+
+export interface ZLinkStreamFrameHeader {
+  readonly kind: ZLinkStreamMessageKind;
+  readonly codec: ZLinkStreamCodec;
+  readonly flags: ZLinkStreamHeaderFlags;
+  readonly requestSeq?: bigint;
+  readonly name: string;
+  readonly metadata: ReadonlyMap<string, string>;
+  readonly correlationId?: string;
+  readonly flowId?: string;
+  readonly flowOrigin?: ZLinkFlowOrigin;
+}
+
+export type ZLinkStreamReplyMessageKind =
+  | ZLinkStreamMessageKind.Response
+  | ZLinkStreamMessageKind.Error;
+
+export interface ZLinkStreamFrame {
+  readonly header: Uint8Array;
+  readonly payload: Uint8Array;
+}
+
+export function resolvePacketName(message: unknown, explicitPacketName: string | undefined): string {
+  const packetName = resolveFrameworkPacketName(message, explicitPacketName, 'Stream');
+  if (packetName.trim().length === 0) {
+    throw new Error('Stream packet name must not be empty.');
+  }
+  return packetName;
+}
+
+export function ensureSingleSubmit(executed: boolean): void {
+  if (executed) {
+    throwAlreadySubmitted('Stream send call');
+  }
+}
+
+export function encodeStreamFrame(header: ZLinkStreamFrameHeader, payload: Uint8Array): Uint8Array {
+  return encodeStreamWireFrame(encodeStreamHeader(header), payload);
+}
+
+export function encodeStreamControlFrame(name: string): Uint8Array {
+  return encodeStreamFrame({
+    kind: ZLinkStreamMessageKind.Control,
+    codec: ZLinkStreamCodec.Raw,
+    flags: ZLinkStreamHeaderFlags.None,
+    name,
+    metadata: EMPTY_STREAM_METADATA
+  }, new Uint8Array());
+}
+
+export function encodeSessionClosingFrame(
+  diagnostic = '',
+  reason = ZLinkStreamCloseReasonCode.ServerDrain
+): Uint8Array {
+  const diagnosticBytes = utf8Encode(diagnostic);
+  if (diagnosticBytes.length > 512) throw new Error('Session-closing diagnostic is too large.');
+  const payload = new Uint8Array(4 + diagnosticBytes.length);
+  payload[0] = 1;
+  payload[1] = reason;
+  payload[2] = diagnosticBytes.length >>> 8;
+  payload[3] = diagnosticBytes.length & 0xff;
+  payload.set(diagnosticBytes, 4);
+  return encodeStreamFrame({
+    kind: ZLinkStreamMessageKind.Control,
+    codec: ZLinkStreamCodec.Raw,
+    flags: ZLinkStreamHeaderFlags.None,
+    name: 'session-closing',
+    metadata: new Map()
+  }, payload);
+}
+
+export function decodeStreamFrame(frame: Uint8Array): ZLinkStreamFrame {
+  return decodeStreamWireFrame(frame);
+}
+
+export function tryDecodeStreamFrame(frame: Uint8Array): ZLinkStreamFrame | undefined {
+  return tryDecodeStreamWireFrame(frame);
+}
+
+export function encodeStreamHeader(header: ZLinkStreamFrameHeader): Uint8Array {
+  const hasRequestSeq = header.requestSeq !== undefined;
+  const hasMetadata = header.metadata.size > 0;
+  const hasCorrelation = header.correlationId !== undefined && header.correlationId.length > 0;
+  const hasFlow = header.flowId !== undefined || header.flowOrigin !== undefined;
+  if (header.kind === ZLinkStreamMessageKind.Control && (hasCorrelation || hasRequestSeq || hasMetadata || hasFlow)) {
+    throw new Error('Control packet must not contain a request sequence, metadata, correlation id, or flow id.');
+  }
+  //  Explicit construction: this runs for every outbound frame, so avoid a
+  //  per-message spread of the whole header.
+  return encodeStreamWireHeader({
+    kind: header.kind,
+    codec: header.codec,
+    flags: header.flags,
+    requestSeq: header.requestSeq,
+    name: header.name,
+    metadata: header.metadata,
+    correlationId: header.correlationId,
+    flowId: header.flowId,
+    flowOrigin: encodeFlowOrigin(header.flowOrigin)
+  });
+}
+
+export function decodeStreamHeader(
+  header: Uint8Array,
+  flowEnabled = true
+): ZLinkStreamFrameHeader {
+  const decoded = decodeStreamWireHeader(header, undefined, flowEnabled);
+  const kind = decoded.kind as ZLinkStreamMessageKind;
+  const flags = decoded.flags as ZLinkStreamHeaderFlags;
+  const hasRequestSeq = (flags & ZLinkStreamHeaderFlags.HasRequestSeq) !== 0;
+  const hasMetadata = (flags & ZLinkStreamHeaderFlags.HasMetadata) !== 0;
+  const hasCorrelation = (flags & ZLinkStreamHeaderFlags.HasCorrelationId) !== 0;
+  const hasFlow = (flags & ZLinkStreamHeaderFlags.HasFlowId) !== 0;
+  if (kind === ZLinkStreamMessageKind.Control && (hasCorrelation || hasRequestSeq || hasMetadata || hasFlow)) {
+    throw new Error('Control packet must not contain a request sequence, metadata, correlation id, or flow id.');
+  }
+  const metadata = publicStreamMetadata(decoded.metadata);
+  return {
+    kind,
+    codec: decoded.codec as ZLinkStreamCodec,
+    flags: (metadata.size === 0
+      ? flags & ~ZLinkStreamHeaderFlags.HasMetadata
+      : flags) & (flowEnabled ? ~0 : ~ZLinkStreamHeaderFlags.HasFlowId),
+    requestSeq: decoded.requestSeq,
+    name: decoded.name,
+    metadata,
+    correlationId: decoded.correlationId,
+    flowId: decoded.flowId,
+    flowOrigin: decodeFlowOrigin(decoded.flowOrigin)
+  };
+}
+
+export function actorRequestDeadlineMetadata(deadlineUnixMs: number | undefined): ReadonlyMap<string, string> {
+  return deadlineUnixMs === undefined
+    ? EMPTY_STREAM_METADATA
+    : new Map([[actorRequestDeadlineMetadataKey, String(deadlineUnixMs)]]);
+}
+
+export function decodeActorRequestDeadlineUnixMs(header: Uint8Array): number | undefined {
+  const value = decodeStreamWireHeader(header).metadata.get(actorRequestDeadlineMetadataKey);
+  if (value === undefined) return undefined;
+  const deadline = Number(value);
+  return Number.isSafeInteger(deadline) && deadline > 0 ? deadline : undefined;
+}
+
+function publicStreamMetadata(metadata: ReadonlyMap<string, string>): ReadonlyMap<string, string> {
+  if (!metadata.has(actorRequestDeadlineMetadataKey)) return metadata;
+  const visible = new Map(metadata);
+  visible.delete(actorRequestDeadlineMetadataKey);
+  return visible;
+}
+
+export function createStreamReplyHeader(
+  requestHeader: ZLinkStreamFrameHeader,
+  kind: ZLinkStreamReplyMessageKind,
+  codec: ZLinkStreamCodec,
+  flags: ZLinkStreamHeaderFlags,
+  metadata: ReadonlyMap<string, string>,
+  includeFlow = true
+): ZLinkStreamFrameHeader {
+  if (requestHeader.requestSeq === undefined) {
+    throw new Error('Stream reply requires a request sequence.');
+  }
+  return {
+    kind,
+    codec,
+    flags,
+    requestSeq: requestHeader.requestSeq,
+    name: '',
+    metadata,
+    // correlation_id survives every diagnostics level; the flow pair is
+    // observation-only and is not copied into the reply when tracing is Off
+    // (spec 27 §4, §7).
+    correlationId: requestHeader.correlationId,
+    ...(includeFlow
+      ? { flowId: requestHeader.flowId, flowOrigin: requestHeader.flowOrigin }
+      : {})
+  };
+}
+
+function encodeFlowOrigin(origin: ZLinkFlowOrigin | undefined): number | undefined {
+  return origin === undefined ? undefined : ({ Inbound: 1, Timer: 2, Application: 3, Lifecycle: 4 } as const)[origin];
+}
+
+function decodeFlowOrigin(origin: number | undefined): ZLinkFlowOrigin | undefined {
+  return origin === undefined ? undefined : ({ 1: 'Inbound', 2: 'Timer', 3: 'Application', 4: 'Lifecycle' } as const)[origin];
+}
+
+export function messageToBytes(message: Message): Uint8Array {
+  const value = message as unknown as {
+    data?: () => Uint8Array;
+    bytes?: Uint8Array;
+    toBytes?: () => Uint8Array;
+  };
+  if (value.data !== undefined) {
+    return value.data();
+  }
+  if (value.bytes !== undefined) {
+    return value.bytes;
+  }
+  if (value.toBytes !== undefined) {
+    return value.toBytes();
+  }
+  throw new Error('Stream payload cannot be copied for relay.');
+}
+
+export function lz4Pickle(payload: Uint8Array): Uint8Array {
+  return lz4PickleUncompressed(payload);
+}
+
+export function lz4Unpickle(payload: Uint8Array, maxDecompressedSize = defaultMaxDecompressedPayloadSize): Uint8Array {
+  return lz4UnpicklePayload(payload, maxDecompressedSize);
+}