1 /*
2 *
3 * Copyright 2024 gRPC authors.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 */
18 19 package grpc
20 21 // ServerStreamingClient represents the client side of a server-streaming (one
22 // request, many responses) RPC. It is generic over the type of the response
23 // message. It is used in generated code.
24 type ServerStreamingClient[Res any] interface {
25 // Recv receives the next response message from the server. The client may
26 // repeatedly call Recv to read messages from the response stream. If
27 // io.EOF is returned, the stream has terminated with an OK status. Any
28 // other error is compatible with the status package and indicates the
29 // RPC's status code and message.
30 Recv() (*Res, error)
31 32 // ClientStream is embedded to provide Context, Header, and Trailer
33 // functionality. No other methods in the ClientStream should be called
34 // directly.
35 ClientStream
36 }
37 38 // ServerStreamingServer represents the server side of a server-streaming (one
39 // request, many responses) RPC. It is generic over the type of the response
40 // message. It is used in generated code.
41 //
42 // To terminate the response stream, return from the handler method and return
43 // an error from the status package, or use nil to indicate an OK status code.
44 type ServerStreamingServer[Res any] interface {
45 // Send sends a response message to the client. The server handler may
46 // call Send multiple times to send multiple messages to the client. An
47 // error is returned if the stream was terminated unexpectedly, and the
48 // handler method should return, as the stream is no longer usable.
49 Send(*Res) error
50 51 // ServerStream is embedded to provide Context, SetHeader, SendHeader, and
52 // SetTrailer functionality. No other methods in the ServerStream should
53 // be called directly.
54 ServerStream
55 }
56 57 // ClientStreamingClient represents the client side of a client-streaming (many
58 // requests, one response) RPC. It is generic over both the type of the request
59 // message stream and the type of the unary response message. It is used in
60 // generated code.
61 type ClientStreamingClient[Req any, Res any] interface {
62 // Send sends a request message to the server. The client may call Send
63 // multiple times to send multiple messages to the server. On error, Send
64 // aborts the stream. If the error was generated by the client, the status
65 // is returned directly. Otherwise, io.EOF is returned, and the status of
66 // the stream may be discovered using CloseAndRecv().
67 Send(*Req) error
68 69 // CloseAndRecv closes the request stream and waits for the server's
70 // response. This method must be called once and only once after sending
71 // all request messages. Any error returned is implemented by the status
72 // package.
73 CloseAndRecv() (*Res, error)
74 75 // ClientStream is embedded to provide Context, Header, and Trailer
76 // functionality. No other methods in the ClientStream should be called
77 // directly.
78 ClientStream
79 }
80 81 // ClientStreamingServer represents the server side of a client-streaming (many
82 // requests, one response) RPC. It is generic over both the type of the request
83 // message stream and the type of the unary response message. It is used in
84 // generated code.
85 //
86 // To terminate the RPC, call SendAndClose and return nil from the method
87 // handler or do not call SendAndClose and return an error from the status
88 // package.
89 type ClientStreamingServer[Req any, Res any] interface {
90 // Recv receives the next request message from the client. The server may
91 // repeatedly call Recv to read messages from the request stream. If
92 // io.EOF is returned, it indicates the client called CloseAndRecv on its
93 // ClientStreamingClient. Any other error indicates the stream was
94 // terminated unexpectedly, and the handler method should return, as the
95 // stream is no longer usable.
96 Recv() (*Req, error)
97 98 // SendAndClose sends a single response message to the client and closes
99 // the stream. This method must be called once and only once after all
100 // request messages have been processed. Recv should not be called after
101 // calling SendAndClose.
102 SendAndClose(*Res) error
103 104 // ServerStream is embedded to provide Context, SetHeader, SendHeader, and
105 // SetTrailer functionality. No other methods in the ServerStream should
106 // be called directly.
107 ServerStream
108 }
109 110 // BidiStreamingClient represents the client side of a bidirectional-streaming
111 // (many requests, many responses) RPC. It is generic over both the type of the
112 // request message stream and the type of the response message stream. It is
113 // used in generated code.
114 type BidiStreamingClient[Req any, Res any] interface {
115 // Send sends a request message to the server. The client may call Send
116 // multiple times to send multiple messages to the server. On error, Send
117 // aborts the stream. If the error was generated by the client, the status
118 // is returned directly. Otherwise, io.EOF is returned, and the status of
119 // the stream may be discovered using Recv().
120 Send(*Req) error
121 122 // Recv receives the next response message from the server. The client may
123 // repeatedly call Recv to read messages from the response stream. If
124 // io.EOF is returned, the stream has terminated with an OK status. Any
125 // other error is compatible with the status package and indicates the
126 // RPC's status code and message.
127 Recv() (*Res, error)
128 129 // ClientStream is embedded to provide Context, Header, Trailer, and
130 // CloseSend functionality. No other methods in the ClientStream should be
131 // called directly.
132 ClientStream
133 }
134 135 // BidiStreamingServer represents the server side of a bidirectional-streaming
136 // (many requests, many responses) RPC. It is generic over both the type of the
137 // request message stream and the type of the response message stream. It is
138 // used in generated code.
139 //
140 // To terminate the stream, return from the handler method and return
141 // an error from the status package, or use nil to indicate an OK status code.
142 type BidiStreamingServer[Req any, Res any] interface {
143 // Recv receives the next request message from the client. The server may
144 // repeatedly call Recv to read messages from the request stream. If
145 // io.EOF is returned, it indicates the client called CloseSend on its
146 // BidiStreamingClient. Any other error indicates the stream was
147 // terminated unexpectedly, and the handler method should return, as the
148 // stream is no longer usable.
149 Recv() (*Req, error)
150 151 // Send sends a response message to the client. The server handler may
152 // call Send multiple times to send multiple messages to the client. An
153 // error is returned if the stream was terminated unexpectedly, and the
154 // handler method should return, as the stream is no longer usable.
155 Send(*Res) error
156 157 // ServerStream is embedded to provide Context, SetHeader, SendHeader, and
158 // SetTrailer functionality. No other methods in the ServerStream should
159 // be called directly.
160 ServerStream
161 }
162 163 // GenericClientStream implements the ServerStreamingClient, ClientStreamingClient,
164 // and BidiStreamingClient interfaces. It is used in generated code.
165 type GenericClientStream[Req any, Res any] struct {
166 ClientStream
167 }
168 169 var _ ServerStreamingClient[string] = (*GenericClientStream[int, string])(nil)
170 var _ ClientStreamingClient[int, string] = (*GenericClientStream[int, string])(nil)
171 var _ BidiStreamingClient[int, string] = (*GenericClientStream[int, string])(nil)
172 173 // Send pushes one message into the stream of requests to be consumed by the
174 // server. The type of message which can be sent is determined by the Req type
175 // parameter of the GenericClientStream receiver.
176 func (x *GenericClientStream[Req, Res]) Send(m *Req) error {
177 return x.ClientStream.SendMsg(m)
178 }
179 180 // Recv reads one message from the stream of responses generated by the server.
181 // The type of the message returned is determined by the Res type parameter
182 // of the GenericClientStream receiver.
183 func (x *GenericClientStream[Req, Res]) Recv() (*Res, error) {
184 m := new(Res)
185 if err := x.ClientStream.RecvMsg(m); err != nil {
186 return nil, err
187 }
188 return m, nil
189 }
190 191 // CloseAndRecv closes the sending side of the stream, then receives the unary
192 // response from the server. The type of message which it returns is determined
193 // by the Res type parameter of the GenericClientStream receiver.
194 func (x *GenericClientStream[Req, Res]) CloseAndRecv() (*Res, error) {
195 if err := x.ClientStream.CloseSend(); err != nil {
196 return nil, err
197 }
198 m := new(Res)
199 if err := x.ClientStream.RecvMsg(m); err != nil {
200 return nil, err
201 }
202 return m, nil
203 }
204 205 // GenericServerStream implements the ServerStreamingServer, ClientStreamingServer,
206 // and BidiStreamingServer interfaces. It is used in generated code.
207 type GenericServerStream[Req any, Res any] struct {
208 ServerStream
209 }
210 211 var _ ServerStreamingServer[string] = (*GenericServerStream[int, string])(nil)
212 var _ ClientStreamingServer[int, string] = (*GenericServerStream[int, string])(nil)
213 var _ BidiStreamingServer[int, string] = (*GenericServerStream[int, string])(nil)
214 215 // Send pushes one message into the stream of responses to be consumed by the
216 // client. The type of message which can be sent is determined by the Res
217 // type parameter of the serverStreamServer receiver.
218 func (x *GenericServerStream[Req, Res]) Send(m *Res) error {
219 return x.ServerStream.SendMsg(m)
220 }
221 222 // SendAndClose pushes the unary response to the client. The type of message
223 // which can be sent is determined by the Res type parameter of the
224 // clientStreamServer receiver.
225 func (x *GenericServerStream[Req, Res]) SendAndClose(m *Res) error {
226 return x.ServerStream.SendMsg(m)
227 }
228 229 // Recv reads one message from the stream of requests generated by the client.
230 // The type of the message returned is determined by the Req type parameter
231 // of the clientStreamServer receiver.
232 func (x *GenericServerStream[Req, Res]) Recv() (*Req, error) {
233 m := new(Req)
234 if err := x.ServerStream.RecvMsg(m); err != nil {
235 return nil, err
236 }
237 return m, nil
238 }
239