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
19package 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.
24type 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.
44type 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.
61type 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.
89type 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.
114type 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.
142type 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.
165type GenericClientStream[Req any, Res any] struct {
166 ClientStream
167}
168
169var _ ServerStreamingClient[string] = (*GenericClientStream[int, string])(nil)
170var _ ClientStreamingClient[int, string] = (*GenericClientStream[int, string])(nil)
171var _ 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.
176func (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.
183func (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.
194func (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.
207type GenericServerStream[Req any, Res any] struct {
208 ServerStream
209}
210
211var _ ServerStreamingServer[string] = (*GenericServerStream[int, string])(nil)
212var _ ClientStreamingServer[int, string] = (*GenericServerStream[int, string])(nil)
213var _ 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.
218func (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.
225func (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.
232func (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}