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