github.com/devkononov/go-func@v0.0.0-20190722084534-f14392d369a7/rpc/client.go (about) 1 // Copyright 2016 The go-ethereum Authors 2 // This file is part of the go-ethereum library. 3 // 4 // The go-ethereum library is free software: you can redistribute it and/or modify 5 // it under the terms of the GNU Lesser General Public License as published by 6 // the Free Software Foundation, either version 3 of the License, or 7 // (at your option) any later version. 8 // 9 // The go-ethereum library is distributed in the hope that it will be useful, 10 // but WITHOUT ANY WARRANTY; without even the implied warranty of 11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 // GNU Lesser General Public License for more details. 13 // 14 // You should have received a copy of the GNU Lesser General Public License 15 // along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>. 16 17 package rpc 18 19 import ( 20 "bytes" 21 "context" 22 "encoding/json" 23 "errors" 24 "fmt" 25 "net/url" 26 "reflect" 27 "strconv" 28 "sync/atomic" 29 "time" 30 31 "github.com/ethereum/go-ethereum/log" 32 ) 33 34 var ( 35 ErrClientQuit = errors.New("client is closed") 36 ErrNoResult = errors.New("no result in JSON-RPC response") 37 ErrSubscriptionQueueOverflow = errors.New("subscription queue overflow") 38 errClientReconnected = errors.New("client reconnected") 39 errDead = errors.New("connection lost") 40 ) 41 42 const ( 43 // Timeouts 44 tcpKeepAliveInterval = 30 * time.Second 45 defaultDialTimeout = 10 * time.Second // used if context has no deadline 46 subscribeTimeout = 5 * time.Second // overall timeout eth_subscribe, rpc_modules calls 47 ) 48 49 const ( 50 // Subscriptions are removed when the subscriber cannot keep up. 51 // 52 // This can be worked around by supplying a channel with sufficiently sized buffer, 53 // but this can be inconvenient and hard to explain in the docs. Another issue with 54 // buffered channels is that the buffer is static even though it might not be needed 55 // most of the time. 56 // 57 // The approach taken here is to maintain a per-subscription linked list buffer 58 // shrinks on demand. If the buffer reaches the size below, the subscription is 59 // dropped. 60 maxClientSubscriptionBuffer = 20000 61 ) 62 63 // BatchElem is an element in a batch request. 64 type BatchElem struct { 65 Method string 66 Args []interface{} 67 // The result is unmarshaled into this field. Result must be set to a 68 // non-nil pointer value of the desired type, otherwise the response will be 69 // discarded. 70 Result interface{} 71 // Error is set if the server returns an error for this request, or if 72 // unmarshaling into Result fails. It is not set for I/O errors. 73 Error error 74 } 75 76 // Client represents a connection to an RPC server. 77 type Client struct { 78 idgen func() ID // for subscriptions 79 isHTTP bool 80 services *serviceRegistry 81 82 idCounter uint32 83 84 // This function, if non-nil, is called when the connection is lost. 85 reconnectFunc reconnectFunc 86 87 // writeConn is used for writing to the connection on the caller's goroutine. It should 88 // only be accessed outside of dispatch, with the write lock held. The write lock is 89 // taken by sending on requestOp and released by sending on sendDone. 90 writeConn jsonWriter 91 92 // for dispatch 93 close chan struct{} 94 closing chan struct{} // closed when client is quitting 95 didClose chan struct{} // closed when client quits 96 reconnected chan ServerCodec // where write/reconnect sends the new connection 97 readOp chan readOp // read messages 98 readErr chan error // errors from read 99 reqInit chan *requestOp // register response IDs, takes write lock 100 reqSent chan error // signals write completion, releases write lock 101 reqTimeout chan *requestOp // removes response IDs when call timeout expires 102 } 103 104 type reconnectFunc func(ctx context.Context) (ServerCodec, error) 105 106 type clientContextKey struct{} 107 108 type clientConn struct { 109 codec ServerCodec 110 handler *handler 111 } 112 113 func (c *Client) newClientConn(conn ServerCodec) *clientConn { 114 ctx := context.WithValue(context.Background(), clientContextKey{}, c) 115 handler := newHandler(ctx, conn, c.idgen, c.services) 116 return &clientConn{conn, handler} 117 } 118 119 func (cc *clientConn) close(err error, inflightReq *requestOp) { 120 cc.handler.close(err, inflightReq) 121 cc.codec.Close() 122 } 123 124 type readOp struct { 125 msgs []*jsonrpcMessage 126 batch bool 127 } 128 129 type requestOp struct { 130 ids []json.RawMessage 131 err error 132 resp chan *jsonrpcMessage // receives up to len(ids) responses 133 sub *ClientSubscription // only set for EthSubscribe requests 134 } 135 136 func (op *requestOp) wait(ctx context.Context, c *Client) (*jsonrpcMessage, error) { 137 select { 138 case <-ctx.Done(): 139 // Send the timeout to dispatch so it can remove the request IDs. 140 if !c.isHTTP { 141 select { 142 case c.reqTimeout <- op: 143 case <-c.closing: 144 } 145 } 146 return nil, ctx.Err() 147 case resp := <-op.resp: 148 return resp, op.err 149 } 150 } 151 152 // Dial creates a new client for the given URL. 153 // 154 // The currently supported URL schemes are "http", "https", "ws" and "wss". If rawurl is a 155 // file name with no URL scheme, a local socket connection is established using UNIX 156 // domain sockets on supported platforms and named pipes on Windows. If you want to 157 // configure transport options, use DialHTTP, DialWebsocket or DialIPC instead. 158 // 159 // For websocket connections, the origin is set to the local host name. 160 // 161 // The client reconnects automatically if the connection is lost. 162 func Dial(rawurl string) (*Client, error) { 163 return DialContext(context.Background(), rawurl) 164 } 165 166 // DialContext creates a new RPC client, just like Dial. 167 // 168 // The context is used to cancel or time out the initial connection establishment. It does 169 // not affect subsequent interactions with the client. 170 func DialContext(ctx context.Context, rawurl string) (*Client, error) { 171 u, err := url.Parse(rawurl) 172 if err != nil { 173 return nil, err 174 } 175 switch u.Scheme { 176 case "http", "https": 177 return DialHTTP(rawurl) 178 case "ws", "wss": 179 return DialWebsocket(ctx, rawurl, "") 180 case "stdio": 181 return DialStdIO(ctx) 182 case "": 183 return DialIPC(ctx, rawurl) 184 default: 185 return nil, fmt.Errorf("no known transport for URL scheme %q", u.Scheme) 186 } 187 } 188 189 // Client retrieves the client from the context, if any. This can be used to perform 190 // 'reverse calls' in a handler method. 191 func ClientFromContext(ctx context.Context) (*Client, bool) { 192 client, ok := ctx.Value(clientContextKey{}).(*Client) 193 return client, ok 194 } 195 196 func newClient(initctx context.Context, connect reconnectFunc) (*Client, error) { 197 conn, err := connect(initctx) 198 if err != nil { 199 return nil, err 200 } 201 c := initClient(conn, randomIDGenerator(), new(serviceRegistry)) 202 c.reconnectFunc = connect 203 return c, nil 204 } 205 206 func initClient(conn ServerCodec, idgen func() ID, services *serviceRegistry) *Client { 207 _, isHTTP := conn.(*httpConn) 208 c := &Client{ 209 idgen: idgen, 210 isHTTP: isHTTP, 211 services: services, 212 writeConn: conn, 213 close: make(chan struct{}), 214 closing: make(chan struct{}), 215 didClose: make(chan struct{}), 216 reconnected: make(chan ServerCodec), 217 readOp: make(chan readOp), 218 readErr: make(chan error), 219 reqInit: make(chan *requestOp), 220 reqSent: make(chan error, 1), 221 reqTimeout: make(chan *requestOp), 222 } 223 if !isHTTP { 224 go c.dispatch(conn) 225 } 226 return c 227 } 228 229 // RegisterName creates a service for the given receiver type under the given name. When no 230 // methods on the given receiver match the criteria to be either a RPC method or a 231 // subscription an error is returned. Otherwise a new service is created and added to the 232 // service collection this client provides to the server. 233 func (c *Client) RegisterName(name string, receiver interface{}) error { 234 return c.services.registerName(name, receiver) 235 } 236 237 func (c *Client) nextID() json.RawMessage { 238 id := atomic.AddUint32(&c.idCounter, 1) 239 return strconv.AppendUint(nil, uint64(id), 10) 240 } 241 242 // SupportedModules calls the rpc_modules method, retrieving the list of 243 // APIs that are available on the server. 244 func (c *Client) SupportedModules() (map[string]string, error) { 245 var result map[string]string 246 ctx, cancel := context.WithTimeout(context.Background(), subscribeTimeout) 247 defer cancel() 248 err := c.CallContext(ctx, &result, "rpc_modules") 249 return result, err 250 } 251 252 // Close closes the client, aborting any in-flight requests. 253 func (c *Client) Close() { 254 if c.isHTTP { 255 return 256 } 257 select { 258 case c.close <- struct{}{}: 259 <-c.didClose 260 case <-c.didClose: 261 } 262 } 263 264 // Call performs a JSON-RPC call with the given arguments and unmarshals into 265 // result if no error occurred. 266 // 267 // The result must be a pointer so that package json can unmarshal into it. You 268 // can also pass nil, in which case the result is ignored. 269 func (c *Client) Call(result interface{}, method string, args ...interface{}) error { 270 ctx := context.Background() 271 return c.CallContext(ctx, result, method, args...) 272 } 273 274 // CallContext performs a JSON-RPC call with the given arguments. If the context is 275 // canceled before the call has successfully returned, CallContext returns immediately. 276 // 277 // The result must be a pointer so that package json can unmarshal into it. You 278 // can also pass nil, in which case the result is ignored. 279 func (c *Client) CallContext(ctx context.Context, result interface{}, method string, args ...interface{}) error { 280 msg, err := c.newMessage(method, args...) 281 if err != nil { 282 return err 283 } 284 op := &requestOp{ids: []json.RawMessage{msg.ID}, resp: make(chan *jsonrpcMessage, 1)} 285 286 if c.isHTTP { 287 err = c.sendHTTP(ctx, op, msg) 288 } else { 289 err = c.send(ctx, op, msg) 290 } 291 if err != nil { 292 return err 293 } 294 295 // dispatch has accepted the request and will close the channel when it quits. 296 switch resp, err := op.wait(ctx, c); { 297 case err != nil: 298 return err 299 case resp.Error != nil: 300 return resp.Error 301 case len(resp.Result) == 0: 302 return ErrNoResult 303 default: 304 return json.Unmarshal(resp.Result, &result) 305 } 306 } 307 308 // BatchCall sends all given requests as a single batch and waits for the server 309 // to return a response for all of them. 310 // 311 // In contrast to Call, BatchCall only returns I/O errors. Any error specific to 312 // a request is reported through the Error field of the corresponding BatchElem. 313 // 314 // Note that batch calls may not be executed atomically on the server side. 315 func (c *Client) BatchCall(b []BatchElem) error { 316 ctx := context.Background() 317 return c.BatchCallContext(ctx, b) 318 } 319 320 // BatchCall sends all given requests as a single batch and waits for the server 321 // to return a response for all of them. The wait duration is bounded by the 322 // context's deadline. 323 // 324 // In contrast to CallContext, BatchCallContext only returns errors that have occurred 325 // while sending the request. Any error specific to a request is reported through the 326 // Error field of the corresponding BatchElem. 327 // 328 // Note that batch calls may not be executed atomically on the server side. 329 func (c *Client) BatchCallContext(ctx context.Context, b []BatchElem) error { 330 msgs := make([]*jsonrpcMessage, len(b)) 331 op := &requestOp{ 332 ids: make([]json.RawMessage, len(b)), 333 resp: make(chan *jsonrpcMessage, len(b)), 334 } 335 for i, elem := range b { 336 msg, err := c.newMessage(elem.Method, elem.Args...) 337 if err != nil { 338 return err 339 } 340 msgs[i] = msg 341 op.ids[i] = msg.ID 342 } 343 344 var err error 345 if c.isHTTP { 346 err = c.sendBatchHTTP(ctx, op, msgs) 347 } else { 348 err = c.send(ctx, op, msgs) 349 } 350 351 // Wait for all responses to come back. 352 for n := 0; n < len(b) && err == nil; n++ { 353 var resp *jsonrpcMessage 354 resp, err = op.wait(ctx, c) 355 if err != nil { 356 break 357 } 358 // Find the element corresponding to this response. 359 // The element is guaranteed to be present because dispatch 360 // only sends valid IDs to our channel. 361 var elem *BatchElem 362 for i := range msgs { 363 if bytes.Equal(msgs[i].ID, resp.ID) { 364 elem = &b[i] 365 break 366 } 367 } 368 if resp.Error != nil { 369 elem.Error = resp.Error 370 continue 371 } 372 if len(resp.Result) == 0 { 373 elem.Error = ErrNoResult 374 continue 375 } 376 elem.Error = json.Unmarshal(resp.Result, elem.Result) 377 } 378 return err 379 } 380 381 // Notify sends a notification, i.e. a method call that doesn't expect a response. 382 func (c *Client) Notify(ctx context.Context, method string, args ...interface{}) error { 383 op := new(requestOp) 384 msg, err := c.newMessage(method, args...) 385 if err != nil { 386 return err 387 } 388 msg.ID = nil 389 390 if c.isHTTP { 391 return c.sendHTTP(ctx, op, msg) 392 } else { 393 return c.send(ctx, op, msg) 394 } 395 } 396 397 // EthSubscribe registers a subscripion under the "eth" namespace. 398 func (c *Client) EthSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error) { 399 return c.Subscribe(ctx, "eth", channel, args...) 400 } 401 402 // ShhSubscribe registers a subscripion under the "shh" namespace. 403 func (c *Client) ShhSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error) { 404 return c.Subscribe(ctx, "shh", channel, args...) 405 } 406 407 // Subscribe calls the "<namespace>_subscribe" method with the given arguments, 408 // registering a subscription. Server notifications for the subscription are 409 // sent to the given channel. The element type of the channel must match the 410 // expected type of content returned by the subscription. 411 // 412 // The context argument cancels the RPC request that sets up the subscription but has no 413 // effect on the subscription after Subscribe has returned. 414 // 415 // Slow subscribers will be dropped eventually. Client buffers up to 20000 notifications 416 // before considering the subscriber dead. The subscription Err channel will receive 417 // ErrSubscriptionQueueOverflow. Use a sufficiently large buffer on the channel or ensure 418 // that the channel usually has at least one reader to prevent this issue. 419 func (c *Client) Subscribe(ctx context.Context, namespace string, channel interface{}, args ...interface{}) (*ClientSubscription, error) { 420 // Check type of channel first. 421 chanVal := reflect.ValueOf(channel) 422 if chanVal.Kind() != reflect.Chan || chanVal.Type().ChanDir()&reflect.SendDir == 0 { 423 panic("first argument to Subscribe must be a writable channel") 424 } 425 if chanVal.IsNil() { 426 panic("channel given to Subscribe must not be nil") 427 } 428 if c.isHTTP { 429 return nil, ErrNotificationsUnsupported 430 } 431 432 msg, err := c.newMessage(namespace+subscribeMethodSuffix, args...) 433 if err != nil { 434 return nil, err 435 } 436 op := &requestOp{ 437 ids: []json.RawMessage{msg.ID}, 438 resp: make(chan *jsonrpcMessage), 439 sub: newClientSubscription(c, namespace, chanVal), 440 } 441 442 // Send the subscription request. 443 // The arrival and validity of the response is signaled on sub.quit. 444 if err := c.send(ctx, op, msg); err != nil { 445 return nil, err 446 } 447 if _, err := op.wait(ctx, c); err != nil { 448 return nil, err 449 } 450 return op.sub, nil 451 } 452 453 func (c *Client) newMessage(method string, paramsIn ...interface{}) (*jsonrpcMessage, error) { 454 msg := &jsonrpcMessage{Version: vsn, ID: c.nextID(), Method: method} 455 if paramsIn != nil { // prevent sending "params":null 456 var err error 457 if msg.Params, err = json.Marshal(paramsIn); err != nil { 458 return nil, err 459 } 460 } 461 return msg, nil 462 } 463 464 // send registers op with the dispatch loop, then sends msg on the connection. 465 // if sending fails, op is deregistered. 466 func (c *Client) send(ctx context.Context, op *requestOp, msg interface{}) error { 467 select { 468 case c.reqInit <- op: 469 err := c.write(ctx, msg) 470 c.reqSent <- err 471 return err 472 case <-ctx.Done(): 473 // This can happen if the client is overloaded or unable to keep up with 474 // subscription notifications. 475 return ctx.Err() 476 case <-c.closing: 477 return ErrClientQuit 478 } 479 } 480 481 func (c *Client) write(ctx context.Context, msg interface{}) error { 482 // The previous write failed. Try to establish a new connection. 483 if c.writeConn == nil { 484 if err := c.reconnect(ctx); err != nil { 485 return err 486 } 487 } 488 err := c.writeConn.Write(ctx, msg) 489 if err != nil { 490 c.writeConn = nil 491 } 492 return err 493 } 494 495 func (c *Client) reconnect(ctx context.Context) error { 496 if c.reconnectFunc == nil { 497 return errDead 498 } 499 500 if _, ok := ctx.Deadline(); !ok { 501 var cancel func() 502 ctx, cancel = context.WithTimeout(ctx, defaultDialTimeout) 503 defer cancel() 504 } 505 newconn, err := c.reconnectFunc(ctx) 506 if err != nil { 507 log.Trace("RPC client reconnect failed", "err", err) 508 return err 509 } 510 select { 511 case c.reconnected <- newconn: 512 c.writeConn = newconn 513 return nil 514 case <-c.didClose: 515 newconn.Close() 516 return ErrClientQuit 517 } 518 } 519 520 // dispatch is the main loop of the client. 521 // It sends read messages to waiting calls to Call and BatchCall 522 // and subscription notifications to registered subscriptions. 523 func (c *Client) dispatch(codec ServerCodec) { 524 var ( 525 lastOp *requestOp // tracks last send operation 526 reqInitLock = c.reqInit // nil while the send lock is held 527 conn = c.newClientConn(codec) 528 reading = true 529 ) 530 defer func() { 531 close(c.closing) 532 if reading { 533 conn.close(ErrClientQuit, nil) 534 c.drainRead() 535 } 536 close(c.didClose) 537 }() 538 539 // Spawn the initial read loop. 540 go c.read(codec) 541 542 for { 543 select { 544 case <-c.close: 545 return 546 547 // Read path: 548 case op := <-c.readOp: 549 if op.batch { 550 conn.handler.handleBatch(op.msgs) 551 } else { 552 conn.handler.handleMsg(op.msgs[0]) 553 } 554 555 case err := <-c.readErr: 556 conn.handler.log.Debug("RPC connection read error", "err", err) 557 conn.close(err, lastOp) 558 reading = false 559 560 // Reconnect: 561 case newcodec := <-c.reconnected: 562 log.Debug("RPC client reconnected", "reading", reading, "conn", newcodec.RemoteAddr()) 563 if reading { 564 // Wait for the previous read loop to exit. This is a rare case which 565 // happens if this loop isn't notified in time after the connection breaks. 566 // In those cases the caller will notice first and reconnect. Closing the 567 // handler terminates all waiting requests (closing op.resp) except for 568 // lastOp, which will be transferred to the new handler. 569 conn.close(errClientReconnected, lastOp) 570 c.drainRead() 571 } 572 go c.read(newcodec) 573 reading = true 574 conn = c.newClientConn(newcodec) 575 // Re-register the in-flight request on the new handler 576 // because that's where it will be sent. 577 conn.handler.addRequestOp(lastOp) 578 579 // Send path: 580 case op := <-reqInitLock: 581 // Stop listening for further requests until the current one has been sent. 582 reqInitLock = nil 583 lastOp = op 584 conn.handler.addRequestOp(op) 585 586 case err := <-c.reqSent: 587 if err != nil { 588 // Remove response handlers for the last send. When the read loop 589 // goes down, it will signal all other current operations. 590 conn.handler.removeRequestOp(lastOp) 591 } 592 // Let the next request in. 593 reqInitLock = c.reqInit 594 lastOp = nil 595 596 case op := <-c.reqTimeout: 597 conn.handler.removeRequestOp(op) 598 } 599 } 600 } 601 602 // drainRead drops read messages until an error occurs. 603 func (c *Client) drainRead() { 604 for { 605 select { 606 case <-c.readOp: 607 case <-c.readErr: 608 return 609 } 610 } 611 } 612 613 // read decodes RPC messages from a codec, feeding them into dispatch. 614 func (c *Client) read(codec ServerCodec) { 615 for { 616 msgs, batch, err := codec.Read() 617 if _, ok := err.(*json.SyntaxError); ok { 618 codec.Write(context.Background(), errorMessage(&parseError{err.Error()})) 619 } 620 if err != nil { 621 c.readErr <- err 622 return 623 } 624 c.readOp <- readOp{msgs, batch} 625 } 626 }