v8-value-serializer.h 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279
  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. #ifndef INCLUDE_V8_VALUE_SERIALIZER_H_
  5. #define INCLUDE_V8_VALUE_SERIALIZER_H_
  6. #include <stddef.h>
  7. #include <stdint.h>
  8. #include <utility>
  9. #include "v8-local-handle.h" // NOLINT(build/include_directory)
  10. #include "v8-maybe.h" // NOLINT(build/include_directory)
  11. #include "v8config.h" // NOLINT(build/include_directory)
  12. namespace v8 {
  13. class ArrayBuffer;
  14. class Isolate;
  15. class Object;
  16. class SharedArrayBuffer;
  17. class String;
  18. class WasmModuleObject;
  19. class Value;
  20. namespace internal {
  21. struct ScriptStreamingData;
  22. } // namespace internal
  23. /**
  24. * Value serialization compatible with the HTML structured clone algorithm.
  25. * The format is backward-compatible (i.e. safe to store to disk).
  26. */
  27. class V8_EXPORT ValueSerializer {
  28. public:
  29. class V8_EXPORT Delegate {
  30. public:
  31. virtual ~Delegate() = default;
  32. /**
  33. * Handles the case where a DataCloneError would be thrown in the structured
  34. * clone spec. Other V8 embedders may throw some other appropriate exception
  35. * type.
  36. */
  37. virtual void ThrowDataCloneError(Local<String> message) = 0;
  38. /**
  39. * The embedder overrides this method to write some kind of host object, if
  40. * possible. If not, a suitable exception should be thrown and
  41. * Nothing<bool>() returned.
  42. */
  43. virtual Maybe<bool> WriteHostObject(Isolate* isolate, Local<Object> object);
  44. /**
  45. * Called when the ValueSerializer is going to serialize a
  46. * SharedArrayBuffer object. The embedder must return an ID for the
  47. * object, using the same ID if this SharedArrayBuffer has already been
  48. * serialized in this buffer. When deserializing, this ID will be passed to
  49. * ValueDeserializer::GetSharedArrayBufferFromId as |clone_id|.
  50. *
  51. * If the object cannot be serialized, an
  52. * exception should be thrown and Nothing<uint32_t>() returned.
  53. */
  54. virtual Maybe<uint32_t> GetSharedArrayBufferId(
  55. Isolate* isolate, Local<SharedArrayBuffer> shared_array_buffer);
  56. virtual Maybe<uint32_t> GetWasmModuleTransferId(
  57. Isolate* isolate, Local<WasmModuleObject> module);
  58. /**
  59. * Returns whether shared values are supported. GetSharedValueId is only
  60. * called if SupportsSharedValues() returns true.
  61. */
  62. virtual bool SupportsSharedValues() const;
  63. /**
  64. * Called when the ValueSerializer serializes a value that is shared across
  65. * Isolates. The embedder must return an ID for the object. This function
  66. * must be idempotent for the same object. When deserializing, the ID will
  67. * be passed to ValueDeserializer::Delegate::GetSharedValueFromId as
  68. * |shared_value_id|.
  69. */
  70. virtual Maybe<uint32_t> GetSharedValueId(Isolate* isolate,
  71. Local<Value> shared_value);
  72. /**
  73. * Allocates memory for the buffer of at least the size provided. The actual
  74. * size (which may be greater or equal) is written to |actual_size|. If no
  75. * buffer has been allocated yet, nullptr will be provided.
  76. *
  77. * If the memory cannot be allocated, nullptr should be returned.
  78. * |actual_size| will be ignored. It is assumed that |old_buffer| is still
  79. * valid in this case and has not been modified.
  80. *
  81. * The default implementation uses the stdlib's `realloc()` function.
  82. */
  83. virtual void* ReallocateBufferMemory(void* old_buffer, size_t size,
  84. size_t* actual_size);
  85. /**
  86. * Frees a buffer allocated with |ReallocateBufferMemory|.
  87. *
  88. * The default implementation uses the stdlib's `free()` function.
  89. */
  90. virtual void FreeBufferMemory(void* buffer);
  91. };
  92. explicit ValueSerializer(Isolate* isolate);
  93. ValueSerializer(Isolate* isolate, Delegate* delegate);
  94. ~ValueSerializer();
  95. /**
  96. * Writes out a header, which includes the format version.
  97. */
  98. void WriteHeader();
  99. /**
  100. * Serializes a JavaScript value into the buffer.
  101. */
  102. V8_WARN_UNUSED_RESULT Maybe<bool> WriteValue(Local<Context> context,
  103. Local<Value> value);
  104. /**
  105. * Returns the stored data (allocated using the delegate's
  106. * ReallocateBufferMemory) and its size. This serializer should not be used
  107. * once the buffer is released. The contents are undefined if a previous write
  108. * has failed. Ownership of the buffer is transferred to the caller.
  109. */
  110. V8_WARN_UNUSED_RESULT std::pair<uint8_t*, size_t> Release();
  111. /**
  112. * Marks an ArrayBuffer as havings its contents transferred out of band.
  113. * Pass the corresponding ArrayBuffer in the deserializing context to
  114. * ValueDeserializer::TransferArrayBuffer.
  115. */
  116. void TransferArrayBuffer(uint32_t transfer_id,
  117. Local<ArrayBuffer> array_buffer);
  118. /**
  119. * Indicate whether to treat ArrayBufferView objects as host objects,
  120. * i.e. pass them to Delegate::WriteHostObject. This should not be
  121. * called when no Delegate was passed.
  122. *
  123. * The default is not to treat ArrayBufferViews as host objects.
  124. */
  125. void SetTreatArrayBufferViewsAsHostObjects(bool mode);
  126. /**
  127. * Write raw data in various common formats to the buffer.
  128. * Note that integer types are written in base-128 varint format, not with a
  129. * binary copy. For use during an override of Delegate::WriteHostObject.
  130. */
  131. void WriteUint32(uint32_t value);
  132. void WriteUint64(uint64_t value);
  133. void WriteDouble(double value);
  134. void WriteRawBytes(const void* source, size_t length);
  135. ValueSerializer(const ValueSerializer&) = delete;
  136. void operator=(const ValueSerializer&) = delete;
  137. private:
  138. struct PrivateData;
  139. PrivateData* private_;
  140. };
  141. /**
  142. * Deserializes values from data written with ValueSerializer, or a compatible
  143. * implementation.
  144. */
  145. class V8_EXPORT ValueDeserializer {
  146. public:
  147. class V8_EXPORT Delegate {
  148. public:
  149. virtual ~Delegate() = default;
  150. /**
  151. * The embedder overrides this method to read some kind of host object, if
  152. * possible. If not, a suitable exception should be thrown and
  153. * MaybeLocal<Object>() returned.
  154. */
  155. virtual MaybeLocal<Object> ReadHostObject(Isolate* isolate);
  156. /**
  157. * Get a WasmModuleObject given a transfer_id previously provided
  158. * by ValueSerializer::Delegate::GetWasmModuleTransferId
  159. */
  160. virtual MaybeLocal<WasmModuleObject> GetWasmModuleFromId(
  161. Isolate* isolate, uint32_t transfer_id);
  162. /**
  163. * Get a SharedArrayBuffer given a clone_id previously provided
  164. * by ValueSerializer::Delegate::GetSharedArrayBufferId
  165. */
  166. virtual MaybeLocal<SharedArrayBuffer> GetSharedArrayBufferFromId(
  167. Isolate* isolate, uint32_t clone_id);
  168. /**
  169. * Returns whether shared values are supported. GetSharedValueFromId is only
  170. * called if SupportsSharedValues() returns true.
  171. */
  172. virtual bool SupportsSharedValues() const;
  173. /**
  174. * Get a value shared across Isolates given a shared_value_id provided by
  175. * ValueSerializer::Delegate::GetSharedValueId.
  176. */
  177. virtual MaybeLocal<Value> GetSharedValueFromId(Isolate* isolate,
  178. uint32_t shared_value_id);
  179. };
  180. ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size);
  181. ValueDeserializer(Isolate* isolate, const uint8_t* data, size_t size,
  182. Delegate* delegate);
  183. ~ValueDeserializer();
  184. /**
  185. * Reads and validates a header (including the format version).
  186. * May, for example, reject an invalid or unsupported wire format.
  187. */
  188. V8_WARN_UNUSED_RESULT Maybe<bool> ReadHeader(Local<Context> context);
  189. /**
  190. * Deserializes a JavaScript value from the buffer.
  191. */
  192. V8_WARN_UNUSED_RESULT MaybeLocal<Value> ReadValue(Local<Context> context);
  193. /**
  194. * Accepts the array buffer corresponding to the one passed previously to
  195. * ValueSerializer::TransferArrayBuffer.
  196. */
  197. void TransferArrayBuffer(uint32_t transfer_id,
  198. Local<ArrayBuffer> array_buffer);
  199. /**
  200. * Similar to TransferArrayBuffer, but for SharedArrayBuffer.
  201. * The id is not necessarily in the same namespace as unshared ArrayBuffer
  202. * objects.
  203. */
  204. void TransferSharedArrayBuffer(uint32_t id,
  205. Local<SharedArrayBuffer> shared_array_buffer);
  206. /**
  207. * Must be called before ReadHeader to enable support for reading the legacy
  208. * wire format (i.e., which predates this being shipped).
  209. *
  210. * Don't use this unless you need to read data written by previous versions of
  211. * blink::ScriptValueSerializer.
  212. */
  213. void SetSupportsLegacyWireFormat(bool supports_legacy_wire_format);
  214. /**
  215. * Reads the underlying wire format version. Likely mostly to be useful to
  216. * legacy code reading old wire format versions. Must be called after
  217. * ReadHeader.
  218. */
  219. uint32_t GetWireFormatVersion() const;
  220. /**
  221. * Reads raw data in various common formats to the buffer.
  222. * Note that integer types are read in base-128 varint format, not with a
  223. * binary copy. For use during an override of Delegate::ReadHostObject.
  224. */
  225. V8_WARN_UNUSED_RESULT bool ReadUint32(uint32_t* value);
  226. V8_WARN_UNUSED_RESULT bool ReadUint64(uint64_t* value);
  227. V8_WARN_UNUSED_RESULT bool ReadDouble(double* value);
  228. V8_WARN_UNUSED_RESULT bool ReadRawBytes(size_t length, const void** data);
  229. ValueDeserializer(const ValueDeserializer&) = delete;
  230. void operator=(const ValueDeserializer&) = delete;
  231. private:
  232. struct PrivateData;
  233. PrivateData* private_;
  234. };
  235. } // namespace v8
  236. #endif // INCLUDE_V8_VALUE_SERIALIZER_H_