use proto syntax for describe

[jhump]

The output of using the describe verb was pretty gross: the JSON format of a descriptor proto. It was very verbose, yet at the same time hard to glean useful info from it.

This change makes it emit proto source instead, which is more concise but also more useful and much easier to read.

Here's an example of the difference. This is the new hotness:

> grpcurl -plaintext 127.0.0.1:12345 describe .Bank
Bank is a service:
service Bank {
  rpc CloseAccount ( .CloseAccountRequest ) returns ( .google.protobuf.Empty );
  rpc Deposit ( .DepositRequest ) returns ( .BalanceResponse );
  rpc GetAccounts ( .google.protobuf.Empty ) returns ( .GetAccountsResponse );
  rpc GetTransactions ( .GetTransactionsRequest ) returns ( stream .Transaction );
  rpc OpenAccount ( .OpenAccountRequest ) returns ( .Account );
  rpc Transfer ( .TransferRequest ) returns ( .TransferResponse );
  rpc Withdraw ( .WithdrawRequest ) returns ( .BalanceResponse );
}

> grpcurl -plaintext 127.0.0.1:12345 describe .Bank.OpenAccount
Bank.OpenAccount is a method:
rpc OpenAccount ( .OpenAccountRequest ) returns ( .Account );

> grpcurl -plaintext 127.0.0.1:12345 describe .OpenAccountRequest
OpenAccountRequest is a message:
message OpenAccountRequest {
  int32 initial_deposit_cents = 1;
  .Account.Type type = 2;
}

> grpcurl -plaintext 127.0.0.1:12345 describe .Account
Account is a message:
message Account {
  uint64 account_number = 1;
  .Account.Type type = 2;
  int32 balance_cents = 3;
  enum Type {
    UNKNOWN = 0;
    CHECKING = 1;
    SAVING = 2;
    MONEY_MARKET = 3;
    LINE_OF_CREDIT = 4;
    LOAN = 5;
    EQUITIES = 6;
  }
}

> grpcurl -plaintext 127.0.0.1:12345 describe .Account.Type.LOAN
Account.Type.LOAN is an enum value:
LOAN = 5;

And, as a reminder, here is the gross output it spits out without this change:

> grpcurl -plaintext 127.0.0.1:12345 describe .Bank
Bank is a service:
{
  "name": "Bank",
  "method": [
    {
      "name": "OpenAccount",
      "inputType": ".OpenAccountRequest",
      "outputType": ".Account",
      "options": {
        
      }
    },
    {
      "name": "CloseAccount",
      "inputType": ".CloseAccountRequest",
      "outputType": ".google.protobuf.Empty",
      "options": {
        
      }
    },
    {
      "name": "GetAccounts",
      "inputType": ".google.protobuf.Empty",
      "outputType": ".GetAccountsResponse",
      "options": {
        
      }
    },
    {
      "name": "GetTransactions",
      "inputType": ".GetTransactionsRequest",
      "outputType": ".Transaction",
      "options": {
        
      },
      "serverStreaming": true
    },
    {
      "name": "Deposit",
      "inputType": ".DepositRequest",
      "outputType": ".BalanceResponse",
      "options": {
        
      }
    },
    {
      "name": "Withdraw",
      "inputType": ".WithdrawRequest",
      "outputType": ".BalanceResponse",
      "options": {
        
      }
    },
    {
      "name": "Transfer",
      "inputType": ".TransferRequest",
      "outputType": ".TransferResponse",
      "options": {
        
      }
    }
  ],
  "options": {
    
  }
}

> grpcurl -plaintext 127.0.0.1:12345 describe .Bank.OpenAccount
Bank.OpenAccount is a method:
{
  "name": "OpenAccount",
  "inputType": ".OpenAccountRequest",
  "outputType": ".Account",
  "options": {
    
  }
}

> grpcurl -plaintext 127.0.0.1:12345 describe .OpenAccountRequest
OpenAccountRequest is a message:
{
  "name": "OpenAccountRequest",
  "field": [
    {
      "name": "initial_deposit_cents",
      "number": 1,
      "label": "LABEL_OPTIONAL",
      "type": "TYPE_INT32",
      "options": {
        
      },
      "jsonName": "initialDepositCents"
    },
    {
      "name": "type",
      "number": 2,
      "label": "LABEL_OPTIONAL",
      "type": "TYPE_ENUM",
      "typeName": ".Account.Type",
      "options": {
        
      },
      "jsonName": "type"
    }
  ],
  "options": {
    
  }
}

> grpcurl -plaintext 127.0.0.1:12345 describe .Account
Account is a message:
{
  "name": "Account",
  "field": [
    {
      "name": "account_number",
      "number": 1,
      "label": "LABEL_OPTIONAL",
      "type": "TYPE_UINT64",
      "options": {
        
      },
      "jsonName": "accountNumber"
    },
    {
      "name": "type",
      "number": 2,
      "label": "LABEL_OPTIONAL",
      "type": "TYPE_ENUM",
      "typeName": ".Account.Type",
      "options": {
        
      },
      "jsonName": "type"
    },
    {
      "name": "balance_cents",
      "number": 3,
      "label": "LABEL_OPTIONAL",
      "type": "TYPE_INT32",
      "options": {
        
      },
      "jsonName": "balanceCents"
    }
  ],
  "enumType": [
    {
      "name": "Type",
      "value": [
        {
          "name": "UNKNOWN",
          "number": 0,
          "options": {
            
          }
        },
        {
          "name": "CHECKING",
          "number": 1,
          "options": {
            
          }
        },
        {
          "name": "SAVING",
          "number": 2,
          "options": {
            
          }
        },
        {
          "name": "MONEY_MARKET",
          "number": 3,
          "options": {
            
          }
        },
        {
          "name": "LINE_OF_CREDIT",
          "number": 4,
          "options": {
            
          }
        },
        {
          "name": "LOAN",
          "number": 5,
          "options": {
            
          }
        },
        {
          "name": "EQUITIES",
          "number": 6,
          "options": {
            
          }
        }
      ],
      "options": {
        
      }
    }
  ],
  "options": {
    
  }
}

> grpcurl -plaintext 127.0.0.1:12345 describe .Account.Type.LOAN
Account.Type.LOAN is an enum value:
{
  "name": "LOAN",
  "number": 5,
  "options": {
    
  }
}

[dragonsinth]

Awesome. We still have the thing where you can print an example of a request proto in json, right?

[jhump]

We still have the thing where you can print an example of a request proto in json, right?

Yep. In fact, if you feel like doing a larger review, I had a bigger change to support plugging in formats other than JSON (based on request #51), which also updated that feature, so it can show a template in protobuf text format.

Here's that change: #54. (I was bad and went ahead and merged it before getting a review. If you do have feedback, I will follow up with a PR to address it all.)

In addition to adding support for protobuf text format (instead of JSON), it also updates JSON handling to better support possible use of google.protobuf.Any messages. (Which, in turn, necessitated some extra API, for gathering a list of all known file descriptors.) Those two things together turned out to be a non-trivial change. (So apologies for the size of the diff.)

[dragonsinth]

No worries, seems reasonable