extensions.go 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607
  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 is a concrete value for the extension field. Let the type of
  169. // desc.ExtensionType be the "API type" and the type of Extension.value
  170. // be the "storage type". The API type and storage type are the same except:
  171. // * For scalars (except []byte), the API type uses *T,
  172. // while the storage type uses T.
  173. // * For repeated fields, the API type uses []T, while the storage type
  174. // uses *[]T.
  175. //
  176. // The reason for the divergence is so that the storage type more naturally
  177. // matches what is expected of when retrieving the values through the
  178. // protobuf reflection APIs.
  179. //
  180. // The value may only be populated if desc is also populated.
  181. value interface{}
  182. // enc is the raw bytes for the extension field.
  183. enc []byte
  184. }
  185. // SetRawExtension is for testing only.
  186. func SetRawExtension(base Message, id int32, b []byte) {
  187. epb, err := extendable(base)
  188. if err != nil {
  189. return
  190. }
  191. extmap := epb.extensionsWrite()
  192. extmap[id] = Extension{enc: b}
  193. }
  194. // isExtensionField returns true iff the given field number is in an extension range.
  195. func isExtensionField(pb extendableProto, field int32) bool {
  196. for _, er := range pb.ExtensionRangeArray() {
  197. if er.Start <= field && field <= er.End {
  198. return true
  199. }
  200. }
  201. return false
  202. }
  203. // checkExtensionTypes checks that the given extension is valid for pb.
  204. func checkExtensionTypes(pb extendableProto, extension *ExtensionDesc) error {
  205. var pbi interface{} = pb
  206. // Check the extended type.
  207. if ea, ok := pbi.(extensionAdapter); ok {
  208. pbi = ea.extendableProtoV1
  209. }
  210. if a, b := reflect.TypeOf(pbi), reflect.TypeOf(extension.ExtendedType); a != b {
  211. return fmt.Errorf("proto: bad extended type; %v does not extend %v", b, a)
  212. }
  213. // Check the range.
  214. if !isExtensionField(pb, extension.Field) {
  215. return errors.New("proto: bad extension number; not in declared ranges")
  216. }
  217. return nil
  218. }
  219. // extPropKey is sufficient to uniquely identify an extension.
  220. type extPropKey struct {
  221. base reflect.Type
  222. field int32
  223. }
  224. var extProp = struct {
  225. sync.RWMutex
  226. m map[extPropKey]*Properties
  227. }{
  228. m: make(map[extPropKey]*Properties),
  229. }
  230. func extensionProperties(ed *ExtensionDesc) *Properties {
  231. key := extPropKey{base: reflect.TypeOf(ed.ExtendedType), field: ed.Field}
  232. extProp.RLock()
  233. if prop, ok := extProp.m[key]; ok {
  234. extProp.RUnlock()
  235. return prop
  236. }
  237. extProp.RUnlock()
  238. extProp.Lock()
  239. defer extProp.Unlock()
  240. // Check again.
  241. if prop, ok := extProp.m[key]; ok {
  242. return prop
  243. }
  244. prop := new(Properties)
  245. prop.Init(reflect.TypeOf(ed.ExtensionType), "unknown_name", ed.Tag, nil)
  246. extProp.m[key] = prop
  247. return prop
  248. }
  249. // HasExtension returns whether the given extension is present in pb.
  250. func HasExtension(pb Message, extension *ExtensionDesc) bool {
  251. // TODO: Check types, field numbers, etc.?
  252. epb, err := extendable(pb)
  253. if err != nil {
  254. return false
  255. }
  256. extmap, mu := epb.extensionsRead()
  257. if extmap == nil {
  258. return false
  259. }
  260. mu.Lock()
  261. _, ok := extmap[extension.Field]
  262. mu.Unlock()
  263. return ok
  264. }
  265. // ClearExtension removes the given extension from pb.
  266. func ClearExtension(pb Message, extension *ExtensionDesc) {
  267. epb, err := extendable(pb)
  268. if err != nil {
  269. return
  270. }
  271. // TODO: Check types, field numbers, etc.?
  272. extmap := epb.extensionsWrite()
  273. delete(extmap, extension.Field)
  274. }
  275. // GetExtension retrieves a proto2 extended field from pb.
  276. //
  277. // If the descriptor is type complete (i.e., ExtensionDesc.ExtensionType is non-nil),
  278. // then GetExtension parses the encoded field and returns a Go value of the specified type.
  279. // If the field is not present, then the default value is returned (if one is specified),
  280. // otherwise ErrMissingExtension is reported.
  281. //
  282. // If the descriptor is not type complete (i.e., ExtensionDesc.ExtensionType is nil),
  283. // then GetExtension returns the raw encoded bytes of the field extension.
  284. func GetExtension(pb Message, extension *ExtensionDesc) (interface{}, error) {
  285. epb, err := extendable(pb)
  286. if err != nil {
  287. return nil, err
  288. }
  289. if extension.ExtendedType != nil {
  290. // can only check type if this is a complete descriptor
  291. if err := checkExtensionTypes(epb, extension); err != nil {
  292. return nil, err
  293. }
  294. }
  295. emap, mu := epb.extensionsRead()
  296. if emap == nil {
  297. return defaultExtensionValue(extension)
  298. }
  299. mu.Lock()
  300. defer mu.Unlock()
  301. e, ok := emap[extension.Field]
  302. if !ok {
  303. // defaultExtensionValue returns the default value or
  304. // ErrMissingExtension if there is no default.
  305. return defaultExtensionValue(extension)
  306. }
  307. if e.value != nil {
  308. // Already decoded. Check the descriptor, though.
  309. if e.desc != extension {
  310. // This shouldn't happen. If it does, it means that
  311. // GetExtension was called twice with two different
  312. // descriptors with the same field number.
  313. return nil, errors.New("proto: descriptor conflict")
  314. }
  315. return extensionAsLegacyType(e.value), nil
  316. }
  317. if extension.ExtensionType == nil {
  318. // incomplete descriptor
  319. return e.enc, nil
  320. }
  321. v, err := decodeExtension(e.enc, extension)
  322. if err != nil {
  323. return nil, err
  324. }
  325. // Remember the decoded version and drop the encoded version.
  326. // That way it is safe to mutate what we return.
  327. e.value = extensionAsStorageType(v)
  328. e.desc = extension
  329. e.enc = nil
  330. emap[extension.Field] = e
  331. return extensionAsLegacyType(e.value), nil
  332. }
  333. // defaultExtensionValue returns the default value for extension.
  334. // If no default for an extension is defined ErrMissingExtension is returned.
  335. func defaultExtensionValue(extension *ExtensionDesc) (interface{}, error) {
  336. if extension.ExtensionType == nil {
  337. // incomplete descriptor, so no default
  338. return nil, ErrMissingExtension
  339. }
  340. t := reflect.TypeOf(extension.ExtensionType)
  341. props := extensionProperties(extension)
  342. sf, _, err := fieldDefault(t, props)
  343. if err != nil {
  344. return nil, err
  345. }
  346. if sf == nil || sf.value == nil {
  347. // There is no default value.
  348. return nil, ErrMissingExtension
  349. }
  350. if t.Kind() != reflect.Ptr {
  351. // We do not need to return a Ptr, we can directly return sf.value.
  352. return sf.value, nil
  353. }
  354. // We need to return an interface{} that is a pointer to sf.value.
  355. value := reflect.New(t).Elem()
  356. value.Set(reflect.New(value.Type().Elem()))
  357. if sf.kind == reflect.Int32 {
  358. // We may have an int32 or an enum, but the underlying data is int32.
  359. // Since we can't set an int32 into a non int32 reflect.value directly
  360. // set it as a int32.
  361. value.Elem().SetInt(int64(sf.value.(int32)))
  362. } else {
  363. value.Elem().Set(reflect.ValueOf(sf.value))
  364. }
  365. return value.Interface(), nil
  366. }
  367. // decodeExtension decodes an extension encoded in b.
  368. func decodeExtension(b []byte, extension *ExtensionDesc) (interface{}, error) {
  369. t := reflect.TypeOf(extension.ExtensionType)
  370. unmarshal := typeUnmarshaler(t, extension.Tag)
  371. // t is a pointer to a struct, pointer to basic type or a slice.
  372. // Allocate space to store the pointer/slice.
  373. value := reflect.New(t).Elem()
  374. var err error
  375. for {
  376. x, n := decodeVarint(b)
  377. if n == 0 {
  378. return nil, io.ErrUnexpectedEOF
  379. }
  380. b = b[n:]
  381. wire := int(x) & 7
  382. b, err = unmarshal(b, valToPointer(value.Addr()), wire)
  383. if err != nil {
  384. return nil, err
  385. }
  386. if len(b) == 0 {
  387. break
  388. }
  389. }
  390. return value.Interface(), nil
  391. }
  392. // GetExtensions returns a slice of the extensions present in pb that are also listed in es.
  393. // The returned slice has the same length as es; missing extensions will appear as nil elements.
  394. func GetExtensions(pb Message, es []*ExtensionDesc) (extensions []interface{}, err error) {
  395. epb, err := extendable(pb)
  396. if err != nil {
  397. return nil, err
  398. }
  399. extensions = make([]interface{}, len(es))
  400. for i, e := range es {
  401. extensions[i], err = GetExtension(epb, e)
  402. if err == ErrMissingExtension {
  403. err = nil
  404. }
  405. if err != nil {
  406. return
  407. }
  408. }
  409. return
  410. }
  411. // ExtensionDescs returns a new slice containing pb's extension descriptors, in undefined order.
  412. // For non-registered extensions, ExtensionDescs returns an incomplete descriptor containing
  413. // just the Field field, which defines the extension's field number.
  414. func ExtensionDescs(pb Message) ([]*ExtensionDesc, error) {
  415. epb, err := extendable(pb)
  416. if err != nil {
  417. return nil, err
  418. }
  419. registeredExtensions := RegisteredExtensions(pb)
  420. emap, mu := epb.extensionsRead()
  421. if emap == nil {
  422. return nil, nil
  423. }
  424. mu.Lock()
  425. defer mu.Unlock()
  426. extensions := make([]*ExtensionDesc, 0, len(emap))
  427. for extid, e := range emap {
  428. desc := e.desc
  429. if desc == nil {
  430. desc = registeredExtensions[extid]
  431. if desc == nil {
  432. desc = &ExtensionDesc{Field: extid}
  433. }
  434. }
  435. extensions = append(extensions, desc)
  436. }
  437. return extensions, nil
  438. }
  439. // SetExtension sets the specified extension of pb to the specified value.
  440. func SetExtension(pb Message, extension *ExtensionDesc, value interface{}) error {
  441. epb, err := extendable(pb)
  442. if err != nil {
  443. return err
  444. }
  445. if err := checkExtensionTypes(epb, extension); err != nil {
  446. return err
  447. }
  448. typ := reflect.TypeOf(extension.ExtensionType)
  449. if typ != reflect.TypeOf(value) {
  450. return fmt.Errorf("proto: bad extension value type. got: %T, want: %T", value, extension.ExtensionType)
  451. }
  452. // nil extension values need to be caught early, because the
  453. // encoder can't distinguish an ErrNil due to a nil extension
  454. // from an ErrNil due to a missing field. Extensions are
  455. // always optional, so the encoder would just swallow the error
  456. // and drop all the extensions from the encoded message.
  457. if reflect.ValueOf(value).IsNil() {
  458. return fmt.Errorf("proto: SetExtension called with nil value of type %T", value)
  459. }
  460. extmap := epb.extensionsWrite()
  461. extmap[extension.Field] = Extension{desc: extension, value: extensionAsStorageType(value)}
  462. return nil
  463. }
  464. // ClearAllExtensions clears all extensions from pb.
  465. func ClearAllExtensions(pb Message) {
  466. epb, err := extendable(pb)
  467. if err != nil {
  468. return
  469. }
  470. m := epb.extensionsWrite()
  471. for k := range m {
  472. delete(m, k)
  473. }
  474. }
  475. // A global registry of extensions.
  476. // The generated code will register the generated descriptors by calling RegisterExtension.
  477. var extensionMaps = make(map[reflect.Type]map[int32]*ExtensionDesc)
  478. // RegisterExtension is called from the generated code.
  479. func RegisterExtension(desc *ExtensionDesc) {
  480. st := reflect.TypeOf(desc.ExtendedType).Elem()
  481. m := extensionMaps[st]
  482. if m == nil {
  483. m = make(map[int32]*ExtensionDesc)
  484. extensionMaps[st] = m
  485. }
  486. if _, ok := m[desc.Field]; ok {
  487. panic("proto: duplicate extension registered: " + st.String() + " " + strconv.Itoa(int(desc.Field)))
  488. }
  489. m[desc.Field] = desc
  490. }
  491. // RegisteredExtensions returns a map of the registered extensions of a
  492. // protocol buffer struct, indexed by the extension number.
  493. // The argument pb should be a nil pointer to the struct type.
  494. func RegisteredExtensions(pb Message) map[int32]*ExtensionDesc {
  495. return extensionMaps[reflect.TypeOf(pb).Elem()]
  496. }
  497. // extensionAsLegacyType converts an value in the storage type as the API type.
  498. // See Extension.value.
  499. func extensionAsLegacyType(v interface{}) interface{} {
  500. switch rv := reflect.ValueOf(v); rv.Kind() {
  501. case reflect.Bool, reflect.Int32, reflect.Int64, reflect.Uint32, reflect.Uint64, reflect.Float32, reflect.Float64, reflect.String:
  502. // Represent primitive types as a pointer to the value.
  503. rv2 := reflect.New(rv.Type())
  504. rv2.Elem().Set(rv)
  505. v = rv2.Interface()
  506. case reflect.Ptr:
  507. // Represent slice types as the value itself.
  508. switch rv.Type().Elem().Kind() {
  509. case reflect.Slice:
  510. if rv.IsNil() {
  511. v = reflect.Zero(rv.Type().Elem()).Interface()
  512. } else {
  513. v = rv.Elem().Interface()
  514. }
  515. }
  516. }
  517. return v
  518. }
  519. // extensionAsStorageType converts an value in the API type as the storage type.
  520. // See Extension.value.
  521. func extensionAsStorageType(v interface{}) interface{} {
  522. switch rv := reflect.ValueOf(v); rv.Kind() {
  523. case reflect.Ptr:
  524. // Represent slice types as the value itself.
  525. switch rv.Type().Elem().Kind() {
  526. case reflect.Bool, reflect.Int32, reflect.Int64, reflect.Uint32, reflect.Uint64, reflect.Float32, reflect.Float64, reflect.String:
  527. if rv.IsNil() {
  528. v = reflect.Zero(rv.Type().Elem()).Interface()
  529. } else {
  530. v = rv.Elem().Interface()
  531. }
  532. }
  533. case reflect.Slice:
  534. // Represent slice types as a pointer to the value.
  535. if rv.Type().Elem().Kind() != reflect.Uint8 {
  536. rv2 := reflect.New(rv.Type())
  537. rv2.Elem().Set(rv)
  538. v = rv2.Interface()
  539. }
  540. }
  541. return v
  542. }