arshal_methods.go 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362
  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. "encoding"
  7. "errors"
  8. "reflect"
  9. "github.com/go-json-experiment/json/internal"
  10. "github.com/go-json-experiment/json/internal/jsonflags"
  11. "github.com/go-json-experiment/json/internal/jsonopts"
  12. "github.com/go-json-experiment/json/internal/jsonwire"
  13. "github.com/go-json-experiment/json/jsontext"
  14. )
  15. var errNonStringValue = errors.New("JSON value must be string type")
  16. // Interfaces for custom serialization.
  17. var (
  18. jsonMarshalerType = reflect.TypeFor[Marshaler]()
  19. jsonMarshalerToType = reflect.TypeFor[MarshalerTo]()
  20. jsonUnmarshalerType = reflect.TypeFor[Unmarshaler]()
  21. jsonUnmarshalerFromType = reflect.TypeFor[UnmarshalerFrom]()
  22. textAppenderType = reflect.TypeFor[encodingTextAppender]()
  23. textMarshalerType = reflect.TypeFor[encoding.TextMarshaler]()
  24. textUnmarshalerType = reflect.TypeFor[encoding.TextUnmarshaler]()
  25. // TODO(https://go.dev/issue/62384): Use encoding.TextAppender instead of this hack.
  26. // This exists for now to provide performance benefits to netip types.
  27. // There is no semantic difference with this change.
  28. appenderToType = reflect.TypeFor[interface{ AppendTo([]byte) []byte }]()
  29. allMarshalerTypes = []reflect.Type{jsonMarshalerToType, jsonMarshalerType, textAppenderType, textMarshalerType}
  30. allUnmarshalerTypes = []reflect.Type{jsonUnmarshalerFromType, jsonUnmarshalerType, textUnmarshalerType}
  31. allMethodTypes = append(allMarshalerTypes, allUnmarshalerTypes...)
  32. )
  33. // TODO(https://go.dev/issue/62384): Use encoding.TextAppender instead
  34. // and document public support for this method in json.Marshal.
  35. type encodingTextAppender interface {
  36. AppendText(b []byte) ([]byte, error)
  37. }
  38. // Marshaler is implemented by types that can marshal themselves.
  39. // It is recommended that types implement [MarshalerTo] unless the implementation
  40. // is trying to avoid a hard dependency on the "jsontext" package.
  41. //
  42. // It is recommended that implementations return a buffer that is safe
  43. // for the caller to retain and potentially mutate.
  44. type Marshaler interface {
  45. MarshalJSON() ([]byte, error)
  46. }
  47. // MarshalerTo is implemented by types that can marshal themselves.
  48. // It is recommended that types implement MarshalerTo instead of [Marshaler]
  49. // since this is both more performant and flexible.
  50. // If a type implements both Marshaler and MarshalerTo,
  51. // then MarshalerTo takes precedence. In such a case, both implementations
  52. // should aim to have equivalent behavior for the default marshal options.
  53. //
  54. // The implementation must write only one JSON value to the Encoder and
  55. // must not retain the pointer to [jsontext.Encoder] or the [Options] value.
  56. type MarshalerTo interface {
  57. MarshalJSONTo(*jsontext.Encoder, Options) error
  58. // TODO: Should users call the MarshalEncode function or
  59. // should/can they call this method directly? Does it matter?
  60. }
  61. // Unmarshaler is implemented by types that can unmarshal themselves.
  62. // It is recommended that types implement [UnmarshalerFrom] unless the implementation
  63. // is trying to avoid a hard dependency on the "jsontext" package.
  64. //
  65. // The input can be assumed to be a valid encoding of a JSON value
  66. // if called from unmarshal functionality in this package.
  67. // UnmarshalJSON must copy the JSON data if it is retained after returning.
  68. // It is recommended that UnmarshalJSON implement merge semantics when
  69. // unmarshaling into a pre-populated value.
  70. //
  71. // Implementations must not retain or mutate the input []byte.
  72. type Unmarshaler interface {
  73. UnmarshalJSON([]byte) error
  74. }
  75. // UnmarshalerFrom is implemented by types that can unmarshal themselves.
  76. // It is recommended that types implement UnmarshalerFrom instead of [Unmarshaler]
  77. // since this is both more performant and flexible.
  78. // If a type implements both Unmarshaler and UnmarshalerFrom,
  79. // then UnmarshalerFrom takes precedence. In such a case, both implementations
  80. // should aim to have equivalent behavior for the default unmarshal options.
  81. //
  82. // The implementation must read only one JSON value from the Decoder.
  83. // It is recommended that UnmarshalJSONFrom implement merge semantics when
  84. // unmarshaling into a pre-populated value.
  85. //
  86. // Implementations must not retain the pointer to [jsontext.Decoder] or
  87. // the [Options] value.
  88. type UnmarshalerFrom interface {
  89. UnmarshalJSONFrom(*jsontext.Decoder, Options) error
  90. // TODO: Should users call the UnmarshalDecode function or
  91. // should/can they call this method directly? Does it matter?
  92. }
  93. func makeMethodArshaler(fncs *arshaler, t reflect.Type) *arshaler {
  94. // Avoid injecting method arshaler on the pointer or interface version
  95. // to avoid ever calling the method on a nil pointer or interface receiver.
  96. // Let it be injected on the value receiver (which is always addressable).
  97. if t.Kind() == reflect.Pointer || t.Kind() == reflect.Interface {
  98. return fncs
  99. }
  100. if needAddr, ok := implements(t, textMarshalerType); ok {
  101. fncs.nonDefault = true
  102. prevMarshal := fncs.marshal
  103. fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) error {
  104. if mo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
  105. (needAddr && va.forcedAddr) {
  106. return prevMarshal(enc, va, mo)
  107. }
  108. marshaler := va.Addr().Interface().(encoding.TextMarshaler)
  109. if err := export.Encoder(enc).AppendRaw('"', false, func(b []byte) ([]byte, error) {
  110. b2, err := marshaler.MarshalText()
  111. return append(b, b2...), err
  112. }); err != nil {
  113. err = wrapSkipFunc(err, "marshal method")
  114. if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  115. return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalText") // unlike unmarshal, always wrapped
  116. }
  117. if !isSemanticError(err) && !export.IsIOError(err) {
  118. err = newMarshalErrorBefore(enc, t, err)
  119. }
  120. return err
  121. }
  122. return nil
  123. }
  124. // TODO(https://go.dev/issue/62384): Rely on encoding.TextAppender instead.
  125. if implementsAny(t, appenderToType) && t.PkgPath() == "net/netip" {
  126. fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) error {
  127. appender := va.Addr().Interface().(interface{ AppendTo([]byte) []byte })
  128. if err := export.Encoder(enc).AppendRaw('"', false, func(b []byte) ([]byte, error) {
  129. return appender.AppendTo(b), nil
  130. }); err != nil {
  131. if !isSemanticError(err) && !export.IsIOError(err) {
  132. err = newMarshalErrorBefore(enc, t, err)
  133. }
  134. return err
  135. }
  136. return nil
  137. }
  138. }
  139. }
  140. if needAddr, ok := implements(t, textAppenderType); ok {
  141. fncs.nonDefault = true
  142. prevMarshal := fncs.marshal
  143. fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) (err error) {
  144. if mo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
  145. (needAddr && va.forcedAddr) {
  146. return prevMarshal(enc, va, mo)
  147. }
  148. appender := va.Addr().Interface().(encodingTextAppender)
  149. if err := export.Encoder(enc).AppendRaw('"', false, appender.AppendText); err != nil {
  150. err = wrapSkipFunc(err, "append method")
  151. if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  152. return internal.NewMarshalerError(va.Addr().Interface(), err, "AppendText") // unlike unmarshal, always wrapped
  153. }
  154. if !isSemanticError(err) && !export.IsIOError(err) {
  155. err = newMarshalErrorBefore(enc, t, err)
  156. }
  157. return err
  158. }
  159. return nil
  160. }
  161. }
  162. if needAddr, ok := implements(t, jsonMarshalerType); ok {
  163. fncs.nonDefault = true
  164. prevMarshal := fncs.marshal
  165. fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) error {
  166. if mo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
  167. ((needAddr && va.forcedAddr) || export.Encoder(enc).Tokens.Last.NeedObjectName()) {
  168. return prevMarshal(enc, va, mo)
  169. }
  170. marshaler := va.Addr().Interface().(Marshaler)
  171. val, err := marshaler.MarshalJSON()
  172. if err != nil {
  173. err = wrapSkipFunc(err, "marshal method")
  174. if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  175. return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalJSON") // unlike unmarshal, always wrapped
  176. }
  177. err = newMarshalErrorBefore(enc, t, err)
  178. return collapseSemanticErrors(err)
  179. }
  180. if err := enc.WriteValue(val); err != nil {
  181. if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  182. return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalJSON") // unlike unmarshal, always wrapped
  183. }
  184. if isSyntacticError(err) {
  185. err = newMarshalErrorBefore(enc, t, err)
  186. }
  187. return err
  188. }
  189. return nil
  190. }
  191. }
  192. if needAddr, ok := implements(t, jsonMarshalerToType); ok {
  193. fncs.nonDefault = true
  194. prevMarshal := fncs.marshal
  195. fncs.marshal = func(enc *jsontext.Encoder, va addressableValue, mo *jsonopts.Struct) error {
  196. if mo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
  197. ((needAddr && va.forcedAddr) || export.Encoder(enc).Tokens.Last.NeedObjectName()) {
  198. return prevMarshal(enc, va, mo)
  199. }
  200. xe := export.Encoder(enc)
  201. prevDepth, prevLength := xe.Tokens.DepthLength()
  202. xe.Flags.Set(jsonflags.WithinArshalCall | 1)
  203. err := va.Addr().Interface().(MarshalerTo).MarshalJSONTo(enc, mo)
  204. xe.Flags.Set(jsonflags.WithinArshalCall | 0)
  205. currDepth, currLength := xe.Tokens.DepthLength()
  206. if (prevDepth != currDepth || prevLength+1 != currLength) && err == nil {
  207. err = errNonSingularValue
  208. }
  209. if err != nil {
  210. err = wrapSkipFunc(err, "marshal method")
  211. if mo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  212. return internal.NewMarshalerError(va.Addr().Interface(), err, "MarshalJSONTo") // unlike unmarshal, always wrapped
  213. }
  214. if !export.IsIOError(err) {
  215. err = newSemanticErrorWithPosition(enc, t, prevDepth, prevLength, err)
  216. }
  217. return err
  218. }
  219. return nil
  220. }
  221. }
  222. if _, ok := implements(t, textUnmarshalerType); ok {
  223. fncs.nonDefault = true
  224. fncs.unmarshal = func(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct) error {
  225. xd := export.Decoder(dec)
  226. var flags jsonwire.ValueFlags
  227. val, err := xd.ReadValue(&flags)
  228. if err != nil {
  229. return err // must be a syntactic or I/O error
  230. }
  231. if val.Kind() == 'n' {
  232. if !uo.Flags.Get(jsonflags.MergeWithLegacySemantics) {
  233. va.SetZero()
  234. }
  235. return nil
  236. }
  237. if val.Kind() != '"' {
  238. return newUnmarshalErrorAfter(dec, t, errNonStringValue)
  239. }
  240. s := jsonwire.UnquoteMayCopy(val, flags.IsVerbatim())
  241. unmarshaler := va.Addr().Interface().(encoding.TextUnmarshaler)
  242. if err := unmarshaler.UnmarshalText(s); err != nil {
  243. err = wrapSkipFunc(err, "unmarshal method")
  244. if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  245. return err // unlike marshal, never wrapped
  246. }
  247. if !isSemanticError(err) && !isSyntacticError(err) && !export.IsIOError(err) {
  248. err = newUnmarshalErrorAfter(dec, t, err)
  249. }
  250. return err
  251. }
  252. return nil
  253. }
  254. }
  255. if _, ok := implements(t, jsonUnmarshalerType); ok {
  256. fncs.nonDefault = true
  257. prevUnmarshal := fncs.unmarshal
  258. fncs.unmarshal = func(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct) error {
  259. if uo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
  260. export.Decoder(dec).Tokens.Last.NeedObjectName() {
  261. return prevUnmarshal(dec, va, uo)
  262. }
  263. val, err := dec.ReadValue()
  264. if err != nil {
  265. return err // must be a syntactic or I/O error
  266. }
  267. unmarshaler := va.Addr().Interface().(Unmarshaler)
  268. if err := unmarshaler.UnmarshalJSON(val); err != nil {
  269. err = wrapSkipFunc(err, "unmarshal method")
  270. if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  271. return err // unlike marshal, never wrapped
  272. }
  273. err = newUnmarshalErrorAfter(dec, t, err)
  274. return collapseSemanticErrors(err)
  275. }
  276. return nil
  277. }
  278. }
  279. if _, ok := implements(t, jsonUnmarshalerFromType); ok {
  280. fncs.nonDefault = true
  281. prevUnmarshal := fncs.unmarshal
  282. fncs.unmarshal = func(dec *jsontext.Decoder, va addressableValue, uo *jsonopts.Struct) error {
  283. if uo.Flags.Get(jsonflags.CallMethodsWithLegacySemantics) &&
  284. export.Decoder(dec).Tokens.Last.NeedObjectName() {
  285. return prevUnmarshal(dec, va, uo)
  286. }
  287. xd := export.Decoder(dec)
  288. prevDepth, prevLength := xd.Tokens.DepthLength()
  289. xd.Flags.Set(jsonflags.WithinArshalCall | 1)
  290. err := va.Addr().Interface().(UnmarshalerFrom).UnmarshalJSONFrom(dec, uo)
  291. xd.Flags.Set(jsonflags.WithinArshalCall | 0)
  292. currDepth, currLength := xd.Tokens.DepthLength()
  293. if (prevDepth != currDepth || prevLength+1 != currLength) && err == nil {
  294. err = errNonSingularValue
  295. }
  296. if err != nil {
  297. err = wrapSkipFunc(err, "unmarshal method")
  298. if uo.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  299. if err2 := xd.SkipUntil(prevDepth, prevLength+1); err2 != nil {
  300. return err2
  301. }
  302. return err // unlike marshal, never wrapped
  303. }
  304. if !isSyntacticError(err) && !export.IsIOError(err) {
  305. err = newSemanticErrorWithPosition(dec, t, prevDepth, prevLength, err)
  306. }
  307. return err
  308. }
  309. return nil
  310. }
  311. }
  312. return fncs
  313. }
  314. // implementsAny is like t.Implements(ifaceType) for a list of interfaces,
  315. // but checks whether either t or reflect.PointerTo(t) implements the interface.
  316. func implementsAny(t reflect.Type, ifaceTypes ...reflect.Type) bool {
  317. for _, ifaceType := range ifaceTypes {
  318. if _, ok := implements(t, ifaceType); ok {
  319. return true
  320. }
  321. }
  322. return false
  323. }
  324. // implements is like t.Implements(ifaceType) but checks whether
  325. // either t or reflect.PointerTo(t) implements the interface.
  326. // It also reports whether the value needs to be addressed
  327. // in order to satisfy the interface.
  328. func implements(t, ifaceType reflect.Type) (needAddr, ok bool) {
  329. switch {
  330. case t.Implements(ifaceType):
  331. return false, true
  332. case reflect.PointerTo(t).Implements(ifaceType):
  333. return true, true
  334. default:
  335. return false, false
  336. }
  337. }