README
¶
Motivation
Evans has been created to use easier than other existing gRPC clients.
If you want to keep your product quality, you must use CI with gRPC testing, should not do use manually testing.
Evans will complete your other use cases just like:
- Manually gRPC API inspection
- To automate some tasks by scripting
Above use cases is corresponding to Evans's two modes, REPL mode, and CLI mode.
REPL mode
REPL mode is the solution for first use case.
You can use it without thinking like package name, service name, RPC name, command usage, and so on because REPL mode has powerful completion!
CLI mode
CLI mode is stateless mode just like grpc-ecosystem/polyglot.
It sends one request per one command as its name suggests.
So it is based on UNIX philosophy.
For example, read inputs from stdin, the command will be a filter command.
On the other hand, the command result will be outputted to stdout by JSON formatted.
So, you can format it by any commands like jq. Also, if you want to use the same command (e.g. use same JSON inputs), you can use --file (-f) option.
Table of Contents
- Installation
- Usage (REPL)
- Usage (CLI)
- Other features
- Supported IDL (interface definition language)
- See Also
Installation
Highly recommended methods are GitHub Releases or Homebrew because these can be software update automatically by the built-in feature in Evans.
From GitHub Releases
Please see GitHub Releases.
Available binaries are:
- macOS
- Linux
- Windows
macOS
$ brew tap ktr0731/evans
$ brew install evans
[Deprecated] go get
Go v1.11.5 (with mod-aware mode) or later required.
go get installation is not supported officially.
$ go get github.com/ktr0731/evans
Usage (REPL)
Basic usage
Evans consists of some commands in REPL mode.
The proto file which read in the demonstration and its implementation are available at ktr0731/grpc-test.
grpc-test's details can see grpc-test --help.
Enter to REPL.
$ cd grpc-test
$ evans api/api.proto
If your server is enabling gRPC reflection, you can launch Evans with only -r (--reflection) option.
$ evans -r
Also if the server requires secure TLS connections, you can launch Evans with the -t (--tls) option.
$ evans --tls --host example.com -r
To show package names of proto files REPL read:
> show package
+---------+
| PACKAGE |
+---------+
| api |
+---------+
To show the summary of services or messages:
> package api
> show service
+---------+----------------------+-----------------------------+----------------+
| SERVICE | RPC | REQUESTTYPE | RESPONSETYPE |
+---------+----------------------+-----------------------------+----------------+
| Example | Unary | SimpleRequest | SimpleResponse |
| | UnaryMessage | UnaryMessageRequest | SimpleResponse |
| | UnaryRepeated | UnaryRepeatedRequest | SimpleResponse |
| | UnaryRepeatedMessage | UnaryRepeatedMessageRequest | SimpleResponse |
| | UnaryRepeatedEnum | UnaryRepeatedEnumRequest | SimpleResponse |
| | UnarySelf | UnarySelfRequest | SimpleResponse |
| | UnaryMap | UnaryMapRequest | SimpleResponse |
| | UnaryMapMessage | UnaryMapMessageRequest | SimpleResponse |
| | UnaryOneof | UnaryOneofRequest | SimpleResponse |
| | UnaryEnum | UnaryEnumRequest | SimpleResponse |
| | UnaryBytes | UnaryBytesRequest | SimpleResponse |
| | ClientStreaming | SimpleRequest | SimpleResponse |
| | ServerStreaming | SimpleRequest | SimpleResponse |
| | BidiStreaming | SimpleRequest | SimpleResponse |
+---------+----------------------+-----------------------------+----------------+
> show message
+-----------------------------+
| MESSAGE |
+-----------------------------+
| SimpleRequest |
| SimpleResponse |
| Name |
| UnaryMessageRequest |
| UnaryRepeatedRequest |
| UnaryRepeatedMessageRequest |
| UnaryRepeatedEnumRequest |
| UnarySelfRequest |
| Person |
| UnaryMapRequest |
| UnaryMapMessageRequest |
| UnaryOneofRequest |
| UnaryEnumRequest |
| UnaryBytesRequest |
+-----------------------------+
To show more description of a message:
> desc SimpleRequest
+-------+-------------+
| FIELD | TYPE |
+-------+-------------+
| name | TYPE_STRING |
+-------+-------------+
Set headers for each request:
> header -h
usage: header <key>=<value>[, <key>=<value>...]
> header foo=bar
To show headers:
> show header
+-------------+-------+
| KEY | VAL |
+-------------+-------+
| foo | bar |
| grpc-client | evans |
+-------------+-------+
To remove the added header:
> header foo
> show header
+-------------+-------+
| KEY | VAL |
+-------------+-------+
| grpc-client | evans |
+-------------+-------+
Call a RPC:
> service Example
> call Unary
name (TYPE_STRING) => ktr
{
"message": "hello, ktr"
}
Evans constructs a gRPC request interactively and sends the request to a gRPC server.
Finally, Evans prints the JSON formatted result.
Repeated fields
repeated is an array-like data structure.
You can input some values and finish with CTRL-D
> call UnaryRepeated
<repeated> name (TYPE_STRING) => foo
<repeated> name (TYPE_STRING) => bar
<repeated> name (TYPE_STRING) => baz
<repeated> name (TYPE_STRING) =>
{
"message": "hello, foo, bar, baz"
}
Enum fields
You can select one from the proposed selections.
To abort it, input CTRL-C.
> call UnaryEnum
? UnaryEnumRequest [Use arrows to move, type to filter]
> Male
Female
{
"message": "M"
}
Bytes type fields
You can use byte literal and Unicode literal.
> call UnaryBytes
data (TYPE_BYTES) => \x46\x6f\x6f
{
"message": "received: (bytes) 46 6f 6f, (string) Foo"
}
> call UnaryBytes
data (TYPE_BYTES) => \u65e5\u672c\u8a9e
{
"message": "received: (bytes) e6 97 a5 e6 9c ac e8 aa 9e, (string) 日本語"
}
Client streaming RPC
Client streaming RPC accepts some requests and then returns only one response.
Finish request inputting with CTRL-D
> call ClientStreaming
name (TYPE_STRING) => ktr
name (TYPE_STRING) => ktr
name (TYPE_STRING) => ktr
name (TYPE_STRING) =>
{
"message": "ktr, you greet 3 times."
}
Server streaming RPC
Server streaming RPC accepts only one request and then returns some responses. Each response is represented as another JSON formatted output.
name (TYPE_STRING) => ktr
{
"message": "hello ktr, I greet 0 times."
}
{
"message": "hello ktr, I greet 1 times."
}
Bidirectional streaming RPC
Bidirectional streaming RPC accepts some requests and returns some responses corresponding to each request. Finish request inputting with CTRL-D
> call BidiStreaming
name (TYPE_STRING) => foo
{
"message": "hello foo, I greet 0 times."
}
{
"message": "hello foo, I greet 1 times."
}
{
"message": "hello foo, I greet 2 times."
}
name (TYPE_STRING) => bar
{
"message": "hello bar, I greet 0 times."
}
name (TYPE_STRING) =>
Usage (CLI)
Basic usage
You can input requests from stdin or files.
Unlike REPL mode, you need to specify --package, --service and --call options.
If gRPC server enables gRPC reflection, --package is unnecessary. (instead, -r requires)
Use --file (-f) to specify a file.
$ cat request.json
{
"name": "ktr"
}
$ evans --service Example --call Unary --file request.json
{
"message": "hello, ktr"
}
Use stdin.
$ echo '{ "name": "ktr" }' | evans --service Example --call Unary
{
"message": "hello, ktr"
}
If .evans.toml is exist in Git project root, you can denote default values.
[default]
protoFile = ["api/api.proto"]
package = "api"
service = "Example"
Then, the command will be more clear.
Repeated fields
$ echo '{ "name": ["foo", "bar"] }' | evans -r --service Example --call UnaryRepeated
{
"message": "hello, foo, bar"
}
Enum fields
$ echo '{ "gender": 0 }' | evans -r --service Example --call UnaryEnum
{
"message": "M"
}
Bytes type fields
You need to encode bytes by Base64.
This constraint is come from Go's standard package encoding/json
$ echo 'Foo' | base64
Rm9vCg==
$ echo '{"data": "Rm9vCg=="}' | evans -r --service Example --call UnaryBytes
Client streaming RPC
$ echo '{ "name": "ktr" } { "name": "ktr" }' | evans -r --service Example --call ClientStreaming
{
"message": "ktr, you greet 2 times."
}
Server streaming RPC
$ echo '{ "name": "ktr" }' | evans -r --service Example --call ServerStreaming
{
"message": "hello ktr, I greet 0 times."
}
{
"message": "hello ktr, I greet 1 times."
}
{
"message": "hello ktr, I greet 2 times."
}
Bidirectional streaming RPC
$ echo '{ "name": "foo" } { "name": "bar" }' | evans -r --service Example --call BidiStreaming
{
"message": "hello foo, I greet 0 times."
}
{
"message": "hello foo, I greet 1 times."
}
{
"message": "hello foo, I greet 2 times."
}
{
"message": "hello foo, I greet 3 times."
}
{
"message": "hello bar, I greet 0 times."
}
Other features
gRPC Web
Evans also support gRPC Web protocol.
Tested gRPC Web implementations are:
At the moment TLS is not supported for gRPC Web.
Supported IDL (interface definition language)
See Also
Evans (DJ YOSHITAKA)
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
adapter
|
|
|
app
Package app provides the entrypoint for Evans.
|
Package app provides the entrypoint for Evans. |
|
cli
Package cli provides the entrypoint to launch CLI mode.
|
Package cli provides the entrypoint to launch CLI mode. |
|
cui
Package cui implements structured character user interfaces.
|
Package cui implements structured character user interfaces. |
|
grpc
Package grpc implements gRPC clients.
|
Package grpc implements gRPC clients. |
|
inputter
Package inputter implements input interfaces to map user input to actual request schema.
|
Package inputter implements input interfaces to map user input to actual request schema. |
|
presenter
Package presenter implements formatted usecase output.
|
Package presenter implements formatted usecase output. |
|
protobuf
Package protobuf provides Protocol Buffers3 related interfaces.
|
Package protobuf provides Protocol Buffers3 related interfaces. |
|
repl
Package repl provides the entrypoint to launch REPL mode.
|
Package repl provides the entrypoint to launch REPL mode. |
|
Package cache provides read/write access to the Evans's cache file.
|
Package cache provides read/write access to the Evans's cache file. |
|
Package config provides config structures, and a mechanism that merges sources such that the global config file, a project local config file and command-line flags.
|
Package config provides config structures, and a mechanism that merges sources such that the global config file, a project local config file and command-line flags. |
|
Package logger provides logging functions.
|
Package logger provides logging functions. |
|
tests
|
|
|
e2e/server/helloworld
Package helloworld is a generated protocol buffer package.
|
Package helloworld is a generated protocol buffer package. |