/src/node/deps/v8/include/v8-value-serializer.h

Source (jump to first uncovered line)
// Copyright 2021 the V8 project authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef INCLUDE_V8_VALUE_SERIALIZER_H_
#define INCLUDE_V8_VALUE_SERIALIZER_H_

#include <stddef.h>
#include <stdint.h>

#include <memory>
#include <utility>

#include "v8-local-handle.h"  // NOLINT(build/include_directory)
#include "v8-maybe.h"         // NOLINT(build/include_directory)
#include "v8config.h"         // NOLINT(build/include_directory)

namespace v8 {

class ArrayBuffer;
class Isolate;
class Object;
class SharedArrayBuffer;
class String;
class WasmModuleObject;
class Value;

namespace internal {
struct ScriptStreamingData;
class SharedObjectConveyorHandles;
class ValueDeserializer;
class ValueSerializer;
}  // namespace internal

/**
 * A move-only class for managing the lifetime of shared value conveyors used
 * by V8 to keep JS shared values alive in transit when serialized.
 *
 * This class is not directly constructible and is always passed to a
 * ValueSerializer::Delegate via ValueSerializer::SetSharedValueConveyor.
 *
 * The embedder must not destruct the SharedValueConveyor until the associated
 * serialized data will no longer be deserialized.
 */
class V8_EXPORT SharedValueConveyor final {
 public:
  SharedValueConveyor(SharedValueConveyor&&) noexcept;
  ~SharedValueConveyor();

  SharedValueConveyor& operator=(SharedValueConveyor&&) noexcept;

 private:
  friend class internal::ValueSerializer;
  friend class internal::ValueDeserializer;

  explicit SharedValueConveyor(Isolate* isolate);

  std::unique_ptr<internal::SharedObjectConveyorHandles> private_;
};

/**
 * Value serialization compatible with the HTML structured clone algorithm.
 * The format is backward-compatible (i.e. safe to store to disk).
 */
class V8_EXPORT ValueSerializer {
 public:
  class V8_EXPORT Delegate {
   public:
    virtual ~Delegate() = default;

    /**
     * Handles the case where a DataCloneError would be thrown in the structured
     * clone spec. Other V8 embedders may throw some other appropriate exception
     * type.
     */
    virtual void ThrowDataCloneError(Local<String> message) = 0;

    /**
     * The embedder overrides this method to enable custom host object filter
     * with Delegate::IsHostObject.
     *
     * This method is called at most once per serializer.
     */
    virtual bool HasCustomHostObject(Isolate* isolate);

    /**
     * The embedder overrides this method to determine if an JS object is a
     * host object and needs to be serialized by the host.
     */
    virtual Maybe<bool> IsHostObject(Isolate* isolate, Local<Object> object);

    /**
     * The embedder overrides this method to write some kind of host object, if
     * possible. If not, a suitable exception should be thrown and
     * Nothing<bool>() returned.
     */
    virtual Maybe<bool> WriteHostObject(Isolate* isolate, Local<Object> object);

    /**
     * Called when the ValueSerializer is going to serialize a
     * SharedArrayBuffer object. The embedder must return an ID for the
     * object, using the same ID if this SharedArrayBuffer has already been
     * serialized in this buffer. When deserializing, this ID will be passed to
     * ValueDeserializer::GetSharedArrayBufferFromId as |clone_id|.
     *
     * If the object cannot be serialized, an
     * exception should be thrown and Nothing<uint32_t>() returned.
     */
    virtual Maybe<uint32_t> GetSharedArrayBufferId(
        Isolate* isolate, Local<SharedArrayBuffer> shared_array_buffer);

    virtual Maybe<uint32_t> GetWasmModuleTransferId(
        Isolate* isolate, Local<WasmModuleObject> module);

    /**
     * Called when the first shared value is serialized. All subsequent shared
     * values will use the same conveyor.
     *
     * The embedder must ensure the lifetime of the conveyor matches the
     * lifetime of the serialized data.
     *
     * If the embedder supports serializing shared values, this method should
     * return true. Otherwise the embedder should throw an exception and return
     * false.
     *
     * This method is called at most once per serializer.
     */
    virtual bool AdoptSharedValueConveyor(Isolate* isolate,
                                          SharedValueConveyor&& conveyor);

    /**
     * Allocates memory for the buffer of at least the size provided. The actual
     * size (which may be greater or equal) is written to |actual_size|. If no
     * buffer has been allocated yet, nullptr will be provided.
     *
     * If the memory cannot be allocated, nullptr should be returned.
     * |actual_size| will be ignored. It is assumed that |old_buffer| is still
     * valid in this case and has not been modified.
     *
     * The default implementation uses the stdlib's `realloc()` function.
     */
    virtual void* ReallocateBufferMemory(void* old_buffer, size_t size,
                                         size_t* actual_size);

    /**
     * Frees a buffer allocated with |ReallocateBufferMemory|.
     *
     * The default implementation uses the stdlib's `free()` function.
     */
    virtual void FreeBufferMemory(void* buffer);
  };

  explicit ValueSerializer(Isolate* isolate);
  ValueSerializer(Isolate* isolate, Delegate* delegate);
  ~ValueSerializer();

  /**
   * Writes out a header, which includes the format version.
   */
  void WriteHeader();

  /**
   * Serializes a JavaScript value into the buffer.
   */
  V8_WARN_UNUSED_RESULT Maybe<bool> WriteValue(Local<Context> context,
                                               Local<Value> value);

  /**
   * Returns the stored data (allocated using the delegate's
   * ReallocateBufferMemory) and its size. This serializer should not be used
   * once the buffer is released. The contents are undefined if a previous write
   * has failed. Ownership of the buffer is transferred to the caller.
   */
  V8_WARN_UNUSED_RESULT std::pair<uint8_t*, size_t> Release();

  /**
   * Marks an ArrayBuffer as havings its contents transferred out of band.
   * Pass the corresponding ArrayBuffer in the deserializing context to
   * ValueDeserializer::TransferArrayBuffer.
   */
  void TransferArrayBuffer(uint32_t transfer_id,
                           Local<ArrayBuffer> array_buffer);

  /**
   * Indicate whether to treat ArrayBufferView objects as host objects,
   * i.e. pass them to Delegate::WriteHostObject. This should not be
   * called when no Delegate was passed.
   *
   * The default is not to treat ArrayBufferViews as host objects.
   */
  void SetTreatArrayBufferViewsAsHostObjects(bool mode);

  /**
   * Write raw data in various common formats to the buffer.
   * Note that integer types are written in base-128 varint format, not with a
   * binary copy. For use during an override of Delegate::WriteHostObject.
   */
  void WriteUint32(uint32_t value);
  void WriteUint64(uint64_t value);
  void WriteDouble(double value);
  void WriteRawBytes(const void* source, size_t length);

  ValueSerializer(const ValueSerializer&) = delete;
  void operator=(const ValueSerializer&) = delete;

 private:
  struct PrivateData;
  PrivateData* private_;
};

/**
 * Deserializes values from data written with ValueSerializer, or a compatible
 * implementation.
 */
class V8_EXPORT ValueDeserializer {
 public:
  class V8_EXPORT Delegate {
   public:
    virtual ~Delegate() = default;

    /**
     * The embedder overrides this method to read some kind of host object, if
     * possible. If not, a suitable exception should be thrown and
     * MaybeLocal<Object>() returned.
     */
    virtual MaybeLocal<Object> ReadHostObject(Isolate* isolate);

    /**
     * Get a WasmModuleObject given a transfer_id previously provided
     * by ValueSerializer::Delegate::GetWasmModuleTransferId
     */
    virtual MaybeLocal<WasmModuleObject> GetWasmModuleFromId(
        Isolate* isolate, uint32_t transfer_id);

    /**
     * Get a SharedArrayBuffer given a clone_id previously provided
     * by ValueSerializer::Delegate::GetSharedArrayBufferId
     */
    virtual MaybeLocal<SharedArrayBuffer> GetSharedArrayBufferFromId(
        Isolate* isolate, uint32_t clone_id);

    /**
     * Get the SharedValueConveyor previously provided by
     * ValueSerializer::Delegate::AdoptSharedValueConveyor.
     */
    virtual const SharedValueConveyor* GetSharedValueConveyor(Isolate* isolate);
  };

  ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size);
  ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size,
                    Delegate* delegate);
  ~ValueDeserializer();

  /**
   * Reads and validates a header (including the format version).
   * May, for example, reject an invalid or unsupported wire format.
   */
  V8_WARN_UNUSED_RESULT Maybe<bool> ReadHeader(Local<Context> context);

  /**
   * Deserializes a JavaScript value from the buffer.
   */
  V8_WARN_UNUSED_RESULT MaybeLocal<Value> ReadValue(Local<Context> context);

  /**
   * Accepts the array buffer corresponding to the one passed previously to
   * ValueSerializer::TransferArrayBuffer.
   */
  void TransferArrayBuffer(uint32_t transfer_id,
                           Local<ArrayBuffer> array_buffer);

  /**
   * Similar to TransferArrayBuffer, but for SharedArrayBuffer.
   * The id is not necessarily in the same namespace as unshared ArrayBuffer
   * objects.
   */
  void TransferSharedArrayBuffer(uint32_t id,
                                 Local<SharedArrayBuffer> shared_array_buffer);

  /**
   * Must be called before ReadHeader to enable support for reading the legacy
   * wire format (i.e., which predates this being shipped).
   *
   * Don't use this unless you need to read data written by previous versions of
   * blink::ScriptValueSerializer.
   */
  void SetSupportsLegacyWireFormat(bool supports_legacy_wire_format);

  /**
   * Reads the underlying wire format version. Likely mostly to be useful to
   * legacy code reading old wire format versions. Must be called after
   * ReadHeader.
   */
  uint32_t GetWireFormatVersion() const;

  /**
   * Reads raw data in various common formats to the buffer.
   * Note that integer types are read in base-128 varint format, not with a
   * binary copy. For use during an override of Delegate::ReadHostObject.
   */
  V8_WARN_UNUSED_RESULT bool ReadUint32(uint32_t* value);
  V8_WARN_UNUSED_RESULT bool ReadUint64(uint64_t* value);
  V8_WARN_UNUSED_RESULT bool ReadDouble(double* value);
  V8_WARN_UNUSED_RESULT bool ReadRawBytes(size_t length, const void** data);

  ValueDeserializer(const ValueDeserializer&) = delete;
  void operator=(const ValueDeserializer&) = delete;

 private:
  struct PrivateData;
  PrivateData* private_;
};

}  // namespace v8

#endif  // INCLUDE_V8_VALUE_SERIALIZER_H_

Coverage Report

Created: 2025-07-04 09:33

Line	Count	Source (jump to first uncovered line)
1		// Copyright 2021 the V8 project authors. All rights reserved.
2		// Use of this source code is governed by a BSD-style license that can be
3		// found in the LICENSE file.
4
5		#ifndef INCLUDE_V8_VALUE_SERIALIZER_H_
6		#define INCLUDE_V8_VALUE_SERIALIZER_H_
7
8		#include <stddef.h>
9		#include <stdint.h>
10
11		#include <memory>
12		#include <utility>
13
14		#include "v8-local-handle.h" // NOLINT(build/include_directory)
15		#include "v8-maybe.h" // NOLINT(build/include_directory)
16		#include "v8config.h" // NOLINT(build/include_directory)
17
18		namespace v8 {
19
20		class ArrayBuffer;
21		class Isolate;
22		class Object;
23		class SharedArrayBuffer;
24		class String;
25		class WasmModuleObject;
26		class Value;
27
28		namespace internal {
29		struct ScriptStreamingData;
30		class SharedObjectConveyorHandles;
31		class ValueDeserializer;
32		class ValueSerializer;
33		} // namespace internal
34
35		/**
36		* A move-only class for managing the lifetime of shared value conveyors used
37		* by V8 to keep JS shared values alive in transit when serialized.
38		*
39		* This class is not directly constructible and is always passed to a
40		* ValueSerializer::Delegate via ValueSerializer::SetSharedValueConveyor.
41		*
42		* The embedder must not destruct the SharedValueConveyor until the associated
43		* serialized data will no longer be deserialized.
44		*/
45		class V8_EXPORT SharedValueConveyor final {
46		public:
47		SharedValueConveyor(SharedValueConveyor&&) noexcept;
48		~SharedValueConveyor();
49
50		SharedValueConveyor& operator=(SharedValueConveyor&&) noexcept;
51
52		private:
53		friend class internal::ValueSerializer;
54		friend class internal::ValueDeserializer;
55
56		explicit SharedValueConveyor(Isolate* isolate);
57
58		std::unique_ptr<internal::SharedObjectConveyorHandles> private_;
59		};
60
61		/**
62		* Value serialization compatible with the HTML structured clone algorithm.
63		* The format is backward-compatible (i.e. safe to store to disk).
64		*/
65		class V8_EXPORT ValueSerializer {
66		public:
67		class V8_EXPORT Delegate {
68		public:
69	2	virtual ~Delegate() = default;
70
71		/**
72		* Handles the case where a DataCloneError would be thrown in the structured
73		* clone spec. Other V8 embedders may throw some other appropriate exception
74		* type.
75		*/
76		virtual void ThrowDataCloneError(Local<String> message) = 0;
77
78		/**
79		* The embedder overrides this method to enable custom host object filter
80		* with Delegate::IsHostObject.
81		*
82		* This method is called at most once per serializer.
83		*/
84		virtual bool HasCustomHostObject(Isolate* isolate);
85
86		/**
87		* The embedder overrides this method to determine if an JS object is a
88		* host object and needs to be serialized by the host.
89		*/
90		virtual Maybe<bool> IsHostObject(Isolate* isolate, Local<Object> object);
91
92		/**
93		* The embedder overrides this method to write some kind of host object, if
94		* possible. If not, a suitable exception should be thrown and
95		* Nothing<bool>() returned.
96		*/
97		virtual Maybe<bool> WriteHostObject(Isolate* isolate, Local<Object> object);
98
99		/**
100		* Called when the ValueSerializer is going to serialize a
101		* SharedArrayBuffer object. The embedder must return an ID for the
102		* object, using the same ID if this SharedArrayBuffer has already been
103		* serialized in this buffer. When deserializing, this ID will be passed to
104		* ValueDeserializer::GetSharedArrayBufferFromId as \|clone_id\|.
105		*
106		* If the object cannot be serialized, an
107		* exception should be thrown and Nothing<uint32_t>() returned.
108		*/
109		virtual Maybe<uint32_t> GetSharedArrayBufferId(
110		Isolate* isolate, Local<SharedArrayBuffer> shared_array_buffer);
111
112		virtual Maybe<uint32_t> GetWasmModuleTransferId(
113		Isolate* isolate, Local<WasmModuleObject> module);
114
115		/**
116		* Called when the first shared value is serialized. All subsequent shared
117		* values will use the same conveyor.
118		*
119		* The embedder must ensure the lifetime of the conveyor matches the
120		* lifetime of the serialized data.
121		*
122		* If the embedder supports serializing shared values, this method should
123		* return true. Otherwise the embedder should throw an exception and return
124		* false.
125		*
126		* This method is called at most once per serializer.
127		*/
128		virtual bool AdoptSharedValueConveyor(Isolate* isolate,
129		SharedValueConveyor&& conveyor);
130
131		/**
132		* Allocates memory for the buffer of at least the size provided. The actual
133		* size (which may be greater or equal) is written to \|actual_size\|. If no
134		* buffer has been allocated yet, nullptr will be provided.
135		*
136		* If the memory cannot be allocated, nullptr should be returned.
137		* \|actual_size\| will be ignored. It is assumed that \|old_buffer\| is still
138		* valid in this case and has not been modified.
139		*
140		* The default implementation uses the stdlib's `realloc()` function.
141		*/
142		virtual void* ReallocateBufferMemory(void* old_buffer, size_t size,
143		size_t* actual_size);
144
145		/**
146		* Frees a buffer allocated with \|ReallocateBufferMemory\|.
147		*
148		* The default implementation uses the stdlib's `free()` function.
149		*/
150		virtual void FreeBufferMemory(void* buffer);
151		};
152
153		explicit ValueSerializer(Isolate* isolate);
154		ValueSerializer(Isolate* isolate, Delegate* delegate);
155		~ValueSerializer();
156
157		/**
158		* Writes out a header, which includes the format version.
159		*/
160		void WriteHeader();
161
162		/**
163		* Serializes a JavaScript value into the buffer.
164		*/
165		V8_WARN_UNUSED_RESULT Maybe<bool> WriteValue(Local<Context> context,
166		Local<Value> value);
167
168		/**
169		* Returns the stored data (allocated using the delegate's
170		* ReallocateBufferMemory) and its size. This serializer should not be used
171		* once the buffer is released. The contents are undefined if a previous write
172		* has failed. Ownership of the buffer is transferred to the caller.
173		*/
174		V8_WARN_UNUSED_RESULT std::pair<uint8_t*, size_t> Release();
175
176		/**
177		* Marks an ArrayBuffer as havings its contents transferred out of band.
178		* Pass the corresponding ArrayBuffer in the deserializing context to
179		* ValueDeserializer::TransferArrayBuffer.
180		*/
181		void TransferArrayBuffer(uint32_t transfer_id,
182		Local<ArrayBuffer> array_buffer);
183
184		/**
185		* Indicate whether to treat ArrayBufferView objects as host objects,
186		* i.e. pass them to Delegate::WriteHostObject. This should not be
187		* called when no Delegate was passed.
188		*
189		* The default is not to treat ArrayBufferViews as host objects.
190		*/
191		void SetTreatArrayBufferViewsAsHostObjects(bool mode);
192
193		/**
194		* Write raw data in various common formats to the buffer.
195		* Note that integer types are written in base-128 varint format, not with a
196		* binary copy. For use during an override of Delegate::WriteHostObject.
197		*/
198		void WriteUint32(uint32_t value);
199		void WriteUint64(uint64_t value);
200		void WriteDouble(double value);
201		void WriteRawBytes(const void* source, size_t length);
202
203		ValueSerializer(const ValueSerializer&) = delete;
204		void operator=(const ValueSerializer&) = delete;
205
206		private:
207		struct PrivateData;
208		PrivateData* private_;
209		};
210
211		/**
212		* Deserializes values from data written with ValueSerializer, or a compatible
213		* implementation.
214		*/
215		class V8_EXPORT ValueDeserializer {
216		public:
217		class V8_EXPORT Delegate {
218		public:
219	0	virtual ~Delegate() = default;
220
221		/**
222		* The embedder overrides this method to read some kind of host object, if
223		* possible. If not, a suitable exception should be thrown and
224		* MaybeLocal<Object>() returned.
225		*/
226		virtual MaybeLocal<Object> ReadHostObject(Isolate* isolate);
227
228		/**
229		* Get a WasmModuleObject given a transfer_id previously provided
230		* by ValueSerializer::Delegate::GetWasmModuleTransferId
231		*/
232		virtual MaybeLocal<WasmModuleObject> GetWasmModuleFromId(
233		Isolate* isolate, uint32_t transfer_id);
234
235		/**
236		* Get a SharedArrayBuffer given a clone_id previously provided
237		* by ValueSerializer::Delegate::GetSharedArrayBufferId
238		*/
239		virtual MaybeLocal<SharedArrayBuffer> GetSharedArrayBufferFromId(
240		Isolate* isolate, uint32_t clone_id);
241
242		/**
243		* Get the SharedValueConveyor previously provided by
244		* ValueSerializer::Delegate::AdoptSharedValueConveyor.
245		*/
246		virtual const SharedValueConveyor* GetSharedValueConveyor(Isolate* isolate);
247		};
248
249		ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size);
250		ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size,
251		Delegate* delegate);
252		~ValueDeserializer();
253
254		/**
255		* Reads and validates a header (including the format version).
256		* May, for example, reject an invalid or unsupported wire format.
257		*/
258		V8_WARN_UNUSED_RESULT Maybe<bool> ReadHeader(Local<Context> context);
259
260		/**
261		* Deserializes a JavaScript value from the buffer.
262		*/
263		V8_WARN_UNUSED_RESULT MaybeLocal<Value> ReadValue(Local<Context> context);
264
265		/**
266		* Accepts the array buffer corresponding to the one passed previously to
267		* ValueSerializer::TransferArrayBuffer.
268		*/
269		void TransferArrayBuffer(uint32_t transfer_id,
270		Local<ArrayBuffer> array_buffer);
271
272		/**
273		* Similar to TransferArrayBuffer, but for SharedArrayBuffer.
274		* The id is not necessarily in the same namespace as unshared ArrayBuffer
275		* objects.
276		*/
277		void TransferSharedArrayBuffer(uint32_t id,
278		Local<SharedArrayBuffer> shared_array_buffer);
279
280		/**
281		* Must be called before ReadHeader to enable support for reading the legacy
282		* wire format (i.e., which predates this being shipped).
283		*
284		* Don't use this unless you need to read data written by previous versions of
285		* blink::ScriptValueSerializer.
286		*/
287		void SetSupportsLegacyWireFormat(bool supports_legacy_wire_format);
288
289		/**
290		* Reads the underlying wire format version. Likely mostly to be useful to
291		* legacy code reading old wire format versions. Must be called after
292		* ReadHeader.
293		*/
294		uint32_t GetWireFormatVersion() const;
295
296		/**
297		* Reads raw data in various common formats to the buffer.
298		* Note that integer types are read in base-128 varint format, not with a
299		* binary copy. For use during an override of Delegate::ReadHostObject.
300		*/
301		V8_WARN_UNUSED_RESULT bool ReadUint32(uint32_t* value);
302		V8_WARN_UNUSED_RESULT bool ReadUint64(uint64_t* value);
303		V8_WARN_UNUSED_RESULT bool ReadDouble(double* value);
304		V8_WARN_UNUSED_RESULT bool ReadRawBytes(size_t length, const void** data);
305
306		ValueDeserializer(const ValueDeserializer&) = delete;
307		void operator=(const ValueDeserializer&) = delete;
308
309		private:
310		struct PrivateData;
311		PrivateData* private_;
312		};
313
314		} // namespace v8
315
316		#endif // INCLUDE_V8_VALUE_SERIALIZER_H_