registry.go

Documentation: go.mongodb.org/mongo-driver/bson/bsoncodec

     1  // Copyright (C) MongoDB, Inc. 2017-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
     8  
     9  import (
    10  	"errors"
    11  	"fmt"
    12  	"reflect"
    13  	"sync"
    14  
    15  	"go.mongodb.org/mongo-driver/bson/bsontype"
    16  )
    17  
    18  // ErrNilType is returned when nil is passed to either LookupEncoder or LookupDecoder.
    19  //
    20  // Deprecated: ErrNilType will not be supported in Go Driver 2.0.
    21  var ErrNilType = errors.New("cannot perform a decoder lookup on <nil>")
    22  
    23  // ErrNotPointer is returned when a non-pointer type is provided to LookupDecoder.
    24  //
    25  // Deprecated: ErrNotPointer will not be supported in Go Driver 2.0.
    26  var ErrNotPointer = errors.New("non-pointer provided to LookupDecoder")
    27  
    28  // ErrNoEncoder is returned when there wasn't an encoder available for a type.
    29  //
    30  // Deprecated: ErrNoEncoder will not be supported in Go Driver 2.0.
    31  type ErrNoEncoder struct {
    32  	Type reflect.Type
    33  }
    34  
    35  func (ene ErrNoEncoder) Error() string {
    36  	if ene.Type == nil {
    37  		return "no encoder found for <nil>"
    38  	}
    39  	return "no encoder found for " + ene.Type.String()
    40  }
    41  
    42  // ErrNoDecoder is returned when there wasn't a decoder available for a type.
    43  //
    44  // Deprecated: ErrNoDecoder will not be supported in Go Driver 2.0.
    45  type ErrNoDecoder struct {
    46  	Type reflect.Type
    47  }
    48  
    49  func (end ErrNoDecoder) Error() string {
    50  	return "no decoder found for " + end.Type.String()
    51  }
    52  
    53  // ErrNoTypeMapEntry is returned when there wasn't a type available for the provided BSON type.
    54  //
    55  // Deprecated: ErrNoTypeMapEntry will not be supported in Go Driver 2.0.
    56  type ErrNoTypeMapEntry struct {
    57  	Type bsontype.Type
    58  }
    59  
    60  func (entme ErrNoTypeMapEntry) Error() string {
    61  	return "no type map entry found for " + entme.Type.String()
    62  }
    63  
    64  // ErrNotInterface is returned when the provided type is not an interface.
    65  //
    66  // Deprecated: ErrNotInterface will not be supported in Go Driver 2.0.
    67  var ErrNotInterface = errors.New("The provided type is not an interface")
    68  
    69  // A RegistryBuilder is used to build a Registry. This type is not goroutine
    70  // safe.
    71  //
    72  // Deprecated: Use Registry instead.
    73  type RegistryBuilder struct {
    74  	registry *Registry
    75  }
    76  
    77  // NewRegistryBuilder creates a new empty RegistryBuilder.
    78  //
    79  // Deprecated: Use NewRegistry instead.
    80  func NewRegistryBuilder() *RegistryBuilder {
    81  	return &RegistryBuilder{
    82  		registry: NewRegistry(),
    83  	}
    84  }
    85  
    86  // RegisterCodec will register the provided ValueCodec for the provided type.
    87  //
    88  // Deprecated: Use Registry.RegisterTypeEncoder and Registry.RegisterTypeDecoder instead.
    89  func (rb *RegistryBuilder) RegisterCodec(t reflect.Type, codec ValueCodec) *RegistryBuilder {
    90  	rb.RegisterTypeEncoder(t, codec)
    91  	rb.RegisterTypeDecoder(t, codec)
    92  	return rb
    93  }
    94  
    95  // RegisterTypeEncoder will register the provided ValueEncoder for the provided type.
    96  //
    97  // The type will be used directly, so an encoder can be registered for a type and a different encoder can be registered
    98  // for a pointer to that type.
    99  //
   100  // If the given type is an interface, the encoder will be called when marshaling a type that is that interface. It
   101  // will not be called when marshaling a non-interface type that implements the interface.
   102  //
   103  // Deprecated: Use Registry.RegisterTypeEncoder instead.
   104  func (rb *RegistryBuilder) RegisterTypeEncoder(t reflect.Type, enc ValueEncoder) *RegistryBuilder {
   105  	rb.registry.RegisterTypeEncoder(t, enc)
   106  	return rb
   107  }
   108  
   109  // RegisterHookEncoder will register an encoder for the provided interface type t. This encoder will be called when
   110  // marshaling a type if the type implements t or a pointer to the type implements t. If the provided type is not
   111  // an interface (i.e. t.Kind() != reflect.Interface), this method will panic.
   112  //
   113  // Deprecated: Use Registry.RegisterInterfaceEncoder instead.
   114  func (rb *RegistryBuilder) RegisterHookEncoder(t reflect.Type, enc ValueEncoder) *RegistryBuilder {
   115  	rb.registry.RegisterInterfaceEncoder(t, enc)
   116  	return rb
   117  }
   118  
   119  // RegisterTypeDecoder will register the provided ValueDecoder for the provided type.
   120  //
   121  // The type will be used directly, so a decoder can be registered for a type and a different decoder can be registered
   122  // for a pointer to that type.
   123  //
   124  // If the given type is an interface, the decoder will be called when unmarshaling into a type that is that interface.
   125  // It will not be called when unmarshaling into a non-interface type that implements the interface.
   126  //
   127  // Deprecated: Use Registry.RegisterTypeDecoder instead.
   128  func (rb *RegistryBuilder) RegisterTypeDecoder(t reflect.Type, dec ValueDecoder) *RegistryBuilder {
   129  	rb.registry.RegisterTypeDecoder(t, dec)
   130  	return rb
   131  }
   132  
   133  // RegisterHookDecoder will register an decoder for the provided interface type t. This decoder will be called when
   134  // unmarshaling into a type if the type implements t or a pointer to the type implements t. If the provided type is not
   135  // an interface (i.e. t.Kind() != reflect.Interface), this method will panic.
   136  //
   137  // Deprecated: Use Registry.RegisterInterfaceDecoder instead.
   138  func (rb *RegistryBuilder) RegisterHookDecoder(t reflect.Type, dec ValueDecoder) *RegistryBuilder {
   139  	rb.registry.RegisterInterfaceDecoder(t, dec)
   140  	return rb
   141  }
   142  
   143  // RegisterEncoder registers the provided type and encoder pair.
   144  //
   145  // Deprecated: Use Registry.RegisterTypeEncoder or Registry.RegisterInterfaceEncoder instead.
   146  func (rb *RegistryBuilder) RegisterEncoder(t reflect.Type, enc ValueEncoder) *RegistryBuilder {
   147  	if t == tEmpty {
   148  		rb.registry.RegisterTypeEncoder(t, enc)
   149  		return rb
   150  	}
   151  	switch t.Kind() {
   152  	case reflect.Interface:
   153  		rb.registry.RegisterInterfaceEncoder(t, enc)
   154  	default:
   155  		rb.registry.RegisterTypeEncoder(t, enc)
   156  	}
   157  	return rb
   158  }
   159  
   160  // RegisterDecoder registers the provided type and decoder pair.
   161  //
   162  // Deprecated: Use Registry.RegisterTypeDecoder or Registry.RegisterInterfaceDecoder instead.
   163  func (rb *RegistryBuilder) RegisterDecoder(t reflect.Type, dec ValueDecoder) *RegistryBuilder {
   164  	if t == nil {
   165  		rb.registry.RegisterTypeDecoder(t, dec)
   166  		return rb
   167  	}
   168  	if t == tEmpty {
   169  		rb.registry.RegisterTypeDecoder(t, dec)
   170  		return rb
   171  	}
   172  	switch t.Kind() {
   173  	case reflect.Interface:
   174  		rb.registry.RegisterInterfaceDecoder(t, dec)
   175  	default:
   176  		rb.registry.RegisterTypeDecoder(t, dec)
   177  	}
   178  	return rb
   179  }
   180  
   181  // RegisterDefaultEncoder will register the provided ValueEncoder to the provided
   182  // kind.
   183  //
   184  // Deprecated: Use Registry.RegisterKindEncoder instead.
   185  func (rb *RegistryBuilder) RegisterDefaultEncoder(kind reflect.Kind, enc ValueEncoder) *RegistryBuilder {
   186  	rb.registry.RegisterKindEncoder(kind, enc)
   187  	return rb
   188  }
   189  
   190  // RegisterDefaultDecoder will register the provided ValueDecoder to the
   191  // provided kind.
   192  //
   193  // Deprecated: Use Registry.RegisterKindDecoder instead.
   194  func (rb *RegistryBuilder) RegisterDefaultDecoder(kind reflect.Kind, dec ValueDecoder) *RegistryBuilder {
   195  	rb.registry.RegisterKindDecoder(kind, dec)
   196  	return rb
   197  }
   198  
   199  // RegisterTypeMapEntry will register the provided type to the BSON type. The primary usage for this
   200  // mapping is decoding situations where an empty interface is used and a default type needs to be
   201  // created and decoded into.
   202  //
   203  // By default, BSON documents will decode into interface{} values as bson.D. To change the default type for BSON
   204  // documents, a type map entry for bsontype.EmbeddedDocument should be registered. For example, to force BSON documents
   205  // to decode to bson.Raw, use the following code:
   206  //
   207  //	rb.RegisterTypeMapEntry(bsontype.EmbeddedDocument, reflect.TypeOf(bson.Raw{}))
   208  //
   209  // Deprecated: Use Registry.RegisterTypeMapEntry instead.
   210  func (rb *RegistryBuilder) RegisterTypeMapEntry(bt bsontype.Type, rt reflect.Type) *RegistryBuilder {
   211  	rb.registry.RegisterTypeMapEntry(bt, rt)
   212  	return rb
   213  }
   214  
   215  // Build creates a Registry from the current state of this RegistryBuilder.
   216  //
   217  // Deprecated: Use NewRegistry instead.
   218  func (rb *RegistryBuilder) Build() *Registry {
   219  	r := &Registry{
   220  		interfaceEncoders: append([]interfaceValueEncoder(nil), rb.registry.interfaceEncoders...),
   221  		interfaceDecoders: append([]interfaceValueDecoder(nil), rb.registry.interfaceDecoders...),
   222  		typeEncoders:      rb.registry.typeEncoders.Clone(),
   223  		typeDecoders:      rb.registry.typeDecoders.Clone(),
   224  		kindEncoders:      rb.registry.kindEncoders.Clone(),
   225  		kindDecoders:      rb.registry.kindDecoders.Clone(),
   226  	}
   227  	rb.registry.typeMap.Range(func(k, v interface{}) bool {
   228  		if k != nil && v != nil {
   229  			r.typeMap.Store(k, v)
   230  		}
   231  		return true
   232  	})
   233  	return r
   234  }
   235  
   236  // A Registry is used to store and retrieve codecs for types and interfaces. This type is the main
   237  // typed passed around and Encoders and Decoders are constructed from it.
   238  type Registry struct {
   239  	interfaceEncoders []interfaceValueEncoder
   240  	interfaceDecoders []interfaceValueDecoder
   241  	typeEncoders      *typeEncoderCache
   242  	typeDecoders      *typeDecoderCache
   243  	kindEncoders      *kindEncoderCache
   244  	kindDecoders      *kindDecoderCache
   245  	typeMap           sync.Map // map[bsontype.Type]reflect.Type
   246  }
   247  
   248  // NewRegistry creates a new empty Registry.
   249  func NewRegistry() *Registry {
   250  	return &Registry{
   251  		typeEncoders: new(typeEncoderCache),
   252  		typeDecoders: new(typeDecoderCache),
   253  		kindEncoders: new(kindEncoderCache),
   254  		kindDecoders: new(kindDecoderCache),
   255  	}
   256  }
   257  
   258  // RegisterTypeEncoder registers the provided ValueEncoder for the provided type.
   259  //
   260  // The type will be used as provided, so an encoder can be registered for a type and a different
   261  // encoder can be registered for a pointer to that type.
   262  //
   263  // If the given type is an interface, the encoder will be called when marshaling a type that is
   264  // that interface. It will not be called when marshaling a non-interface type that implements the
   265  // interface. To get the latter behavior, call RegisterHookEncoder instead.
   266  //
   267  // RegisterTypeEncoder should not be called concurrently with any other Registry method.
   268  func (r *Registry) RegisterTypeEncoder(valueType reflect.Type, enc ValueEncoder) {
   269  	r.typeEncoders.Store(valueType, enc)
   270  }
   271  
   272  // RegisterTypeDecoder registers the provided ValueDecoder for the provided type.
   273  //
   274  // The type will be used as provided, so a decoder can be registered for a type and a different
   275  // decoder can be registered for a pointer to that type.
   276  //
   277  // If the given type is an interface, the decoder will be called when unmarshaling into a type that
   278  // is that interface. It will not be called when unmarshaling into a non-interface type that
   279  // implements the interface. To get the latter behavior, call RegisterHookDecoder instead.
   280  //
   281  // RegisterTypeDecoder should not be called concurrently with any other Registry method.
   282  func (r *Registry) RegisterTypeDecoder(valueType reflect.Type, dec ValueDecoder) {
   283  	r.typeDecoders.Store(valueType, dec)
   284  }
   285  
   286  // RegisterKindEncoder registers the provided ValueEncoder for the provided kind.
   287  //
   288  // Use RegisterKindEncoder to register an encoder for any type with the same underlying kind. For
   289  // example, consider the type MyInt defined as
   290  //
   291  //	type MyInt int32
   292  //
   293  // To define an encoder for MyInt and int32, use RegisterKindEncoder like
   294  //
   295  //	reg.RegisterKindEncoder(reflect.Int32, myEncoder)
   296  //
   297  // RegisterKindEncoder should not be called concurrently with any other Registry method.
   298  func (r *Registry) RegisterKindEncoder(kind reflect.Kind, enc ValueEncoder) {
   299  	r.kindEncoders.Store(kind, enc)
   300  }
   301  
   302  // RegisterKindDecoder registers the provided ValueDecoder for the provided kind.
   303  //
   304  // Use RegisterKindDecoder to register a decoder for any type with the same underlying kind. For
   305  // example, consider the type MyInt defined as
   306  //
   307  //	type MyInt int32
   308  //
   309  // To define an decoder for MyInt and int32, use RegisterKindDecoder like
   310  //
   311  //	reg.RegisterKindDecoder(reflect.Int32, myDecoder)
   312  //
   313  // RegisterKindDecoder should not be called concurrently with any other Registry method.
   314  func (r *Registry) RegisterKindDecoder(kind reflect.Kind, dec ValueDecoder) {
   315  	r.kindDecoders.Store(kind, dec)
   316  }
   317  
   318  // RegisterInterfaceEncoder registers an encoder for the provided interface type iface. This encoder will
   319  // be called when marshaling a type if the type implements iface or a pointer to the type
   320  // implements iface. If the provided type is not an interface
   321  // (i.e. iface.Kind() != reflect.Interface), this method will panic.
   322  //
   323  // RegisterInterfaceEncoder should not be called concurrently with any other Registry method.
   324  func (r *Registry) RegisterInterfaceEncoder(iface reflect.Type, enc ValueEncoder) {
   325  	if iface.Kind() != reflect.Interface {
   326  		panicStr := fmt.Errorf("RegisterInterfaceEncoder expects a type with kind reflect.Interface, "+
   327  			"got type %s with kind %s", iface, iface.Kind())
   328  		panic(panicStr)
   329  	}
   330  
   331  	for idx, encoder := range r.interfaceEncoders {
   332  		if encoder.i == iface {
   333  			r.interfaceEncoders[idx].ve = enc
   334  			return
   335  		}
   336  	}
   337  
   338  	r.interfaceEncoders = append(r.interfaceEncoders, interfaceValueEncoder{i: iface, ve: enc})
   339  }
   340  
   341  // RegisterInterfaceDecoder registers an decoder for the provided interface type iface. This decoder will
   342  // be called when unmarshaling into a type if the type implements iface or a pointer to the type
   343  // implements iface. If the provided type is not an interface (i.e. iface.Kind() != reflect.Interface),
   344  // this method will panic.
   345  //
   346  // RegisterInterfaceDecoder should not be called concurrently with any other Registry method.
   347  func (r *Registry) RegisterInterfaceDecoder(iface reflect.Type, dec ValueDecoder) {
   348  	if iface.Kind() != reflect.Interface {
   349  		panicStr := fmt.Errorf("RegisterInterfaceDecoder expects a type with kind reflect.Interface, "+
   350  			"got type %s with kind %s", iface, iface.Kind())
   351  		panic(panicStr)
   352  	}
   353  
   354  	for idx, decoder := range r.interfaceDecoders {
   355  		if decoder.i == iface {
   356  			r.interfaceDecoders[idx].vd = dec
   357  			return
   358  		}
   359  	}
   360  
   361  	r.interfaceDecoders = append(r.interfaceDecoders, interfaceValueDecoder{i: iface, vd: dec})
   362  }
   363  
   364  // RegisterTypeMapEntry will register the provided type to the BSON type. The primary usage for this
   365  // mapping is decoding situations where an empty interface is used and a default type needs to be
   366  // created and decoded into.
   367  //
   368  // By default, BSON documents will decode into interface{} values as bson.D. To change the default type for BSON
   369  // documents, a type map entry for bsontype.EmbeddedDocument should be registered. For example, to force BSON documents
   370  // to decode to bson.Raw, use the following code:
   371  //
   372  //	reg.RegisterTypeMapEntry(bsontype.EmbeddedDocument, reflect.TypeOf(bson.Raw{}))
   373  func (r *Registry) RegisterTypeMapEntry(bt bsontype.Type, rt reflect.Type) {
   374  	r.typeMap.Store(bt, rt)
   375  }
   376  
   377  // LookupEncoder returns the first matching encoder in the Registry. It uses the following lookup
   378  // order:
   379  //
   380  // 1. An encoder registered for the exact type. If the given type is an interface, an encoder
   381  // registered using RegisterTypeEncoder for that interface will be selected.
   382  //
   383  // 2. An encoder registered using RegisterInterfaceEncoder for an interface implemented by the type
   384  // or by a pointer to the type.
   385  //
   386  // 3. An encoder registered using RegisterKindEncoder for the kind of value.
   387  //
   388  // If no encoder is found, an error of type ErrNoEncoder is returned. LookupEncoder is safe for
   389  // concurrent use by multiple goroutines after all codecs and encoders are registered.
   390  func (r *Registry) LookupEncoder(valueType reflect.Type) (ValueEncoder, error) {
   391  	if valueType == nil {
   392  		return nil, ErrNoEncoder{Type: valueType}
   393  	}
   394  	enc, found := r.lookupTypeEncoder(valueType)
   395  	if found {
   396  		if enc == nil {
   397  			return nil, ErrNoEncoder{Type: valueType}
   398  		}
   399  		return enc, nil
   400  	}
   401  
   402  	enc, found = r.lookupInterfaceEncoder(valueType, true)
   403  	if found {
   404  		return r.typeEncoders.LoadOrStore(valueType, enc), nil
   405  	}
   406  
   407  	if v, ok := r.kindEncoders.Load(valueType.Kind()); ok {
   408  		return r.storeTypeEncoder(valueType, v), nil
   409  	}
   410  	return nil, ErrNoEncoder{Type: valueType}
   411  }
   412  
   413  func (r *Registry) storeTypeEncoder(rt reflect.Type, enc ValueEncoder) ValueEncoder {
   414  	return r.typeEncoders.LoadOrStore(rt, enc)
   415  }
   416  
   417  func (r *Registry) lookupTypeEncoder(rt reflect.Type) (ValueEncoder, bool) {
   418  	return r.typeEncoders.Load(rt)
   419  }
   420  
   421  func (r *Registry) lookupInterfaceEncoder(valueType reflect.Type, allowAddr bool) (ValueEncoder, bool) {
   422  	if valueType == nil {
   423  		return nil, false
   424  	}
   425  	for _, ienc := range r.interfaceEncoders {
   426  		if valueType.Implements(ienc.i) {
   427  			return ienc.ve, true
   428  		}
   429  		if allowAddr && valueType.Kind() != reflect.Ptr && reflect.PtrTo(valueType).Implements(ienc.i) {
   430  			// if *t implements an interface, this will catch if t implements an interface further
   431  			// ahead in interfaceEncoders
   432  			defaultEnc, found := r.lookupInterfaceEncoder(valueType, false)
   433  			if !found {
   434  				defaultEnc, _ = r.kindEncoders.Load(valueType.Kind())
   435  			}
   436  			return newCondAddrEncoder(ienc.ve, defaultEnc), true
   437  		}
   438  	}
   439  	return nil, false
   440  }
   441  
   442  // LookupDecoder returns the first matching decoder in the Registry. It uses the following lookup
   443  // order:
   444  //
   445  // 1. A decoder registered for the exact type. If the given type is an interface, a decoder
   446  // registered using RegisterTypeDecoder for that interface will be selected.
   447  //
   448  // 2. A decoder registered using RegisterInterfaceDecoder for an interface implemented by the type or by
   449  // a pointer to the type.
   450  //
   451  // 3. A decoder registered using RegisterKindDecoder for the kind of value.
   452  //
   453  // If no decoder is found, an error of type ErrNoDecoder is returned. LookupDecoder is safe for
   454  // concurrent use by multiple goroutines after all codecs and decoders are registered.
   455  func (r *Registry) LookupDecoder(valueType reflect.Type) (ValueDecoder, error) {
   456  	if valueType == nil {
   457  		return nil, ErrNilType
   458  	}
   459  	dec, found := r.lookupTypeDecoder(valueType)
   460  	if found {
   461  		if dec == nil {
   462  			return nil, ErrNoDecoder{Type: valueType}
   463  		}
   464  		return dec, nil
   465  	}
   466  
   467  	dec, found = r.lookupInterfaceDecoder(valueType, true)
   468  	if found {
   469  		return r.storeTypeDecoder(valueType, dec), nil
   470  	}
   471  
   472  	if v, ok := r.kindDecoders.Load(valueType.Kind()); ok {
   473  		return r.storeTypeDecoder(valueType, v), nil
   474  	}
   475  	return nil, ErrNoDecoder{Type: valueType}
   476  }
   477  
   478  func (r *Registry) lookupTypeDecoder(valueType reflect.Type) (ValueDecoder, bool) {
   479  	return r.typeDecoders.Load(valueType)
   480  }
   481  
   482  func (r *Registry) storeTypeDecoder(typ reflect.Type, dec ValueDecoder) ValueDecoder {
   483  	return r.typeDecoders.LoadOrStore(typ, dec)
   484  }
   485  
   486  func (r *Registry) lookupInterfaceDecoder(valueType reflect.Type, allowAddr bool) (ValueDecoder, bool) {
   487  	for _, idec := range r.interfaceDecoders {
   488  		if valueType.Implements(idec.i) {
   489  			return idec.vd, true
   490  		}
   491  		if allowAddr && valueType.Kind() != reflect.Ptr && reflect.PtrTo(valueType).Implements(idec.i) {
   492  			// if *t implements an interface, this will catch if t implements an interface further
   493  			// ahead in interfaceDecoders
   494  			defaultDec, found := r.lookupInterfaceDecoder(valueType, false)
   495  			if !found {
   496  				defaultDec, _ = r.kindDecoders.Load(valueType.Kind())
   497  			}
   498  			return newCondAddrDecoder(idec.vd, defaultDec), true
   499  		}
   500  	}
   501  	return nil, false
   502  }
   503  
   504  // LookupTypeMapEntry inspects the registry's type map for a Go type for the corresponding BSON
   505  // type. If no type is found, ErrNoTypeMapEntry is returned.
   506  //
   507  // LookupTypeMapEntry should not be called concurrently with any other Registry method.
   508  func (r *Registry) LookupTypeMapEntry(bt bsontype.Type) (reflect.Type, error) {
   509  	v, ok := r.typeMap.Load(bt)
   510  	if v == nil || !ok {
   511  		return nil, ErrNoTypeMapEntry{Type: bt}
   512  	}
   513  	return v.(reflect.Type), nil
   514  }
   515  
   516  type interfaceValueEncoder struct {
   517  	i  reflect.Type
   518  	ve ValueEncoder
   519  }
   520  
   521  type interfaceValueDecoder struct {
   522  	i  reflect.Type
   523  	vd ValueDecoder
   524  }
   525
View as plain text