Skip to content

Commit d0ebcdf

Browse files
easwarsdfawley
andauthored
examples: improve interceptor example with better markdown formatting (#8612)
This PR changes the existing example to use fenced code blocks instead of backticks to show the interceptor signatures. This greatly improves how the document is rendered. The PR also changes the word `overload` to `override` because it is the latter that we are showcasing here, and Go does not support overloading anyways. RELEASE NOTES: none --------- Co-authored-by: Doug Fawley <[email protected]>
1 parent 4e9b800 commit d0ebcdf

File tree

1 file changed

+28
-17
lines changed

1 file changed

+28
-17
lines changed

examples/features/interceptor/README.md

Lines changed: 28 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,14 @@ types of interceptors in total.
3030

3131
The type for client-side unary interceptors is
3232
[`UnaryClientInterceptor`](https://godoc.org/google.golang.org/grpc#UnaryClientInterceptor).
33-
It is essentially a function type with signature: `func(ctx context.Context,
34-
method string, req, reply interface{}, cc *ClientConn, invoker UnaryInvoker,
35-
opts ...CallOption) error`. Unary interceptor implementations can usually be
36-
divided into three parts: pre-processing, invoking the RPC method, and
37-
post-processing.
33+
It is a function type with signature:
34+
35+
```golang
36+
func(ctx context.Context, method string, req, reply interface{}, cc *ClientConn, invoker UnaryInvoker, opts ...CallOption) error
37+
```
38+
39+
Unary interceptor implementations can usually be divided into three parts:
40+
pre-processing, invoking the RPC method, and post-processing.
3841

3942
For pre-processing, users can get info about the current RPC call by examining
4043
the args passed in. The args include the RPC context, method string, request to
@@ -59,22 +62,26 @@ To install a unary interceptor on a ClientConn, configure `Dial` with the
5962

6063
The type for client-side stream interceptors is
6164
[`StreamClientInterceptor`](https://godoc.org/google.golang.org/grpc#StreamClientInterceptor).
62-
It is a function type with signature: `func(ctx context.Context, desc
63-
*StreamDesc, cc *ClientConn, method string, streamer Streamer, opts
64-
...CallOption) (ClientStream, error)`. An implementation of a stream interceptor
65-
usually includes pre-processing, and stream operation interception.
65+
It is a function type with signature:
66+
67+
```golang
68+
func(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, streamer Streamer, opts ...CallOption) (ClientStream, error)
69+
```
70+
71+
An implementation of a stream interceptor usually includes pre-processing, and
72+
stream operation interception.
6673

6774
The pre-processing is similar to unary interceptors.
6875

6976
However, rather than invoking the RPC method followed by post-processing, stream
7077
interceptors intercept the users' operations on the stream. The interceptor
7178
first calls the passed-in `streamer` to get a `ClientStream`, and then wraps the
72-
`ClientStream` while overloading its methods with the interception logic.
79+
`ClientStream` while overriding its methods with the interception logic.
7380
Finally, the interceptor returns the wrapped `ClientStream` to user to operate
7481
on.
7582

7683
In the example, we define a new struct `wrappedStream`, which embeds a
77-
`ClientStream`. We then implement (overload) the `SendMsg` and `RecvMsg` methods
84+
`ClientStream`. We then implement (override) the `SendMsg` and `RecvMsg` methods
7885
on `wrappedStream` to intercept these two operations on the embedded
7986
`ClientStream`. In the example, we log the message type info and time info for
8087
interception purpose.
@@ -92,9 +99,11 @@ different information provided as args.
9299

93100
The type for server-side unary interceptors is
94101
[`UnaryServerInterceptor`](https://godoc.org/google.golang.org/grpc#UnaryServerInterceptor).
95-
It is a function type with signature: `func(ctx context.Context, req
96-
interface{}, info *UnaryServerInfo, handler UnaryHandler) (resp interface{}, err
97-
error)`.
102+
It is a function type with signature:
103+
104+
```golang
105+
func(ctx context.Context, req interface{}, info *UnaryServerInfo, handler UnaryHandler) (resp interface{}, err error)
106+
```
98107

99108
Refer to the client-side unary interceptor section for a detailed implementation
100109
and explanation.
@@ -107,13 +116,15 @@ To install a unary interceptor on a Server, configure `NewServer` with the
107116

108117
The type for server-side stream interceptors is
109118
[`StreamServerInterceptor`](https://godoc.org/google.golang.org/grpc#StreamServerInterceptor).
110-
It is a function type with the signature: `func(srv interface{}, ss
111-
ServerStream, info *StreamServerInfo, handler StreamHandler) error`.
119+
It is a function type with the signature:
120+
121+
```golang
122+
func(srv interface{}, ss ServerStream, info *StreamServerInfo, handler StreamHandler) error
123+
```
112124

113125
Refer to the client-side stream interceptor section for a detailed
114126
implementation and explanation.
115127

116128
To install a stream interceptor on a Server, configure `NewServer` with the
117129
[`StreamInterceptor`](https://godoc.org/google.golang.org/grpc#StreamInterceptor)
118130
`ServerOption`.
119-

0 commit comments

Comments
 (0)