1 // Copyright (C) MongoDB, Inc. 2022-present. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may 4 // not use this file except in compliance with the License. You may obtain 5 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 6 7 // Package bsoncodec provides a system for encoding values to BSON representations and decoding 8 // values from BSON representations. This package considers both binary BSON and ExtendedJSON as 9 // BSON representations. The types in this package enable a flexible system for handling this 10 // encoding and decoding. 11 // 12 // The codec system is composed of two parts: 13 // 14 // 1) ValueEncoders and ValueDecoders that handle encoding and decoding Go values to and from BSON 15 // representations. 16 // 17 // 2) A Registry that holds these ValueEncoders and ValueDecoders and provides methods for 18 // retrieving them. 19 // 20 // # ValueEncoders and ValueDecoders 21 // 22 // The ValueEncoder interface is implemented by types that can encode a provided Go type to BSON. 23 // The value to encode is provided as a reflect.Value and a bsonrw.ValueWriter is used within the 24 // EncodeValue method to actually create the BSON representation. For convenience, ValueEncoderFunc 25 // is provided to allow use of a function with the correct signature as a ValueEncoder. An 26 // EncodeContext instance is provided to allow implementations to lookup further ValueEncoders and 27 // to provide configuration information. 28 // 29 // The ValueDecoder interface is the inverse of the ValueEncoder. Implementations should ensure that 30 // the value they receive is settable. Similar to ValueEncoderFunc, ValueDecoderFunc is provided to 31 // allow the use of a function with the correct signature as a ValueDecoder. A DecodeContext 32 // instance is provided and serves similar functionality to the EncodeContext. 33 // 34 // # Registry 35 // 36 // A Registry is a store for ValueEncoders, ValueDecoders, and a type map. See the Registry type 37 // documentation for examples of registering various custom encoders and decoders. A Registry can 38 // have three main types of codecs: 39 // 40 // 1. Type encoders/decoders - These can be registered using the RegisterTypeEncoder and 41 // RegisterTypeDecoder methods. The registered codec will be invoked when encoding/decoding a value 42 // whose type matches the registered type exactly. 43 // If the registered type is an interface, the codec will be invoked when encoding or decoding 44 // values whose type is the interface, but not for values with concrete types that implement the 45 // interface. 46 // 47 // 2. Hook encoders/decoders - These can be registered using the RegisterHookEncoder and 48 // RegisterHookDecoder methods. These methods only accept interface types and the registered codecs 49 // will be invoked when encoding or decoding values whose types implement the interface. An example 50 // of a hook defined by the driver is bson.Marshaler. The driver will call the MarshalBSON method 51 // for any value whose type implements bson.Marshaler, regardless of the value's concrete type. 52 // 53 // 3. Type map entries - This can be used to associate a BSON type with a Go type. These type 54 // associations are used when decoding into a bson.D/bson.M or a struct field of type interface{}. 55 // For example, by default, BSON int32 and int64 values decode as Go int32 and int64 instances, 56 // respectively, when decoding into a bson.D. The following code would change the behavior so these 57 // values decode as Go int instances instead: 58 // 59 // intType := reflect.TypeOf(int(0)) 60 // registry.RegisterTypeMapEntry(bsontype.Int32, intType).RegisterTypeMapEntry(bsontype.Int64, intType) 61 // 62 // 4. Kind encoder/decoders - These can be registered using the RegisterDefaultEncoder and 63 // RegisterDefaultDecoder methods. The registered codec will be invoked when encoding or decoding 64 // values whose reflect.Kind matches the registered reflect.Kind as long as the value's type doesn't 65 // match a registered type or hook encoder/decoder first. These methods should be used to change the 66 // behavior for all values for a specific kind. 67 // 68 // # Registry Lookup Procedure 69 // 70 // When looking up an encoder in a Registry, the precedence rules are as follows: 71 // 72 // 1. A type encoder registered for the exact type of the value. 73 // 74 // 2. A hook encoder registered for an interface that is implemented by the value or by a pointer to 75 // the value. If the value matches multiple hooks (e.g. the type implements bsoncodec.Marshaler and 76 // bsoncodec.ValueMarshaler), the first one registered will be selected. Note that registries 77 // constructed using bson.NewRegistry have driver-defined hooks registered for the 78 // bsoncodec.Marshaler, bsoncodec.ValueMarshaler, and bsoncodec.Proxy interfaces, so those will take 79 // precedence over any new hooks. 80 // 81 // 3. A kind encoder registered for the value's kind. 82 // 83 // If all of these lookups fail to find an encoder, an error of type ErrNoEncoder is returned. The 84 // same precedence rules apply for decoders, with the exception that an error of type ErrNoDecoder 85 // will be returned if no decoder is found. 86 // 87 // # DefaultValueEncoders and DefaultValueDecoders 88 // 89 // The DefaultValueEncoders and DefaultValueDecoders types provide a full set of ValueEncoders and 90 // ValueDecoders for handling a wide range of Go types, including all of the types within the 91 // primitive package. To make registering these codecs easier, a helper method on each type is 92 // provided. For the DefaultValueEncoders type the method is called RegisterDefaultEncoders and for 93 // the DefaultValueDecoders type the method is called RegisterDefaultDecoders, this method also 94 // handles registering type map entries for each BSON type. 95 package bsoncodec 96