watch.proto 5.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. syntax = "proto3";
  2. package docker.swarmkit.v1;
  3. import "specs.proto";
  4. import "objects.proto";
  5. import "types.proto";
  6. import "gogoproto/gogo.proto";
  7. import "plugin/plugin.proto";
  8. message Object {
  9. oneof Object {
  10. Node node = 1;
  11. Service service = 2;
  12. Network network = 3;
  13. Task task = 4;
  14. Cluster cluster = 5;
  15. Secret secret = 6;
  16. Resource resource = 7;
  17. Extension extension = 8;
  18. Config config = 9;
  19. }
  20. }
  21. // FIXME(aaronl): These messages should ideally be embedded in SelectBy, but
  22. // protoc generates bad code for that.
  23. message SelectBySlot {
  24. string service_id = 1 [(gogoproto.customname) = "ServiceID"];
  25. uint64 slot = 2;
  26. }
  27. message SelectByCustom {
  28. string kind = 1;
  29. string index = 2;
  30. string value = 3;
  31. }
  32. message SelectBy {
  33. // TODO(aaronl): Are all of these things we want to expose in
  34. // the API? Exposing them may commit us to maintaining those
  35. // internal indices going forward.
  36. oneof By {
  37. // supported by all object types
  38. string id = 1 [(gogoproto.customname) = "ID"]; // not applicable for FindObjects - use GetObject instead
  39. string id_prefix = 2 [(gogoproto.customname) = "IDPrefix"];
  40. string name = 3;
  41. string name_prefix = 4;
  42. SelectByCustom custom = 5;
  43. SelectByCustom custom_prefix = 6;
  44. // supported by tasks only
  45. string service_id = 7 [(gogoproto.customname) = "ServiceID"];
  46. string node_id = 8 [(gogoproto.customname) = "NodeID"];
  47. SelectBySlot slot = 9;
  48. TaskState desired_state = 10;
  49. // supported by nodes only
  50. NodeRole role = 11;
  51. NodeSpec.Membership membership = 12;
  52. // supported by: service, task
  53. string referenced_network_id = 13 [(gogoproto.customname) = "ReferencedNetworkID"];
  54. string referenced_secret_id = 14 [(gogoproto.customname) = "ReferencedSecretID"];
  55. string referenced_config_id = 16 [(gogoproto.customname) = "ReferencedConfigID"];
  56. // supported by: resource
  57. string kind = 15;
  58. }
  59. }
  60. // Watch defines the RPC methods for monitoring data store change.
  61. service Watch {
  62. // Watch starts a stream that returns any changes to objects that match
  63. // the specified selectors. When the stream begins, it immediately sends
  64. // an empty message back to the client. It is important to wait for
  65. // this message before taking any actions that depend on an established
  66. // stream of changes for consistency.
  67. rpc Watch(WatchRequest) returns (stream WatchMessage) {
  68. option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
  69. };
  70. }
  71. message WatchRequest {
  72. message WatchEntry {
  73. // Kind can contain a builtin type such as "node", "secret", etc. or
  74. // the kind specified by a custom-defined object.
  75. string kind = 1;
  76. // Action (create/update/delete)
  77. // This is a bitmask, so multiple actions may be OR'd together
  78. WatchActionKind action = 2;
  79. // Filters are combined using AND logic - an event must match
  80. // all of them to pass the filter.
  81. repeated SelectBy filters = 3;
  82. }
  83. // Multiple entries are combined using OR logic - i.e. if an event
  84. // matches all of the selectors specified in any single watch entry,
  85. // the event will be sent to the client.
  86. repeated WatchEntry entries = 1;
  87. // ResumeFrom provides an version to resume the watch from, if non-nil.
  88. // The watch will return changes since this version, and continue to
  89. // return new changes afterwards. Watch will return an error if the
  90. // server has compacted its log and no longer has complete history to
  91. // this point.
  92. Version resume_from = 2;
  93. // IncludeOldObject causes WatchMessages to include a copy of the
  94. // previous version of the object on updates. Note that only live
  95. // changes will include the old object (not historical changes
  96. // retrieved using ResumeFrom).
  97. bool include_old_object = 3;
  98. }
  99. // WatchMessage is the type of the stream that's returned to the client by
  100. // Watch. Note that the first item of this stream will always be a WatchMessage
  101. // with a nil Object, to signal that the stream has started.
  102. message WatchMessage {
  103. message Event {
  104. // Action (create/update/delete)
  105. // Note that WatchMessage does not expose "commit" events that
  106. // mark transaction boundaries.
  107. WatchActionKind action = 1;
  108. // Matched object
  109. Object object = 2;
  110. // For updates, OldObject will optionally be included in the
  111. // watch message, containing the previous version of the
  112. // object, if IncludeOldObject was set in WatchRequest.
  113. Object old_object = 3;
  114. }
  115. repeated Event events = 1;
  116. // Index versions this change to the data store. It can be used to
  117. // resume the watch from this point.
  118. Version version = 2;
  119. }
  120. // WatchActionKind distinguishes between creations, updates, and removals. It
  121. // is structured as a bitmap so multiple kinds of events can be requested with
  122. // a mask.
  123. enum WatchActionKind {
  124. option (gogoproto.goproto_enum_prefix) = false;
  125. option (gogoproto.enum_customname) = "WatchActionKind";
  126. WATCH_ACTION_UNKNOWN = 0 [(gogoproto.enumvalue_customname) = "WatchActionKindUnknown"]; // default value, invalid
  127. WATCH_ACTION_CREATE = 1 [(gogoproto.enumvalue_customname) = "WatchActionKindCreate"];
  128. WATCH_ACTION_UPDATE = 2 [(gogoproto.enumvalue_customname) = "WatchActionKindUpdate"];
  129. WATCH_ACTION_REMOVE = 4 [(gogoproto.enumvalue_customname) = "WatchActionKindRemove"];
  130. }