Add API for watch bookmarks

pkg/watch/json/types.go

@@ -32,7 +32,7 @@ import (
 type WatchEvent struct {
 	// The type of the watch event; added, modified, deleted, or error.
 	// +optional
-	Type watch.EventType `json:"type,omitempty" description:"the type of watch event; may be ADDED, MODIFIED, DELETED, or ERROR"`
+	Type watch.EventType `json:"type,omitempty" description:"the type of watch event; may be ADDED, MODIFIED, DELETED, BOOKMARK or ERROR"`
 
 	// For added or modified objects, this is the new object; for deleted objects,
 	// it's the state of the object immediately prior to its deletion.

staging/src/k8s.io/apimachinery/pkg/apis/meta/internalversion/types.go

@@ -35,6 +35,15 @@ type ListOptions struct {
 	FieldSelector fields.Selector
 	// If true, watch for changes to this list
 	Watch bool
+	// allowWatchBookmarks requests watch events with type "BOOKMARK".
+	// Servers that do not implement bookmarks may ignore this flag and
+	// bookmarks are sent at the server's discretion. Clients should not
+	// assume bookmarks are returned at any specific interval, nor may they
+	// assume the server will send any BOOKMARK event during a session.
+	// If this is not a watch, this field is ignored.
+	// If the feature gate WatchBookmarks is not enabled in apiserver,
+	// this field is ignored.
+	AllowWatchBookmarks bool
 	// When specified with a watch call, shows changes that occur after that particular version of a resource.
 	// Defaults to changes from the beginning of history.
 	// When specified for list:

staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/types.go

@@ -349,6 +349,20 @@ type ListOptions struct {
 	// add, update, and remove notifications. Specify resourceVersion.
 	// +optional
 	Watch bool `json:"watch,omitempty" protobuf:"varint,3,opt,name=watch"`
+	// allowWatchBookmarks requests watch events with type "BOOKMARK".
+	// Servers that do not implement bookmarks may ignore this flag and
+	// bookmarks are sent at the server's discretion. Clients should not
+	// assume bookmarks are returned at any specific interval, nor may they
+	// assume the server will send any BOOKMARK event during a session.
+	// If this is not a watch, this field is ignored.
+	// If the feature gate WatchBookmarks is not enabled in apiserver,
+	// this field is ignored.
+	//
+	// This field is alpha and can be changed or removed without notice.
+	//
+	// +optional
+	AllowWatchBookmarks bool `json:"allowWatchBookmarks,omitempty"`
+
 	// When specified with a watch call, shows changes that occur after that particular version of a resource.
 	// Defaults to changes from the beginning of history.
 	// When specified for list:

staging/src/k8s.io/apimachinery/pkg/watch/watch.go

@@ -44,6 +44,7 @@ const (
 	Added    EventType = "ADDED"
 	Modified EventType = "MODIFIED"
 	Deleted  EventType = "DELETED"
+	Bookmark EventType = "BOOKMARK"
 	Error    EventType = "ERROR"
 
 	DefaultChanSize int32 = 100
@@ -57,6 +58,10 @@ type Event struct {
 	// Object is:
 	//  * If Type is Added or Modified: the new state of the object.
 	//  * If Type is Deleted: the state of the object immediately before deletion.
+	//  * If Type is Bookmark: the object (instance of a type being watched) where
+	//    only ResourceVersion field is set. On successful restart of watch from a
+	//    bookmark resourceVersion, client is guaranteed to not get repeat event
+	//    nor miss any events.
 	//  * If Type is Error: *api.Status is recommended; other types may make sense
 	//    depending on context.
 	Object runtime.Object

staging/src/k8s.io/apiserver/pkg/features/kube_features.go

@@ -109,6 +109,12 @@ const (
 	//
 	// Allows kube-proxy to create DSR loadbalancers for Windows
 	WinDSR utilfeature.Feature = "WinDSR"
+
+	// owner: @wojtek-t
+	// alpha: v1.15
+	//
+	// Enables support for watch bookmark events.
+	WatchBookmark utilfeature.Feature = "WatchBookmark"
 )
 
 func init() {
@@ -130,4 +136,5 @@ var defaultKubernetesFeatureGates = map[utilfeature.Feature]utilfeature.FeatureS
 	StorageVersionHash:      {Default: false, PreRelease: utilfeature.Alpha},
 	WinOverlay:              {Default: false, PreRelease: utilfeature.Alpha},
 	WinDSR:                  {Default: false, PreRelease: utilfeature.Alpha},
+	WatchBookmark:           {Default: false, PreRelease: utilfeature.Alpha},
 }