From f153bf5041d314adf66d5795b00463c83a9511d9 Mon Sep 17 00:00:00 2001 From: Arjan Bal Date: Wed, 24 Apr 2024 11:30:33 +0530 Subject: [PATCH] Improve grammar in the interceptor tutorial --- examples/features/interceptor/README.md | 147 ++++++++++++------------ 1 file changed, 74 insertions(+), 73 deletions(-) diff --git a/examples/features/interceptor/README.md b/examples/features/interceptor/README.md index 0f1908be590a..68e6a965be7e 100644 --- a/examples/features/interceptor/README.md +++ b/examples/features/interceptor/README.md @@ -1,9 +1,10 @@ # Interceptor gRPC provides simple APIs to implement and install interceptors on a per -ClientConn/Server basis. Interceptor intercepts the execution of each RPC call. -Users can use interceptors to do logging, authentication/authorization, metrics -collection, and many other functionality that can be shared across RPCs. +ClientConn/Server basis. Interceptors act as a layer between the application and +gRPC and can be used to observe or control the behavior of gRPC. Interceptors +can be used for logging, authentication/authorization, metrics collection, and +other functionality that is shared across RPCs. ## Try it @@ -17,102 +18,102 @@ go run client/main.go ## Explanation -In gRPC, interceptors can be categorized into two kinds in terms of the type of -RPC calls they intercept. The first one is the **unary interceptor**, which -intercepts unary RPC calls. And the other is the **stream interceptor** which -deals with streaming RPC calls. See -[here](https://grpc.io/docs/guides/concepts.html#rpc-life-cycle) for explanation -about unary RPCs and streaming RPCs. Each of client and server has their own -types of unary and stream interceptors. Thus, there are in total four different -types of interceptors in gRPC. +gRPC has separate interceptors for unary RPCs and streaming RPCs. See the +[gRPC docs](https://grpc.io/docs/guides/concepts.html#rpc-life-cycle) for an +explanation about unary and streaming RPCs. Both the client and the server have +their own types of unary and stream interceptors. Thus, there are four different +types of interceptors in total. ### Client-side #### Unary Interceptor -[`UnaryClientInterceptor`](https://godoc.org/google.golang.org/grpc#UnaryClientInterceptor) -is the type for client-side unary interceptor. It is essentially a function type -with signature: `func(ctx context.Context, method string, req, reply -interface{}, cc *ClientConn, invoker UnaryInvoker, opts ...CallOption) error`. -An implementation of a unary interceptor can usually be divided into three -parts: pre-processing, invoking RPC method, and post-processing. +The type for client-side unary interceptors is +[`UnaryClientInterceptor`](https://godoc.org/google.golang.org/grpc#UnaryClientInterceptor). +It is essentially a function type with signature: `func(ctx context.Context, +method string, req, reply interface{}, cc *ClientConn, invoker UnaryInvoker, +opts ...CallOption) error`. Unary interceptor implementations can usually be +divided into three parts: pre-processing, invoking the RPC method, and +post-processing. For pre-processing, users can get info about the current RPC call by examining -the args passed in, such as RPC context, method string, request to be sent, and -CallOptions configured. With the info, users can even modify the RPC call. For -instance, in the example, we examine the list of CallOptions and see if call -credential has been configured. If not, configure it to use oauth2 with token -"some-secret-token" as fallback. In our example, we intentionally omit -configuring the per RPC credential to resort to fallback. +the args passed in. The args include the RPC context, method string, request to +be sent, and the CallOptions configured. With this info, users can even modify +the RPC call. For instance, in the example, we examine the list of CallOptions +and check if the call credentials have been configured. If not, the interceptor +configures the RPC call to use oauth2 with a token "some-secret-token" as a +fallback. In our example, we intentionally omit configuring the per RPC +credential to resort to the fallback. -After pre-processing is done, use can invoke the RPC call by calling the -`invoker`. +After pre-processing, users can invoke the RPC call by calling the `invoker`. -Once the invoker returns the reply and error, user can do post-processing of the -RPC call. Usually, it's about dealing with the returned reply and error. In the -example, we log the RPC timing and error info. +Once the invoker returns, users can post-process the RPC call. This usually +involves dealing with the returned reply and error. In the example, we log the +RPC timing and error info. -To install a unary interceptor on a ClientConn, configure `Dial` with -`DialOption` -[`WithUnaryInterceptor`](https://godoc.org/google.golang.org/grpc#WithUnaryInterceptor). +To install a unary interceptor on a ClientConn, configure `Dial` with the +[`WithUnaryInterceptor`](https://godoc.org/google.golang.org/grpc#WithUnaryInterceptor) +`DialOption`. #### Stream Interceptor -[`StreamClientInterceptor`](https://godoc.org/google.golang.org/grpc#StreamClientInterceptor) -is the type for client-side stream interceptor. It is a function type with -signature: `func(ctx context.Context, desc *StreamDesc, cc *ClientConn, method -string, streamer Streamer, opts ...CallOption) (ClientStream, error)`. An -implementation of a stream interceptor usually include pre-processing, and -stream operation interception. - -For pre-processing, it's similar to unary interceptor. - -However, rather than doing the RPC method invocation and post-processing -afterwards, stream interceptor intercepts the users' operation on the stream. -First, the interceptor calls the passed-in `streamer` to get a `ClientStream`, -and then wraps around the `ClientStream` and overloading its methods with -intercepting logic. Finally, interceptors returns the wrapped `ClientStream` to -user to operate on. - -In the example, we define a new struct `wrappedStream`, which is embedded with a -`ClientStream`. Then, we implement (overload) the `SendMsg` and `RecvMsg` -methods on `wrappedStream` to intercept these two operations on the embedded +The type for client-side stream interceptors is +[`StreamClientInterceptor`](https://godoc.org/google.golang.org/grpc#StreamClientInterceptor). +It is a function type with signature: `func(ctx context.Context, desc +*StreamDesc, cc *ClientConn, method string, streamer Streamer, opts +...CallOption) (ClientStream, error)`. An implementation of a stream interceptor +usually includes pre-processing, and stream operation interception. + +The pre-processing is similar to unary interceptors. + +However, rather than invoking the RPC method followed by post-processing, stream +interceptors intercept the users' operations on the stream. The interceptor +first calls the passed-in `streamer` to get a `ClientStream`, and then wraps the +`ClientStream` while overloading its methods with the interception logic. +Finally, the interceptor returns the wrapped `ClientStream` to user to operate +on. + +In the example, we define a new struct `wrappedStream`, which embeds a +`ClientStream`. We then implement (overload) the `SendMsg` and `RecvMsg` methods +on `wrappedStream` to intercept these two operations on the embedded `ClientStream`. In the example, we log the message type info and time info for interception purpose. -To install the stream interceptor for a ClientConn, configure `Dial` with -`DialOption` -[`WithStreamInterceptor`](https://godoc.org/google.golang.org/grpc#WithStreamInterceptor). +To install a stream interceptor for a ClientConn, configure `Dial` with the +[`WithStreamInterceptor`](https://godoc.org/google.golang.org/grpc#WithStreamInterceptor) +`DialOption`. ### Server-side -Server side interceptor is similar to client side, though with slightly -different provided info. +Server side interceptors are similar to client side interceptors, with slightly +different information provided as args. #### Unary Interceptor -[`UnaryServerInterceptor`](https://godoc.org/google.golang.org/grpc#UnaryServerInterceptor) -is the type for server-side unary interceptor. It is a function type with -signature: `func(ctx context.Context, req interface{}, info *UnaryServerInfo, -handler UnaryHandler) (resp interface{}, err error)`. +The type for server-side unary interceptors is +[`UnaryServerInterceptor`](https://godoc.org/google.golang.org/grpc#UnaryServerInterceptor). +It is a function type with signature: `func(ctx context.Context, req +interface{}, info *UnaryServerInfo, handler UnaryHandler) (resp interface{}, err +error)`. -Refer to client-side unary interceptor section for detailed implementation -explanation. +Refer to the client-side unary interceptor section for a detailed implementation +and explanation. -To install the unary interceptor for a Server, configure `NewServer` with -`ServerOption` -[`UnaryInterceptor`](https://godoc.org/google.golang.org/grpc#UnaryInterceptor). +To install a unary interceptor on a Server, configure `NewServer` with the +[`UnaryInterceptor`](https://godoc.org/google.golang.org/grpc#UnaryInterceptor) +`ServerOption`. #### Stream Interceptor -[`StreamServerInterceptor`](https://godoc.org/google.golang.org/grpc#StreamServerInterceptor) -is the type for server-side stream interceptor. It is a function type with -signature: `func(srv interface{}, ss ServerStream, info *StreamServerInfo, -handler StreamHandler) error`. +The type for server-side stream interceptors is +[`StreamServerInterceptor`](https://godoc.org/google.golang.org/grpc#StreamServerInterceptor). +It is a function type with the signature: `func(srv interface{}, ss +ServerStream, info *StreamServerInfo, handler StreamHandler) error`. -Refer to client-side stream interceptor section for detailed implementation -explanation. +Refer to the client-side stream interceptor section for a detailed +implementation and explanation. + +To install a stream interceptor on a Server, configure `NewServer` with the +[`StreamInterceptor`](https://godoc.org/google.golang.org/grpc#StreamInterceptor) +`ServerOption`. -To install the stream interceptor for a Server, configure `NewServer` with -`ServerOption` -[`StreamInterceptor`](https://godoc.org/google.golang.org/grpc#StreamInterceptor).