cmd/bpa-operator/vendor/github.com/golang/protobuf/jsonpb/jsonpb.go

   1 // Go support for Protocol Buffers - Google's data interchange format
   2 //
   3 // Copyright 2015 The Go Authors.  All rights reserved.
   4 // https://github.com/golang/protobuf
   5 //
   6 // Redistribution and use in source and binary forms, with or without
   7 // modification, are permitted provided that the following conditions are
   8 // met:
   9 //
  10 //     * Redistributions of source code must retain the above copyright
  11 // notice, this list of conditions and the following disclaimer.
  12 //     * Redistributions in binary form must reproduce the above
  13 // copyright notice, this list of conditions and the following disclaimer
  14 // in the documentation and/or other materials provided with the
  15 // distribution.
  16 //     * Neither the name of Google Inc. nor the names of its
  17 // contributors may be used to endorse or promote products derived from
  18 // this software without specific prior written permission.
  19 //
  20 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31
  32 /*
  33 Package jsonpb provides marshaling and unmarshaling between protocol buffers and JSON.
  34 It follows the specification at https://developers.google.com/protocol-buffers/docs/proto3#json.
  35
  36 This package produces a different output than the standard "encoding/json" package,
  37 which does not operate correctly on protocol buffers.
  38 */
  39 package jsonpb
  40
  41 import (
  42         "bytes"
  43         "encoding/json"
  44         "errors"
  45         "fmt"
  46         "io"
  47         "math"
  48         "reflect"
  49         "sort"
  50         "strconv"
  51         "strings"
  52         "time"
  53
  54         "github.com/golang/protobuf/proto"
  55
  56         stpb "github.com/golang/protobuf/ptypes/struct"
  57 )
  58
  59 const secondInNanos = int64(time.Second / time.Nanosecond)
  60
  61 // Marshaler is a configurable object for converting between
  62 // protocol buffer objects and a JSON representation for them.
  63 type Marshaler struct {
  64         // Whether to render enum values as integers, as opposed to string values.
  65         EnumsAsInts bool
  66
  67         // Whether to render fields with zero values.
  68         EmitDefaults bool
  69
  70         // A string to indent each level by. The presence of this field will
  71         // also cause a space to appear between the field separator and
  72         // value, and for newlines to be appear between fields and array
  73         // elements.
  74         Indent string
  75
  76         // Whether to use the original (.proto) name for fields.
  77         OrigName bool
  78
  79         // A custom URL resolver to use when marshaling Any messages to JSON.
  80         // If unset, the default resolution strategy is to extract the
  81         // fully-qualified type name from the type URL and pass that to
  82         // proto.MessageType(string).
  83         AnyResolver AnyResolver
  84 }
  85
  86 // AnyResolver takes a type URL, present in an Any message, and resolves it into
  87 // an instance of the associated message.
  88 type AnyResolver interface {
  89         Resolve(typeUrl string) (proto.Message, error)
  90 }
  91
  92 func defaultResolveAny(typeUrl string) (proto.Message, error) {
  93         // Only the part of typeUrl after the last slash is relevant.
  94         mname := typeUrl
  95         if slash := strings.LastIndex(mname, "/"); slash >= 0 {
  96                 mname = mname[slash+1:]
  97         }
  98         mt := proto.MessageType(mname)
  99         if mt == nil {
 100                 return nil, fmt.Errorf("unknown message type %q", mname)
 101         }
 102         return reflect.New(mt.Elem()).Interface().(proto.Message), nil
 103 }
 104
 105 // JSONPBMarshaler is implemented by protobuf messages that customize the
 106 // way they are marshaled to JSON. Messages that implement this should
 107 // also implement JSONPBUnmarshaler so that the custom format can be
 108 // parsed.
 109 //
 110 // The JSON marshaling must follow the proto to JSON specification:
 111 //      https://developers.google.com/protocol-buffers/docs/proto3#json
 112 type JSONPBMarshaler interface {
 113         MarshalJSONPB(*Marshaler) ([]byte, error)
 114 }
 115
 116 // JSONPBUnmarshaler is implemented by protobuf messages that customize
 117 // the way they are unmarshaled from JSON. Messages that implement this
 118 // should also implement JSONPBMarshaler so that the custom format can be
 119 // produced.
 120 //
 121 // The JSON unmarshaling must follow the JSON to proto specification:
 122 //      https://developers.google.com/protocol-buffers/docs/proto3#json
 123 type JSONPBUnmarshaler interface {
 124         UnmarshalJSONPB(*Unmarshaler, []byte) error
 125 }
 126
 127 // Marshal marshals a protocol buffer into JSON.
 128 func (m *Marshaler) Marshal(out io.Writer, pb proto.Message) error {
 129         v := reflect.ValueOf(pb)
 130         if pb == nil || (v.Kind() == reflect.Ptr && v.IsNil()) {
 131                 return errors.New("Marshal called with nil")
 132         }
 133         // Check for unset required fields first.
 134         if err := checkRequiredFields(pb); err != nil {
 135                 return err
 136         }
 137         writer := &errWriter{writer: out}
 138         return m.marshalObject(writer, pb, "", "")
 139 }
 140
 141 // MarshalToString converts a protocol buffer object to JSON string.
 142 func (m *Marshaler) MarshalToString(pb proto.Message) (string, error) {
 143         var buf bytes.Buffer
 144         if err := m.Marshal(&buf, pb); err != nil {
 145                 return "", err
 146         }
 147         return buf.String(), nil
 148 }
 149
 150 type int32Slice []int32
 151
 152 var nonFinite = map[string]float64{
 153         `"NaN"`:       math.NaN(),
 154         `"Infinity"`:  math.Inf(1),
 155         `"-Infinity"`: math.Inf(-1),
 156 }
 157
 158 // For sorting extensions ids to ensure stable output.
 159 func (s int32Slice) Len() int           { return len(s) }
 160 func (s int32Slice) Less(i, j int) bool { return s[i] < s[j] }
 161 func (s int32Slice) Swap(i, j int)      { s[i], s[j] = s[j], s[i] }
 162
 163 type wkt interface {
 164         XXX_WellKnownType() string
 165 }
 166
 167 // marshalObject writes a struct to the Writer.
 168 func (m *Marshaler) marshalObject(out *errWriter, v proto.Message, indent, typeURL string) error {
 169         if jsm, ok := v.(JSONPBMarshaler); ok {
 170                 b, err := jsm.MarshalJSONPB(m)
 171                 if err != nil {
 172                         return err
 173                 }
 174                 if typeURL != "" {
 175                         // we are marshaling this object to an Any type
 176                         var js map[string]*json.RawMessage
 177                         if err = json.Unmarshal(b, &js); err != nil {
 178                                 return fmt.Errorf("type %T produced invalid JSON: %v", v, err)
 179                         }
 180                         turl, err := json.Marshal(typeURL)
 181                         if err != nil {
 182                                 return fmt.Errorf("failed to marshal type URL %q to JSON: %v", typeURL, err)
 183                         }
 184                         js["@type"] = (*json.RawMessage)(&turl)
 185                         if b, err = json.Marshal(js); err != nil {
 186                                 return err
 187                         }
 188                 }
 189
 190                 out.write(string(b))
 191                 return out.err
 192         }
 193
 194         s := reflect.ValueOf(v).Elem()
 195
 196         // Handle well-known types.
 197         if wkt, ok := v.(wkt); ok {
 198                 switch wkt.XXX_WellKnownType() {
 199                 case "DoubleValue", "FloatValue", "Int64Value", "UInt64Value",
 200                         "Int32Value", "UInt32Value", "BoolValue", "StringValue", "BytesValue":
 201                         // "Wrappers use the same representation in JSON
 202                         //  as the wrapped primitive type, ..."
 203                         sprop := proto.GetProperties(s.Type())
 204                         return m.marshalValue(out, sprop.Prop[0], s.Field(0), indent)
 205                 case "Any":
 206                         // Any is a bit more involved.
 207                         return m.marshalAny(out, v, indent)
 208                 case "Duration":
 209                         // "Generated output always contains 0, 3, 6, or 9 fractional digits,
 210                         //  depending on required precision."
 211                         s, ns := s.Field(0).Int(), s.Field(1).Int()
 212                         if ns <= -secondInNanos || ns >= secondInNanos {
 213                                 return fmt.Errorf("ns out of range (%v, %v)", -secondInNanos, secondInNanos)
 214                         }
 215                         if (s > 0 && ns < 0) || (s < 0 && ns > 0) {
 216                                 return errors.New("signs of seconds and nanos do not match")
 217                         }
 218                         if s < 0 {
 219                                 ns = -ns
 220                         }
 221                         x := fmt.Sprintf("%d.%09d", s, ns)
 222                         x = strings.TrimSuffix(x, "000")
 223                         x = strings.TrimSuffix(x, "000")
 224                         x = strings.TrimSuffix(x, ".000")
 225                         out.write(`"`)
 226                         out.write(x)
 227                         out.write(`s"`)
 228                         return out.err
 229                 case "Struct", "ListValue":
 230                         // Let marshalValue handle the `Struct.fields` map or the `ListValue.values` slice.
 231                         // TODO: pass the correct Properties if needed.
 232                         return m.marshalValue(out, &proto.Properties{}, s.Field(0), indent)
 233                 case "Timestamp":
 234                         // "RFC 3339, where generated output will always be Z-normalized
 235                         //  and uses 0, 3, 6 or 9 fractional digits."
 236                         s, ns := s.Field(0).Int(), s.Field(1).Int()
 237                         if ns < 0 || ns >= secondInNanos {
 238                                 return fmt.Errorf("ns out of range [0, %v)", secondInNanos)
 239                         }
 240                         t := time.Unix(s, ns).UTC()
 241                         // time.RFC3339Nano isn't exactly right (we need to get 3/6/9 fractional digits).
 242                         x := t.Format("2006-01-02T15:04:05.000000000")
 243                         x = strings.TrimSuffix(x, "000")
 244                         x = strings.TrimSuffix(x, "000")
 245                         x = strings.TrimSuffix(x, ".000")
 246                         out.write(`"`)
 247                         out.write(x)
 248                         out.write(`Z"`)
 249                         return out.err
 250                 case "Value":
 251                         // Value has a single oneof.
 252                         kind := s.Field(0)
 253                         if kind.IsNil() {
 254                                 // "absence of any variant indicates an error"
 255                                 return errors.New("nil Value")
 256                         }
 257                         // oneof -> *T -> T -> T.F
 258                         x := kind.Elem().Elem().Field(0)
 259                         // TODO: pass the correct Properties if needed.
 260                         return m.marshalValue(out, &proto.Properties{}, x, indent)
 261                 }
 262         }
 263
 264         out.write("{")
 265         if m.Indent != "" {
 266                 out.write("\n")
 267         }
 268
 269         firstField := true
 270
 271         if typeURL != "" {
 272                 if err := m.marshalTypeURL(out, indent, typeURL); err != nil {
 273                         return err
 274                 }
 275                 firstField = false
 276         }
 277
 278         for i := 0; i < s.NumField(); i++ {
 279                 value := s.Field(i)
 280                 valueField := s.Type().Field(i)
 281                 if strings.HasPrefix(valueField.Name, "XXX_") {
 282                         continue
 283                 }
 284
 285                 // IsNil will panic on most value kinds.
 286                 switch value.Kind() {
 287                 case reflect.Chan, reflect.Func, reflect.Interface:
 288                         if value.IsNil() {
 289                                 continue
 290                         }
 291                 }
 292
 293                 if !m.EmitDefaults {
 294                         switch value.Kind() {
 295                         case reflect.Bool:
 296                                 if !value.Bool() {
 297                                         continue
 298                                 }
 299                         case reflect.Int32, reflect.Int64:
 300                                 if value.Int() == 0 {
 301                                         continue
 302                                 }
 303                         case reflect.Uint32, reflect.Uint64:
 304                                 if value.Uint() == 0 {
 305                                         continue
 306                                 }
 307                         case reflect.Float32, reflect.Float64:
 308                                 if value.Float() == 0 {
 309                                         continue
 310                                 }
 311                         case reflect.String:
 312                                 if value.Len() == 0 {
 313                                         continue
 314                                 }
 315                         case reflect.Map, reflect.Ptr, reflect.Slice:
 316                                 if value.IsNil() {
 317                                         continue
 318                                 }
 319                         }
 320                 }
 321
 322                 // Oneof fields need special handling.
 323                 if valueField.Tag.Get("protobuf_oneof") != "" {
 324                         // value is an interface containing &T{real_value}.
 325                         sv := value.Elem().Elem() // interface -> *T -> T
 326                         value = sv.Field(0)
 327                         valueField = sv.Type().Field(0)
 328                 }
 329                 prop := jsonProperties(valueField, m.OrigName)
 330                 if !firstField {
 331                         m.writeSep(out)
 332                 }
 333                 if err := m.marshalField(out, prop, value, indent); err != nil {
 334                         return err
 335                 }
 336                 firstField = false
 337         }
 338
 339         // Handle proto2 extensions.
 340         if ep, ok := v.(proto.Message); ok {
 341                 extensions := proto.RegisteredExtensions(v)
 342                 // Sort extensions for stable output.
 343                 ids := make([]int32, 0, len(extensions))
 344                 for id, desc := range extensions {
 345                         if !proto.HasExtension(ep, desc) {
 346                                 continue
 347                         }
 348                         ids = append(ids, id)
 349                 }
 350                 sort.Sort(int32Slice(ids))
 351                 for _, id := range ids {
 352                         desc := extensions[id]
 353                         if desc == nil {
 354                                 // unknown extension
 355                                 continue
 356                         }
 357                         ext, extErr := proto.GetExtension(ep, desc)
 358                         if extErr != nil {
 359                                 return extErr
 360                         }
 361                         value := reflect.ValueOf(ext)
 362                         var prop proto.Properties
 363                         prop.Parse(desc.Tag)
 364                         prop.JSONName = fmt.Sprintf("[%s]", desc.Name)
 365                         if !firstField {
 366                                 m.writeSep(out)
 367                         }
 368                         if err := m.marshalField(out, &prop, value, indent); err != nil {
 369                                 return err
 370                         }
 371                         firstField = false
 372                 }
 373
 374         }
 375
 376         if m.Indent != "" {
 377                 out.write("\n")
 378                 out.write(indent)
 379         }
 380         out.write("}")
 381         return out.err
 382 }
 383
 384 func (m *Marshaler) writeSep(out *errWriter) {
 385         if m.Indent != "" {
 386                 out.write(",\n")
 387         } else {
 388                 out.write(",")
 389         }
 390 }
 391
 392 func (m *Marshaler) marshalAny(out *errWriter, any proto.Message, indent string) error {
 393         // "If the Any contains a value that has a special JSON mapping,
 394         //  it will be converted as follows: {"@type": xxx, "value": yyy}.
 395         //  Otherwise, the value will be converted into a JSON object,
 396         //  and the "@type" field will be inserted to indicate the actual data type."
 397         v := reflect.ValueOf(any).Elem()
 398         turl := v.Field(0).String()
 399         val := v.Field(1).Bytes()
 400
 401         var msg proto.Message
 402         var err error
 403         if m.AnyResolver != nil {
 404                 msg, err = m.AnyResolver.Resolve(turl)
 405         } else {
 406                 msg, err = defaultResolveAny(turl)
 407         }
 408         if err != nil {
 409                 return err
 410         }
 411
 412         if err := proto.Unmarshal(val, msg); err != nil {
 413                 return err
 414         }
 415
 416         if _, ok := msg.(wkt); ok {
 417                 out.write("{")
 418                 if m.Indent != "" {
 419                         out.write("\n")
 420                 }
 421                 if err := m.marshalTypeURL(out, indent, turl); err != nil {
 422                         return err
 423                 }
 424                 m.writeSep(out)
 425                 if m.Indent != "" {
 426                         out.write(indent)
 427                         out.write(m.Indent)
 428                         out.write(`"value": `)
 429                 } else {
 430                         out.write(`"value":`)
 431                 }
 432                 if err := m.marshalObject(out, msg, indent+m.Indent, ""); err != nil {
 433                         return err
 434                 }
 435                 if m.Indent != "" {
 436                         out.write("\n")
 437                         out.write(indent)
 438                 }
 439                 out.write("}")
 440                 return out.err
 441         }
 442
 443         return m.marshalObject(out, msg, indent, turl)
 444 }
 445
 446 func (m *Marshaler) marshalTypeURL(out *errWriter, indent, typeURL string) error {
 447         if m.Indent != "" {
 448                 out.write(indent)
 449                 out.write(m.Indent)
 450         }
 451         out.write(`"@type":`)
 452         if m.Indent != "" {
 453                 out.write(" ")
 454         }
 455         b, err := json.Marshal(typeURL)
 456         if err != nil {
 457                 return err
 458         }
 459         out.write(string(b))
 460         return out.err
 461 }
 462
 463 // marshalField writes field description and value to the Writer.
 464 func (m *Marshaler) marshalField(out *errWriter, prop *proto.Properties, v reflect.Value, indent string) error {
 465         if m.Indent != "" {
 466                 out.write(indent)
 467                 out.write(m.Indent)
 468         }
 469         out.write(`"`)
 470         out.write(prop.JSONName)
 471         out.write(`":`)
 472         if m.Indent != "" {
 473                 out.write(" ")
 474         }
 475         if err := m.marshalValue(out, prop, v, indent); err != nil {
 476                 return err
 477         }
 478         return nil
 479 }
 480
 481 // marshalValue writes the value to the Writer.
 482 func (m *Marshaler) marshalValue(out *errWriter, prop *proto.Properties, v reflect.Value, indent string) error {
 483         var err error
 484         v = reflect.Indirect(v)
 485
 486         // Handle nil pointer
 487         if v.Kind() == reflect.Invalid {
 488                 out.write("null")
 489                 return out.err
 490         }
 491
 492         // Handle repeated elements.
 493         if v.Kind() == reflect.Slice && v.Type().Elem().Kind() != reflect.Uint8 {
 494                 out.write("[")
 495                 comma := ""
 496                 for i := 0; i < v.Len(); i++ {
 497                         sliceVal := v.Index(i)
 498                         out.write(comma)
 499                         if m.Indent != "" {
 500                                 out.write("\n")
 501                                 out.write(indent)
 502                                 out.write(m.Indent)
 503                                 out.write(m.Indent)
 504                         }
 505                         if err := m.marshalValue(out, prop, sliceVal, indent+m.Indent); err != nil {
 506                                 return err
 507                         }
 508                         comma = ","
 509                 }
 510                 if m.Indent != "" {
 511                         out.write("\n")
 512                         out.write(indent)
 513                         out.write(m.Indent)
 514                 }
 515                 out.write("]")
 516                 return out.err
 517         }
 518
 519         // Handle well-known types.
 520         // Most are handled up in marshalObject (because 99% are messages).
 521         if wkt, ok := v.Interface().(wkt); ok {
 522                 switch wkt.XXX_WellKnownType() {
 523                 case "NullValue":
 524                         out.write("null")
 525                         return out.err
 526                 }
 527         }
 528
 529         // Handle enumerations.
 530         if !m.EnumsAsInts && prop.Enum != "" {
 531                 // Unknown enum values will are stringified by the proto library as their
 532                 // value. Such values should _not_ be quoted or they will be interpreted
 533                 // as an enum string instead of their value.
 534                 enumStr := v.Interface().(fmt.Stringer).String()
 535                 var valStr string
 536                 if v.Kind() == reflect.Ptr {
 537                         valStr = strconv.Itoa(int(v.Elem().Int()))
 538                 } else {
 539                         valStr = strconv.Itoa(int(v.Int()))
 540                 }
 541                 isKnownEnum := enumStr != valStr
 542                 if isKnownEnum {
 543                         out.write(`"`)
 544                 }
 545                 out.write(enumStr)
 546                 if isKnownEnum {
 547                         out.write(`"`)
 548                 }
 549                 return out.err
 550         }
 551
 552         // Handle nested messages.
 553         if v.Kind() == reflect.Struct {
 554                 return m.marshalObject(out, v.Addr().Interface().(proto.Message), indent+m.Indent, "")
 555         }
 556
 557         // Handle maps.
 558         // Since Go randomizes map iteration, we sort keys for stable output.
 559         if v.Kind() == reflect.Map {
 560                 out.write(`{`)
 561                 keys := v.MapKeys()
 562                 sort.Sort(mapKeys(keys))
 563                 for i, k := range keys {
 564                         if i > 0 {
 565                                 out.write(`,`)
 566                         }
 567                         if m.Indent != "" {
 568                                 out.write("\n")
 569                                 out.write(indent)
 570                                 out.write(m.Indent)
 571                                 out.write(m.Indent)
 572                         }
 573
 574                         // TODO handle map key prop properly
 575                         b, err := json.Marshal(k.Interface())
 576                         if err != nil {
 577                                 return err
 578                         }
 579                         s := string(b)
 580
 581                         // If the JSON is not a string value, encode it again to make it one.
 582                         if !strings.HasPrefix(s, `"`) {
 583                                 b, err := json.Marshal(s)
 584                                 if err != nil {
 585                                         return err
 586                                 }
 587                                 s = string(b)
 588                         }
 589
 590                         out.write(s)
 591                         out.write(`:`)
 592                         if m.Indent != "" {
 593                                 out.write(` `)
 594                         }
 595
 596                         vprop := prop
 597                         if prop != nil && prop.MapValProp != nil {
 598                                 vprop = prop.MapValProp
 599                         }
 600                         if err := m.marshalValue(out, vprop, v.MapIndex(k), indent+m.Indent); err != nil {
 601                                 return err
 602                         }
 603                 }
 604                 if m.Indent != "" {
 605                         out.write("\n")
 606                         out.write(indent)
 607                         out.write(m.Indent)
 608                 }
 609                 out.write(`}`)
 610                 return out.err
 611         }
 612
 613         // Handle non-finite floats, e.g. NaN, Infinity and -Infinity.
 614         if v.Kind() == reflect.Float32 || v.Kind() == reflect.Float64 {
 615                 f := v.Float()
 616                 var sval string
 617                 switch {
 618                 case math.IsInf(f, 1):
 619                         sval = `"Infinity"`
 620                 case math.IsInf(f, -1):
 621                         sval = `"-Infinity"`
 622                 case math.IsNaN(f):
 623                         sval = `"NaN"`
 624                 }
 625                 if sval != "" {
 626                         out.write(sval)
 627                         return out.err
 628                 }
 629         }
 630
 631         // Default handling defers to the encoding/json library.
 632         b, err := json.Marshal(v.Interface())
 633         if err != nil {
 634                 return err
 635         }
 636         needToQuote := string(b[0]) != `"` && (v.Kind() == reflect.Int64 || v.Kind() == reflect.Uint64)
 637         if needToQuote {
 638                 out.write(`"`)
 639         }
 640         out.write(string(b))
 641         if needToQuote {
 642                 out.write(`"`)
 643         }
 644         return out.err
 645 }
 646
 647 // Unmarshaler is a configurable object for converting from a JSON
 648 // representation to a protocol buffer object.
 649 type Unmarshaler struct {
 650         // Whether to allow messages to contain unknown fields, as opposed to
 651         // failing to unmarshal.
 652         AllowUnknownFields bool
 653
 654         // A custom URL resolver to use when unmarshaling Any messages from JSON.
 655         // If unset, the default resolution strategy is to extract the
 656         // fully-qualified type name from the type URL and pass that to
 657         // proto.MessageType(string).
 658         AnyResolver AnyResolver
 659 }
 660
 661 // UnmarshalNext unmarshals the next protocol buffer from a JSON object stream.
 662 // This function is lenient and will decode any options permutations of the
 663 // related Marshaler.
 664 func (u *Unmarshaler) UnmarshalNext(dec *json.Decoder, pb proto.Message) error {
 665         inputValue := json.RawMessage{}
 666         if err := dec.Decode(&inputValue); err != nil {
 667                 return err
 668         }
 669         if err := u.unmarshalValue(reflect.ValueOf(pb).Elem(), inputValue, nil); err != nil {
 670                 return err
 671         }
 672         return checkRequiredFields(pb)
 673 }
 674
 675 // Unmarshal unmarshals a JSON object stream into a protocol
 676 // buffer. This function is lenient and will decode any options
 677 // permutations of the related Marshaler.
 678 func (u *Unmarshaler) Unmarshal(r io.Reader, pb proto.Message) error {
 679         dec := json.NewDecoder(r)
 680         return u.UnmarshalNext(dec, pb)
 681 }
 682
 683 // UnmarshalNext unmarshals the next protocol buffer from a JSON object stream.
 684 // This function is lenient and will decode any options permutations of the
 685 // related Marshaler.
 686 func UnmarshalNext(dec *json.Decoder, pb proto.Message) error {
 687         return new(Unmarshaler).UnmarshalNext(dec, pb)
 688 }
 689
 690 // Unmarshal unmarshals a JSON object stream into a protocol
 691 // buffer. This function is lenient and will decode any options
 692 // permutations of the related Marshaler.
 693 func Unmarshal(r io.Reader, pb proto.Message) error {
 694         return new(Unmarshaler).Unmarshal(r, pb)
 695 }
 696
 697 // UnmarshalString will populate the fields of a protocol buffer based
 698 // on a JSON string. This function is lenient and will decode any options
 699 // permutations of the related Marshaler.
 700 func UnmarshalString(str string, pb proto.Message) error {
 701         return new(Unmarshaler).Unmarshal(strings.NewReader(str), pb)
 702 }
 703
 704 // unmarshalValue converts/copies a value into the target.
 705 // prop may be nil.
 706 func (u *Unmarshaler) unmarshalValue(target reflect.Value, inputValue json.RawMessage, prop *proto.Properties) error {
 707         targetType := target.Type()
 708
 709         // Allocate memory for pointer fields.
 710         if targetType.Kind() == reflect.Ptr {
 711                 // If input value is "null" and target is a pointer type, then the field should be treated as not set
 712                 // UNLESS the target is structpb.Value, in which case it should be set to structpb.NullValue.
 713                 _, isJSONPBUnmarshaler := target.Interface().(JSONPBUnmarshaler)
 714                 if string(inputValue) == "null" && targetType != reflect.TypeOf(&stpb.Value{}) && !isJSONPBUnmarshaler {
 715                         return nil
 716                 }
 717                 target.Set(reflect.New(targetType.Elem()))
 718
 719                 return u.unmarshalValue(target.Elem(), inputValue, prop)
 720         }
 721
 722         if jsu, ok := target.Addr().Interface().(JSONPBUnmarshaler); ok {
 723                 return jsu.UnmarshalJSONPB(u, []byte(inputValue))
 724         }
 725
 726         // Handle well-known types that are not pointers.
 727         if w, ok := target.Addr().Interface().(wkt); ok {
 728                 switch w.XXX_WellKnownType() {
 729                 case "DoubleValue", "FloatValue", "Int64Value", "UInt64Value",
 730                         "Int32Value", "UInt32Value", "BoolValue", "StringValue", "BytesValue":
 731                         return u.unmarshalValue(target.Field(0), inputValue, prop)
 732                 case "Any":
 733                         // Use json.RawMessage pointer type instead of value to support pre-1.8 version.
 734                         // 1.8 changed RawMessage.MarshalJSON from pointer type to value type, see
 735                         // https://github.com/golang/go/issues/14493
 736                         var jsonFields map[string]*json.RawMessage
 737                         if err := json.Unmarshal(inputValue, &jsonFields); err != nil {
 738                                 return err
 739                         }
 740
 741                         val, ok := jsonFields["@type"]
 742                         if !ok || val == nil {
 743                                 return errors.New("Any JSON doesn't have '@type'")
 744                         }
 745
 746                         var turl string
 747                         if err := json.Unmarshal([]byte(*val), &turl); err != nil {
 748                                 return fmt.Errorf("can't unmarshal Any's '@type': %q", *val)
 749                         }
 750                         target.Field(0).SetString(turl)
 751
 752                         var m proto.Message
 753                         var err error
 754                         if u.AnyResolver != nil {
 755                                 m, err = u.AnyResolver.Resolve(turl)
 756                         } else {
 757                                 m, err = defaultResolveAny(turl)
 758                         }
 759                         if err != nil {
 760                                 return err
 761                         }
 762
 763                         if _, ok := m.(wkt); ok {
 764                                 val, ok := jsonFields["value"]
 765                                 if !ok {
 766                                         return errors.New("Any JSON doesn't have 'value'")
 767                                 }
 768
 769                                 if err := u.unmarshalValue(reflect.ValueOf(m).Elem(), *val, nil); err != nil {
 770                                         return fmt.Errorf("can't unmarshal Any nested proto %T: %v", m, err)
 771                                 }
 772                         } else {
 773                                 delete(jsonFields, "@type")
 774                                 nestedProto, err := json.Marshal(jsonFields)
 775                                 if err != nil {
 776                                         return fmt.Errorf("can't generate JSON for Any's nested proto to be unmarshaled: %v", err)
 777                                 }
 778
 779                                 if err = u.unmarshalValue(reflect.ValueOf(m).Elem(), nestedProto, nil); err != nil {
 780                                         return fmt.Errorf("can't unmarshal Any nested proto %T: %v", m, err)
 781                                 }
 782                         }
 783
 784                         b, err := proto.Marshal(m)
 785                         if err != nil {
 786                                 return fmt.Errorf("can't marshal proto %T into Any.Value: %v", m, err)
 787                         }
 788                         target.Field(1).SetBytes(b)
 789
 790                         return nil
 791                 case "Duration":
 792                         unq, err := unquote(string(inputValue))
 793                         if err != nil {
 794                                 return err
 795                         }
 796
 797                         d, err := time.ParseDuration(unq)
 798                         if err != nil {
 799                                 return fmt.Errorf("bad Duration: %v", err)
 800                         }
 801
 802                         ns := d.Nanoseconds()
 803                         s := ns / 1e9
 804                         ns %= 1e9
 805                         target.Field(0).SetInt(s)
 806                         target.Field(1).SetInt(ns)
 807                         return nil
 808                 case "Timestamp":
 809                         unq, err := unquote(string(inputValue))
 810                         if err != nil {
 811                                 return err
 812                         }
 813
 814                         t, err := time.Parse(time.RFC3339Nano, unq)
 815                         if err != nil {
 816                                 return fmt.Errorf("bad Timestamp: %v", err)
 817                         }
 818
 819                         target.Field(0).SetInt(t.Unix())
 820                         target.Field(1).SetInt(int64(t.Nanosecond()))
 821                         return nil
 822                 case "Struct":
 823                         var m map[string]json.RawMessage
 824                         if err := json.Unmarshal(inputValue, &m); err != nil {
 825                                 return fmt.Errorf("bad StructValue: %v", err)
 826                         }
 827
 828                         target.Field(0).Set(reflect.ValueOf(map[string]*stpb.Value{}))
 829                         for k, jv := range m {
 830                                 pv := &stpb.Value{}
 831                                 if err := u.unmarshalValue(reflect.ValueOf(pv).Elem(), jv, prop); err != nil {
 832                                         return fmt.Errorf("bad value in StructValue for key %q: %v", k, err)
 833                                 }
 834                                 target.Field(0).SetMapIndex(reflect.ValueOf(k), reflect.ValueOf(pv))
 835                         }
 836                         return nil
 837                 case "ListValue":
 838                         var s []json.RawMessage
 839                         if err := json.Unmarshal(inputValue, &s); err != nil {
 840                                 return fmt.Errorf("bad ListValue: %v", err)
 841                         }
 842
 843                         target.Field(0).Set(reflect.ValueOf(make([]*stpb.Value, len(s))))
 844                         for i, sv := range s {
 845                                 if err := u.unmarshalValue(target.Field(0).Index(i), sv, prop); err != nil {
 846                                         return err
 847                                 }
 848                         }
 849                         return nil
 850                 case "Value":
 851                         ivStr := string(inputValue)
 852                         if ivStr == "null" {
 853                                 target.Field(0).Set(reflect.ValueOf(&stpb.Value_NullValue{}))
 854                         } else if v, err := strconv.ParseFloat(ivStr, 0); err == nil {
 855                                 target.Field(0).Set(reflect.ValueOf(&stpb.Value_NumberValue{v}))
 856                         } else if v, err := unquote(ivStr); err == nil {
 857                                 target.Field(0).Set(reflect.ValueOf(&stpb.Value_StringValue{v}))
 858                         } else if v, err := strconv.ParseBool(ivStr); err == nil {
 859                                 target.Field(0).Set(reflect.ValueOf(&stpb.Value_BoolValue{v}))
 860                         } else if err := json.Unmarshal(inputValue, &[]json.RawMessage{}); err == nil {
 861                                 lv := &stpb.ListValue{}
 862                                 target.Field(0).Set(reflect.ValueOf(&stpb.Value_ListValue{lv}))
 863                                 return u.unmarshalValue(reflect.ValueOf(lv).Elem(), inputValue, prop)
 864                         } else if err := json.Unmarshal(inputValue, &map[string]json.RawMessage{}); err == nil {
 865                                 sv := &stpb.Struct{}
 866                                 target.Field(0).Set(reflect.ValueOf(&stpb.Value_StructValue{sv}))
 867                                 return u.unmarshalValue(reflect.ValueOf(sv).Elem(), inputValue, prop)
 868                         } else {
 869                                 return fmt.Errorf("unrecognized type for Value %q", ivStr)
 870                         }
 871                         return nil
 872                 }
 873         }
 874
 875         // Handle enums, which have an underlying type of int32,
 876         // and may appear as strings.
 877         // The case of an enum appearing as a number is handled
 878         // at the bottom of this function.
 879         if inputValue[0] == '"' && prop != nil && prop.Enum != "" {
 880                 vmap := proto.EnumValueMap(prop.Enum)
 881                 // Don't need to do unquoting; valid enum names
 882                 // are from a limited character set.
 883                 s := inputValue[1 : len(inputValue)-1]
 884                 n, ok := vmap[string(s)]
 885                 if !ok {
 886                         return fmt.Errorf("unknown value %q for enum %s", s, prop.Enum)
 887                 }
 888                 if target.Kind() == reflect.Ptr { // proto2
 889                         target.Set(reflect.New(targetType.Elem()))
 890                         target = target.Elem()
 891                 }
 892                 if targetType.Kind() != reflect.Int32 {
 893                         return fmt.Errorf("invalid target %q for enum %s", targetType.Kind(), prop.Enum)
 894                 }
 895                 target.SetInt(int64(n))
 896                 return nil
 897         }
 898
 899         // Handle nested messages.
 900         if targetType.Kind() == reflect.Struct {
 901                 var jsonFields map[string]json.RawMessage
 902                 if err := json.Unmarshal(inputValue, &jsonFields); err != nil {
 903                         return err
 904                 }
 905
 906                 consumeField := func(prop *proto.Properties) (json.RawMessage, bool) {
 907                         // Be liberal in what names we accept; both orig_name and camelName are okay.
 908                         fieldNames := acceptedJSONFieldNames(prop)
 909
 910                         vOrig, okOrig := jsonFields[fieldNames.orig]
 911                         vCamel, okCamel := jsonFields[fieldNames.camel]
 912                         if !okOrig && !okCamel {
 913                                 return nil, false
 914                         }
 915                         // If, for some reason, both are present in the data, favour the camelName.
 916                         var raw json.RawMessage
 917                         if okOrig {
 918                                 raw = vOrig
 919                                 delete(jsonFields, fieldNames.orig)
 920                         }
 921                         if okCamel {
 922                                 raw = vCamel
 923                                 delete(jsonFields, fieldNames.camel)
 924                         }
 925                         return raw, true
 926                 }
 927
 928                 sprops := proto.GetProperties(targetType)
 929                 for i := 0; i < target.NumField(); i++ {
 930                         ft := target.Type().Field(i)
 931                         if strings.HasPrefix(ft.Name, "XXX_") {
 932                                 continue
 933                         }
 934
 935                         valueForField, ok := consumeField(sprops.Prop[i])
 936                         if !ok {
 937                                 continue
 938                         }
 939
 940                         if err := u.unmarshalValue(target.Field(i), valueForField, sprops.Prop[i]); err != nil {
 941                                 return err
 942                         }
 943                 }
 944                 // Check for any oneof fields.
 945                 if len(jsonFields) > 0 {
 946                         for _, oop := range sprops.OneofTypes {
 947                                 raw, ok := consumeField(oop.Prop)
 948                                 if !ok {
 949                                         continue
 950                                 }
 951                                 nv := reflect.New(oop.Type.Elem())
 952                                 target.Field(oop.Field).Set(nv)
 953                                 if err := u.unmarshalValue(nv.Elem().Field(0), raw, oop.Prop); err != nil {
 954                                         return err
 955                                 }
 956                         }
 957                 }
 958                 // Handle proto2 extensions.
 959                 if len(jsonFields) > 0 {
 960                         if ep, ok := target.Addr().Interface().(proto.Message); ok {
 961                                 for _, ext := range proto.RegisteredExtensions(ep) {
 962                                         name := fmt.Sprintf("[%s]", ext.Name)
 963                                         raw, ok := jsonFields[name]
 964                                         if !ok {
 965                                                 continue
 966                                         }
 967                                         delete(jsonFields, name)
 968                                         nv := reflect.New(reflect.TypeOf(ext.ExtensionType).Elem())
 969                                         if err := u.unmarshalValue(nv.Elem(), raw, nil); err != nil {
 970                                                 return err
 971                                         }
 972                                         if err := proto.SetExtension(ep, ext, nv.Interface()); err != nil {
 973                                                 return err
 974                                         }
 975                                 }
 976                         }
 977                 }
 978                 if !u.AllowUnknownFields && len(jsonFields) > 0 {
 979                         // Pick any field to be the scapegoat.
 980                         var f string
 981                         for fname := range jsonFields {
 982                                 f = fname
 983                                 break
 984                         }
 985                         return fmt.Errorf("unknown field %q in %v", f, targetType)
 986                 }
 987                 return nil
 988         }
 989
 990         // Handle arrays (which aren't encoded bytes)
 991         if targetType.Kind() == reflect.Slice && targetType.Elem().Kind() != reflect.Uint8 {
 992                 var slc []json.RawMessage
 993                 if err := json.Unmarshal(inputValue, &slc); err != nil {
 994                         return err
 995                 }
 996                 if slc != nil {
 997                         l := len(slc)
 998                         target.Set(reflect.MakeSlice(targetType, l, l))
 999                         for i := 0; i < l; i++ {
1000                                 if err := u.unmarshalValue(target.Index(i), slc[i], prop); err != nil {
1001                                         return err
1002                                 }
1003                         }
1004                 }
1005                 return nil
1006         }
1007
1008         // Handle maps (whose keys are always strings)
1009         if targetType.Kind() == reflect.Map {
1010                 var mp map[string]json.RawMessage
1011                 if err := json.Unmarshal(inputValue, &mp); err != nil {
1012                         return err
1013                 }
1014                 if mp != nil {
1015                         target.Set(reflect.MakeMap(targetType))
1016                         for ks, raw := range mp {
1017                                 // Unmarshal map key. The core json library already decoded the key into a
1018                                 // string, so we handle that specially. Other types were quoted post-serialization.
1019                                 var k reflect.Value
1020                                 if targetType.Key().Kind() == reflect.String {
1021                                         k = reflect.ValueOf(ks)
1022                                 } else {
1023                                         k = reflect.New(targetType.Key()).Elem()
1024                                         var kprop *proto.Properties
1025                                         if prop != nil && prop.MapKeyProp != nil {
1026                                                 kprop = prop.MapKeyProp
1027                                         }
1028                                         if err := u.unmarshalValue(k, json.RawMessage(ks), kprop); err != nil {
1029                                                 return err
1030                                         }
1031                                 }
1032
1033                                 // Unmarshal map value.
1034                                 v := reflect.New(targetType.Elem()).Elem()
1035                                 var vprop *proto.Properties
1036                                 if prop != nil && prop.MapValProp != nil {
1037                                         vprop = prop.MapValProp
1038                                 }
1039                                 if err := u.unmarshalValue(v, raw, vprop); err != nil {
1040                                         return err
1041                                 }
1042                                 target.SetMapIndex(k, v)
1043                         }
1044                 }
1045                 return nil
1046         }
1047
1048         // Non-finite numbers can be encoded as strings.
1049         isFloat := targetType.Kind() == reflect.Float32 || targetType.Kind() == reflect.Float64
1050         if isFloat {
1051                 if num, ok := nonFinite[string(inputValue)]; ok {
1052                         target.SetFloat(num)
1053                         return nil
1054                 }
1055         }
1056
1057         // integers & floats can be encoded as strings. In this case we drop
1058         // the quotes and proceed as normal.
1059         isNum := targetType.Kind() == reflect.Int64 || targetType.Kind() == reflect.Uint64 ||
1060                 targetType.Kind() == reflect.Int32 || targetType.Kind() == reflect.Uint32 ||
1061                 targetType.Kind() == reflect.Float32 || targetType.Kind() == reflect.Float64
1062         if isNum && strings.HasPrefix(string(inputValue), `"`) {
1063                 inputValue = inputValue[1 : len(inputValue)-1]
1064         }
1065
1066         // Use the encoding/json for parsing other value types.
1067         return json.Unmarshal(inputValue, target.Addr().Interface())
1068 }
1069
1070 func unquote(s string) (string, error) {
1071         var ret string
1072         err := json.Unmarshal([]byte(s), &ret)
1073         return ret, err
1074 }
1075
1076 // jsonProperties returns parsed proto.Properties for the field and corrects JSONName attribute.
1077 func jsonProperties(f reflect.StructField, origName bool) *proto.Properties {
1078         var prop proto.Properties
1079         prop.Init(f.Type, f.Name, f.Tag.Get("protobuf"), &f)
1080         if origName || prop.JSONName == "" {
1081                 prop.JSONName = prop.OrigName
1082         }
1083         return &prop
1084 }
1085
1086 type fieldNames struct {
1087         orig, camel string
1088 }
1089
1090 func acceptedJSONFieldNames(prop *proto.Properties) fieldNames {
1091         opts := fieldNames{orig: prop.OrigName, camel: prop.OrigName}
1092         if prop.JSONName != "" {
1093                 opts.camel = prop.JSONName
1094         }
1095         return opts
1096 }
1097
1098 // Writer wrapper inspired by https://blog.golang.org/errors-are-values
1099 type errWriter struct {
1100         writer io.Writer
1101         err    error
1102 }
1103
1104 func (w *errWriter) write(str string) {
1105         if w.err != nil {
1106                 return
1107         }
1108         _, w.err = w.writer.Write([]byte(str))
1109 }
1110
1111 // Map fields may have key types of non-float scalars, strings and enums.
1112 // The easiest way to sort them in some deterministic order is to use fmt.
1113 // If this turns out to be inefficient we can always consider other options,
1114 // such as doing a Schwartzian transform.
1115 //
1116 // Numeric keys are sorted in numeric order per
1117 // https://developers.google.com/protocol-buffers/docs/proto#maps.
1118 type mapKeys []reflect.Value
1119
1120 func (s mapKeys) Len() int      { return len(s) }
1121 func (s mapKeys) Swap(i, j int) { s[i], s[j] = s[j], s[i] }
1122 func (s mapKeys) Less(i, j int) bool {
1123         if k := s[i].Kind(); k == s[j].Kind() {
1124                 switch k {
1125                 case reflect.String:
1126                         return s[i].String() < s[j].String()
1127                 case reflect.Int32, reflect.Int64:
1128                         return s[i].Int() < s[j].Int()
1129                 case reflect.Uint32, reflect.Uint64:
1130                         return s[i].Uint() < s[j].Uint()
1131                 }
1132         }
1133         return fmt.Sprint(s[i].Interface()) < fmt.Sprint(s[j].Interface())
1134 }
1135
1136 // checkRequiredFields returns an error if any required field in the given proto message is not set.
1137 // This function is used by both Marshal and Unmarshal.  While required fields only exist in a
1138 // proto2 message, a proto3 message can contain proto2 message(s).
1139 func checkRequiredFields(pb proto.Message) error {
1140         // Most well-known type messages do not contain required fields.  The "Any" type may contain
1141         // a message that has required fields.
1142         //
1143         // When an Any message is being marshaled, the code will invoked proto.Unmarshal on Any.Value
1144         // field in order to transform that into JSON, and that should have returned an error if a
1145         // required field is not set in the embedded message.
1146         //
1147         // When an Any message is being unmarshaled, the code will have invoked proto.Marshal on the
1148         // embedded message to store the serialized message in Any.Value field, and that should have
1149         // returned an error if a required field is not set.
1150         if _, ok := pb.(wkt); ok {
1151                 return nil
1152         }
1153
1154         v := reflect.ValueOf(pb)
1155         // Skip message if it is not a struct pointer.
1156         if v.Kind() != reflect.Ptr {
1157                 return nil
1158         }
1159         v = v.Elem()
1160         if v.Kind() != reflect.Struct {
1161                 return nil
1162         }
1163
1164         for i := 0; i < v.NumField(); i++ {
1165                 field := v.Field(i)
1166                 sfield := v.Type().Field(i)
1167
1168                 if sfield.PkgPath != "" {
1169                         // blank PkgPath means the field is exported; skip if not exported
1170                         continue
1171                 }
1172
1173                 if strings.HasPrefix(sfield.Name, "XXX_") {
1174                         continue
1175                 }
1176
1177                 // Oneof field is an interface implemented by wrapper structs containing the actual oneof
1178                 // field, i.e. an interface containing &T{real_value}.
1179                 if sfield.Tag.Get("protobuf_oneof") != "" {
1180                         if field.Kind() != reflect.Interface {
1181                                 continue
1182                         }
1183                         v := field.Elem()
1184                         if v.Kind() != reflect.Ptr || v.IsNil() {
1185                                 continue
1186                         }
1187                         v = v.Elem()
1188                         if v.Kind() != reflect.Struct || v.NumField() < 1 {
1189                                 continue
1190                         }
1191                         field = v.Field(0)
1192                         sfield = v.Type().Field(0)
1193                 }
1194
1195                 protoTag := sfield.Tag.Get("protobuf")
1196                 if protoTag == "" {
1197                         continue
1198                 }
1199                 var prop proto.Properties
1200                 prop.Init(sfield.Type, sfield.Name, protoTag, &sfield)
1201
1202                 switch field.Kind() {
1203                 case reflect.Map:
1204                         if field.IsNil() {
1205                                 continue
1206                         }
1207                         // Check each map value.
1208                         keys := field.MapKeys()
1209                         for _, k := range keys {
1210                                 v := field.MapIndex(k)
1211                                 if err := checkRequiredFieldsInValue(v); err != nil {
1212                                         return err
1213                                 }
1214                         }
1215                 case reflect.Slice:
1216                         // Handle non-repeated type, e.g. bytes.
1217                         if !prop.Repeated {
1218                                 if prop.Required && field.IsNil() {
1219                                         return fmt.Errorf("required field %q is not set", prop.Name)
1220                                 }
1221                                 continue
1222                         }
1223
1224                         // Handle repeated type.
1225                         if field.IsNil() {
1226                                 continue
1227                         }
1228                         // Check each slice item.
1229                         for i := 0; i < field.Len(); i++ {
1230                                 v := field.Index(i)
1231                                 if err := checkRequiredFieldsInValue(v); err != nil {
1232                                         return err
1233                                 }
1234                         }
1235                 case reflect.Ptr:
1236                         if field.IsNil() {
1237                                 if prop.Required {
1238                                         return fmt.Errorf("required field %q is not set", prop.Name)
1239                                 }
1240                                 continue
1241                         }
1242                         if err := checkRequiredFieldsInValue(field); err != nil {
1243                                 return err
1244                         }
1245                 }
1246         }
1247
1248         // Handle proto2 extensions.
1249         for _, ext := range proto.RegisteredExtensions(pb) {
1250                 if !proto.HasExtension(pb, ext) {
1251                         continue
1252                 }
1253                 ep, err := proto.GetExtension(pb, ext)
1254                 if err != nil {
1255                         return err
1256                 }
1257                 err = checkRequiredFieldsInValue(reflect.ValueOf(ep))
1258                 if err != nil {
1259                         return err
1260                 }
1261         }
1262
1263         return nil
1264 }
1265
1266 func checkRequiredFieldsInValue(v reflect.Value) error {
1267         if pm, ok := v.Interface().(proto.Message); ok {
1268                 return checkRequiredFields(pm)
1269         }
1270         return nil
1271 }