errors.go 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418
  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. "cmp"
  7. "errors"
  8. "fmt"
  9. "reflect"
  10. "strconv"
  11. "strings"
  12. "sync"
  13. "github.com/go-json-experiment/json/internal/jsonflags"
  14. "github.com/go-json-experiment/json/internal/jsonopts"
  15. "github.com/go-json-experiment/json/internal/jsonwire"
  16. "github.com/go-json-experiment/json/jsontext"
  17. )
  18. // ErrUnknownName indicates that a JSON object member could not be
  19. // unmarshaled because the name is not known to the target Go struct.
  20. // This error is directly wrapped within a [SemanticError] when produced.
  21. //
  22. // The name of an unknown JSON object member can be extracted as:
  23. //
  24. // err := ...
  25. // var serr json.SemanticError
  26. // if errors.As(err, &serr) && serr.Err == json.ErrUnknownName {
  27. // ptr := serr.JSONPointer // JSON pointer to unknown name
  28. // name := ptr.LastToken() // unknown name itself
  29. // ...
  30. // }
  31. //
  32. // This error is only returned if [RejectUnknownMembers] is true.
  33. var ErrUnknownName = errors.New("unknown object member name")
  34. const errorPrefix = "json: "
  35. func isSemanticError(err error) bool {
  36. _, ok := err.(*SemanticError)
  37. return ok
  38. }
  39. func isSyntacticError(err error) bool {
  40. _, ok := err.(*jsontext.SyntacticError)
  41. return ok
  42. }
  43. // isFatalError reports whether this error must terminate asharling.
  44. // All errors are considered fatal unless operating under
  45. // [jsonflags.ReportErrorsWithLegacySemantics] in which case only
  46. // syntactic errors and I/O errors are considered fatal.
  47. func isFatalError(err error, flags jsonflags.Flags) bool {
  48. return !flags.Get(jsonflags.ReportErrorsWithLegacySemantics) ||
  49. isSyntacticError(err) || export.IsIOError(err)
  50. }
  51. // SemanticError describes an error determining the meaning
  52. // of JSON data as Go data or vice-versa.
  53. //
  54. // The contents of this error as produced by this package may change over time.
  55. type SemanticError struct {
  56. requireKeyedLiterals
  57. nonComparable
  58. action string // either "marshal" or "unmarshal"
  59. // ByteOffset indicates that an error occurred after this byte offset.
  60. ByteOffset int64
  61. // JSONPointer indicates that an error occurred within this JSON value
  62. // as indicated using the JSON Pointer notation (see RFC 6901).
  63. JSONPointer jsontext.Pointer
  64. // JSONKind is the JSON kind that could not be handled.
  65. JSONKind jsontext.Kind // may be zero if unknown
  66. // JSONValue is the JSON number or string that could not be unmarshaled.
  67. // It is not populated during marshaling.
  68. JSONValue jsontext.Value // may be nil if irrelevant or unknown
  69. // GoType is the Go type that could not be handled.
  70. GoType reflect.Type // may be nil if unknown
  71. // Err is the underlying error.
  72. Err error // may be nil
  73. }
  74. // coder is implemented by [jsontext.Encoder] or [jsontext.Decoder].
  75. type coder interface{ StackPointer() jsontext.Pointer }
  76. // newInvalidFormatError wraps err in a SemanticError because
  77. // the current type t cannot handle the provided options format.
  78. // This error must be called before producing or consuming the next value.
  79. //
  80. // If [jsonflags.ReportErrorsWithLegacySemantics] is specified,
  81. // then this automatically skips the next value when unmarshaling
  82. // to ensure that the value is fully consumed.
  83. func newInvalidFormatError(c coder, t reflect.Type, o *jsonopts.Struct) error {
  84. err := fmt.Errorf("invalid format flag %q", o.Format)
  85. switch c := c.(type) {
  86. case *jsontext.Encoder:
  87. err = newMarshalErrorBefore(c, t, err)
  88. case *jsontext.Decoder:
  89. err = newUnmarshalErrorBeforeWithSkipping(c, o, t, err)
  90. }
  91. return err
  92. }
  93. // newMarshalErrorBefore wraps err in a SemanticError assuming that e
  94. // is positioned right before the next token or value, which causes an error.
  95. func newMarshalErrorBefore(e *jsontext.Encoder, t reflect.Type, err error) error {
  96. return &SemanticError{action: "marshal", GoType: t, Err: err,
  97. ByteOffset: e.OutputOffset() + int64(export.Encoder(e).CountNextDelimWhitespace()),
  98. JSONPointer: jsontext.Pointer(export.Encoder(e).AppendStackPointer(nil, +1))}
  99. }
  100. // newUnmarshalErrorBefore wraps err in a SemanticError assuming that d
  101. // is positioned right before the next token or value, which causes an error.
  102. // It does not record the next JSON kind as this error is used to indicate
  103. // the receiving Go value is invalid to unmarshal into (and not a JSON error).
  104. func newUnmarshalErrorBefore(d *jsontext.Decoder, t reflect.Type, err error) error {
  105. return &SemanticError{action: "unmarshal", GoType: t, Err: err,
  106. ByteOffset: d.InputOffset() + int64(export.Decoder(d).CountNextDelimWhitespace()),
  107. JSONPointer: jsontext.Pointer(export.Decoder(d).AppendStackPointer(nil, +1))}
  108. }
  109. // newUnmarshalErrorBeforeWithSkipping is like [newUnmarshalErrorBefore],
  110. // but automatically skips the next value if
  111. // [jsonflags.ReportErrorsWithLegacySemantics] is specified.
  112. func newUnmarshalErrorBeforeWithSkipping(d *jsontext.Decoder, o *jsonopts.Struct, t reflect.Type, err error) error {
  113. err = newUnmarshalErrorBefore(d, t, err)
  114. if o.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  115. if err2 := export.Decoder(d).SkipValue(); err2 != nil {
  116. return err2
  117. }
  118. }
  119. return err
  120. }
  121. // newUnmarshalErrorAfter wraps err in a SemanticError assuming that d
  122. // is positioned right after the previous token or value, which caused an error.
  123. func newUnmarshalErrorAfter(d *jsontext.Decoder, t reflect.Type, err error) error {
  124. tokOrVal := export.Decoder(d).PreviousTokenOrValue()
  125. return &SemanticError{action: "unmarshal", GoType: t, Err: err,
  126. ByteOffset: d.InputOffset() - int64(len(tokOrVal)),
  127. JSONPointer: jsontext.Pointer(export.Decoder(d).AppendStackPointer(nil, -1)),
  128. JSONKind: jsontext.Value(tokOrVal).Kind()}
  129. }
  130. // newUnmarshalErrorAfter wraps err in a SemanticError assuming that d
  131. // is positioned right after the previous token or value, which caused an error.
  132. // It also stores a copy of the last JSON value if it is a string or number.
  133. func newUnmarshalErrorAfterWithValue(d *jsontext.Decoder, t reflect.Type, err error) error {
  134. serr := newUnmarshalErrorAfter(d, t, err).(*SemanticError)
  135. if serr.JSONKind == '"' || serr.JSONKind == '0' {
  136. serr.JSONValue = jsontext.Value(export.Decoder(d).PreviousTokenOrValue()).Clone()
  137. }
  138. return serr
  139. }
  140. // newUnmarshalErrorAfterWithSkipping is like [newUnmarshalErrorAfter],
  141. // but automatically skips the remainder of the current value if
  142. // [jsonflags.ReportErrorsWithLegacySemantics] is specified.
  143. func newUnmarshalErrorAfterWithSkipping(d *jsontext.Decoder, o *jsonopts.Struct, t reflect.Type, err error) error {
  144. err = newUnmarshalErrorAfter(d, t, err)
  145. if o.Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
  146. if err2 := export.Decoder(d).SkipValueRemainder(); err2 != nil {
  147. return err2
  148. }
  149. }
  150. return err
  151. }
  152. // newSemanticErrorWithPosition wraps err in a SemanticError assuming that
  153. // the error occurred at the provided depth, and length.
  154. // If err is already a SemanticError, then position information is only
  155. // injected if it is currently unpopulated.
  156. //
  157. // If the position is unpopulated, it is ambiguous where the error occurred
  158. // in the user code, whether it was before or after the current position.
  159. // For the byte offset, we assume that the error occurred before the last read
  160. // token or value when decoding, or before the next value when encoding.
  161. // For the JSON pointer, we point to the parent object or array unless
  162. // we can be certain that it happened with an object member.
  163. //
  164. // This is used to annotate errors returned by user-provided
  165. // v2 MarshalJSON or UnmarshalJSON methods or functions.
  166. func newSemanticErrorWithPosition(c coder, t reflect.Type, prevDepth int, prevLength int64, err error) error {
  167. serr, _ := err.(*SemanticError)
  168. if serr == nil {
  169. serr = &SemanticError{Err: err}
  170. }
  171. var currDepth int
  172. var currLength int64
  173. var coderState interface{ AppendStackPointer([]byte, int) []byte }
  174. var offset int64
  175. switch c := c.(type) {
  176. case *jsontext.Encoder:
  177. e := export.Encoder(c)
  178. serr.action = cmp.Or(serr.action, "marshal")
  179. currDepth, currLength = e.Tokens.DepthLength()
  180. offset = c.OutputOffset() + int64(export.Encoder(c).CountNextDelimWhitespace())
  181. coderState = e
  182. case *jsontext.Decoder:
  183. d := export.Decoder(c)
  184. serr.action = cmp.Or(serr.action, "unmarshal")
  185. currDepth, currLength = d.Tokens.DepthLength()
  186. tokOrVal := d.PreviousTokenOrValue()
  187. offset = c.InputOffset() - int64(len(tokOrVal))
  188. if (prevDepth == currDepth && prevLength == currLength) || len(tokOrVal) == 0 {
  189. // If no Read method was called in the user-defined method or
  190. // if the Peek method was called, then use the offset of the next value.
  191. offset = c.InputOffset() + int64(export.Decoder(c).CountNextDelimWhitespace())
  192. }
  193. coderState = d
  194. }
  195. serr.ByteOffset = cmp.Or(serr.ByteOffset, offset)
  196. if serr.JSONPointer == "" {
  197. where := 0 // default to ambiguous positioning
  198. switch {
  199. case prevDepth == currDepth && prevLength+0 == currLength:
  200. where = +1
  201. case prevDepth == currDepth && prevLength+1 == currLength:
  202. where = -1
  203. }
  204. serr.JSONPointer = jsontext.Pointer(coderState.AppendStackPointer(nil, where))
  205. }
  206. serr.GoType = cmp.Or(serr.GoType, t)
  207. return serr
  208. }
  209. // collapseSemanticErrors collapses double SemanticErrors at the outer levels
  210. // into a single SemanticError by preserving the inner error,
  211. // but prepending the ByteOffset and JSONPointer with the outer error.
  212. //
  213. // For example:
  214. //
  215. // collapseSemanticErrors(&SemanticError{
  216. // ByteOffset: len64(`[0,{"alpha":[0,1,`),
  217. // JSONPointer: "/1/alpha/2",
  218. // GoType: reflect.TypeFor[outerType](),
  219. // Err: &SemanticError{
  220. // ByteOffset: len64(`{"foo":"bar","fizz":[0,`),
  221. // JSONPointer: "/fizz/1",
  222. // GoType: reflect.TypeFor[innerType](),
  223. // Err: ...,
  224. // },
  225. // })
  226. //
  227. // results in:
  228. //
  229. // &SemanticError{
  230. // ByteOffset: len64(`[0,{"alpha":[0,1,`) + len64(`{"foo":"bar","fizz":[0,`),
  231. // JSONPointer: "/1/alpha/2" + "/fizz/1",
  232. // GoType: reflect.TypeFor[innerType](),
  233. // Err: ...,
  234. // }
  235. //
  236. // This is used to annotate errors returned by user-provided
  237. // v1 MarshalJSON or UnmarshalJSON methods with precise position information
  238. // if they themselves happened to return a SemanticError.
  239. // Since MarshalJSON and UnmarshalJSON are not operating on the root JSON value,
  240. // their positioning must be relative to the nested JSON value
  241. // returned by UnmarshalJSON or passed to MarshalJSON.
  242. // Therefore, we can construct an absolute position by concatenating
  243. // the outer with the inner positions.
  244. //
  245. // Note that we do not use collapseSemanticErrors with user-provided functions
  246. // that take in an [jsontext.Encoder] or [jsontext.Decoder] since they contain
  247. // methods to report position relative to the root JSON value.
  248. // We assume user-constructed errors are correctly precise about position.
  249. func collapseSemanticErrors(err error) error {
  250. if serr1, ok := err.(*SemanticError); ok {
  251. if serr2, ok := serr1.Err.(*SemanticError); ok {
  252. serr2.ByteOffset = serr1.ByteOffset + serr2.ByteOffset
  253. serr2.JSONPointer = serr1.JSONPointer + serr2.JSONPointer
  254. *serr1 = *serr2
  255. }
  256. }
  257. return err
  258. }
  259. // errorModalVerb is a modal verb like "cannot" or "unable to".
  260. //
  261. // Once per process, Hyrum-proof the error message by deliberately
  262. // switching between equivalent renderings of the same error message.
  263. // The randomization is tied to the Hyrum-proofing already applied
  264. // on map iteration in Go.
  265. var errorModalVerb = sync.OnceValue(func() string {
  266. for phrase := range map[string]struct{}{"cannot": {}, "unable to": {}} {
  267. return phrase // use whichever phrase we get in the first iteration
  268. }
  269. return ""
  270. })
  271. func (e *SemanticError) Error() string {
  272. var sb strings.Builder
  273. sb.WriteString(errorPrefix)
  274. sb.WriteString(errorModalVerb())
  275. // Format action.
  276. var preposition string
  277. switch e.action {
  278. case "marshal":
  279. sb.WriteString(" marshal")
  280. preposition = " from"
  281. case "unmarshal":
  282. sb.WriteString(" unmarshal")
  283. preposition = " into"
  284. default:
  285. sb.WriteString(" handle")
  286. preposition = " with"
  287. }
  288. // Format JSON kind.
  289. switch e.JSONKind {
  290. case 'n':
  291. sb.WriteString(" JSON null")
  292. case 'f', 't':
  293. sb.WriteString(" JSON boolean")
  294. case '"':
  295. sb.WriteString(" JSON string")
  296. case '0':
  297. sb.WriteString(" JSON number")
  298. case '{', '}':
  299. sb.WriteString(" JSON object")
  300. case '[', ']':
  301. sb.WriteString(" JSON array")
  302. default:
  303. if e.action == "" {
  304. preposition = ""
  305. }
  306. }
  307. if len(e.JSONValue) > 0 && len(e.JSONValue) < 100 {
  308. sb.WriteByte(' ')
  309. sb.Write(e.JSONValue)
  310. }
  311. // Format Go type.
  312. if e.GoType != nil {
  313. typeString := e.GoType.String()
  314. if len(typeString) > 100 {
  315. // An excessively long type string most likely occurs for
  316. // an anonymous struct declaration with many fields.
  317. // Reduce the noise by just printing the kind,
  318. // and optionally prepending it with the package name
  319. // if the struct happens to include an unexported field.
  320. typeString = e.GoType.Kind().String()
  321. if e.GoType.Kind() == reflect.Struct && e.GoType.Name() == "" {
  322. for i := range e.GoType.NumField() {
  323. if pkgPath := e.GoType.Field(i).PkgPath; pkgPath != "" {
  324. typeString = pkgPath[strings.LastIndexByte(pkgPath, '/')+len("/"):] + ".struct"
  325. break
  326. }
  327. }
  328. }
  329. }
  330. sb.WriteString(preposition)
  331. sb.WriteString(" Go ")
  332. sb.WriteString(typeString)
  333. }
  334. // Special handling for unknown names.
  335. if e.Err == ErrUnknownName {
  336. sb.WriteString(": ")
  337. sb.WriteString(ErrUnknownName.Error())
  338. sb.WriteString(" ")
  339. sb.WriteString(strconv.Quote(e.JSONPointer.LastToken()))
  340. if parent := e.JSONPointer.Parent(); parent != "" {
  341. sb.WriteString(" within ")
  342. sb.WriteString(strconv.Quote(jsonwire.TruncatePointer(string(parent), 100)))
  343. }
  344. return sb.String()
  345. }
  346. // Format where.
  347. // Avoid printing if it overlaps with a wrapped SyntacticError.
  348. switch serr, _ := e.Err.(*jsontext.SyntacticError); {
  349. case e.JSONPointer != "":
  350. if serr == nil || !e.JSONPointer.Contains(serr.JSONPointer) {
  351. sb.WriteString(" within ")
  352. sb.WriteString(strconv.Quote(jsonwire.TruncatePointer(string(e.JSONPointer), 100)))
  353. }
  354. case e.ByteOffset > 0:
  355. if serr == nil || !(e.ByteOffset <= serr.ByteOffset) {
  356. sb.WriteString(" after offset ")
  357. sb.WriteString(strconv.FormatInt(e.ByteOffset, 10))
  358. }
  359. }
  360. // Format underlying error.
  361. if e.Err != nil {
  362. errString := e.Err.Error()
  363. if isSyntacticError(e.Err) {
  364. errString = strings.TrimPrefix(errString, "jsontext: ")
  365. }
  366. sb.WriteString(": ")
  367. sb.WriteString(errString)
  368. }
  369. return sb.String()
  370. }
  371. func (e *SemanticError) Unwrap() error {
  372. return e.Err
  373. }
  374. func newDuplicateNameError(ptr jsontext.Pointer, quotedName []byte, offset int64) error {
  375. if quotedName != nil {
  376. name, _ := jsonwire.AppendUnquote(nil, quotedName)
  377. ptr = ptr.AppendToken(string(name))
  378. }
  379. return &jsontext.SyntacticError{
  380. ByteOffset: offset,
  381. JSONPointer: ptr,
  382. Err: jsontext.ErrDuplicateName,
  383. }
  384. }