Home | History | Annotate | Download | only in src 
      1 // Copyright 2016 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 V8_VALUE_SERIALIZER_H_
      6 #define V8_VALUE_SERIALIZER_H_
      7 
      8 #include <cstdint>
      9 #include <vector>
     10 
     11 #include "include/v8.h"
     12 #include "src/base/compiler-specific.h"
     13 #include "src/base/macros.h"
     14 #include "src/identity-map.h"
     15 #include "src/maybe-handles.h"
     16 #include "src/messages.h"
     17 #include "src/vector.h"
     18 #include "src/zone/zone.h"
     19 
     20 namespace v8 {
     21 namespace internal {
     22 
     23 class BigInt;
     24 class HeapNumber;
     25 class Isolate;
     26 class JSArrayBuffer;
     27 class JSArrayBufferView;
     28 class JSDate;
     29 class JSMap;
     30 class JSRegExp;
     31 class JSSet;
     32 class JSValue;
     33 class MutableHeapNumber;
     34 class Object;
     35 class Oddball;
     36 class Smi;
     37 class WasmMemoryObject;
     38 class WasmModuleObject;
     39 
     40 enum class SerializationTag : uint8_t;
     41 
     42 /**
     43  * Writes V8 objects in a binary format that allows the objects to be cloned
     44  * according to the HTML structured clone algorithm.
     45  *
     46  * Format is based on Blink's previous serialization logic.
     47  */
     48 class ValueSerializer {
     49  public:
     50   ValueSerializer(Isolate* isolate, v8::ValueSerializer::Delegate* delegate);
     51   ~ValueSerializer();
     52 
     53   /*
     54    * Writes out a header, which includes the format version.
     55    */
     56   void WriteHeader();
     57 
     58   /*
     59    * Serializes a V8 object into the buffer.
     60    */
     61   Maybe<bool> WriteObject(Handle<Object> object) V8_WARN_UNUSED_RESULT;
     62 
     63   /*
     64    * Returns the stored data. This serializer should not be used once the buffer
     65    * is released. The contents are undefined if a previous write has failed.
     66    */
     67   std::vector<uint8_t> ReleaseBuffer();
     68 
     69   /*
     70    * Returns the buffer, allocated via the delegate, and its size.
     71    * Caller assumes ownership of the buffer.
     72    */
     73   std::pair<uint8_t*, size_t> Release();
     74 
     75   /*
     76    * Marks an ArrayBuffer as havings its contents transferred out of band.
     77    * Pass the corresponding JSArrayBuffer in the deserializing context to
     78    * ValueDeserializer::TransferArrayBuffer.
     79    */
     80   void TransferArrayBuffer(uint32_t transfer_id,
     81                            Handle<JSArrayBuffer> array_buffer);
     82 
     83   /*
     84    * Publicly exposed wire format writing methods.
     85    * These are intended for use within the delegate's WriteHostObject method.
     86    */
     87   void WriteUint32(uint32_t value);
     88   void WriteUint64(uint64_t value);
     89   void WriteRawBytes(const void* source, size_t length);
     90   void WriteDouble(double value);
     91 
     92   /*
     93    * Indicate whether to treat ArrayBufferView objects as host objects,
     94    * i.e. pass them to Delegate::WriteHostObject. This should not be
     95    * called when no Delegate was passed.
     96    *
     97    * The default is not to treat ArrayBufferViews as host objects.
     98    */
     99   void SetTreatArrayBufferViewsAsHostObjects(bool mode);
    100 
    101  private:
    102   // Managing allocations of the internal buffer.
    103   Maybe<bool> ExpandBuffer(size_t required_capacity);
    104 
    105   // Writing the wire format.
    106   void WriteTag(SerializationTag tag);
    107   template <typename T>
    108   void WriteVarint(T value);
    109   template <typename T>
    110   void WriteZigZag(T value);
    111   void WriteOneByteString(Vector<const uint8_t> chars);
    112   void WriteTwoByteString(Vector<const uc16> chars);
    113   void WriteBigIntContents(BigInt* bigint);
    114   Maybe<uint8_t*> ReserveRawBytes(size_t bytes);
    115 
    116   // Writing V8 objects of various kinds.
    117   void WriteOddball(Oddball* oddball);
    118   void WriteSmi(Smi* smi);
    119   void WriteHeapNumber(HeapNumber* number);
    120   void WriteMutableHeapNumber(MutableHeapNumber* number);
    121   void WriteBigInt(BigInt* bigint);
    122   void WriteString(Handle<String> string);
    123   Maybe<bool> WriteJSReceiver(Handle<JSReceiver> receiver)
    124       V8_WARN_UNUSED_RESULT;
    125   Maybe<bool> WriteJSObject(Handle<JSObject> object) V8_WARN_UNUSED_RESULT;
    126   Maybe<bool> WriteJSObjectSlow(Handle<JSObject> object) V8_WARN_UNUSED_RESULT;
    127   Maybe<bool> WriteJSArray(Handle<JSArray> array) V8_WARN_UNUSED_RESULT;
    128   void WriteJSDate(JSDate* date);
    129   Maybe<bool> WriteJSValue(Handle<JSValue> value) V8_WARN_UNUSED_RESULT;
    130   void WriteJSRegExp(JSRegExp* regexp);
    131   Maybe<bool> WriteJSMap(Handle<JSMap> map) V8_WARN_UNUSED_RESULT;
    132   Maybe<bool> WriteJSSet(Handle<JSSet> map) V8_WARN_UNUSED_RESULT;
    133   Maybe<bool> WriteJSArrayBuffer(Handle<JSArrayBuffer> array_buffer)
    134       V8_WARN_UNUSED_RESULT;
    135   Maybe<bool> WriteJSArrayBufferView(JSArrayBufferView* array_buffer);
    136   Maybe<bool> WriteWasmModule(Handle<WasmModuleObject> object)
    137       V8_WARN_UNUSED_RESULT;
    138   Maybe<bool> WriteWasmMemory(Handle<WasmMemoryObject> object)
    139       V8_WARN_UNUSED_RESULT;
    140   Maybe<bool> WriteHostObject(Handle<JSObject> object) V8_WARN_UNUSED_RESULT;
    141 
    142   /*
    143    * Reads the specified keys from the object and writes key-value pairs to the
    144    * buffer. Returns the number of keys actually written, which may be smaller
    145    * if some keys are not own properties when accessed.
    146    */
    147   Maybe<uint32_t> WriteJSObjectPropertiesSlow(
    148       Handle<JSObject> object, Handle<FixedArray> keys) V8_WARN_UNUSED_RESULT;
    149 
    150   /*
    151    * Asks the delegate to handle an error that occurred during data cloning, by
    152    * throwing an exception appropriate for the host.
    153    */
    154   void ThrowDataCloneError(MessageTemplate::Template template_index);
    155   V8_NOINLINE void ThrowDataCloneError(MessageTemplate::Template template_index,
    156                                        Handle<Object> arg0);
    157 
    158   Maybe<bool> ThrowIfOutOfMemory();
    159 
    160   Isolate* const isolate_;
    161   v8::ValueSerializer::Delegate* const delegate_;
    162   bool treat_array_buffer_views_as_host_objects_ = false;
    163   uint8_t* buffer_ = nullptr;
    164   size_t buffer_size_ = 0;
    165   size_t buffer_capacity_ = 0;
    166   bool out_of_memory_ = false;
    167   Zone zone_;
    168 
    169   // To avoid extra lookups in the identity map, ID+1 is actually stored in the
    170   // map (checking if the used identity is zero is the fast way of checking if
    171   // the entry is new).
    172   IdentityMap<uint32_t, ZoneAllocationPolicy> id_map_;
    173   uint32_t next_id_ = 0;
    174 
    175   // A similar map, for transferred array buffers.
    176   IdentityMap<uint32_t, ZoneAllocationPolicy> array_buffer_transfer_map_;
    177 
    178   DISALLOW_COPY_AND_ASSIGN(ValueSerializer);
    179 };
    180 
    181 /*
    182  * Deserializes values from data written with ValueSerializer, or a compatible
    183  * implementation.
    184  */
    185 class ValueDeserializer {
    186  public:
    187   ValueDeserializer(Isolate* isolate, Vector<const uint8_t> data,
    188                     v8::ValueDeserializer::Delegate* delegate);
    189   ~ValueDeserializer();
    190 
    191   /*
    192    * Runs version detection logic, which may fail if the format is invalid.
    193    */
    194   Maybe<bool> ReadHeader() V8_WARN_UNUSED_RESULT;
    195 
    196   /*
    197    * Reads the underlying wire format version. Likely mostly to be useful to
    198    * legacy code reading old wire format versions. Must be called after
    199    * ReadHeader.
    200    */
    201   uint32_t GetWireFormatVersion() const { return version_; }
    202 
    203   /*
    204    * Deserializes a V8 object from the buffer.
    205    */
    206   MaybeHandle<Object> ReadObject() V8_WARN_UNUSED_RESULT;
    207 
    208   /*
    209    * Reads an object, consuming the entire buffer.
    210    *
    211    * This is required for the legacy "version 0" format, which did not allow
    212    * reference deduplication, and instead relied on a "stack" model for
    213    * deserializing, with the contents of objects and arrays provided first.
    214    */
    215   MaybeHandle<Object> ReadObjectUsingEntireBufferForLegacyFormat()
    216       V8_WARN_UNUSED_RESULT;
    217 
    218   /*
    219    * Accepts the array buffer corresponding to the one passed previously to
    220    * ValueSerializer::TransferArrayBuffer.
    221    */
    222   void TransferArrayBuffer(uint32_t transfer_id,
    223                            Handle<JSArrayBuffer> array_buffer);
    224 
    225   /*
    226    * Publicly exposed wire format writing methods.
    227    * These are intended for use within the delegate's WriteHostObject method.
    228    */
    229   bool ReadUint32(uint32_t* value) V8_WARN_UNUSED_RESULT;
    230   bool ReadUint64(uint64_t* value) V8_WARN_UNUSED_RESULT;
    231   bool ReadDouble(double* value) V8_WARN_UNUSED_RESULT;
    232   bool ReadRawBytes(size_t length, const void** data) V8_WARN_UNUSED_RESULT;
    233   void set_expect_inline_wasm(bool expect_inline_wasm) {
    234     expect_inline_wasm_ = expect_inline_wasm;
    235   }
    236 
    237  private:
    238   // Reading the wire format.
    239   Maybe<SerializationTag> PeekTag() const V8_WARN_UNUSED_RESULT;
    240   void ConsumeTag(SerializationTag peeked_tag);
    241   Maybe<SerializationTag> ReadTag() V8_WARN_UNUSED_RESULT;
    242   template <typename T>
    243   Maybe<T> ReadVarint() V8_WARN_UNUSED_RESULT;
    244   template <typename T>
    245   Maybe<T> ReadZigZag() V8_WARN_UNUSED_RESULT;
    246   Maybe<double> ReadDouble() V8_WARN_UNUSED_RESULT;
    247   Maybe<Vector<const uint8_t>> ReadRawBytes(int size) V8_WARN_UNUSED_RESULT;
    248   bool expect_inline_wasm() const { return expect_inline_wasm_; }
    249 
    250   // Reads a string if it matches the one provided.
    251   // Returns true if this was the case. Otherwise, nothing is consumed.
    252   bool ReadExpectedString(Handle<String> expected) V8_WARN_UNUSED_RESULT;
    253 
    254   // Like ReadObject, but skips logic for special cases in simulating the
    255   // "stack machine".
    256   MaybeHandle<Object> ReadObjectInternal() V8_WARN_UNUSED_RESULT;
    257 
    258   // Reads a string intended to be part of a more complicated object.
    259   // Before v12, these are UTF-8 strings. After, they can be any encoding
    260   // permissible for a string (with the relevant tag).
    261   MaybeHandle<String> ReadString() V8_WARN_UNUSED_RESULT;
    262 
    263   // Reading V8 objects of specific kinds.
    264   // The tag is assumed to have already been read.
    265   MaybeHandle<BigInt> ReadBigInt() V8_WARN_UNUSED_RESULT;
    266   MaybeHandle<String> ReadUtf8String() V8_WARN_UNUSED_RESULT;
    267   MaybeHandle<String> ReadOneByteString() V8_WARN_UNUSED_RESULT;
    268   MaybeHandle<String> ReadTwoByteString() V8_WARN_UNUSED_RESULT;
    269   MaybeHandle<JSObject> ReadJSObject() V8_WARN_UNUSED_RESULT;
    270   MaybeHandle<JSArray> ReadSparseJSArray() V8_WARN_UNUSED_RESULT;
    271   MaybeHandle<JSArray> ReadDenseJSArray() V8_WARN_UNUSED_RESULT;
    272   MaybeHandle<JSDate> ReadJSDate() V8_WARN_UNUSED_RESULT;
    273   MaybeHandle<JSValue> ReadJSValue(SerializationTag tag) V8_WARN_UNUSED_RESULT;
    274   MaybeHandle<JSRegExp> ReadJSRegExp() V8_WARN_UNUSED_RESULT;
    275   MaybeHandle<JSMap> ReadJSMap() V8_WARN_UNUSED_RESULT;
    276   MaybeHandle<JSSet> ReadJSSet() V8_WARN_UNUSED_RESULT;
    277   MaybeHandle<JSArrayBuffer> ReadJSArrayBuffer(bool is_shared)
    278       V8_WARN_UNUSED_RESULT;
    279   MaybeHandle<JSArrayBuffer> ReadTransferredJSArrayBuffer()
    280       V8_WARN_UNUSED_RESULT;
    281   MaybeHandle<JSArrayBufferView> ReadJSArrayBufferView(
    282       Handle<JSArrayBuffer> buffer) V8_WARN_UNUSED_RESULT;
    283   MaybeHandle<JSObject> ReadWasmModule() V8_WARN_UNUSED_RESULT;
    284   MaybeHandle<JSObject> ReadWasmModuleTransfer() V8_WARN_UNUSED_RESULT;
    285   MaybeHandle<WasmMemoryObject> ReadWasmMemory() V8_WARN_UNUSED_RESULT;
    286   MaybeHandle<JSObject> ReadHostObject() V8_WARN_UNUSED_RESULT;
    287 
    288   /*
    289    * Reads key-value pairs into the object until the specified end tag is
    290    * encountered. If successful, returns the number of properties read.
    291    */
    292   Maybe<uint32_t> ReadJSObjectProperties(Handle<JSObject> object,
    293                                          SerializationTag end_tag,
    294                                          bool can_use_transitions);
    295 
    296   // Manipulating the map from IDs to reified objects.
    297   bool HasObjectWithID(uint32_t id);
    298   MaybeHandle<JSReceiver> GetObjectWithID(uint32_t id);
    299   void AddObjectWithID(uint32_t id, Handle<JSReceiver> object);
    300 
    301   Isolate* const isolate_;
    302   v8::ValueDeserializer::Delegate* const delegate_;
    303   const uint8_t* position_;
    304   const uint8_t* const end_;
    305   PretenureFlag pretenure_;
    306   uint32_t version_ = 0;
    307   uint32_t next_id_ = 0;
    308   bool expect_inline_wasm_ = false;
    309 
    310   // Always global handles.
    311   Handle<FixedArray> id_map_;
    312   MaybeHandle<SimpleNumberDictionary> array_buffer_transfer_map_;
    313 
    314   DISALLOW_COPY_AND_ASSIGN(ValueDeserializer);
    315 };
    316 
    317 }  // namespace internal
    318 }  // namespace v8
    319 
    320 #endif  // V8_VALUE_SERIALIZER_H_
    321