gnsi/pathz: clarify rotation behaviour for ongoing gNMI subscribers

The index.md is updated with a section covering the expected
behaviour for ongoing subscriptions when a server
experiences a pathz policy change.
This commit also updates the pathz.UploadResponse value so that
 it contains information about ongoing subscriptions and whether
they would experience different behaviour under the incoming policy.
.pb.go files were regenerated.

pathz/index.md

@@ -91,6 +91,69 @@ out the action.
 If the stream is disconnected prior to the Finalize message being
 sent, the proposed configuration is rolled back automatically.
 
+### AuthorizationPolicy rotation and gNMI subscriptions
+
+When a gNMI client connects and begins a subscription, the active
+pathz policy on the system is applied to that subscription for the entire
+duration of that subscription.     
+If a new pathz policy is rotated and finalized, ongoing subscriptions will not be
+affected and will continue to be subscribed with whatever authorization
+they had upon beginning the subscription.     
+These clients will not be aware that the pathz policy has been updated
+until they disconnect and reconnect, at which point the new policy will
+be applied to their subscription, and the subset of YANG leafs which they are
+permitted to read may change.
+
+While rotating a pathz policy, network operators may wish to know which of
+the ongoing subscriptions would be affected if the rotation were finalized and
+the gNMI subscriber were to then disconnect and reconnect.     
+For this purpose, the `pathz.UploadResponse` contains information about the
+current ongoing subscriptions, as well as whether or not these subscriptions
+would be impacted by the pathz policy which was uploaded in the
+`pathz.UploadRequest` earlier in the Rotate stream.
+
+A subscription being "impacted" means that for the subscription path and the
+user who made that subscription, the pathz policy from the
+`pathz.UploadRequest` specifies some rules which would mean that the best-matching
+rule for that user and path (or any subpaths underneath that path) would change if
+the rotation gets finalized.
+
+For example, consider a system with the following installed rules:
+```
+/a/b/[k0=*]/c -> user Alice, action PERMIT
+/a/b/[k0=*]/c -> user Bob, action PERMIT
+/a/b/[k0=*]/c -> user Charlie, action PERMIT
+```
+Then:    
+user Alice subscribes to `/a`   
+user Bob subscribes to `/a`   
+user Charlie subscribes to `/a/b/[k0=X]/c/d`   
+
+Next, a pathz Rotate stream begins, and a `pathz.UploadRequest` is sent containing
+the following policy:
+```
+/a/b/[k0=*]/c -> user Alice, action PERMIT READ
+/a/b/[k0=*]/c -> user Bob, action PERMIT READ
+/a/b/[k0=Y]/c -> user Bob, action DENY READ
+/a/b/[k0=*]/c -> user Charlie, action PERMIT READ
+/a/b/[k0=Y]/c -> user Charlie, action DENY READ
+```
+
+The uploadResponse returned specifies that for this incoming policy:
+1. Alice's subscription to `/a` is not impacted. 
+2. Bob's subscription to `/a` is impacted. 
+3. Charlie's subscription `/a/b/[k0=X]/c/d` is not impacted
+
+- Alice's subscription is not impacted as the best-matching rule for `/a`
+ and every path beneath `/a` remains the same.   
+- Bob's subscription is impacted as currently the best-matching rule
+for the subpath `/a/b/[k0=Y]/c` is PERMIT READ, while under this
+incoming policy it is DENY READ.    
+If this rotation is finalized, his view of the YANG tree would change
+when he disconnects/reconnects.
+- Charlie's subscription is not impacted as the best-matching rule for his path
+continues to be the `/a/b/[k0=*]/c` PERMIT READ rule
+
 ## Open Questions/Considerations
 
 None to date.