arshal_funcs.go 15 KB

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