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