std/marshal

NAME

std/marshal - Serialize and deserialize ZuzuScript values.

SYNOPSIS

  from std/marshal import dump, load, safe_to_dump;

  let original := {
      name: "Ada",
      tags: [ "compiler", "runtime" ],
  };

  let blob := dump(original);
  let copy := load(blob);

  if ( safe_to_dump(original) ) {
      // Store blob, send it to another trusted worker, etc.
  }

IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and Electron. It is partially supported by zuzu-js in the browser: general marshal round-trip coverage passes, but Path round-trip and safe_to_dump coverage for paths is unsupported.

DESCRIPTION

std/marshal exposes the Zuzu Marshal CBOR v1 format. It serializes supported ZuzuScript values to a compact BinaryString and loads that binary representation back into live values. It is intended for trusted persistence, worker/process handoff, RPC between cooperating Zuzu runtimes, and implementation interoperability tests.

Security warning: load is not safe for untrusted blobs in version 1 of the format. Loading may evaluate embedded ZuzuScript code records to reconstruct functions, classes, and traits, and it may run user __on_load__ hooks. Treat a marshal blob from an untrusted source as untrusted code. For untrusted data interchange, prefer a data-only format such as std/data/json, std/data/cbor, or std/data/yaml with your own validation.

EXPORTS

Functions

dump(value)
Parameters: value is any value. Returns: BinaryString. Serializes value to a Zuzu Marshal CBOR v1 blob.
load(BinaryString blob)
Parameters: blob is a Zuzu Marshal CBOR v1 blob. Returns: value. Loads and reconstructs the marshalled value.
safe_to_dump(value)
Parameters: value is any value. Returns: Boolean. Returns true when value can currently be marshalled.

Supported Values

The implementation currently supports:

Scalar values: null, Booleans, finite Numbers, Strings, and
BinaryStrings.
Collections and structured values: Pairs, Arrays, Dicts,
PairLists, Sets, Bags, Times, and Paths.
User-defined functions, classes, and traits when their source
and dependencies can be reconstructed. Captured values must be marshalable scalar constants; internal function/class/trait dependencies must be suitable const bindings.
User objects whose class and slot values are marshalable.
Bound methods whose receiver and method identity can be
reconstructed.

Shared object identity is preserved for non-scalar values. Cyclic graphs are supported where every value in the cycle is otherwise marshalable. Scalars are loaded as ordinary scalar values rather than identity-preserving references.

Lifecycle Hooks

If an object defines __on_dump__, the hook is called before its slots are encoded. If it defines __on_load__, the hook is called after the object graph has been reconstructed. __build__ is not called during load.

Hook failures are wrapped as MarshallingException during dump and UnmarshallingException during load.

Common Failure Modes

dump can throw MarshallingException for values that cannot be represented, including native functions, regular expressions, file or database handles, unsupported runtime-backed objects, non-finite numbers, non-scalar function captures, non-const code dependencies, or errors from __on_dump__.

load can throw UnmarshallingException for invalid CBOR, a wrong envelope, an unsupported version, invalid object or code references, duplicate Dict keys, duplicate object slot names, unsupported object kinds, malformed code records, errors from __on_load__, and malformed or misplaced weak storage records.

Weak Storage Records

Zuzu Marshal CBOR v1 uses weak storage records to preserve weak object slots and weak collection entries. A loader must not silently load a weak storage record as a strong reference, because that would change the graph semantics. Weak records in forbidden positions, or nested inside other weak records, are rejected with UnmarshallingException.

COPYRIGHT AND LICENCE

std/marshal is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.

Module