Improve documentation to the AttributeContext (#366)

Signed-off-by: Hong Zhang <wora2000@gmail.com>

api/auth/external_auth.proto

@@ -3,15 +3,18 @@ syntax = "proto3";
 // [#proto-status: draft]
 
 package envoy.api.v2.auth;
+
 option go_package = "auth";
 
 import "api/address.proto";
 import "google/protobuf/timestamp.proto";
 import "google/rpc/status.proto";
 
-// Authorization service.
-// Primarily responds with `OK` or `NOT OK`.
+// A generic interface for performing authorization check on incoming
+// requests to a networked service.
 service Authorization {
+  // Performs authorization check based on the attributes associated with the
+  // incoming request, and returns status `OK` or not `OK`.
   rpc Check(CheckRequest) returns (CheckResponse);
 }
 
@@ -28,8 +31,9 @@ message CheckResponse {
 // An attribute is a piece of metadata that describes an activity on a network.
 // For example, the size of an HTTP request, or the status code of an HTTP response.
 //
-// Each attribute has a type and a name, which is logically defined as a proto message field.
-// AttributeContext is a collection of individual attributes.
+// Each attribute has a type and a name, which is logically defined as a proto message field
+// of the `AttributeContext`. The `AttributeContext` is a collection of individual attributes
+// supported by Envoy authorization system.
 message AttributeContext {
   // This message defines attributes for a node that handles a network request.
   // The node can be either a service or an application that sends, forwards,
@@ -37,7 +41,7 @@ message AttributeContext {
   // `principal`, and `labels` as appropriate.
   message Peer {
     // The address of the peer, this is typically the IP address.
-    // It can also be UDS, or others.
+    // It can also be UDS path, or others.
     Address address = 1;
 
     // The canonical service name of the peer.
@@ -57,9 +61,10 @@ message AttributeContext {
     // If an X.509 certificate is used to assert the identity this field should be sourced from
     // `Subject` or `Subject Alternative Names`. The primary identity should be the principal.
     // The principal format is issuer specific.
-    // For example
-    // SPIFFE format is `spiffe://trust-domain/path`
-    // Google account format is `https://accounts.google.com/{userid}`
+    //
+    // Example:
+    // *    SPIFFE format is `spiffe://trust-domain/path`
+    // *    Google account format is `https://accounts.google.com/{userid}`
     string principal = 4;
   }
 
@@ -68,20 +73,19 @@ message AttributeContext {
     // The timestamp when the proxy receives the first byte of the request.
     google.protobuf.Timestamp time = 1;
 
-    // HTTP and related requests.
+    // Represents an HTTP request or an HTTP-like request.
     HTTPRequest http = 2;
 
     // More request types are added here as necessary.
   }
 
   // This message defines attributes for an HTTP request.
-  // HTTP, H2, grpc are all considered http requests.
+  // HTTP/1.x, HTTP/2, gRPC are all considered as HTTP requests.
   message HTTPRequest {
     // The unique ID for a request, which can be propagated to downstream
     // systems. The ID should have low probability of collision
     // within a single day for a specific service.
-    // For http it should be X-Request-ID or equivalent.
-    // For tcp is should be a connection id.
+    // For HTTP requests, it should be X-Request-ID or equivalent.
     string id = 1;
 
     // The HTTP request method, such as `GET`, `POST`.
@@ -105,7 +109,7 @@ message AttributeContext {
     // appears in the first line of the HTTP request. No decoding is performed.
     string query = 7;
 
-    // The HTTP URL fragment. No URL decoding is performed.
+    // The HTTP URL fragment, excluding leading `#`. No URL decoding is performed.
     string fragment = 8;
 
     // The HTTP request size in bytes. If unknown, it must be -1.