encode.go

Documentation: google.golang.org/protobuf/encoding/protojson

     1  // Copyright 2019 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  
     5  package protojson
     6  
     7  import (
     8  	"encoding/base64"
     9  	"fmt"
    10  
    11  	"google.golang.org/protobuf/internal/encoding/json"
    12  	"google.golang.org/protobuf/internal/encoding/messageset"
    13  	"google.golang.org/protobuf/internal/errors"
    14  	"google.golang.org/protobuf/internal/filedesc"
    15  	"google.golang.org/protobuf/internal/flags"
    16  	"google.golang.org/protobuf/internal/genid"
    17  	"google.golang.org/protobuf/internal/order"
    18  	"google.golang.org/protobuf/internal/pragma"
    19  	"google.golang.org/protobuf/proto"
    20  	"google.golang.org/protobuf/reflect/protoreflect"
    21  	"google.golang.org/protobuf/reflect/protoregistry"
    22  )
    23  
    24  const defaultIndent = "  "
    25  
    26  // Format formats the message as a multiline string.
    27  // This function is only intended for human consumption and ignores errors.
    28  // Do not depend on the output being stable. It may change over time across
    29  // different versions of the program.
    30  func Format(m proto.Message) string {
    31  	return MarshalOptions{Multiline: true}.Format(m)
    32  }
    33  
    34  // Marshal writes the given [proto.Message] in JSON format using default options.
    35  // Do not depend on the output being stable. It may change over time across
    36  // different versions of the program.
    37  func Marshal(m proto.Message) ([]byte, error) {
    38  	return MarshalOptions{}.Marshal(m)
    39  }
    40  
    41  // MarshalOptions is a configurable JSON format marshaler.
    42  type MarshalOptions struct {
    43  	pragma.NoUnkeyedLiterals
    44  
    45  	// Multiline specifies whether the marshaler should format the output in
    46  	// indented-form with every textual element on a new line.
    47  	// If Indent is an empty string, then an arbitrary indent is chosen.
    48  	Multiline bool
    49  
    50  	// Indent specifies the set of indentation characters to use in a multiline
    51  	// formatted output such that every entry is preceded by Indent and
    52  	// terminated by a newline. If non-empty, then Multiline is treated as true.
    53  	// Indent can only be composed of space or tab characters.
    54  	Indent string
    55  
    56  	// AllowPartial allows messages that have missing required fields to marshal
    57  	// without returning an error. If AllowPartial is false (the default),
    58  	// Marshal will return error if there are any missing required fields.
    59  	AllowPartial bool
    60  
    61  	// UseProtoNames uses proto field name instead of lowerCamelCase name in JSON
    62  	// field names.
    63  	UseProtoNames bool
    64  
    65  	// UseEnumNumbers emits enum values as numbers.
    66  	UseEnumNumbers bool
    67  
    68  	// EmitUnpopulated specifies whether to emit unpopulated fields. It does not
    69  	// emit unpopulated oneof fields or unpopulated extension fields.
    70  	// The JSON value emitted for unpopulated fields are as follows:
    71  	//  ╔═══════╤════════════════════════════╗
    72  	//  ║ JSON  │ Protobuf field             ║
    73  	//  ╠═══════╪════════════════════════════╣
    74  	//  ║ false │ proto3 boolean fields      ║
    75  	//  ║ 0     │ proto3 numeric fields      ║
    76  	//  ║ ""    │ proto3 string/bytes fields ║
    77  	//  ║ null  │ proto2 scalar fields       ║
    78  	//  ║ null  │ message fields             ║
    79  	//  ║ []    │ list fields                ║
    80  	//  ║ {}    │ map fields                 ║
    81  	//  ╚═══════╧════════════════════════════╝
    82  	EmitUnpopulated bool
    83  
    84  	// EmitDefaultValues specifies whether to emit default-valued primitive fields,
    85  	// empty lists, and empty maps. The fields affected are as follows:
    86  	//  ╔═══════╤════════════════════════════════════════╗
    87  	//  ║ JSON  │ Protobuf field                         ║
    88  	//  ╠═══════╪════════════════════════════════════════╣
    89  	//  ║ false │ non-optional scalar boolean fields     ║
    90  	//  ║ 0     │ non-optional scalar numeric fields     ║
    91  	//  ║ ""    │ non-optional scalar string/byte fields ║
    92  	//  ║ []    │ empty repeated fields                  ║
    93  	//  ║ {}    │ empty map fields                       ║
    94  	//  ╚═══════╧════════════════════════════════════════╝
    95  	//
    96  	// Behaves similarly to EmitUnpopulated, but does not emit "null"-value fields,
    97  	// i.e. presence-sensing fields that are omitted will remain omitted to preserve
    98  	// presence-sensing.
    99  	// EmitUnpopulated takes precedence over EmitDefaultValues since the former generates
   100  	// a strict superset of the latter.
   101  	EmitDefaultValues bool
   102  
   103  	// Resolver is used for looking up types when expanding google.protobuf.Any
   104  	// messages. If nil, this defaults to using protoregistry.GlobalTypes.
   105  	Resolver interface {
   106  		protoregistry.ExtensionTypeResolver
   107  		protoregistry.MessageTypeResolver
   108  	}
   109  }
   110  
   111  // Format formats the message as a string.
   112  // This method is only intended for human consumption and ignores errors.
   113  // Do not depend on the output being stable. It may change over time across
   114  // different versions of the program.
   115  func (o MarshalOptions) Format(m proto.Message) string {
   116  	if m == nil || !m.ProtoReflect().IsValid() {
   117  		return "<nil>" // invalid syntax, but okay since this is for debugging
   118  	}
   119  	o.AllowPartial = true
   120  	b, _ := o.Marshal(m)
   121  	return string(b)
   122  }
   123  
   124  // Marshal marshals the given [proto.Message] in the JSON format using options in
   125  // MarshalOptions. Do not depend on the output being stable. It may change over
   126  // time across different versions of the program.
   127  func (o MarshalOptions) Marshal(m proto.Message) ([]byte, error) {
   128  	return o.marshal(nil, m)
   129  }
   130  
   131  // MarshalAppend appends the JSON format encoding of m to b,
   132  // returning the result.
   133  func (o MarshalOptions) MarshalAppend(b []byte, m proto.Message) ([]byte, error) {
   134  	return o.marshal(b, m)
   135  }
   136  
   137  // marshal is a centralized function that all marshal operations go through.
   138  // For profiling purposes, avoid changing the name of this function or
   139  // introducing other code paths for marshal that do not go through this.
   140  func (o MarshalOptions) marshal(b []byte, m proto.Message) ([]byte, error) {
   141  	if o.Multiline && o.Indent == "" {
   142  		o.Indent = defaultIndent
   143  	}
   144  	if o.Resolver == nil {
   145  		o.Resolver = protoregistry.GlobalTypes
   146  	}
   147  
   148  	internalEnc, err := json.NewEncoder(b, o.Indent)
   149  	if err != nil {
   150  		return nil, err
   151  	}
   152  
   153  	// Treat nil message interface as an empty message,
   154  	// in which case the output in an empty JSON object.
   155  	if m == nil {
   156  		return append(b, '{', '}'), nil
   157  	}
   158  
   159  	enc := encoder{internalEnc, o}
   160  	if err := enc.marshalMessage(m.ProtoReflect(), ""); err != nil {
   161  		return nil, err
   162  	}
   163  	if o.AllowPartial {
   164  		return enc.Bytes(), nil
   165  	}
   166  	return enc.Bytes(), proto.CheckInitialized(m)
   167  }
   168  
   169  type encoder struct {
   170  	*json.Encoder
   171  	opts MarshalOptions
   172  }
   173  
   174  // typeFieldDesc is a synthetic field descriptor used for the "@type" field.
   175  var typeFieldDesc = func() protoreflect.FieldDescriptor {
   176  	var fd filedesc.Field
   177  	fd.L0.FullName = "@type"
   178  	fd.L0.Index = -1
   179  	fd.L1.Cardinality = protoreflect.Optional
   180  	fd.L1.Kind = protoreflect.StringKind
   181  	return &fd
   182  }()
   183  
   184  // typeURLFieldRanger wraps a protoreflect.Message and modifies its Range method
   185  // to additionally iterate over a synthetic field for the type URL.
   186  type typeURLFieldRanger struct {
   187  	order.FieldRanger
   188  	typeURL string
   189  }
   190  
   191  func (m typeURLFieldRanger) Range(f func(protoreflect.FieldDescriptor, protoreflect.Value) bool) {
   192  	if !f(typeFieldDesc, protoreflect.ValueOfString(m.typeURL)) {
   193  		return
   194  	}
   195  	m.FieldRanger.Range(f)
   196  }
   197  
   198  // unpopulatedFieldRanger wraps a protoreflect.Message and modifies its Range
   199  // method to additionally iterate over unpopulated fields.
   200  type unpopulatedFieldRanger struct {
   201  	protoreflect.Message
   202  
   203  	skipNull bool
   204  }
   205  
   206  func (m unpopulatedFieldRanger) Range(f func(protoreflect.FieldDescriptor, protoreflect.Value) bool) {
   207  	fds := m.Descriptor().Fields()
   208  	for i := 0; i < fds.Len(); i++ {
   209  		fd := fds.Get(i)
   210  		if m.Has(fd) || fd.ContainingOneof() != nil {
   211  			continue // ignore populated fields and fields within a oneofs
   212  		}
   213  
   214  		v := m.Get(fd)
   215  		isProto2Scalar := fd.Syntax() == protoreflect.Proto2 && fd.Default().IsValid()
   216  		isSingularMessage := fd.Cardinality() != protoreflect.Repeated && fd.Message() != nil
   217  		if isProto2Scalar || isSingularMessage {
   218  			if m.skipNull {
   219  				continue
   220  			}
   221  			v = protoreflect.Value{} // use invalid value to emit null
   222  		}
   223  		if !f(fd, v) {
   224  			return
   225  		}
   226  	}
   227  	m.Message.Range(f)
   228  }
   229  
   230  // marshalMessage marshals the fields in the given protoreflect.Message.
   231  // If the typeURL is non-empty, then a synthetic "@type" field is injected
   232  // containing the URL as the value.
   233  func (e encoder) marshalMessage(m protoreflect.Message, typeURL string) error {
   234  	if !flags.ProtoLegacy && messageset.IsMessageSet(m.Descriptor()) {
   235  		return errors.New("no support for proto1 MessageSets")
   236  	}
   237  
   238  	if marshal := wellKnownTypeMarshaler(m.Descriptor().FullName()); marshal != nil {
   239  		return marshal(e, m)
   240  	}
   241  
   242  	e.StartObject()
   243  	defer e.EndObject()
   244  
   245  	var fields order.FieldRanger = m
   246  	switch {
   247  	case e.opts.EmitUnpopulated:
   248  		fields = unpopulatedFieldRanger{Message: m, skipNull: false}
   249  	case e.opts.EmitDefaultValues:
   250  		fields = unpopulatedFieldRanger{Message: m, skipNull: true}
   251  	}
   252  	if typeURL != "" {
   253  		fields = typeURLFieldRanger{fields, typeURL}
   254  	}
   255  
   256  	var err error
   257  	order.RangeFields(fields, order.IndexNameFieldOrder, func(fd protoreflect.FieldDescriptor, v protoreflect.Value) bool {
   258  		name := fd.JSONName()
   259  		if e.opts.UseProtoNames {
   260  			name = fd.TextName()
   261  		}
   262  
   263  		if err = e.WriteName(name); err != nil {
   264  			return false
   265  		}
   266  		if err = e.marshalValue(v, fd); err != nil {
   267  			return false
   268  		}
   269  		return true
   270  	})
   271  	return err
   272  }
   273  
   274  // marshalValue marshals the given protoreflect.Value.
   275  func (e encoder) marshalValue(val protoreflect.Value, fd protoreflect.FieldDescriptor) error {
   276  	switch {
   277  	case fd.IsList():
   278  		return e.marshalList(val.List(), fd)
   279  	case fd.IsMap():
   280  		return e.marshalMap(val.Map(), fd)
   281  	default:
   282  		return e.marshalSingular(val, fd)
   283  	}
   284  }
   285  
   286  // marshalSingular marshals the given non-repeated field value. This includes
   287  // all scalar types, enums, messages, and groups.
   288  func (e encoder) marshalSingular(val protoreflect.Value, fd protoreflect.FieldDescriptor) error {
   289  	if !val.IsValid() {
   290  		e.WriteNull()
   291  		return nil
   292  	}
   293  
   294  	switch kind := fd.Kind(); kind {
   295  	case protoreflect.BoolKind:
   296  		e.WriteBool(val.Bool())
   297  
   298  	case protoreflect.StringKind:
   299  		if e.WriteString(val.String()) != nil {
   300  			return errors.InvalidUTF8(string(fd.FullName()))
   301  		}
   302  
   303  	case protoreflect.Int32Kind, protoreflect.Sint32Kind, protoreflect.Sfixed32Kind:
   304  		e.WriteInt(val.Int())
   305  
   306  	case protoreflect.Uint32Kind, protoreflect.Fixed32Kind:
   307  		e.WriteUint(val.Uint())
   308  
   309  	case protoreflect.Int64Kind, protoreflect.Sint64Kind, protoreflect.Uint64Kind,
   310  		protoreflect.Sfixed64Kind, protoreflect.Fixed64Kind:
   311  		// 64-bit integers are written out as JSON string.
   312  		e.WriteString(val.String())
   313  
   314  	case protoreflect.FloatKind:
   315  		// Encoder.WriteFloat handles the special numbers NaN and infinites.
   316  		e.WriteFloat(val.Float(), 32)
   317  
   318  	case protoreflect.DoubleKind:
   319  		// Encoder.WriteFloat handles the special numbers NaN and infinites.
   320  		e.WriteFloat(val.Float(), 64)
   321  
   322  	case protoreflect.BytesKind:
   323  		e.WriteString(base64.StdEncoding.EncodeToString(val.Bytes()))
   324  
   325  	case protoreflect.EnumKind:
   326  		if fd.Enum().FullName() == genid.NullValue_enum_fullname {
   327  			e.WriteNull()
   328  		} else {
   329  			desc := fd.Enum().Values().ByNumber(val.Enum())
   330  			if e.opts.UseEnumNumbers || desc == nil {
   331  				e.WriteInt(int64(val.Enum()))
   332  			} else {
   333  				e.WriteString(string(desc.Name()))
   334  			}
   335  		}
   336  
   337  	case protoreflect.MessageKind, protoreflect.GroupKind:
   338  		if err := e.marshalMessage(val.Message(), ""); err != nil {
   339  			return err
   340  		}
   341  
   342  	default:
   343  		panic(fmt.Sprintf("%v has unknown kind: %v", fd.FullName(), kind))
   344  	}
   345  	return nil
   346  }
   347  
   348  // marshalList marshals the given protoreflect.List.
   349  func (e encoder) marshalList(list protoreflect.List, fd protoreflect.FieldDescriptor) error {
   350  	e.StartArray()
   351  	defer e.EndArray()
   352  
   353  	for i := 0; i < list.Len(); i++ {
   354  		item := list.Get(i)
   355  		if err := e.marshalSingular(item, fd); err != nil {
   356  			return err
   357  		}
   358  	}
   359  	return nil
   360  }
   361  
   362  // marshalMap marshals given protoreflect.Map.
   363  func (e encoder) marshalMap(mmap protoreflect.Map, fd protoreflect.FieldDescriptor) error {
   364  	e.StartObject()
   365  	defer e.EndObject()
   366  
   367  	var err error
   368  	order.RangeEntries(mmap, order.GenericKeyOrder, func(k protoreflect.MapKey, v protoreflect.Value) bool {
   369  		if err = e.WriteName(k.String()); err != nil {
   370  			return false
   371  		}
   372  		if err = e.marshalSingular(v, fd.MapValue()); err != nil {
   373  			return false
   374  		}
   375  		return true
   376  	})
   377  	return err
   378  }
   379
View as plain text