blob: 147b5ecc62fda7c03eaa1d24b418d0202316ae5c [file] [log] [blame]
Matthias Andreas Benkard832a54e2019-01-29 09:27:38 +01001// Protocol Buffers for Go with Gadgets
2//
3// Copyright (c) 2013, The GoGo Authors. All rights reserved.
4// http://github.com/gogo/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//
17// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
20// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
21// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
22// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
23// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28
29/*
30Package gogoproto provides extensions for protocol buffers to achieve:
31
32 - fast marshalling and unmarshalling.
33 - peace of mind by optionally generating test and benchmark code.
34 - more canonical Go structures.
35 - less typing by optionally generating extra helper code.
36 - goprotobuf compatibility
37
38More Canonical Go Structures
39
40A lot of time working with a goprotobuf struct will lead you to a place where you create another struct that is easier to work with and then have a function to copy the values between the two structs.
41You might also find that basic structs that started their life as part of an API need to be sent over the wire. With gob, you could just send it. With goprotobuf, you need to make a parallel struct.
42Gogoprotobuf tries to fix these problems with the nullable, embed, customtype and customname field extensions.
43
44 - nullable, if false, a field is generated without a pointer (see warning below).
45 - embed, if true, the field is generated as an embedded field.
46 - customtype, It works with the Marshal and Unmarshal methods, to allow you to have your own types in your struct, but marshal to bytes. For example, custom.Uuid or custom.Fixed128
47 - customname (beta), Changes the generated fieldname. This is especially useful when generated methods conflict with fieldnames.
48 - casttype (beta), Changes the generated fieldtype. All generated code assumes that this type is castable to the protocol buffer field type. It does not work for structs or enums.
49 - castkey (beta), Changes the generated fieldtype for a map key. All generated code assumes that this type is castable to the protocol buffer field type. Only supported on maps.
50 - castvalue (beta), Changes the generated fieldtype for a map value. All generated code assumes that this type is castable to the protocol buffer field type. Only supported on maps.
51
52Warning about nullable: According to the Protocol Buffer specification, you should be able to tell whether a field is set or unset. With the option nullable=false this feature is lost, since your non-nullable fields will always be set. It can be seen as a layer on top of Protocol Buffers, where before and after marshalling all non-nullable fields are set and they cannot be unset.
53
54Let us look at:
55
56 github.com/gogo/protobuf/test/example/example.proto
57
58for a quicker overview.
59
60The following message:
61
62 package test;
63
64 import "github.com/gogo/protobuf/gogoproto/gogo.proto";
65
66 message A {
67 optional string Description = 1 [(gogoproto.nullable) = false];
68 optional int64 Number = 2 [(gogoproto.nullable) = false];
69 optional bytes Id = 3 [(gogoproto.customtype) = "github.com/gogo/protobuf/test/custom.Uuid", (gogoproto.nullable) = false];
70 }
71
72Will generate a go struct which looks a lot like this:
73
74 type A struct {
75 Description string
76 Number int64
77 Id github_com_gogo_protobuf_test_custom.Uuid
78 }
79
80You will see there are no pointers, since all fields are non-nullable.
81You will also see a custom type which marshals to a string.
82Be warned it is your responsibility to test your custom types thoroughly.
83You should think of every possible empty and nil case for your marshaling, unmarshaling and size methods.
84
85Next we will embed the message A in message B.
86
87 message B {
88 optional A A = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true];
89 repeated bytes G = 2 [(gogoproto.customtype) = "github.com/gogo/protobuf/test/custom.Uint128", (gogoproto.nullable) = false];
90 }
91
92See below that A is embedded in B.
93
94 type B struct {
95 A
96 G []github_com_gogo_protobuf_test_custom.Uint128
97 }
98
99Also see the repeated custom type.
100
101 type Uint128 [2]uint64
102
103Next we will create a custom name for one of our fields.
104
105 message C {
106 optional int64 size = 1 [(gogoproto.customname) = "MySize"];
107 }
108
109See below that the field's name is MySize and not Size.
110
111 type C struct {
112 MySize *int64
113 }
114
115The is useful when having a protocol buffer message with a field name which conflicts with a generated method.
116As an example, having a field name size and using the sizer plugin to generate a Size method will cause a go compiler error.
117Using customname you can fix this error without changing the field name.
118This is typically useful when working with a protocol buffer that was designed before these methods and/or the go language were avialable.
119
120Gogoprotobuf also has some more subtle changes, these could be changed back:
121
122 - the generated package name for imports do not have the extra /filename.pb,
123 but are actually the imports specified in the .proto file.
124
125Gogoprotobuf also has lost some features which should be brought back with time:
126
127 - Marshalling and unmarshalling with reflect and without the unsafe package,
128 this requires work in pointer_reflect.go
129
130Why does nullable break protocol buffer specifications:
131
132The protocol buffer specification states, somewhere, that you should be able to tell whether a
133field is set or unset. With the option nullable=false this feature is lost,
134since your non-nullable fields will always be set. It can be seen as a layer on top of
135protocol buffers, where before and after marshalling all non-nullable fields are set
136and they cannot be unset.
137
138Goprotobuf Compatibility:
139
140Gogoprotobuf is compatible with Goprotobuf, because it is compatible with protocol buffers.
141Gogoprotobuf generates the same code as goprotobuf if no extensions are used.
142The enumprefix, getters and stringer extensions can be used to remove some of the unnecessary code generated by goprotobuf:
143
144 - gogoproto_import, if false, the generated code imports github.com/golang/protobuf/proto instead of github.com/gogo/protobuf/proto.
145 - goproto_enum_prefix, if false, generates the enum constant names without the messagetype prefix
146 - goproto_enum_stringer (experimental), if false, the enum is generated without the default string method, this is useful for rather using enum_stringer, or allowing you to write your own string method.
147 - goproto_getters, if false, the message is generated without get methods, this is useful when you would rather want to use face
148 - goproto_stringer, if false, the message is generated without the default string method, this is useful for rather using stringer, or allowing you to write your own string method.
149 - goproto_extensions_map (beta), if false, the extensions field is generated as type []byte instead of type map[int32]proto.Extension
150 - goproto_unrecognized (beta), if false, XXX_unrecognized field is not generated. This is useful in conjunction with gogoproto.nullable=false, to generate structures completely devoid of pointers and reduce GC pressure at the cost of losing information about unrecognized fields.
151 - goproto_registration (beta), if true, the generated files will register all messages and types against both gogo/protobuf and golang/protobuf. This is necessary when using third-party packages which read registrations from golang/protobuf (such as the grpc-gateway).
152
153Less Typing and Peace of Mind is explained in their specific plugin folders godoc:
154
155 - github.com/gogo/protobuf/plugin/<extension_name>
156
157If you do not use any of these extension the code that is generated
158will be the same as if goprotobuf has generated it.
159
160The most complete way to see examples is to look at
161
162 github.com/gogo/protobuf/test/thetest.proto
163
164Gogoprototest is a seperate project,
165because we want to keep gogoprotobuf independant of goprotobuf,
166but we still want to test it thoroughly.
167
168*/
169package gogoproto