arshal_funcs.go

     1  // Copyright 2020 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  //go:build goexperiment.jsonv2
     6  
     7  package json
     8  
     9  import (
    10  	"errors"
    11  	"fmt"
    12  	"io"
    13  	"reflect"
    14  	"sync"
    15  
    16  	"encoding/json/internal"
    17  	"encoding/json/internal/jsonflags"
    18  	"encoding/json/internal/jsonopts"
    19  	"encoding/json/jsontext"
    20  )
    21  
    22  var errUnsupportedMutation = errors.New("unsupported calls must not read or write any tokens")
    23  var errNonSingularValue = errors.New("must read or write exactly one value")
    24  
    25  // Marshalers is a list of functions that may override the marshal behavior
    26  // of specific types. Populate [WithMarshalers] to use it with
    27  // [Marshal], [MarshalWrite], or [MarshalEncode].
    28  // A nil *Marshalers is equivalent to an empty list.
    29  // There are no exported fields or methods on Marshalers.
    30  type Marshalers = typedMarshalers
    31  
    32  // JoinMarshalers constructs a flattened list of marshal functions.
    33  // If multiple functions in the list are applicable for a value of a given type,
    34  // then those earlier in the list take precedence over those that come later.
    35  // If a function returns [errors.ErrUnsupported],
    36  // then the next applicable function is called,
    37  // otherwise the default marshaling behavior is used.
    38  //
    39  // For example:
    40  //
    41  //	m1 := JoinMarshalers(f1, f2)
    42  //	m2 := JoinMarshalers(f0, m1, f3)     // equivalent to m3
    43  //	m3 := JoinMarshalers(f0, f1, f2, f3) // equivalent to m2
    44  func JoinMarshalers(ms ...*Marshalers) *Marshalers {
    45  	return newMarshalers(ms...)
    46  }
    47  
    48  // Unmarshalers is a list of functions that may override the unmarshal behavior
    49  // of specific types. Populate [WithUnmarshalers] to use it with
    50  // [Unmarshal], [UnmarshalRead], or [UnmarshalDecode].
    51  // A nil *Unmarshalers is equivalent to an empty list.
    52  // There are no exported fields or methods on Unmarshalers.
    53  type Unmarshalers = typedUnmarshalers
    54  
    55  // JoinUnmarshalers constructs a flattened list of unmarshal functions.
    56  // If multiple functions in the list are applicable for a value of a given type,
    57  // then those earlier in the list take precedence over those that come later.
    58  // If a function returns [errors.ErrUnsupported],
    59  // then the next applicable function is called,
    60  // otherwise the default unmarshaling behavior is used.
    61  //
    62  // For example:
    63  //
    64  //	u1 := JoinUnmarshalers(f1, f2)
    65  //	u2 := JoinUnmarshalers(f0, u1, f3)     // equivalent to u3
    66  //	u3 := JoinUnmarshalers(f0, f1, f2, f3) // equivalent to u2
    67  func JoinUnmarshalers(us ...*Unmarshalers) *Unmarshalers {
    68  	return newUnmarshalers(us...)
    69  }
    70  
    71  type typedMarshalers = typedArshalers[jsontext.Encoder]
    72  type typedUnmarshalers = typedArshalers[jsontext.Decoder]
    73  type typedArshalers[Coder any] struct {
    74  	nonComparable
    75  
    76  	fncVals  []typedArshaler[Coder]
    77  	fncCache sync.Map // map[reflect.Type]arshaler
    78  
    79  	// fromAny reports whether any of Go types used to represent arbitrary JSON
    80  	// (i.e., any, bool, string, float64, map[string]any, or []any) matches
    81  	// any of the provided type-specific arshalers.
    82  	//
    83  	// This bit of information is needed in arshal_default.go to determine
    84  	// whether to use the specialized logic in arshal_any.go to handle
    85  	// the any interface type. The logic in arshal_any.go does not support
    86  	// type-specific arshal functions, so we must avoid using that logic
    87  	// if this is true.
    88  	fromAny bool
    89  }
    90  type typedMarshaler = typedArshaler[jsontext.Encoder]
    91  type typedUnmarshaler = typedArshaler[jsontext.Decoder]
    92  type typedArshaler[Coder any] struct {
    93  	typ     reflect.Type
    94  	fnc     func(*Coder, addressableValue, *jsonopts.Struct) error
    95  	maySkip bool
    96  }
    97  
    98  func newMarshalers(ms ...*Marshalers) *Marshalers       { return newTypedArshalers(ms...) }
    99  func newUnmarshalers(us ...*Unmarshalers) *Unmarshalers { return newTypedArshalers(us...) }
   100  func newTypedArshalers[Coder any](as ...*typedArshalers[Coder]) *typedArshalers[Coder] {
   101  	var a typedArshalers[Coder]
   102  	for _, a2 := range as {
   103  		if a2 != nil {
   104  			a.fncVals = append(a.fncVals, a2.fncVals...)
   105  			a.fromAny = a.fromAny || a2.fromAny
   106  		}
   107  	}
   108  	if len(a.fncVals) == 0 {
   109  		return nil
   110  	}
   111  	return &a
   112  }
   113  
   114  func (a *typedArshalers[Coder]) lookup(fnc func(*Coder, addressableValue, *jsonopts.Struct) error, t reflect.Type) (func(*Coder, addressableValue, *jsonopts.Struct) error, bool) {
   115  	if a == nil {
   116  		return fnc, false
   117  	}
   118  	if v, ok := a.fncCache.Load(t); ok {
   119  		if v == nil {
   120  			return fnc, false
   121  		}
   122  		return v.(func(*Coder, addressableValue, *jsonopts.Struct) error), true
   123  	}
   124  
   125  	// Collect a list of arshalers that can be called for this type.
   126  	// This list may be longer than 1 since some arshalers can be skipped.
   127  	var fncs []func(*Coder, addressableValue, *jsonopts.Struct) error
   128  	for _, fncVal := range a.fncVals {
   129  		if !castableTo(t, fncVal.typ) {
   130  			continue
   131  		}
   132  		fncs = append(fncs, fncVal.fnc)
   133  		if !fncVal.maySkip {
   134  			break // subsequent arshalers will never be called
   135  		}
   136  	}
   137  
   138  	if len(fncs) == 0 {
   139  		a.fncCache.Store(t, nil) // nil to indicate that no funcs found
   140  		return fnc, false
   141  	}
   142  
   143  	// Construct an arshaler that may call every applicable arshaler.
   144  	fncDefault := fnc
   145  	fnc = func(c *Coder, v addressableValue, o *jsonopts.Struct) error {
   146  		for _, fnc := range fncs {
   147  			if err := fnc(c, v, o); !errors.Is(err, errors.ErrUnsupported) {
   148  				return err // may be nil or non-nil
   149  			}
   150  		}
   151  		return fncDefault(c, v, o)
   152  	}
   153  
   154  	// Use the first stored so duplicate work can be garbage collected.
   155  	v, _ := a.fncCache.LoadOrStore(t, fnc)
   156  	return v.(func(*Coder, addressableValue, *jsonopts.Struct) error), true
   157  }
   158  
   159  // MarshalFunc constructs a type-specific marshaler that
   160  // specifies how to marshal values of type T.
   161  // T can be any type except a named pointer.
   162  // The function is always provided with a non-nil pointer value
   163  // if T is an interface or pointer type.
   164  //
   165  // The function must marshal exactly one JSON value.
   166  // The value of T must not be retained outside the function call.
   167  // It is recommended that fn return a []byte buffer that is safe
   168  // for the caller to retain and potentially mutate.
   169  // It may not return [errors.ErrUnsupported].
   170  func MarshalFunc[T any](fn func(T) ([]byte, error)) *Marshalers {
   171  	t := reflect.TypeFor[T]()
   172  	assertCastableTo(t, true)
   173  	typFnc := typedMarshaler{
   174  		typ: t,
   175  		fnc: func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) error {
   176  			v, _ := reflect.TypeAssert[T](va.castTo(t))
   177  			val, err := fn(v)
   178  			if err != nil {
   179  				err = wrapErrUnsupported(err, "marshal function of type func(T) ([]byte, error)")
   180  				if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
   181  					return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalFunc") // unlike unmarshal, always wrapped
   182  				}
   183  				err = newMarshalErrorBefore(enc, t, err)
   184  				return collapseSemanticErrors(err)
   185  			}
   186  			if err := enc.WriteValue(val); err != nil {
   187  				if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
   188  					return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalFunc") // unlike unmarshal, always wrapped
   189  				}
   190  				if isSyntacticError(err) {
   191  					err = newMarshalErrorBefore(enc, t, err)
   192  				}
   193  				return err
   194  			}
   195  			return nil
   196  		},
   197  	}
   198  	return &Marshalers{fncVals: []typedMarshaler{typFnc}, fromAny: castableToFromAny(t)}
   199  }
   200  
   201  // MarshalToFunc constructs a type-specific marshaler that
   202  // specifies how to marshal values of type T.
   203  // T can be any type except a named pointer.
   204  // The function is always provided with a non-nil pointer value
   205  // if T is an interface or pointer type.
   206  //
   207  // The function must marshal exactly one JSON value by calling write methods
   208  // on the provided encoder. It may return [errors.ErrUnsupported] such that marshaling can
   209  // move on to the next marshal function. However, no mutable method calls may
   210  // be called on the encoder if [errors.ErrUnsupported] is returned.
   211  // The pointer to [jsontext.Encoder] and the value of T
   212  // must not be retained outside the function call.
   213  func MarshalToFunc[T any](fn func(*jsontext.Encoder, T) error) *Marshalers {
   214  	t := reflect.TypeFor[T]()
   215  	assertCastableTo(t, true)
   216  	typFnc := typedMarshaler{
   217  		typ: t,
   218  		fnc: func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) error {
   219  			xe := export.Encoder(enc)
   220  			prevDepth, prevLength := xe.Tokens.DepthLength()
   221  			xe.Flags.Set(jsonflags.WithinArshalCall | 1)
   222  			v, _ := reflect.TypeAssert[T](va.castTo(t))
   223  			err := fn(enc, v)
   224  			xe.Flags.Set(jsonflags.WithinArshalCall | 0)
   225  			currDepth, currLength := xe.Tokens.DepthLength()
   226  			if err == nil && (prevDepth != currDepth || prevLength+1 != currLength) {
   227  				err = errNonSingularValue
   228  			}
   229  			if err != nil {
   230  				if errors.Is(err, errors.ErrUnsupported) {
   231  					if prevDepth == currDepth && prevLength == currLength {
   232  						return err // forward [errors.ErrUnsupported]
   233  					}
   234  					err = errUnsupportedMutation
   235  				}
   236  				if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
   237  					return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalToFunc") // unlike unmarshal, always wrapped
   238  				}
   239  				if !export.IsIOError(err) {
   240  					err = newSemanticErrorWithPosition(enc, t, prevDepth, prevLength, err)
   241  				}
   242  				return err
   243  			}
   244  			return nil
   245  		},
   246  		maySkip: true,
   247  	}
   248  	return &Marshalers{fncVals: []typedMarshaler{typFnc}, fromAny: castableToFromAny(t)}
   249  }
   250  
   251  // UnmarshalFunc constructs a type-specific unmarshaler that
   252  // specifies how to unmarshal values of type T.
   253  // T must be an unnamed pointer or an interface type.
   254  // The function is always provided with a non-nil pointer value.
   255  //
   256  // The function must unmarshal exactly one JSON value.
   257  // The input []byte must not be mutated.
   258  // The input []byte and value T must not be retained outside the function call.
   259  // It may not return [errors.ErrUnsupported].
   260  func UnmarshalFunc[T any](fn func([]byte, T) error) *Unmarshalers {
   261  	t := reflect.TypeFor[T]()
   262  	assertCastableTo(t, false)
   263  	typFnc := typedUnmarshaler{
   264  		typ: t,
   265  		fnc: func(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct) error {
   266  			val, err := dec.ReadValue()
   267  			if err != nil {
   268  				return err // must be a syntactic or I/O error
   269  			}
   270  			v, _ := reflect.TypeAssert[T](va.castTo(t))
   271  			err = fn(val, v)
   272  			if err != nil {
   273  				err = wrapErrUnsupported(err, "unmarshal function of type func([]byte, T) error")
   274  				if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
   275  					return err // unlike marshal, never wrapped
   276  				}
   277  				err = newUnmarshalErrorAfter(dec, t, err)
   278  				return collapseSemanticErrors(err)
   279  			}
   280  			return nil
   281  		},
   282  	}
   283  	return &Unmarshalers{fncVals: []typedUnmarshaler{typFnc}, fromAny: castableToFromAny(t)}
   284  }
   285  
   286  // UnmarshalFromFunc constructs a type-specific unmarshaler that
   287  // specifies how to unmarshal values of type T.
   288  // T must be an unnamed pointer or an interface type.
   289  // The function is always provided with a non-nil pointer value.
   290  //
   291  // The function must unmarshal exactly one JSON value by calling read methods
   292  // on the provided decoder. It may return [errors.ErrUnsupported] such that unmarshaling can
   293  // move on to the next unmarshal function. However, no mutable method calls may
   294  // be called on the decoder if [errors.ErrUnsupported] is returned.
   295  // The pointer to [jsontext.Decoder] and the value of T
   296  // must not be retained outside the function call.
   297  func UnmarshalFromFunc[T any](fn func(*jsontext.Decoder, T) error) *Unmarshalers {
   298  	t := reflect.TypeFor[T]()
   299  	assertCastableTo(t, false)
   300  	typFnc := typedUnmarshaler{
   301  		typ: t,
   302  		fnc: func(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct) error {
   303  			xd := export.Decoder(dec)
   304  			prevDepth, prevLength := xd.Tokens.DepthLength()
   305  			if prevDepth == 1 && xd.AtEOF() {
   306  				return io.EOF // check EOF early to avoid fn reporting an EOF
   307  			}
   308  			xd.Flags.Set(jsonflags.WithinArshalCall | 1)
   309  			v, _ := reflect.TypeAssert[T](va.castTo(t))
   310  			err := fn(dec, v)
   311  			xd.Flags.Set(jsonflags.WithinArshalCall | 0)
   312  			currDepth, currLength := xd.Tokens.DepthLength()
   313  			if err == nil && (prevDepth != currDepth || prevLength+1 != currLength) {
   314  				err = errNonSingularValue
   315  			}
   316  			if err != nil {
   317  				if errors.Is(err, errors.ErrUnsupported) {
   318  					if prevDepth == currDepth && prevLength == currLength {
   319  						return err // forward [errors.ErrUnsupported]
   320  					}
   321  					err = errUnsupportedMutation
   322  				}
   323  				if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
   324  					if err2 := xd.SkipUntil(prevDepth, prevLength+1); err2 != nil {
   325  						return err2
   326  					}
   327  					return err // unlike marshal, never wrapped
   328  				}
   329  				if !isSyntacticError(err) && !export.IsIOError(err) {
   330  					err = newSemanticErrorWithPosition(dec, t, prevDepth, prevLength, err)
   331  				}
   332  				return err
   333  			}
   334  			return nil
   335  		},
   336  		maySkip: true,
   337  	}
   338  	return &Unmarshalers{fncVals: []typedUnmarshaler{typFnc}, fromAny: castableToFromAny(t)}
   339  }
   340  
   341  // assertCastableTo asserts that "to" is a valid type to be casted to.
   342  // These are the Go types that type-specific arshalers may operate upon.
   343  //
   344  // Let AllTypes be the universal set of all possible Go types.
   345  // This function generally asserts that:
   346  //
   347  //	len([from for from in AllTypes if castableTo(from, to)]) > 0
   348  //
   349  // otherwise it panics.
   350  //
   351  // As a special-case if marshal is false, then we forbid any non-pointer or
   352  // non-interface type since it is almost always a bug trying to unmarshal
   353  // into something where the end-user caller did not pass in an addressable value
   354  // since they will not observe the mutations.
   355  func assertCastableTo(to reflect.Type, marshal bool) {
   356  	switch to.Kind() {
   357  	case reflect.Interface:
   358  		return
   359  	case reflect.Pointer:
   360  		// Only allow unnamed pointers to be consistent with the fact that
   361  		// taking the address of a value produces an unnamed pointer type.
   362  		if to.Name() == "" {
   363  			return
   364  		}
   365  	default:
   366  		// Technically, non-pointer types are permissible for unmarshal.
   367  		// However, they are often a bug since the receiver would be immutable.
   368  		// Thus, only allow them for marshaling.
   369  		if marshal {
   370  			return
   371  		}
   372  	}
   373  	if marshal {
   374  		panic(fmt.Sprintf("input type %v must be an interface type, an unnamed pointer type, or a non-pointer type", to))
   375  	} else {
   376  		panic(fmt.Sprintf("input type %v must be an interface type or an unnamed pointer type", to))
   377  	}
   378  }
   379  
   380  // castableTo checks whether values of type "from" can be casted to type "to".
   381  // Nil pointer or interface "from" values are never considered castable.
   382  //
   383  // This function must be kept in sync with addressableValue.castTo.
   384  func castableTo(from, to reflect.Type) bool {
   385  	switch to.Kind() {
   386  	case reflect.Interface:
   387  		// TODO: This breaks when ordinary interfaces can have type sets
   388  		// since interfaces now exist where only the value form of a type (T)
   389  		// implements the interface, but not the pointer variant (*T).
   390  		// See https://go.dev/issue/45346.
   391  		return reflect.PointerTo(from).Implements(to)
   392  	case reflect.Pointer:
   393  		// Common case for unmarshaling.
   394  		// From must be a concrete or interface type.
   395  		return reflect.PointerTo(from) == to
   396  	default:
   397  		// Common case for marshaling.
   398  		// From must be a concrete type.
   399  		return from == to
   400  	}
   401  }
   402  
   403  // castTo casts va to the specified type.
   404  // If the type is an interface, then the underlying type will always
   405  // be a non-nil pointer to a concrete type.
   406  //
   407  // Requirement: castableTo(va.Type(), to) must hold.
   408  func (va addressableValue) castTo(to reflect.Type) reflect.Value {
   409  	switch to.Kind() {
   410  	case reflect.Interface:
   411  		return va.Addr().Convert(to)
   412  	case reflect.Pointer:
   413  		return va.Addr()
   414  	default:
   415  		return va.Value
   416  	}
   417  }
   418  
   419  // castableToFromAny reports whether "to" can be casted to from any
   420  // of the dynamic types used to represent arbitrary JSON.
   421  func castableToFromAny(to reflect.Type) bool {
   422  	for _, from := range []reflect.Type{anyType, boolType, stringType, float64Type, mapStringAnyType, sliceAnyType} {
   423  		if castableTo(from, to) {
   424  			return true
   425  		}
   426  	}
   427  	return false
   428  }
   429
View as plain text