tringuyen-yw/GrpCurl-Help.adoc

## GrpCurl-Help.adoc

      
    Raw
  

              GrpCurl-Help.adoc
            
          
GrpCurl Help


The below is the copy from grpcurl -help. Output current as of June 2020, using


$ grpcurl -version
grpcurl 1.6.0


Usage:


  grpcurl [flags] [address] [list|describe] [symbol]


The address is only optional when used with list or describe and a
protoset or proto flag is provided.


If list is indicated, the symbol (if present) should be a fully-qualified
service name. If present, all methods of that service are listed. If not
present, all exposed services are listed, or all services defined in protosets.


If describe is indicated, the descriptor for the given symbol is shown. The
symbol should be a fully-qualified service, enum, or message name. If no symbol
is given then the descriptors for all exposed or known services are shown.


If neither verb is present, the symbol must be a fully-qualified method name in
service/method or service.method format. In this case, the request body will
be used to invoke the named method. If no body is given but one is required
(i.e. the method is unary or server-streaming), an empty instance of the
method`s request type will be sent.


The address will typically be in the form "host:port" where host can be an IP
address or a hostname and port is a numeric port or service name. If an IPv6
address is given, it must be surrounded by brackets, like "[2001:db8::1]". For
Unix variants, if a -unix=true flag is present, then the address must be the
path to the domain socket.


Available flags:

-H value

Additional headers in name: value format. May specify more than one
via multiple flags. These headers will also be included in reflection
requests requests to a server.

-authority string

The authoritative name of the remote server. This value is passed as the
value of the ":authority" pseudo-header in the HTTP/2 protocol. When TLS
is used, this will also be used as the server name when verifying the
server`s certificate. It defaults to the address that is provided in the
positional arguments.

-cacert string

File containing trusted root certificates for verifying the server.
Ignored if -insecure is specified.

-cert string

File containing client certificate (public key), to present to the
server. Not valid with -plaintext option. Must also provide -key option.

-connect-timeout float

The maximum time, in seconds, to wait for connection to be established.
Defaults to 10 seconds.

-d string

Data for request contents. If the value is @ then the request contents
are read from stdin. For calls that accept a stream of requests, the
contents should include all such request messages concatenated together
(possibly delimited; see -format).

-emit-defaults

Emit default values for JSON-encoded responses.

-expand-headers

If set, headers may use ${NAME} syntax to reference environment
variables. These will be expanded to the actual environment variable
value before sending to the server. For example, if there is an
environment variable defined like FOO=bar, then a header of
key: ${FOO} would expand to key: bar. This applies to -H,
-rpc-header, and -reflect-header options. No other expansion/escaping is
performed. This can be used to supply credentials/secrets without having
to put them in command-line arguments.

-format string

The format of request data. The allowed values are json or text. For
json, the input data must be in JSON format. Multiple request values
may be concatenated (messages with a JSON representation other than
object must be separated by whitespace, such as a newline). For text,
the input data must be in the protobuf text format, in which case
multiple request values must be separated by the "record separator"
ASCII character: 0x1E. The stream should not end in a record separator.
If it does, it will be interpreted as a final, blank message after the
separator. (default "json")

-format-error

When a non-zero status is returned, format the response using the
value set by the -format flag .

-help

Print usage instructions and exit.

-import-path value

The path to a directory from which proto sources can be imported, for
use with -proto flags. Multiple import paths can be configured by
specifying multiple -import-path flags. Paths will be searched in the
order given. If no import paths are given, all files (including all
imports) must be provided as -proto flags, and grpcurl will attempt to
resolve all import statements from the set of file names given.

-insecure

Skip server certificate and domain verification. (NOT SECURE!) Not
valid with -plaintext option.

-keepalive-time float

If present, the maximum idle time in seconds, after which a keepalive
probe is sent. If the connection remains idle and no keepalive response
is received for this same period then the connection is closed and the
operation fails.

-key string

File containing client private key, to present to the server. Not valid
with -plaintext option. Must also provide -cert option.

-max-msg-sz int

The maximum encoded size of a response message, in bytes, that grpcurl
will accept. If not specified, defaults to 4,194,304 (4 megabytes).

-max-time float

The maximum total time the operation can take, in seconds. This is
useful for preventing batch jobs that use grpcurl from hanging due to
slow or bad network links or due to incorrect stream method usage.

-msg-template

When describing messages, show a template of input data.

-plaintext

Use plain-text HTTP/2 when connecting to server (no TLS).

-proto value

The name of a proto source file. Source files given will be used to
determine the RPC schema instead of querying for it from the remote
server via the gRPC reflection API. When set: the list action lists
the services found in the given files and their imports (vs. those
exposed by the remote server), and the describe action describes
symbols found in the given files. May specify more than one via multiple
-proto flags. Imports will be resolved using the given -import-path
flags. Multiple proto files can be specified by specifying multiple
-proto flags. It is an error to use both -protoset and -proto flags.

-protoset value

The name of a file containing an encoded FileDescriptorSet. This file`s
contents will be used to determine the RPC schema instead of querying
for it from the remote server via the gRPC reflection API. When set: the
list action lists the services found in the given descriptors (vs.
those exposed by the remote server), and the describe action describes
symbols found in the given descriptors. May specify more than one via
multiple -protoset flags. It is an error to use both -protoset and
-proto flags.

-protoset-out string

The name of a file to be written that will contain a FileDescriptorSet
proto. With the list and describe verbs, the listed or described
elements and their transitive dependencies will be written to the named
file if this option is given. When invoking an RPC and this option is
given, the method being invoked and its transitive dependencies will be
included in the output file.

-reflect-header value

Additional reflection headers in name: value format. May specify more
than one via multiple flags. These headers will only be used during
reflection requests and will be excluded when invoking the requested RPC
method.

-rpc-header value

Additional RPC headers in name: value format. May specify more than
one via multiple flags. These headers will only be used when invoking
the requested RPC method. They are excluded from reflection requests.

-servername string

Override server name when validating TLS certificate. This flag is
ignored if -plaintext or -insecure is used.
NOTE: Prefer -authority. This flag may be removed in the future. It is
an error to use both -authority and -servername (though this will be
permitted if they are both set to the same value, to increase backwards
compatibility with earlier releases that allowed both to be set).

-unix

Indicates that the server address is the path to a Unix domain socket.

-use-reflection

When true, server reflection will be used to determine the RPC schema.
Defaults to true unless a -proto or -protoset option is provided. If
-use-reflection is used in combination with a -proto or -protoset flag,
the provided descriptor sources will be used in addition to server
reflection to resolve messages and extensions.

-v

Enable verbose output.

-version

Print version.


(end)


## Testing-GRPC-service-with-gRPCurl.adoc

      
    Raw
  

              Testing-GRPC-service-with-gRPCurl.adoc
            
          
    Testing GRPC Service with GRPCurl


Documentation


Install & quick examples: https://github.com/fullstorydev/grpcurl


The grpcurl -help command shows the syntax help on the console. You may need to refer to this help quite often when experimenting with grpcurl at the begining. For convenience a copy of grpcurl -help content is provided here.


Discover the services exposed by a GRPC server


Here is the friends.proto content. We are going to use grpcurl to query the friends grpc server to match that proto descriptor.


syntax = "proto3";

import "cloudstate/entity_key.proto";

package cloudstate.samples.chat.friends;

message Friend{
    string user = 1;
    string avatar = 2;
}

message FriendRequest {
    string user = 1 [(.cloudstate.entity_key) = true];
    Friend friend = 2;
}

message User {
    string user = 1 [(.cloudstate.entity_key) = true];
}

message FriendsList {
    repeated Friend friends = 1;
}

message Empty {
}

service Friends {
    rpc Add(FriendRequest) returns (Empty);
    rpc Remove(FriendRequest) returns (Empty);
    rpc GetFriends(User) returns (FriendsList);
}


Assumption: the Cloudstate chat JS sample has been deployed on a K8S cluster
https://github.com/lightbend/cloudstate-samples/tree/master/chat


run this cmd on one of the node on the K8S cluster using the ClusterIP of the friends service obtained by


$ kubectl get service/friends

NAME      TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)   AGE
friends   ClusterIP   10.152.183.173   <none>        80/TCP    9d


We see that the friends service is exposed on the CLusterIP 10.152.183.173 and listening to port 80
Now we would like to discover the services exposed by the friends GRPC server


ℹ️


the -plaintext means plain-text HTTP/2 when connecting to the server hosting the GRPC service. TLS (Transport Layer Security) is the default protocol when communicating with a GRPC server.


$ grpcurl -plaintext 10.152.183.173:80 list

cloudstate.samples.chat.friends.Friends
grpc.reflection.v1alpha.ServerReflection


Query a GRPC service metadata


Among the services exposed by the GRPC server at 10.152.183.173:80. We see indeed a service named Friends under the package name cloudstate.samples.chat.friends as defined in the service descriptor friends.proto. Thus its fully qualified named cloudstate.samples.chat.friends.Friends. Let’s explore the Friends service further.


List a service


# list all services (server supports reflection)
$ grpcurl -plaintext 10.152.183.173:80 list

cloudstate.samples.chat.friends.Friends
grpc.reflection.v1alpha.ServerReflection


#---"list serviceName": show the methods of serviceName
$ grpcurl -plaintext 10.152.183.173:80 list cloudstate.samples.chat.friends.Friends

cloudstate.samples.chat.friends.Friends.Add
cloudstate.samples.chat.friends.Friends.GetFriends
cloudstate.samples.chat.friends.Friends.Remove


Describe


The "describe" verb will print the type of any symbol that the server knows about or that is found in a given protoset file. It also prints a description of that symbol, in the form of snippets of proto source. It won’t necessarily be the original source that defined the element, but it will be equivalent.


#---"describe serviceName": show the protobuf Service Descriptor of serviceName
#   which details the method signature and return type
$ grpcurl -plaintext 10.152.183.173:80 describe cloudstate.samples.chat.friends.Friends

cloudstate.samples.chat.friends.Friends is a service:
service Friends {
  rpc Add ( .cloudstate.samples.chat.friends.FriendRequest ) returns ( .cloudstate.samples.chat.friends.Empty );
  rpc GetFriends ( .cloudstate.samples.chat.friends.User ) returns ( .cloudstate.samples.chat.friends.FriendsList );
  rpc Remove ( .cloudstate.samples.chat.friends.FriendRequest ) returns ( .cloudstate.samples.chat.friends.Empty );
}


$ grpcurl -plaintext 192.168.1.98:31380 describe cloudstate.samples.chat.chat.Chat

cloudstate.samples.chat.chat.Chat is a service:
service Chat {
  rpc GetBundleImg ( .cloudstate.samples.chat.chat.ImgRequest ) returns ( .google.api.HttpBody ) {
    option (.google.api.http) = { get:"/pages/imgs/{img}"  };
  }
  rpc GetBundleJs ( .cloudstate.samples.chat.chat.Empty ) returns ( .google.api.HttpBody ) {
    option (.google.api.http) = { get:"/pages/build/bundle.js"  };
  }
  rpc GetChatPage ( .cloudstate.samples.chat.chat.Empty ) returns ( .google.api.HttpBody ) {
    option (.google.api.http) = { get:"/pages/chat.html"  };
  }
}

#---describe a single method
$ grpcurl -plaintext 192.168.1.98:31380 describe cloudstate.samples.chat.chat.Chat.GetChatPage

    cloudstate.samples.chat.chat.Chat.GetChatPage is a method:
    rpc GetChatPage ( .cloudstate.samples.chat.chat.Empty ) returns ( .google.api.HttpBody ) {
      option (.google.api.http) = { get:"/pages/chat.html"  };
    }

#---describe a message
$ grpcurl -plaintext 10.152.183.173:80 describe cloudstate.samples.chat.friends.Friend

    cloudstate.samples.chat.friends.Friend is a message:
    message Friend {
      string user = 1;
      string avatar = 2;
    }


Invoking GRPC methods


Now we would like to test some methods, for example Add and GetFriends. As seen above when we "describe" the Friends service, the methods require to pass parameters of type FriendRequest and User. From the command line, grpcrul pass the parameters values serialized as JSON string. We need to explore the protobuf definition of those complex types until we reach the basic JSON data types


$ grpcurl -plaintext 10.152.183.173:80 describe cloudstate.samples.chat.friends.FriendRequest

    cloudstate.samples.chat.friends.FriendRequest is a message:
    message FriendRequest {
      string user = 1 [(.cloudstate.entity_key) = true];
      .cloudstate.samples.chat.friends.Friend friend = 2;
    }

$ grpcurl -plaintext 10.152.183.173:80 describe cloudstate.samples.chat.friends.Friend

    cloudstate.samples.chat.friends.Friend is a message:
    message Friend {
      string user = 1;
      string avatar = 2;
    }

$ grpcurl -plaintext 10.152.183.173:80 describe cloudstate.samples.chat.friends.User

    cloudstate.samples.chat.friends.User is a message:
    message User {
      string user = 1 [(.cloudstate.entity_key) = true];
    }


We can serialize a FriendRequest value as JSON string:


{
  "user": "Tri",
  "friend": {
    "user": "Justin",
    "avatar": "Octopus"
  }
}


Now let’s try to invoke the Add method of the Friends service. The details about the method signature was described previously at Query a GRPC service metadata


$ grpcurl -plaintext -d '{"user": "Tri", "friend": {"user":"Justin", "avatar":"Octopus"}}' \
  10.152.183.173:80 \
  cloudstate.samples.chat.friends.Friends/Add

$ grpcurl -plaintext -d '{"user": "Tri", "friend": {"user":"SpongeBob", "avatar":"Lobster"}}' \
  10.152.183.173:80 \
  cloudstate.samples.chat.friends.Friends/Add

# screen output:
{
}


Now we can verify that user "Tri" has two friends "Justin" and "SpongeBob". By can invoking the GetFriends method which returns a FriendsList


$ grpcurl -plaintext -d '{"user": "Tri"}' \
  10.152.183.173:80 \
  cloudstate.samples.chat.friends.Friends/GetFriends

# screen output:
{
  "friends": [
    {
      "user": "Justin",
      "avatar": "Octopus"
    },
    {
      "user": "SpongeBob",
      "avatar": "Lobster"
    }
  ]
}


For completeness, let’s also test the Remove method


$ grpcurl -plaintext -d '{"user": "Tri", "friend": {"user":"SpongeBob", "avatar":"Lobster"}}' \
  10.152.183.173:80 \
  cloudstate.samples.chat.friends.Friends/Remove

#---Verification: GetFriends should not list the removed `FriendRequest`
$ grpcurl -plaintext -d '{"user": "Tri"}' 10.152.183.173:80 cloudstate.samples.chat.friends.Friends/GetFriends

{
  "friends": [
    {
      "user": "Justin",
      "avatar": "Octopus"
    }
  ]
}


Summary


You have designed a GRPC service


You deploy the service on Kubernetes


You want to test your service by sending requests using curl, as you used to do with REST services. But curl is not compatible with gRPC wire format.


grpcurl is a command line tool designed to test gRPC service ala curl. grpcurl allows you to:


query the metadata of your gRPC service and the schema of your data defined in protobuf format


invoke the methods of your GRPC service


grpcrul supports many more powerful features of GRPC (TLS authentication, streaming & bi-directional streaming request/response). Discover the fullk features of gRPCurl on GitHub