Debian Codegraph @

third_party/spirv-tools/utils/vscode/src/lsp/jsonrpc2/jsonrpc2.go

raw
1 // Copyright 2018 The Go Authors.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 // Package jsonrpc2 is a minimal implementation of the JSON RPC 2 spec.
16 // https://www.jsonrpc.org/specification
17 // It is intended to be compatible with other implementations at the wire level.
18 package jsonrpc2
19
20 import (
21 "context"
22 "encoding/json"
23 "fmt"
24 "sync"
25 "sync/atomic"
26 )
27
28 // Conn is a JSON RPC 2 client server connection.
29 // Conn is bidirectional; it does not have a designated server or client end.
30 type Conn struct {
31 seq int64 // must only be accessed using atomic operations
32 handlers []Handler
33 stream Stream
34 err error
35 pendingMu sync.Mutex // protects the pending map
36 pending map[ID]chan *WireResponse
37 handlingMu sync.Mutex // protects the handling map
38 handling map[ID]*Request
39 }
40
41 type requestState int
42
43 const (
44 requestWaiting = requestState(iota)
45 requestSerial
46 requestParallel
47 requestReplied
48 requestDone
49 )
50
51 // Request is sent to a server to represent a Call or Notify operaton.
52 type Request struct {
53 conn *Conn
54 cancel context.CancelFunc
55 state requestState
56 nextRequest chan struct{}
57
58 // The Wire values of the request.
59 WireRequest
60 }
61
62 // NewErrorf builds a Error struct for the supplied message and code.
63 // If args is not empty, message and args will be passed to Sprintf.
64 func NewErrorf(code int64, format string, args ...interface{}) *Error {
65 return &Error{
66 Code: code,
67 Message: fmt.Sprintf(format, args...),
68 }
69 }
70
71 // NewConn creates a new connection object around the supplied stream.
72 // You must call Run for the connection to be active.
73 func NewConn(s Stream) *Conn {
74 conn := &Conn{
75 handlers: []Handler{defaultHandler{}},
76 stream: s,
77 pending: make(map[ID]chan *WireResponse),
78 handling: make(map[ID]*Request),
79 }
80 return conn
81 }
82
83 // AddHandler adds a new handler to the set the connection will invoke.
84 // Handlers are invoked in the reverse order of how they were added, this
85 // allows the most recent addition to be the first one to attempt to handle a
86 // message.
87 func (c *Conn) AddHandler(handler Handler) {
88 // prepend the new handlers so we use them first
89 c.handlers = append([]Handler{handler}, c.handlers...)
90 }
91
92 // Cancel cancels a pending Call on the server side.
93 // The call is identified by its id.
94 // JSON RPC 2 does not specify a cancel message, so cancellation support is not
95 // directly wired in. This method allows a higher level protocol to choose how
96 // to propagate the cancel.
97 func (c *Conn) Cancel(id ID) {
98 c.handlingMu.Lock()
99 handling, found := c.handling[id]
100 c.handlingMu.Unlock()
101 if found {
102 handling.cancel()
103 }
104 }
105
106 // Notify is called to send a notification request over the connection.
107 // It will return as soon as the notification has been sent, as no response is
108 // possible.
109 func (c *Conn) Notify(ctx context.Context, method string, params interface{}) (err error) {
110 jsonParams, err := marshalToRaw(params)
111 if err != nil {
112 return fmt.Errorf("marshalling notify parameters: %v", err)
113 }
114 request := &WireRequest{
115 Method: method,
116 Params: jsonParams,
117 }
118 data, err := json.Marshal(request)
119 if err != nil {
120 return fmt.Errorf("marshalling notify request: %v", err)
121 }
122 for _, h := range c.handlers {
123 ctx = h.Request(ctx, c, Send, request)
124 }
125 defer func() {
126 for _, h := range c.handlers {
127 h.Done(ctx, err)
128 }
129 }()
130 n, err := c.stream.Write(ctx, data)
131 for _, h := range c.handlers {
132 ctx = h.Wrote(ctx, n)
133 }
134 return err
135 }
136
137 // Call sends a request over the connection and then waits for a response.
138 // If the response is not an error, it will be decoded into result.
139 // result must be of a type you an pass to json.Unmarshal.
140 func (c *Conn) Call(ctx context.Context, method string, params, result interface{}) (err error) {
141 // generate a new request identifier
142 id := ID{Number: atomic.AddInt64(&c.seq, 1)}
143 jsonParams, err := marshalToRaw(params)
144 if err != nil {
145 return fmt.Errorf("marshalling call parameters: %v", err)
146 }
147 request := &WireRequest{
148 ID: &id,
149 Method: method,
150 Params: jsonParams,
151 }
152 // marshal the request now it is complete
153 data, err := json.Marshal(request)
154 if err != nil {
155 return fmt.Errorf("marshalling call request: %v", err)
156 }
157 for _, h := range c.handlers {
158 ctx = h.Request(ctx, c, Send, request)
159 }
160 // we have to add ourselves to the pending map before we send, otherwise we
161 // are racing the response
162 rchan := make(chan *WireResponse)
163 c.pendingMu.Lock()
164 c.pending[id] = rchan
165 c.pendingMu.Unlock()
166 defer func() {
167 // clean up the pending response handler on the way out
168 c.pendingMu.Lock()
169 delete(c.pending, id)
170 c.pendingMu.Unlock()
171 for _, h := range c.handlers {
172 h.Done(ctx, err)
173 }
174 }()
175 // now we are ready to send
176 n, err := c.stream.Write(ctx, data)
177 for _, h := range c.handlers {
178 ctx = h.Wrote(ctx, n)
179 }
180 if err != nil {
181 // sending failed, we will never get a response, so don't leave it pending
182 return err
183 }
184 // now wait for the response
185 select {
186 case response := <-rchan:
187 for _, h := range c.handlers {
188 ctx = h.Response(ctx, c, Receive, response)
189 }
190 // is it an error response?
191 if response.Error != nil {
192 return response.Error
193 }
194 if result == nil || response.Result == nil {
195 return nil
196 }
197 if err := json.Unmarshal(*response.Result, result); err != nil {
198 return fmt.Errorf("unmarshalling result: %v", err)
199 }
200 return nil
201 case <-ctx.Done():
202 // allow the handler to propagate the cancel
203 cancelled := false
204 for _, h := range c.handlers {
205 if h.Cancel(ctx, c, id, cancelled) {
206 cancelled = true
207 }
208 }
209 return ctx.Err()
210 }
211 }
212
213 // Conn returns the connection that created this request.
214 func (r *Request) Conn() *Conn { return r.conn }
215
216 // IsNotify returns true if this request is a notification.
217 func (r *Request) IsNotify() bool {
218 return r.ID == nil
219 }
220
221 // Parallel indicates that the system is now allowed to process other requests
222 // in parallel with this one.
223 // It is safe to call any number of times, but must only be called from the
224 // request handling go routine.
225 // It is implied by both reply and by the handler returning.
226 func (r *Request) Parallel() {
227 if r.state >= requestParallel {
228 return
229 }
230 r.state = requestParallel
231 close(r.nextRequest)
232 }
233
234 // Reply sends a reply to the given request.
235 // It is an error to call this if request was not a call.
236 // You must call this exactly once for any given request.
237 // It should only be called from the handler go routine.
238 // If err is set then result will be ignored.
239 // If the request has not yet dropped into parallel mode
240 // it will be before this function returns.
241 func (r *Request) Reply(ctx context.Context, result interface{}, err error) error {
242 if r.state >= requestReplied {
243 return fmt.Errorf("reply invoked more than once")
244 }
245 if r.IsNotify() {
246 return fmt.Errorf("reply not invoked with a valid call")
247 }
248 // reply ends the handling phase of a call, so if we are not yet
249 // parallel we should be now. The go routine is allowed to continue
250 // to do work after replying, which is why it is important to unlock
251 // the rpc system at this point.
252 r.Parallel()
253 r.state = requestReplied
254
255 var raw *json.RawMessage
256 if err == nil {
257 raw, err = marshalToRaw(result)
258 }
259 response := &WireResponse{
260 Result: raw,
261 ID: r.ID,
262 }
263 if err != nil {
264 if callErr, ok := err.(*Error); ok {
265 response.Error = callErr
266 } else {
267 response.Error = NewErrorf(0, "%s", err)
268 }
269 }
270 data, err := json.Marshal(response)
271 if err != nil {
272 return err
273 }
274 for _, h := range r.conn.handlers {
275 ctx = h.Response(ctx, r.conn, Send, response)
276 }
277 n, err := r.conn.stream.Write(ctx, data)
278 for _, h := range r.conn.handlers {
279 ctx = h.Wrote(ctx, n)
280 }
281
282 if err != nil {
283 // TODO(iancottrell): if a stream write fails, we really need to shut down
284 // the whole stream
285 return err
286 }
287 return nil
288 }
289
290 func (c *Conn) setHandling(r *Request, active bool) {
291 if r.ID == nil {
292 return
293 }
294 r.conn.handlingMu.Lock()
295 defer r.conn.handlingMu.Unlock()
296 if active {
297 r.conn.handling[*r.ID] = r
298 } else {
299 delete(r.conn.handling, *r.ID)
300 }
301 }
302
303 // combined has all the fields of both Request and Response.
304 // We can decode this and then work out which it is.
305 type combined struct {
306 VersionTag VersionTag `json:"jsonrpc"`
307 ID *ID `json:"id,omitempty"`
308 Method string `json:"method"`
309 Params *json.RawMessage `json:"params,omitempty"`
310 Result *json.RawMessage `json:"result,omitempty"`
311 Error *Error `json:"error,omitempty"`
312 }
313
314 // Run blocks until the connection is terminated, and returns any error that
315 // caused the termination.
316 // It must be called exactly once for each Conn.
317 // It returns only when the reader is closed or there is an error in the stream.
318 func (c *Conn) Run(runCtx context.Context) error {
319 // we need to make the next request "lock" in an unlocked state to allow
320 // the first incoming request to proceed. All later requests are unlocked
321 // by the preceding request going to parallel mode.
322 nextRequest := make(chan struct{})
323 close(nextRequest)
324 for {
325 // get the data for a message
326 data, n, err := c.stream.Read(runCtx)
327 if err != nil {
328 // the stream failed, we cannot continue
329 return err
330 }
331 // read a combined message
332 msg := &combined{}
333 if err := json.Unmarshal(data, msg); err != nil {
334 // a badly formed message arrived, log it and continue
335 // we trust the stream to have isolated the error to just this message
336 for _, h := range c.handlers {
337 h.Error(runCtx, fmt.Errorf("unmarshal failed: %v", err))
338 }
339 continue
340 }
341 // work out which kind of message we have
342 switch {
343 case msg.Method != "":
344 // if method is set it must be a request
345 reqCtx, cancelReq := context.WithCancel(runCtx)
346 thisRequest := nextRequest
347 nextRequest = make(chan struct{})
348 req := &Request{
349 conn: c,
350 cancel: cancelReq,
351 nextRequest: nextRequest,
352 WireRequest: WireRequest{
353 VersionTag: msg.VersionTag,
354 Method: msg.Method,
355 Params: msg.Params,
356 ID: msg.ID,
357 },
358 }
359 for _, h := range c.handlers {
360 reqCtx = h.Request(reqCtx, c, Receive, &req.WireRequest)
361 reqCtx = h.Read(reqCtx, n)
362 }
363 c.setHandling(req, true)
364 go func() {
365 <-thisRequest
366 req.state = requestSerial
367 defer func() {
368 c.setHandling(req, false)
369 if !req.IsNotify() && req.state < requestReplied {
370 req.Reply(reqCtx, nil, NewErrorf(CodeInternalError, "method %q did not reply", req.Method))
371 }
372 req.Parallel()
373 for _, h := range c.handlers {
374 h.Done(reqCtx, err)
375 }
376 cancelReq()
377 }()
378 delivered := false
379 for _, h := range c.handlers {
380 if h.Deliver(reqCtx, req, delivered) {
381 delivered = true
382 }
383 }
384 }()
385 case msg.ID != nil:
386 // we have a response, get the pending entry from the map
387 c.pendingMu.Lock()
388 rchan := c.pending[*msg.ID]
389 if rchan != nil {
390 delete(c.pending, *msg.ID)
391 }
392 c.pendingMu.Unlock()
393 // and send the reply to the channel
394 response := &WireResponse{
395 Result: msg.Result,
396 Error: msg.Error,
397 ID: msg.ID,
398 }
399 rchan <- response
400 close(rchan)
401 default:
402 for _, h := range c.handlers {
403 h.Error(runCtx, fmt.Errorf("message not a call, notify or response, ignoring"))
404 }
405 }
406 }
407 }
408
409 func marshalToRaw(obj interface{}) (*json.RawMessage, error) {
410 data, err := json.Marshal(obj)
411 if err != nil {
412 return nil, err
413 }
414 raw := json.RawMessage(data)
415 return &raw, nil
416 }