github.com/ethereum/go-ethereum@v1.14.3/rpc/subscription.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 "container/list" 21 "context" 22 crand "crypto/rand" 23 "encoding/binary" 24 "encoding/hex" 25 "encoding/json" 26 "errors" 27 "math/rand" 28 "reflect" 29 "strings" 30 "sync" 31 "time" 32 ) 33 34 var ( 35 // ErrNotificationsUnsupported is returned by the client when the connection doesn't 36 // support notifications. You can use this error value to check for subscription 37 // support like this: 38 // 39 // sub, err := client.EthSubscribe(ctx, channel, "newHeads", true) 40 // if errors.Is(err, rpc.ErrNotificationsUnsupported) { 41 // // Server does not support subscriptions, fall back to polling. 42 // } 43 // 44 ErrNotificationsUnsupported = notificationsUnsupportedError{} 45 46 // ErrSubscriptionNotFound is returned when the notification for the given id is not found 47 ErrSubscriptionNotFound = errors.New("subscription not found") 48 ) 49 50 var globalGen = randomIDGenerator() 51 52 // ID defines a pseudo random number that is used to identify RPC subscriptions. 53 type ID string 54 55 // NewID returns a new, random ID. 56 func NewID() ID { 57 return globalGen() 58 } 59 60 // randomIDGenerator returns a function generates a random IDs. 61 func randomIDGenerator() func() ID { 62 var buf = make([]byte, 8) 63 var seed int64 64 if _, err := crand.Read(buf); err == nil { 65 seed = int64(binary.BigEndian.Uint64(buf)) 66 } else { 67 seed = int64(time.Now().Nanosecond()) 68 } 69 70 var ( 71 mu sync.Mutex 72 rng = rand.New(rand.NewSource(seed)) 73 ) 74 return func() ID { 75 mu.Lock() 76 defer mu.Unlock() 77 id := make([]byte, 16) 78 rng.Read(id) 79 return encodeID(id) 80 } 81 } 82 83 func encodeID(b []byte) ID { 84 id := hex.EncodeToString(b) 85 id = strings.TrimLeft(id, "0") 86 if id == "" { 87 id = "0" // ID's are RPC quantities, no leading zero's and 0 is 0x0. 88 } 89 return ID("0x" + id) 90 } 91 92 type notifierKey struct{} 93 94 // NotifierFromContext returns the Notifier value stored in ctx, if any. 95 func NotifierFromContext(ctx context.Context) (*Notifier, bool) { 96 n, ok := ctx.Value(notifierKey{}).(*Notifier) 97 return n, ok 98 } 99 100 // Notifier is tied to an RPC connection that supports subscriptions. 101 // Server callbacks use the notifier to send notifications. 102 type Notifier struct { 103 h *handler 104 namespace string 105 106 mu sync.Mutex 107 sub *Subscription 108 buffer []any 109 callReturned bool 110 activated bool 111 } 112 113 // CreateSubscription returns a new subscription that is coupled to the 114 // RPC connection. By default subscriptions are inactive and notifications 115 // are dropped until the subscription is marked as active. This is done 116 // by the RPC server after the subscription ID is send to the client. 117 func (n *Notifier) CreateSubscription() *Subscription { 118 n.mu.Lock() 119 defer n.mu.Unlock() 120 121 if n.sub != nil { 122 panic("can't create multiple subscriptions with Notifier") 123 } else if n.callReturned { 124 panic("can't create subscription after subscribe call has returned") 125 } 126 n.sub = &Subscription{ID: n.h.idgen(), namespace: n.namespace, err: make(chan error, 1)} 127 return n.sub 128 } 129 130 // Notify sends a notification to the client with the given data as payload. 131 // If an error occurs the RPC connection is closed and the error is returned. 132 func (n *Notifier) Notify(id ID, data any) error { 133 n.mu.Lock() 134 defer n.mu.Unlock() 135 136 if n.sub == nil { 137 panic("can't Notify before subscription is created") 138 } else if n.sub.ID != id { 139 panic("Notify with wrong ID") 140 } 141 if n.activated { 142 return n.send(n.sub, data) 143 } 144 n.buffer = append(n.buffer, data) 145 return nil 146 } 147 148 // takeSubscription returns the subscription (if one has been created). No subscription can 149 // be created after this call. 150 func (n *Notifier) takeSubscription() *Subscription { 151 n.mu.Lock() 152 defer n.mu.Unlock() 153 n.callReturned = true 154 return n.sub 155 } 156 157 // activate is called after the subscription ID was sent to client. Notifications are 158 // buffered before activation. This prevents notifications being sent to the client before 159 // the subscription ID is sent to the client. 160 func (n *Notifier) activate() error { 161 n.mu.Lock() 162 defer n.mu.Unlock() 163 164 for _, data := range n.buffer { 165 if err := n.send(n.sub, data); err != nil { 166 return err 167 } 168 } 169 n.activated = true 170 return nil 171 } 172 173 func (n *Notifier) send(sub *Subscription, data any) error { 174 msg := jsonrpcSubscriptionNotification{ 175 Version: vsn, 176 Method: n.namespace + notificationMethodSuffix, 177 Params: subscriptionResultEnc{ 178 ID: string(sub.ID), 179 Result: data, 180 }, 181 } 182 return n.h.conn.writeJSON(context.Background(), &msg, false) 183 } 184 185 // A Subscription is created by a notifier and tied to that notifier. The client can use 186 // this subscription to wait for an unsubscribe request for the client, see Err(). 187 type Subscription struct { 188 ID ID 189 namespace string 190 err chan error // closed on unsubscribe 191 } 192 193 // Err returns a channel that is closed when the client send an unsubscribe request. 194 func (s *Subscription) Err() <-chan error { 195 return s.err 196 } 197 198 // MarshalJSON marshals a subscription as its ID. 199 func (s *Subscription) MarshalJSON() ([]byte, error) { 200 return json.Marshal(s.ID) 201 } 202 203 // ClientSubscription is a subscription established through the Client's Subscribe or 204 // EthSubscribe methods. 205 type ClientSubscription struct { 206 client *Client 207 etype reflect.Type 208 channel reflect.Value 209 namespace string 210 subid string 211 212 // The in channel receives notification values from client dispatcher. 213 in chan json.RawMessage 214 215 // The error channel receives the error from the forwarding loop. 216 // It is closed by Unsubscribe. 217 err chan error 218 errOnce sync.Once 219 220 // Closing of the subscription is requested by sending on 'quit'. This is handled by 221 // the forwarding loop, which closes 'forwardDone' when it has stopped sending to 222 // sub.channel. Finally, 'unsubDone' is closed after unsubscribing on the server side. 223 quit chan error 224 forwardDone chan struct{} 225 unsubDone chan struct{} 226 } 227 228 // This is the sentinel value sent on sub.quit when Unsubscribe is called. 229 var errUnsubscribed = errors.New("unsubscribed") 230 231 func newClientSubscription(c *Client, namespace string, channel reflect.Value) *ClientSubscription { 232 sub := &ClientSubscription{ 233 client: c, 234 namespace: namespace, 235 etype: channel.Type().Elem(), 236 channel: channel, 237 in: make(chan json.RawMessage), 238 quit: make(chan error), 239 forwardDone: make(chan struct{}), 240 unsubDone: make(chan struct{}), 241 err: make(chan error, 1), 242 } 243 return sub 244 } 245 246 // Err returns the subscription error channel. The intended use of Err is to schedule 247 // resubscription when the client connection is closed unexpectedly. 248 // 249 // The error channel receives a value when the subscription has ended due to an error. The 250 // received error is nil if Close has been called on the underlying client and no other 251 // error has occurred. 252 // 253 // The error channel is closed when Unsubscribe is called on the subscription. 254 func (sub *ClientSubscription) Err() <-chan error { 255 return sub.err 256 } 257 258 // Unsubscribe unsubscribes the notification and closes the error channel. 259 // It can safely be called more than once. 260 func (sub *ClientSubscription) Unsubscribe() { 261 sub.errOnce.Do(func() { 262 select { 263 case sub.quit <- errUnsubscribed: 264 <-sub.unsubDone 265 case <-sub.unsubDone: 266 } 267 close(sub.err) 268 }) 269 } 270 271 // deliver is called by the client's message dispatcher to send a notification value. 272 func (sub *ClientSubscription) deliver(result json.RawMessage) (ok bool) { 273 select { 274 case sub.in <- result: 275 return true 276 case <-sub.forwardDone: 277 return false 278 } 279 } 280 281 // close is called by the client's message dispatcher when the connection is closed. 282 func (sub *ClientSubscription) close(err error) { 283 select { 284 case sub.quit <- err: 285 case <-sub.forwardDone: 286 } 287 } 288 289 // run is the forwarding loop of the subscription. It runs in its own goroutine and 290 // is launched by the client's handler after the subscription has been created. 291 func (sub *ClientSubscription) run() { 292 defer close(sub.unsubDone) 293 294 unsubscribe, err := sub.forward() 295 296 // The client's dispatch loop won't be able to execute the unsubscribe call if it is 297 // blocked in sub.deliver() or sub.close(). Closing forwardDone unblocks them. 298 close(sub.forwardDone) 299 300 // Call the unsubscribe method on the server. 301 if unsubscribe { 302 sub.requestUnsubscribe() 303 } 304 305 // Send the error. 306 if err != nil { 307 if err == ErrClientQuit { 308 // ErrClientQuit gets here when Client.Close is called. This is reported as a 309 // nil error because it's not an error, but we can't close sub.err here. 310 err = nil 311 } 312 sub.err <- err 313 } 314 } 315 316 // forward is the forwarding loop. It takes in RPC notifications and sends them 317 // on the subscription channel. 318 func (sub *ClientSubscription) forward() (unsubscribeServer bool, err error) { 319 cases := []reflect.SelectCase{ 320 {Dir: reflect.SelectRecv, Chan: reflect.ValueOf(sub.quit)}, 321 {Dir: reflect.SelectRecv, Chan: reflect.ValueOf(sub.in)}, 322 {Dir: reflect.SelectSend, Chan: sub.channel}, 323 } 324 buffer := list.New() 325 326 for { 327 var chosen int 328 var recv reflect.Value 329 if buffer.Len() == 0 { 330 // Idle, omit send case. 331 chosen, recv, _ = reflect.Select(cases[:2]) 332 } else { 333 // Non-empty buffer, send the first queued item. 334 cases[2].Send = reflect.ValueOf(buffer.Front().Value) 335 chosen, recv, _ = reflect.Select(cases) 336 } 337 338 switch chosen { 339 case 0: // <-sub.quit 340 if !recv.IsNil() { 341 err = recv.Interface().(error) 342 } 343 if err == errUnsubscribed { 344 // Exiting because Unsubscribe was called, unsubscribe on server. 345 return true, nil 346 } 347 return false, err 348 349 case 1: // <-sub.in 350 val, err := sub.unmarshal(recv.Interface().(json.RawMessage)) 351 if err != nil { 352 return true, err 353 } 354 if buffer.Len() == maxClientSubscriptionBuffer { 355 return true, ErrSubscriptionQueueOverflow 356 } 357 buffer.PushBack(val) 358 359 case 2: // sub.channel<- 360 cases[2].Send = reflect.Value{} // Don't hold onto the value. 361 buffer.Remove(buffer.Front()) 362 } 363 } 364 } 365 366 func (sub *ClientSubscription) unmarshal(result json.RawMessage) (interface{}, error) { 367 val := reflect.New(sub.etype) 368 err := json.Unmarshal(result, val.Interface()) 369 return val.Elem().Interface(), err 370 } 371 372 func (sub *ClientSubscription) requestUnsubscribe() error { 373 var result interface{} 374 return sub.client.Call(&result, sub.namespace+unsubscribeMethodSuffix, sub.subid) 375 }