Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

## Unreleased

- Keep cause-free Error serialization on its terminal fast path with byte-identical v14 output; use a distinct v16 Error cause tag and capability negotiation with older IPC peers.

- Preserve Error cause graphs in structured cloning and worker messages, while retaining v14 bytes for cause-free values and negotiating cause support for advanced IPC with older Bun processes; thanks fuller-stack-dev.

- Sync oven-sh/bun through `ad4089bf49d9f4c3ab7c8d95a58f3e0f0f186054`, including lint, format, binding, WebSocket and SQL updates, while retaining the fork runtime and CI contracts.
Expand Down
2 changes: 1 addition & 1 deletion docs/guides/process/ipc.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ process.on("message", message => {

By default, Bun serializes messages with the JSC `serialize` API. This API supports everything [`structuredClone` supports](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), including strings, typed arrays, and objects. The API does not support transferring ownership of objects.

Advanced IPC preserves `Error.cause` once the peer has advertised support on that channel. Messages sent before that advertisement, or to an older Bun process, omit causes and retain the v14 format used by older builds. Cause-free messages always retain v14 bytes. This allows an already-running process to communicate with a child started from an updated Bun executable. In-process `structuredClone`, Worker, MessagePort, and BroadcastChannel messages preserve causes without IPC negotiation.
Advanced IPC preserves `Error.cause` once the peer has advertised v16 cause-format support on that channel. Messages sent before that advertisement, or to an older Bun process, omit causes and retain the v14 format used by older builds. The unreleased intermediate v15 capability does not enable v16 causes. Cause-free messages always retain v14 bytes. This allows an already-running process to communicate with a child started from an updated Bun executable. In-process `structuredClone`, Worker, MessagePort, and BroadcastChannel messages preserve causes without IPC negotiation.

```ts child.ts icon="/icons/typescript.svg"
// send a string
Expand Down
2 changes: 1 addition & 1 deletion docs/runtime/nodejs-compat.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -315,7 +315,7 @@ Destroying an HTTP/2 session releases its TLS transport without waiting for the

Map and Set serialization copies entries and ignores custom own properties, like `structuredClone`. Existing Bun records with own-property sections remain readable.

🟡 `writeHeapSnapshot`, `getHeapSnapshot`, `getHeapStatistics`, `getHeapSpaceStatistics`, `queryObjects`, `GCProfiler` and `startupSnapshot` are implemented. `queryObjects()` collects garbage and returns a count or shallow summaries of objects matching the constructor's prototype chain in the current context. The heap statistics describe JavaScriptCore's single heap, and `setFlagsFromString` ignores the flags it is given. `serialize` and `deserialize` use JavaScriptCore's wire format instead of V8's. Cause-free values retain the v14 format; Error cause graphs use v15, which older Bun builds cannot deserialize. These bytes are not interchangeable with Node.js serialization. Missing `startCpuProfile`, `startHeapProfile`, `Serializer`/`Deserializer`, `takeCoverage`/`stopCoverage` and `promiseHooks`. For profiling, use [`bun:jsc`](/project/benchmarking#javascript-heap-stats) instead.
🟡 `writeHeapSnapshot`, `getHeapSnapshot`, `getHeapStatistics`, `getHeapSpaceStatistics`, `queryObjects`, `GCProfiler` and `startupSnapshot` are implemented. `queryObjects()` collects garbage and returns a count or shallow summaries of objects matching the constructor's prototype chain in the current context. The heap statistics describe JavaScriptCore's single heap, and `setFlagsFromString` ignores the flags it is given. `serialize` and `deserialize` use JavaScriptCore's wire format instead of V8's. Cause-free values retain the v14 format; Error cause graphs use v16, which older Bun builds cannot deserialize. Readers reject v15, an unreleased intermediate format. These bytes are not interchangeable with Node.js serialization. Missing `startCpuProfile`, `startHeapProfile`, `Serializer`/`Deserializer`, `takeCoverage`/`stopCoverage` and `promiseHooks`. For profiling, use [`bun:jsc`](/project/benchmarking#javascript-heap-stats) instead.

### [`node:vm`](https://nodejs.org/api/vm.html)

Expand Down
169 changes: 79 additions & 90 deletions src/jsc/bindings/webcore/SerializedScriptValue.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,7 @@ enum SerializationTag {
DOMExceptionTag = 51,
ResizableArrayBufferTag = 54,
ErrorInstanceTag = 55,
ErrorInstanceWithCauseTag = 56,

Bun__BlobTag = 254,
// bun types start at 254 and decrease with each addition
Expand Down Expand Up @@ -417,11 +418,12 @@ const uint8_t cryptoKeyOKPOpNameTagMaximumValue = 1;
* Version 13. added support for ErrorInstance objects.
* Version 14. Date, RegExp, Error, DOMException, CryptoKey, KeyObject, X509Certificate,
* and Bun cloneable types are recorded in the object reference pool on both sides.
* Version 15. ErrorInstance records include an own data cause, traversed as part of the graph.
* Version 15. Unreleased intermediate format with inline Error cause-presence bytes; rejected.
* Version 16. A distinct ErrorInstanceWithCauseTag carries an own data cause.
*/
[[maybe_unused]] static constexpr unsigned CurrentVersion = 15;
[[maybe_unused]] static constexpr unsigned CurrentVersion = 16;
static constexpr unsigned DefaultVersion = 14;
static constexpr unsigned FirstVersionWithErrorCause = 15;
static constexpr unsigned FirstVersionWithErrorCause = 16;
// Deserializers must not pool the version 14 terminal types for older payloads,
// whose writers never counted them, or the pool indices stop matching the writer's.
[[maybe_unused]] static constexpr unsigned FirstVersionWithPooledTerminals = 14;
Expand Down Expand Up @@ -456,9 +458,9 @@ static constexpr unsigned StringDataIs8BitFlag = 0x80000000;
* MapData :- (<key:Value><value:Value>)* NonMapPropertiesTag (<name:StringData><value:Value>)* TerminatorTag
* SetData :- (<key:Value>)* NonSetPropertiesTag (<name:StringData><value:Value>)* TerminatorTag
*
* Error :- ErrorInstanceTag <type:uint8_t> <message:NullableString> <line:uint32_t> <column:uint32_t>
* <sourceURL:NullableString> <stack:NullableString> <hasCause:uint8_t> Value?
* (hasCause and its value are present only in version 15; version 14 is otherwise emitted.)
* Error :- ErrorInstanceWithCauseTag ErrorMetadata Value (version 16 only)
* ErrorMetadata :- <type:uint8_t> <message:NullableString> <line:uint32_t> <column:uint32_t>
* <sourceURL:NullableString> <stack:NullableString>
*
* Terminal :-
* UndefinedTag
Expand Down Expand Up @@ -486,6 +488,7 @@ static constexpr unsigned StringDataIs8BitFlag = 0x80000000;
* | ArrayBuffer
* | ArrayBufferViewTag ArrayBufferViewSubtag <byteOffset:uint64_t> <byteLength:uint64_t> (ArrayBuffer | ObjectReference)
* | CryptoKeyTag <wrappedKeyLength:uint32_t> <factor:byte{wrappedKeyLength}>
* | ErrorInstanceTag ErrorMetadata
* | DOMPoint
* | DOMRect
* | DOMMatrix
Expand Down Expand Up @@ -746,8 +749,6 @@ class CloneSerializer : public CloneBase {
if (serializer.m_failed)
code = SerializationReturnCode::UnspecifiedError;
}
if (code == SerializationReturnCode::SuccessfullyCompleted)
serializer.finishErrorCauseFormat();
serializedBlockListRefs = WTF::move(serializer.m_serializedBlockListRefs);
return code;
}
Expand Down Expand Up @@ -1130,29 +1131,38 @@ class CloneSerializer : public CloneBase {
code = SerializationReturnCode::DataCloneError;
}

JSValue dumpError(ErrorInstance* errorInstance)
JSValue errorCause(ErrorInstance* errorInstance)
{
auto& vm = m_lexicalGlobalObject->vm();
auto scope = DECLARE_THROW_SCOPE(vm);
JSValue cause;
bool hasCause = false;
// Snapshot and root before metadata getters/coercions can replace the cause or collect it.
// Worker error events retain their separate bounded, best-effort metadata owner.
bool supportsCause = m_context != SerializationContext::WorkerError && m_context != SerializationContext::LegacyIPC;
if (supportsCause) {
if (m_context == SerializationContext::WorkerError || m_context == SerializationContext::LegacyIPC)
return {};

// Unlike stack/line/column, cause has no lazy Error metadata slot.
unsigned attributes = 0;
JSValue cause = errorInstance->getDirect(vm, vm.propertyNames->cause, attributes);
if (errorInstance->classInfo() != ErrorInstance::info() || (attributes & PropertyAttribute::CustomAccessorOrValue)) [[unlikely]] {
JSC::PropertyDescriptor descriptor;
bool found = errorInstance->getOwnPropertyDescriptor(m_lexicalGlobalObject, vm.propertyNames->cause, descriptor);
RETURN_IF_EXCEPTION(scope, JSValue());
hasCause = found && descriptor.isDataDescriptor();
if (hasCause) {
cause = descriptor.value();
m_gcBuffer.appendWithCrashOnOverflow(cause);
}
}
cause = found && descriptor.isDataDescriptor() ? descriptor.value() : JSValue();
} else if (attributes & PropertyAttribute::Accessor)
return {};

// Root the own data value before any Error metadata can run user code.
if (cause)
m_gcBuffer.appendWithCrashOnOverflow(cause);
return cause;
}

bool dumpError(ErrorInstance* errorInstance, SerializationTag tag)
{
auto& vm = m_lexicalGlobalObject->vm();
auto scope = DECLARE_THROW_SCOPE(vm);
auto errorTypeValue = errorInstance->get(m_lexicalGlobalObject, vm.propertyNames->name);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
auto errorTypeString = errorTypeValue.toWTFString(m_lexicalGlobalObject);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);

// .message/.line/.column/.sourceURL: HTML spec + Node/WebKit read
// OWN data descriptors only (an inherited or accessor .message is
Expand All @@ -1167,62 +1177,57 @@ class CloneSerializer : public CloneBase {
// Symbol message from reaching ErrorInstance's lazy materialization.
JSC::PropertyDescriptor d;
bool found = errorInstance->getOwnPropertyDescriptor(m_lexicalGlobalObject, vm.propertyNames->message, d);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
if (found && d.isDataDescriptor() && d.value()) {
message = d.value().toWTFString(m_lexicalGlobalObject);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
}
}
// Trigger ErrorInstance's lazy materialization up front so a throwing
// prepareStackTrace propagates here instead of tripping the exception
// assertion inside JSObject::getOwnPropertyDescriptor.
errorInstance->materializeErrorInfoIfNeeded(vm);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
{
JSC::PropertyDescriptor d;
bool found = errorInstance->getOwnPropertyDescriptor(m_lexicalGlobalObject, vm.propertyNames->line, d);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
if (found && d.isDataDescriptor() && d.value().isNumber())
line = d.value().toNumber(m_lexicalGlobalObject);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
}
{
JSC::PropertyDescriptor d;
bool found = errorInstance->getOwnPropertyDescriptor(m_lexicalGlobalObject, vm.propertyNames->column, d);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
if (found && d.isDataDescriptor() && d.value().isNumber())
column = d.value().toNumber(m_lexicalGlobalObject);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
}
{
JSC::PropertyDescriptor d;
bool found = errorInstance->getOwnPropertyDescriptor(m_lexicalGlobalObject, vm.propertyNames->sourceURL, d);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
if (found && d.isDataDescriptor() && d.value().isString())
sourceURL = d.value().toWTFString(m_lexicalGlobalObject);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
}
{
JSValue v = errorInstance->get(m_lexicalGlobalObject, vm.propertyNames->stack);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
if (v.isString())
stack = v.toWTFString(m_lexicalGlobalObject);
RETURN_IF_EXCEPTION(scope, JSValue());
RETURN_IF_EXCEPTION(scope, false);
}

write(ErrorInstanceTag);
write(tag);
write(errorNameToSerializableErrorType(errorTypeString));
writeNullableString(message);
write(line);
write(column);
writeNullableString(sourceURL);
writeNullableString(stack);
if (supportsCause) {
m_errorCauseOffsets.append(m_buffer.size());
write(static_cast<uint8_t>(hasCause));
m_hasErrorCause |= hasCause;
}
return cause;
return true;
}

bool dumpIfTerminal(JSValue value, SerializationReturnCode& code)
Expand Down Expand Up @@ -1318,8 +1323,22 @@ class CloneSerializer : public CloneBase {
write(String(JSC::Yarr::flagsString(regExp->regExp()->flags()).span()));
return true;
}
if (obj->inherits<ErrorInstance>())
return false;
if (auto* error = dynamicDowncast<ErrorInstance>(obj)) {
if (m_pendingError == error)
return false;
if (!startObjectInternal(error))
return true;
JSValue cause = errorCause(error);
RETURN_IF_EXCEPTION(scope, false);
if (cause) {
m_pendingError = error;
m_pendingErrorCause = cause;
return false;
}
dumpError(error, ErrorInstanceTag);
RETURN_IF_EXCEPTION(scope, false);
return true;
}
if (obj->inherits<JSMessagePort>()) {
auto index = m_transferredMessagePorts.find(obj);
if (index != m_transferredMessagePorts.end()) {
Expand Down Expand Up @@ -1698,32 +1717,6 @@ class CloneSerializer : public CloneBase {
writeConstantPoolIndex(m_objectPool, i);
}

void finishErrorCauseFormat()
{
if (m_hasErrorCause) {
m_buffer[0] = CurrentVersion;
return;
}
size_t removed = 0;
for (auto& reference : m_objectReferences) {
while (removed < m_errorCauseOffsets.size() && m_errorCauseOffsets[removed] < reference.offset)
++removed;
reference.offset -= removed;
}
size_t readOffset = 0;
size_t writeOffset = 0;
for (auto offset : m_errorCauseOffsets) {
size_t length = offset - readOffset;
memmove(m_buffer.mutableSpan().data() + writeOffset, m_buffer.span().data() + readOffset, length);
writeOffset += length;
readOffset = offset + 1;
}
size_t length = m_buffer.size() - readOffset;
memmove(m_buffer.mutableSpan().data() + writeOffset, m_buffer.span().data() + readOffset, length);
m_buffer.shrink(writeOffset + length);
m_errorCauseOffsets.clear();
}

// Retain the v14 pre-scan's Buffer order and framing. Only cause-bearing
// graphs add identities discovered by the native walk.
bool finishBufferEnvelope()
Expand Down Expand Up @@ -1758,7 +1751,6 @@ class CloneSerializer : public CloneBase {
fail();
return false;
}
finishErrorCauseFormat();
Vector<uint8_t> valueBytes = WTF::move(m_buffer);
m_buffer = {};
write(m_hasErrorCause ? CurrentVersion : DefaultVersion);
Expand Down Expand Up @@ -2148,7 +2140,9 @@ class CloneSerializer : public CloneBase {
};
Vector<ObjectReference> m_objectReferences;
Vector<JSObject*> m_nodeBuffers;
Vector<size_t> m_errorCauseOffsets;
// The dispatcher can check a nonterminal Error twice before visiting its cause.
ErrorInstance* m_pendingError { nullptr };
JSValue m_pendingErrorCause;
bool m_hasErrorCause { false };
ObjectPool m_objectPool;
ObjectPool m_transferredMessagePorts;
Expand Down Expand Up @@ -2400,12 +2394,14 @@ SerializationReturnCode CloneSerializer::serialize(JSValue in)
if (inputObjectStack.size() > maximumFilterRecursion)
return SerializationReturnCode::StackOverflowError;
auto* error = uncheckedDowncast<ErrorInstance>(inValue);
if (!startObjectInternal(error))
break;
JSValue cause = dumpError(error);
ASSERT(m_pendingError == error);
JSValue cause = std::exchange(m_pendingErrorCause, JSValue());
m_pendingError = nullptr;
m_hasErrorCause = true;
m_buffer[0] = CurrentVersion;
dumpError(error, ErrorInstanceWithCauseTag);
RETURN_IF_EXCEPTION(scope, SerializationReturnCode::ExistingExceptionError);
if (!cause)
break;
ASSERT(cause);
// Keep the Error in the same pool before traversing its cause, including self references.
inputObjectStack.append(error);
inValue = cause;
Expand Down Expand Up @@ -2588,7 +2584,7 @@ class CloneDeserializer : public CloneBase {

DeserializationResult deserialize();

bool isValid() const { return m_version <= CurrentVersion; }
bool isValid() const { return m_version <= DefaultVersion || m_version == CurrentVersion; }

template<typename T> bool readLittleEndian(T& value)
{
Expand Down Expand Up @@ -3931,11 +3927,11 @@ class CloneDeserializer : public CloneBase {
addTerminalToObjectPool(obj);
return obj;
}
case ErrorInstanceTag:
if (m_version < FirstVersionWithErrorCause) {
auto* error = readError();
return error ? JSValue(error) : JSValue();
}
case ErrorInstanceTag: {
auto* error = readError();
return error ? JSValue(error) : JSValue();
}
case ErrorInstanceWithCauseTag:
m_ptr = preTagPtr;
return JSValue();
case ObjectReferenceTag: {
Expand Down Expand Up @@ -4352,13 +4348,6 @@ DeserializationResult CloneDeserializer::deserialize()
auto* error = readError();
if (scope.exception() || !error)
goto error;
uint8_t hasCause;
if (!read(hasCause) || hasCause > 1)
goto error;
if (!hasCause) {
outValue = error;
break;
}
outputObjectStack.append(error);
stateStack.append(ErrorEndVisitCause);
goto stateUnknown;
Expand Down Expand Up @@ -4393,7 +4382,7 @@ DeserializationResult CloneDeserializer::deserialize()
goto mapObjectStartState;
if (tag == SetObjectTag)
goto setObjectStartState;
if (tag == ErrorInstanceTag && m_version >= FirstVersionWithErrorCause)
if (tag == ErrorInstanceWithCauseTag && m_version >= FirstVersionWithErrorCause)
goto errorStartState;
goto error;
}
Expand Down
Loading
Loading