extensions.go 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543
  1. // Go support for Protocol Buffers - Google's data interchange format
  2. //
  3. // Copyright 2010 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. package proto
  32. /*
  33. * Types and routines for supporting protocol buffer extensions.
  34. */
  35. import (
  36. "errors"
  37. "fmt"
  38. "io"
  39. "reflect"
  40. "strconv"
  41. "sync"
  42. )
  43. // ErrMissingExtension is the error returned by GetExtension if the named extension is not in the message.
  44. var ErrMissingExtension = errors.New("proto: missing extension")
  45. // ExtensionRange represents a range of message extensions for a protocol buffer.
  46. // Used in code generated by the protocol compiler.
  47. type ExtensionRange struct {
  48. Start, End int32 // both inclusive
  49. }
  50. // extendableProto is an interface implemented by any protocol buffer generated by the current
  51. // proto compiler that may be extended.
  52. type extendableProto interface {
  53. Message
  54. ExtensionRangeArray() []ExtensionRange
  55. extensionsWrite() map[int32]Extension
  56. extensionsRead() (map[int32]Extension, sync.Locker)
  57. }
  58. // extendableProtoV1 is an interface implemented by a protocol buffer generated by the previous
  59. // version of the proto compiler that may be extended.
  60. type extendableProtoV1 interface {
  61. Message
  62. ExtensionRangeArray() []ExtensionRange
  63. ExtensionMap() map[int32]Extension
  64. }
  65. // extensionAdapter is a wrapper around extendableProtoV1 that implements extendableProto.
  66. type extensionAdapter struct {
  67. extendableProtoV1
  68. }
  69. func (e extensionAdapter) extensionsWrite() map[int32]Extension {
  70. return e.ExtensionMap()
  71. }
  72. func (e extensionAdapter) extensionsRead() (map[int32]Extension, sync.Locker) {
  73. return e.ExtensionMap(), notLocker{}
  74. }
  75. // notLocker is a sync.Locker whose Lock and Unlock methods are nops.
  76. type notLocker struct{}
  77. func (n notLocker) Lock() {}
  78. func (n notLocker) Unlock() {}
  79. // extendable returns the extendableProto interface for the given generated proto message.
  80. // If the proto message has the old extension format, it returns a wrapper that implements
  81. // the extendableProto interface.
  82. func extendable(p interface{}) (extendableProto, error) {
  83. switch p := p.(type) {
  84. case extendableProto:
  85. if isNilPtr(p) {
  86. return nil, fmt.Errorf("proto: nil %T is not extendable", p)
  87. }
  88. return p, nil
  89. case extendableProtoV1:
  90. if isNilPtr(p) {
  91. return nil, fmt.Errorf("proto: nil %T is not extendable", p)
  92. }
  93. return extensionAdapter{p}, nil
  94. }
  95. // Don't allocate a specific error containing %T:
  96. // this is the hot path for Clone and MarshalText.
  97. return nil, errNotExtendable
  98. }
  99. var errNotExtendable = errors.New("proto: not an extendable proto.Message")
  100. func isNilPtr(x interface{}) bool {
  101. v := reflect.ValueOf(x)
  102. return v.Kind() == reflect.Ptr && v.IsNil()
  103. }
  104. // XXX_InternalExtensions is an internal representation of proto extensions.
  105. //
  106. // Each generated message struct type embeds an anonymous XXX_InternalExtensions field,
  107. // thus gaining the unexported 'extensions' method, which can be called only from the proto package.
  108. //
  109. // The methods of XXX_InternalExtensions are not concurrency safe in general,
  110. // but calls to logically read-only methods such as has and get may be executed concurrently.
  111. type XXX_InternalExtensions struct {
  112. // The struct must be indirect so that if a user inadvertently copies a
  113. // generated message and its embedded XXX_InternalExtensions, they
  114. // avoid the mayhem of a copied mutex.
  115. //
  116. // The mutex serializes all logically read-only operations to p.extensionMap.
  117. // It is up to the client to ensure that write operations to p.extensionMap are
  118. // mutually exclusive with other accesses.
  119. p *struct {
  120. mu sync.Mutex
  121. extensionMap map[int32]Extension
  122. }
  123. }
  124. // extensionsWrite returns the extension map, creating it on first use.
  125. func (e *XXX_InternalExtensions) extensionsWrite() map[int32]Extension {
  126. if e.p == nil {
  127. e.p = new(struct {
  128. mu sync.Mutex
  129. extensionMap map[int32]Extension
  130. })
  131. e.p.extensionMap = make(map[int32]Extension)
  132. }
  133. return e.p.extensionMap
  134. }
  135. // extensionsRead returns the extensions map for read-only use. It may be nil.
  136. // The caller must hold the returned mutex's lock when accessing Elements within the map.
  137. func (e *XXX_InternalExtensions) extensionsRead() (map[int32]Extension, sync.Locker) {
  138. if e.p == nil {
  139. return nil, nil
  140. }
  141. return e.p.extensionMap, &e.p.mu
  142. }
  143. // ExtensionDesc represents an extension specification.
  144. // Used in generated code from the protocol compiler.
  145. type ExtensionDesc struct {
  146. ExtendedType Message // nil pointer to the type that is being extended
  147. ExtensionType interface{} // nil pointer to the extension type
  148. Field int32 // field number
  149. Name string // fully-qualified name of extension, for text formatting
  150. Tag string // protobuf tag style
  151. Filename string // name of the file in which the extension is defined
  152. }
  153. func (ed *ExtensionDesc) repeated() bool {
  154. t := reflect.TypeOf(ed.ExtensionType)
  155. return t.Kind() == reflect.Slice && t.Elem().Kind() != reflect.Uint8
  156. }
  157. // Extension represents an extension in a message.
  158. type Extension struct {
  159. // When an extension is stored in a message using SetExtension
  160. // only desc and value are set. When the message is marshaled
  161. // enc will be set to the encoded form of the message.
  162. //
  163. // When a message is unmarshaled and contains extensions, each
  164. // extension will have only enc set. When such an extension is
  165. // accessed using GetExtension (or GetExtensions) desc and value
  166. // will be set.
  167. desc *ExtensionDesc
  168. value interface{}
  169. enc []byte
  170. }
  171. // SetRawExtension is for testing only.
  172. func SetRawExtension(base Message, id int32, b []byte) {
  173. epb, err := extendable(base)
  174. if err != nil {
  175. return
  176. }
  177. extmap := epb.extensionsWrite()
  178. extmap[id] = Extension{enc: b}
  179. }
  180. // isExtensionField returns true iff the given field number is in an extension range.
  181. func isExtensionField(pb extendableProto, field int32) bool {
  182. for _, er := range pb.ExtensionRangeArray() {
  183. if er.Start <= field && field <= er.End {
  184. return true
  185. }
  186. }
  187. return false
  188. }
  189. // checkExtensionTypes checks that the given extension is valid for pb.
  190. func checkExtensionTypes(pb extendableProto, extension *ExtensionDesc) error {
  191. var pbi interface{} = pb
  192. // Check the extended type.
  193. if ea, ok := pbi.(extensionAdapter); ok {
  194. pbi = ea.extendableProtoV1
  195. }
  196. if a, b := reflect.TypeOf(pbi), reflect.TypeOf(extension.ExtendedType); a != b {
  197. return fmt.Errorf("proto: bad extended type; %v does not extend %v", b, a)
  198. }
  199. // Check the range.
  200. if !isExtensionField(pb, extension.Field) {
  201. return errors.New("proto: bad extension number; not in declared ranges")
  202. }
  203. return nil
  204. }
  205. // extPropKey is sufficient to uniquely identify an extension.
  206. type extPropKey struct {
  207. base reflect.Type
  208. field int32
  209. }
  210. var extProp = struct {
  211. sync.RWMutex
  212. m map[extPropKey]*Properties
  213. }{
  214. m: make(map[extPropKey]*Properties),
  215. }
  216. func extensionProperties(ed *ExtensionDesc) *Properties {
  217. key := extPropKey{base: reflect.TypeOf(ed.ExtendedType), field: ed.Field}
  218. extProp.RLock()
  219. if prop, ok := extProp.m[key]; ok {
  220. extProp.RUnlock()
  221. return prop
  222. }
  223. extProp.RUnlock()
  224. extProp.Lock()
  225. defer extProp.Unlock()
  226. // Check again.
  227. if prop, ok := extProp.m[key]; ok {
  228. return prop
  229. }
  230. prop := new(Properties)
  231. prop.Init(reflect.TypeOf(ed.ExtensionType), "unknown_name", ed.Tag, nil)
  232. extProp.m[key] = prop
  233. return prop
  234. }
  235. // HasExtension returns whether the given extension is present in pb.
  236. func HasExtension(pb Message, extension *ExtensionDesc) bool {
  237. // TODO: Check types, field numbers, etc.?
  238. epb, err := extendable(pb)
  239. if err != nil {
  240. return false
  241. }
  242. extmap, mu := epb.extensionsRead()
  243. if extmap == nil {
  244. return false
  245. }
  246. mu.Lock()
  247. _, ok := extmap[extension.Field]
  248. mu.Unlock()
  249. return ok
  250. }
  251. // ClearExtension removes the given extension from pb.
  252. func ClearExtension(pb Message, extension *ExtensionDesc) {
  253. epb, err := extendable(pb)
  254. if err != nil {
  255. return
  256. }
  257. // TODO: Check types, field numbers, etc.?
  258. extmap := epb.extensionsWrite()
  259. delete(extmap, extension.Field)
  260. }
  261. // GetExtension retrieves a proto2 extended field from pb.
  262. //
  263. // If the descriptor is type complete (i.e., ExtensionDesc.ExtensionType is non-nil),
  264. // then GetExtension parses the encoded field and returns a Go value of the specified type.
  265. // If the field is not present, then the default value is returned (if one is specified),
  266. // otherwise ErrMissingExtension is reported.
  267. //
  268. // If the descriptor is not type complete (i.e., ExtensionDesc.ExtensionType is nil),
  269. // then GetExtension returns the raw encoded bytes of the field extension.
  270. func GetExtension(pb Message, extension *ExtensionDesc) (interface{}, error) {
  271. epb, err := extendable(pb)
  272. if err != nil {
  273. return nil, err
  274. }
  275. if extension.ExtendedType != nil {
  276. // can only check type if this is a complete descriptor
  277. if err := checkExtensionTypes(epb, extension); err != nil {
  278. return nil, err
  279. }
  280. }
  281. emap, mu := epb.extensionsRead()
  282. if emap == nil {
  283. return defaultExtensionValue(extension)
  284. }
  285. mu.Lock()
  286. defer mu.Unlock()
  287. e, ok := emap[extension.Field]
  288. if !ok {
  289. // defaultExtensionValue returns the default value or
  290. // ErrMissingExtension if there is no default.
  291. return defaultExtensionValue(extension)
  292. }
  293. if e.value != nil {
  294. // Already decoded. Check the descriptor, though.
  295. if e.desc != extension {
  296. // This shouldn't happen. If it does, it means that
  297. // GetExtension was called twice with two different
  298. // descriptors with the same field number.
  299. return nil, errors.New("proto: descriptor conflict")
  300. }
  301. return e.value, nil
  302. }
  303. if extension.ExtensionType == nil {
  304. // incomplete descriptor
  305. return e.enc, nil
  306. }
  307. v, err := decodeExtension(e.enc, extension)
  308. if err != nil {
  309. return nil, err
  310. }
  311. // Remember the decoded version and drop the encoded version.
  312. // That way it is safe to mutate what we return.
  313. e.value = v
  314. e.desc = extension
  315. e.enc = nil
  316. emap[extension.Field] = e
  317. return e.value, nil
  318. }
  319. // defaultExtensionValue returns the default value for extension.
  320. // If no default for an extension is defined ErrMissingExtension is returned.
  321. func defaultExtensionValue(extension *ExtensionDesc) (interface{}, error) {
  322. if extension.ExtensionType == nil {
  323. // incomplete descriptor, so no default
  324. return nil, ErrMissingExtension
  325. }
  326. t := reflect.TypeOf(extension.ExtensionType)
  327. props := extensionProperties(extension)
  328. sf, _, err := fieldDefault(t, props)
  329. if err != nil {
  330. return nil, err
  331. }
  332. if sf == nil || sf.value == nil {
  333. // There is no default value.
  334. return nil, ErrMissingExtension
  335. }
  336. if t.Kind() != reflect.Ptr {
  337. // We do not need to return a Ptr, we can directly return sf.value.
  338. return sf.value, nil
  339. }
  340. // We need to return an interface{} that is a pointer to sf.value.
  341. value := reflect.New(t).Elem()
  342. value.Set(reflect.New(value.Type().Elem()))
  343. if sf.kind == reflect.Int32 {
  344. // We may have an int32 or an enum, but the underlying data is int32.
  345. // Since we can't set an int32 into a non int32 reflect.value directly
  346. // set it as a int32.
  347. value.Elem().SetInt(int64(sf.value.(int32)))
  348. } else {
  349. value.Elem().Set(reflect.ValueOf(sf.value))
  350. }
  351. return value.Interface(), nil
  352. }
  353. // decodeExtension decodes an extension encoded in b.
  354. func decodeExtension(b []byte, extension *ExtensionDesc) (interface{}, error) {
  355. t := reflect.TypeOf(extension.ExtensionType)
  356. unmarshal := typeUnmarshaler(t, extension.Tag)
  357. // t is a pointer to a struct, pointer to basic type or a slice.
  358. // Allocate space to store the pointer/slice.
  359. value := reflect.New(t).Elem()
  360. var err error
  361. for {
  362. x, n := decodeVarint(b)
  363. if n == 0 {
  364. return nil, io.ErrUnexpectedEOF
  365. }
  366. b = b[n:]
  367. wire := int(x) & 7
  368. b, err = unmarshal(b, valToPointer(value.Addr()), wire)
  369. if err != nil {
  370. return nil, err
  371. }
  372. if len(b) == 0 {
  373. break
  374. }
  375. }
  376. return value.Interface(), nil
  377. }
  378. // GetExtensions returns a slice of the extensions present in pb that are also listed in es.
  379. // The returned slice has the same length as es; missing extensions will appear as nil elements.
  380. func GetExtensions(pb Message, es []*ExtensionDesc) (extensions []interface{}, err error) {
  381. epb, err := extendable(pb)
  382. if err != nil {
  383. return nil, err
  384. }
  385. extensions = make([]interface{}, len(es))
  386. for i, e := range es {
  387. extensions[i], err = GetExtension(epb, e)
  388. if err == ErrMissingExtension {
  389. err = nil
  390. }
  391. if err != nil {
  392. return
  393. }
  394. }
  395. return
  396. }
  397. // ExtensionDescs returns a new slice containing pb's extension descriptors, in undefined order.
  398. // For non-registered extensions, ExtensionDescs returns an incomplete descriptor containing
  399. // just the Field field, which defines the extension's field number.
  400. func ExtensionDescs(pb Message) ([]*ExtensionDesc, error) {
  401. epb, err := extendable(pb)
  402. if err != nil {
  403. return nil, err
  404. }
  405. registeredExtensions := RegisteredExtensions(pb)
  406. emap, mu := epb.extensionsRead()
  407. if emap == nil {
  408. return nil, nil
  409. }
  410. mu.Lock()
  411. defer mu.Unlock()
  412. extensions := make([]*ExtensionDesc, 0, len(emap))
  413. for extid, e := range emap {
  414. desc := e.desc
  415. if desc == nil {
  416. desc = registeredExtensions[extid]
  417. if desc == nil {
  418. desc = &ExtensionDesc{Field: extid}
  419. }
  420. }
  421. extensions = append(extensions, desc)
  422. }
  423. return extensions, nil
  424. }
  425. // SetExtension sets the specified extension of pb to the specified value.
  426. func SetExtension(pb Message, extension *ExtensionDesc, value interface{}) error {
  427. epb, err := extendable(pb)
  428. if err != nil {
  429. return err
  430. }
  431. if err := checkExtensionTypes(epb, extension); err != nil {
  432. return err
  433. }
  434. typ := reflect.TypeOf(extension.ExtensionType)
  435. if typ != reflect.TypeOf(value) {
  436. return fmt.Errorf("proto: bad extension value type. got: %T, want: %T", value, extension.ExtensionType)
  437. }
  438. // nil extension values need to be caught early, because the
  439. // encoder can't distinguish an ErrNil due to a nil extension
  440. // from an ErrNil due to a missing field. Extensions are
  441. // always optional, so the encoder would just swallow the error
  442. // and drop all the extensions from the encoded message.
  443. if reflect.ValueOf(value).IsNil() {
  444. return fmt.Errorf("proto: SetExtension called with nil value of type %T", value)
  445. }
  446. extmap := epb.extensionsWrite()
  447. extmap[extension.Field] = Extension{desc: extension, value: value}
  448. return nil
  449. }
  450. // ClearAllExtensions clears all extensions from pb.
  451. func ClearAllExtensions(pb Message) {
  452. epb, err := extendable(pb)
  453. if err != nil {
  454. return
  455. }
  456. m := epb.extensionsWrite()
  457. for k := range m {
  458. delete(m, k)
  459. }
  460. }
  461. // A global registry of extensions.
  462. // The generated code will register the generated descriptors by calling RegisterExtension.
  463. var extensionMaps = make(map[reflect.Type]map[int32]*ExtensionDesc)
  464. // RegisterExtension is called from the generated code.
  465. func RegisterExtension(desc *ExtensionDesc) {
  466. st := reflect.TypeOf(desc.ExtendedType).Elem()
  467. m := extensionMaps[st]
  468. if m == nil {
  469. m = make(map[int32]*ExtensionDesc)
  470. extensionMaps[st] = m
  471. }
  472. if _, ok := m[desc.Field]; ok {
  473. panic("proto: duplicate extension registered: " + st.String() + " " + strconv.Itoa(int(desc.Field)))
  474. }
  475. m[desc.Field] = desc
  476. }
  477. // RegisteredExtensions returns a map of the registered extensions of a
  478. // protocol buffer struct, indexed by the extension number.
  479. // The argument pb should be a nil pointer to the struct type.
  480. func RegisteredExtensions(pb Message) map[int32]*ExtensionDesc {
  481. return extensionMaps[reflect.TypeOf(pb).Elem()]
  482. }