encoding/jsonpb: rearrange and add descriptions in well_known_types.go

Rearranged well_known_types.go such that marshaling and unmarshaling
funcs for a particular type are closer, and added description for its
JSON representation.

Change-Id: Id9f5e4060158f66392a351debaffe1d7260919e4
Reviewed-on: https://go-review.googlesource.com/c/protobuf/+/169497
Reviewed-by: Joe Tsai <thebrokentoaster@gmail.com>

encoding/jsonpb/well_known_types.go

@@ -17,7 +17,8 @@ import (
 )
 
 // isCustomType returns true if type name has special JSON conversion rules.
-// The list of custom types here has to match the ones in marshalCustomTypes.
+// The list of custom types here has to match the ones in marshalCustomType and
+// unmarshalCustomType.
 func isCustomType(name pref.FullName) bool {
 	switch name {
 	case "google.protobuf.Any",
@@ -59,7 +60,7 @@ func (e encoder) marshalCustomType(m pref.Message) error {
 		"google.protobuf.UInt64Value",
 		"google.protobuf.StringValue",
 		"google.protobuf.BytesValue":
-		return e.marshalKnownScalar(m)
+		return e.marshalWrapperType(m)
 
 	case "google.protobuf.Struct":
 		return e.marshalStruct(m)
@@ -83,6 +84,50 @@ func (e encoder) marshalCustomType(m pref.Message) error {
 	panic(fmt.Sprintf("%q does not have a custom marshaler", name))
 }
 
+// unmarshalCustomType unmarshals given well-known type message that have
+// special JSON conversion rules. It needs to be a message type where
+// isCustomType returns true, else it will panic.
+func (d decoder) unmarshalCustomType(m pref.Message) error {
+	name := m.Type().FullName()
+	switch name {
+	case "google.protobuf.Any",
+		"google.protobuf.Duration",
+		"google.protobuf.Timestamp":
+		panic(fmt.Sprintf("unmarshaling of %v is not implemented yet", name))
+
+	case "google.protobuf.BoolValue",
+		"google.protobuf.DoubleValue",
+		"google.protobuf.FloatValue",
+		"google.protobuf.Int32Value",
+		"google.protobuf.Int64Value",
+		"google.protobuf.UInt32Value",
+		"google.protobuf.UInt64Value",
+		"google.protobuf.StringValue",
+		"google.protobuf.BytesValue":
+		return d.unmarshalWrapperType(m)
+
+	case "google.protobuf.Struct":
+		return d.unmarshalStruct(m)
+
+	case "google.protobuf.ListValue":
+		return d.unmarshalListValue(m)
+
+	case "google.protobuf.Value":
+		return d.unmarshalKnownValue(m)
+
+	case "google.protobuf.FieldMask":
+		return d.unmarshalFieldMask(m)
+	}
+
+	panic(fmt.Sprintf("%q does not have a custom unmarshaler", name))
+}
+
+// The JSON representation of an Any message uses the regular representation of
+// the deserialized, embedded message, with an additional field `@type` which
+// contains the type URL.  If the embedded message type is well-known and has a
+// custom JSON representation, that representation will be embedded adding a
+// field `value` which holds the custom JSON in addition to the `@type` field.
+
 func (e encoder) marshalAny(m pref.Message) error {
 	var nerr errors.NonFatal
 	msgType := m.Type()
@@ -98,7 +143,7 @@ func (e encoder) marshalAny(m pref.Message) error {
 			return nil
 		} else {
 			// Return error if type_url field is not set, but value is set.
-			return errors.New("field %s.type_url is not set", msgType.FullName())
+			return errors.New("%s: type_url is not set", msgType.FullName())
 		}
 	}
 
@@ -115,14 +160,14 @@ func (e encoder) marshalAny(m pref.Message) error {
 	// Resolve the type in order to unmarshal value field.
 	emt, err := e.resolver.FindMessageByURL(typeURL)
 	if !nerr.Merge(err) {
-		return errors.New("unable to resolve %v: %v", typeURL, err)
+		return errors.New("%s: unable to resolve %q: %v", msgType.FullName(), typeURL, err)
 	}
 
 	em := emt.New()
 	// TODO: Need to set types registry in binary unmarshaling.
 	err = proto.Unmarshal(valueVal.Bytes(), em.Interface())
 	if !nerr.Merge(err) {
-		return errors.New("unable to unmarshal %v: %v", typeURL, err)
+		return errors.New("%s: unable to unmarshal %q: %v", msgType.FullName(), typeURL, err)
 	}
 
 	// If type of value has custom JSON encoding, marshal out a field "value"
@@ -141,7 +186,9 @@ func (e encoder) marshalAny(m pref.Message) error {
 	return nerr.E
 }
 
-func (e encoder) marshalKnownScalar(m pref.Message) error {
+// Wrapper types are encoded as JSON primitives like string, number or boolean.
+
+func (e encoder) marshalWrapperType(m pref.Message) error {
 	msgType := m.Type()
 	fieldDescs := msgType.Fields()
 	knownFields := m.KnownFields()
@@ -153,6 +200,26 @@ func (e encoder) marshalKnownScalar(m pref.Message) error {
 	return e.marshalSingular(val, fd)
 }
 
+func (d decoder) unmarshalWrapperType(m pref.Message) error {
+	var nerr errors.NonFatal
+	msgType := m.Type()
+	fieldDescs := msgType.Fields()
+	knownFields := m.KnownFields()
+
+	// The "value" field has the same field number for all wrapper types.
+	const num = fieldnum.BoolValue_Value
+	fd := fieldDescs.ByNumber(num)
+	val, err := d.unmarshalScalar(fd)
+	if !nerr.Merge(err) {
+		return err
+	}
+	knownFields.Set(num, val)
+	return nerr.E
+}
+
+// The JSON representation for Struct is a JSON object that contains the encoded
+// Struct.fields map and follows the serialization rules for a map.
+
 func (e encoder) marshalStruct(m pref.Message) error {
 	msgType := m.Type()
 	fieldDescs := msgType.Fields()
@@ -163,6 +230,20 @@ func (e encoder) marshalStruct(m pref.Message) error {
 	return e.marshalMap(val.Map(), fd)
 }
 
+func (d decoder) unmarshalStruct(m pref.Message) error {
+	msgType := m.Type()
+	fieldDescs := msgType.Fields()
+	knownFields := m.KnownFields()
+
+	fd := fieldDescs.ByNumber(fieldnum.Struct_Fields)
+	val := knownFields.Get(fieldnum.Struct_Fields)
+	return d.unmarshalMap(val.Map(), fd)
+}
+
+// The JSON representation for ListValue is JSON array that contains the encoded
+// ListValue.values repeated field and follows the serialization rules for a
+// repeated field.
+
 func (e encoder) marshalListValue(m pref.Message) error {
 	msgType := m.Type()
 	fieldDescs := msgType.Fields()
@@ -173,6 +254,20 @@ func (e encoder) marshalListValue(m pref.Message) error {
 	return e.marshalList(val.List(), fd)
 }
 
+func (d decoder) unmarshalListValue(m pref.Message) error {
+	msgType := m.Type()
+	fieldDescs := msgType.Fields()
+	knownFields := m.KnownFields()
+
+	fd := fieldDescs.ByNumber(fieldnum.ListValue_Values)
+	val := knownFields.Get(fieldnum.ListValue_Values)
+	return d.unmarshalList(val.List(), fd)
+}
+
+// The JSON representation for a Value is dependent on the oneof field that is
+// set. Each of the field in the oneof has its own custom serialization rule. A
+// Value message needs to be a oneof field set, else it is an error.
+
 func (e encoder) marshalKnownValue(m pref.Message) error {
 	msgType := m.Type()
 	fieldDescs := msgType.Oneofs().Get(0).Fields()
@@ -193,9 +288,99 @@ func (e encoder) marshalKnownValue(m pref.Message) error {
 	return errors.New("%s: none of the variants is set", msgType.FullName())
 }
 
+func isKnownValue(fd pref.FieldDescriptor) bool {
+	md := fd.MessageType()
+	return md != nil && md.FullName() == "google.protobuf.Value"
+}
+
+func (d decoder) unmarshalKnownValue(m pref.Message) error {
+	var nerr errors.NonFatal
+	knownFields := m.KnownFields()
+
+	switch d.Peek() {
+	case json.Null:
+		d.Read()
+		knownFields.Set(fieldnum.Value_NullValue, pref.ValueOf(pref.EnumNumber(0)))
+
+	case json.Bool:
+		jval, err := d.Read()
+		if err != nil {
+			return err
+		}
+		val, err := unmarshalBool(jval)
+		if err != nil {
+			return err
+		}
+		knownFields.Set(fieldnum.Value_BoolValue, val)
+
+	case json.Number:
+		jval, err := d.Read()
+		if err != nil {
+			return err
+		}
+		val, err := unmarshalFloat(jval, 64)
+		if err != nil {
+			return err
+		}
+		knownFields.Set(fieldnum.Value_NumberValue, val)
+
+	case json.String:
+		// A JSON string may have been encoded from the number_value field,
+		// e.g. "NaN", "Infinity", etc. Parsing a proto double type also allows
+		// for it to be in JSON string form. Given this custom encoding spec,
+		// however, there is no way to identify that and hence a JSON string is
+		// always assigned to the string_value field, which means that certain
+		// encoding cannot be parsed back to the same field.
+		jval, err := d.Read()
+		if !nerr.Merge(err) {
+			return err
+		}
+		val, err := unmarshalString(jval)
+		if !nerr.Merge(err) {
+			return err
+		}
+		knownFields.Set(fieldnum.Value_StringValue, val)
+
+	case json.StartObject:
+		m := knownFields.NewMessage(fieldnum.Value_StructValue)
+		if err := d.unmarshalStruct(m); !nerr.Merge(err) {
+			return err
+		}
+		knownFields.Set(fieldnum.Value_StructValue, pref.ValueOf(m))
+
+	case json.StartArray:
+		m := knownFields.NewMessage(fieldnum.Value_ListValue)
+		if err := d.unmarshalListValue(m); !nerr.Merge(err) {
+			return err
+		}
+		knownFields.Set(fieldnum.Value_ListValue, pref.ValueOf(m))
+
+	default:
+		jval, err := d.Read()
+		if err != nil {
+			return err
+		}
+		return unexpectedJSONError{jval}
+	}
+
+	return nerr.E
+}
+
+// The JSON representation for a Duration is a JSON string that ends in the
+// suffix "s" (indicating seconds) and is preceded by the number of seconds,
+// with nanoseconds expressed as fractional seconds.
+//
+// Durations less than one second are represented with a 0 seconds field and a
+// positive or negative nanos field. For durations of one second or more, a
+// non-zero value for the nanos field must be of the same sign as the seconds
+// field.
+//
+// Duration.seconds must be from -315,576,000,000 to +315,576,000,000 inclusive.
+// Duration.nanos must be from -999,999,999 to +999,999,999 inclusive.
+
 const (
-	secondsInNanos       = int64(time.Second / time.Nanosecond)
-	maxSecondsInDuration = int64(315576000000)
+	secondsInNanos       = 999999999
+	maxSecondsInDuration = 315576000000
 )
 
 func (e encoder) marshalDuration(m pref.Message) error {
@@ -207,10 +392,10 @@ func (e encoder) marshalDuration(m pref.Message) error {
 	secs := secsVal.Int()
 	nanos := nanosVal.Int()
 	if secs < -maxSecondsInDuration || secs > maxSecondsInDuration {
-		return errors.New("%s.seconds out of range", msgType.FullName())
+		return errors.New("%s: seconds out of range", msgType.FullName())
 	}
 	if nanos <= -secondsInNanos || nanos >= secondsInNanos {
-		return errors.New("%s.nanos out of range", msgType.FullName())
+		return errors.New("%s: nanos out of range", msgType.FullName())
 	}
 	if (secs > 0 && nanos < 0) || (secs < 0 && nanos > 0) {
 		return errors.New("%s: signs of seconds and nanos do not match", msgType.FullName())
@@ -232,6 +417,19 @@ func (e encoder) marshalDuration(m pref.Message) error {
 	return nil
 }
 
+// The JSON representation for a Timestamp is a JSON string in the RFC 3339
+// format, i.e. "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" where
+// {year} is always expressed using four digits while {month}, {day}, {hour},
+// {min}, and {sec} are zero-padded to two digits each. The fractional seconds,
+// which can go up to 9 digits, up to 1 nanosecond resolution, is optional. The
+// "Z" suffix indicates the timezone ("UTC"); the timezone is required. Encoding
+// should always use UTC (as indicated by "Z") and a decoder should be able to
+// accept both UTC and other timezones (as indicated by an offset).
+//
+// Timestamp.seconds must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z
+// inclusive.
+// Timestamp.nanos must be from 0 to 999,999,999 inclusive.
+
 const (
 	maxTimestampSeconds = 253402300799
 	minTimestampSeconds = -62135596800
@@ -246,10 +444,10 @@ func (e encoder) marshalTimestamp(m pref.Message) error {
 	secs := secsVal.Int()
 	nanos := nanosVal.Int()
 	if secs < minTimestampSeconds || secs > maxTimestampSeconds {
-		return errors.New("%s.seconds out of range", msgType.FullName())
+		return errors.New("%s: seconds out of range %q", msgType.FullName(), secs)
 	}
 	if nanos < 0 || nanos >= secondsInNanos {
-		return errors.New("%s.nanos out of range", msgType.FullName())
+		return errors.New("%s: nanos out of range %q", msgType.FullName(), nanos)
 	}
 	// Uses RFC 3339, where generated output will be Z-normalized and uses 0, 3,
 	// 6 or 9 fractional digits.
@@ -262,6 +460,11 @@ func (e encoder) marshalTimestamp(m pref.Message) error {
 	return nil
 }
 
+// The JSON representation for a FieldMask is a JSON string where paths are
+// separated by a comma. Fields name in each path are converted to/from
+// lower-camel naming conventions. Encoding should fail if the path name would
+// end up differently after a round-trip.
+
 func (e encoder) marshalFieldMask(m pref.Message) error {
 	msgType := m.Type()
 	knownFields := m.KnownFields()
@@ -285,6 +488,34 @@ func (e encoder) marshalFieldMask(m pref.Message) error {
 	return nil
 }
 
+func (d decoder) unmarshalFieldMask(m pref.Message) error {
+	var nerr errors.NonFatal
+	jval, err := d.Read()
+	if !nerr.Merge(err) {
+		return err
+	}
+	if jval.Type() != json.String {
+		return unexpectedJSONError{jval}
+	}
+	str := strings.TrimSpace(jval.String())
+	if str == "" {
+		return nil
+	}
+	paths := strings.Split(str, ",")
+
+	knownFields := m.KnownFields()
+	val := knownFields.Get(fieldnum.FieldMask_Paths)
+	list := val.List()
+
+	for _, s := range paths {
+		s = strings.TrimSpace(s)
+		// Convert to snake_case. Unlike encoding, no validation is done because
+		// it is not possible to know the original path names.
+		list.Append(pref.ValueOf(snakeCase(s)))
+	}
+	return nil
+}
+
 // camelCase converts given string into camelCase where ASCII character after _
 // is turned into uppercase and _'s are removed.
 func camelCase(s string) string {
@@ -330,184 +561,3 @@ func isASCIILower(c byte) bool {
 func isASCIIUpper(c byte) bool {
 	return 'A' <= c && c <= 'Z'
 }
-
-// unmarshalCustomType unmarshals given well-known type message that have
-// special JSON conversion rules. It needs to be a message type where
-// isCustomType returns true, else it will panic.
-func (d decoder) unmarshalCustomType(m pref.Message) error {
-	name := m.Type().FullName()
-	switch name {
-	case "google.protobuf.Any",
-		"google.protobuf.Duration",
-		"google.protobuf.Timestamp":
-		panic(fmt.Sprintf("unmarshaling of %v is not implemented yet", name))
-
-	case "google.protobuf.BoolValue",
-		"google.protobuf.DoubleValue",
-		"google.protobuf.FloatValue",
-		"google.protobuf.Int32Value",
-		"google.protobuf.Int64Value",
-		"google.protobuf.UInt32Value",
-		"google.protobuf.UInt64Value",
-		"google.protobuf.StringValue",
-		"google.protobuf.BytesValue":
-		return d.unmarshalKnownScalar(m)
-
-	case "google.protobuf.Struct":
-		return d.unmarshalStruct(m)
-
-	case "google.protobuf.ListValue":
-		return d.unmarshalListValue(m)
-
-	case "google.protobuf.Value":
-		return d.unmarshalKnownValue(m)
-
-	case "google.protobuf.FieldMask":
-		return d.unmarshalFieldMask(m)
-	}
-
-	panic(fmt.Sprintf("%q does not have a custom unmarshaler", name))
-}
-
-func (d decoder) unmarshalKnownScalar(m pref.Message) error {
-	var nerr errors.NonFatal
-	msgType := m.Type()
-	fieldDescs := msgType.Fields()
-	knownFields := m.KnownFields()
-
-	// The "value" field has the same field number for all wrapper types.
-	const num = fieldnum.BoolValue_Value
-	fd := fieldDescs.ByNumber(num)
-	val, err := d.unmarshalScalar(fd)
-	if !nerr.Merge(err) {
-		return err
-	}
-	knownFields.Set(num, val)
-	return nerr.E
-}
-
-func (d decoder) unmarshalStruct(m pref.Message) error {
-	msgType := m.Type()
-	fieldDescs := msgType.Fields()
-	knownFields := m.KnownFields()
-
-	fd := fieldDescs.ByNumber(fieldnum.Struct_Fields)
-	val := knownFields.Get(fieldnum.Struct_Fields)
-	return d.unmarshalMap(val.Map(), fd)
-}
-
-func (d decoder) unmarshalListValue(m pref.Message) error {
-	msgType := m.Type()
-	fieldDescs := msgType.Fields()
-	knownFields := m.KnownFields()
-
-	fd := fieldDescs.ByNumber(fieldnum.ListValue_Values)
-	val := knownFields.Get(fieldnum.ListValue_Values)
-	return d.unmarshalList(val.List(), fd)
-}
-
-func isKnownValue(fd pref.FieldDescriptor) bool {
-	md := fd.MessageType()
-	return md != nil && md.FullName() == "google.protobuf.Value"
-}
-
-func (d decoder) unmarshalKnownValue(m pref.Message) error {
-	var nerr errors.NonFatal
-	knownFields := m.KnownFields()
-
-	switch d.Peek() {
-	case json.Null:
-		d.Read()
-		knownFields.Set(fieldnum.Value_NullValue, pref.ValueOf(pref.EnumNumber(0)))
-
-	case json.Bool:
-		jval, err := d.Read()
-		if err != nil {
-			return err
-		}
-		val, err := unmarshalBool(jval)
-		if err != nil {
-			return err
-		}
-		knownFields.Set(fieldnum.Value_BoolValue, val)
-
-	case json.Number:
-		jval, err := d.Read()
-		if err != nil {
-			return err
-		}
-		val, err := unmarshalFloat(jval, 64)
-		if err != nil {
-			return err
-		}
-		knownFields.Set(fieldnum.Value_NumberValue, val)
-
-	case json.String:
-		// A JSON string may have been encoded from the number_value field,
-		// e.g. "NaN", "Infinity", etc. Parsing a proto double type also allows
-		// for it to be in JSON string form. Given this custom encoding spec,
-		// however, there is no way to identify that and hence a JSON string is
-		// always assigned to the string_value field, which means that certain
-		// encoding cannot be parsed back to the same field.
-		jval, err := d.Read()
-		if !nerr.Merge(err) {
-			return err
-		}
-		val, err := unmarshalString(jval)
-		if !nerr.Merge(err) {
-			return err
-		}
-		knownFields.Set(fieldnum.Value_StringValue, val)
-
-	case json.StartObject:
-		m := knownFields.NewMessage(fieldnum.Value_StructValue)
-		if err := d.unmarshalStruct(m); !nerr.Merge(err) {
-			return err
-		}
-		knownFields.Set(fieldnum.Value_StructValue, pref.ValueOf(m))
-
-	case json.StartArray:
-		m := knownFields.NewMessage(fieldnum.Value_ListValue)
-		if err := d.unmarshalListValue(m); !nerr.Merge(err) {
-			return err
-		}
-		knownFields.Set(fieldnum.Value_ListValue, pref.ValueOf(m))
-
-	default:
-		jval, err := d.Read()
-		if err != nil {
-			return err
-		}
-		return unexpectedJSONError{jval}
-	}
-
-	return nerr.E
-}
-
-func (d decoder) unmarshalFieldMask(m pref.Message) error {
-	var nerr errors.NonFatal
-	jval, err := d.Read()
-	if !nerr.Merge(err) {
-		return err
-	}
-	if jval.Type() != json.String {
-		return unexpectedJSONError{jval}
-	}
-	str := strings.TrimSpace(jval.String())
-	if str == "" {
-		return nil
-	}
-	paths := strings.Split(str, ",")
-
-	knownFields := m.KnownFields()
-	val := knownFields.Get(fieldnum.FieldMask_Paths)
-	list := val.List()
-
-	for _, s := range paths {
-		s = strings.TrimSpace(s)
-		// Convert to snake_case. Unlike encoding, no validation is done because
-		// it is not possible to know the original path names.
-		list.Append(pref.ValueOf(snakeCase(s)))
-	}
-	return nil
-}