Source file src/pkg/net/http/httputil/persist.go
1 // Copyright 2009 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package httputil provides HTTP utility functions, complementing the 6 // more common ones in the net/http package. 7 package httputil 8 9 import ( 10 "bufio" 11 "errors" 12 "io" 13 "net" 14 "net/http" 15 "net/textproto" 16 "sync" 17 ) 18 19 var ( 20 ErrPersistEOF = &http.ProtocolError{ErrorString: "persistent connection closed"} 21 ErrClosed = &http.ProtocolError{ErrorString: "connection closed by user"} 22 ErrPipeline = &http.ProtocolError{ErrorString: "pipeline error"} 23 ) 24 25 // This is an API usage error - the local side is closed. 26 // ErrPersistEOF (above) reports that the remote side is closed. 27 var errClosed = errors.New("i/o operation on closed connection") 28 29 // A ServerConn reads requests and sends responses over an underlying 30 // connection, until the HTTP keepalive logic commands an end. ServerConn 31 // also allows hijacking the underlying connection by calling Hijack 32 // to regain control over the connection. ServerConn supports pipe-lining, 33 // i.e. requests can be read out of sync (but in the same order) while the 34 // respective responses are sent. 35 // 36 // ServerConn is low-level and should not be needed by most applications. 37 // See Server. 38 type ServerConn struct { 39 lk sync.Mutex // read-write protects the following fields 40 c net.Conn 41 r *bufio.Reader 42 re, we error // read/write errors 43 lastbody io.ReadCloser 44 nread, nwritten int 45 pipereq map[*http.Request]uint 46 47 pipe textproto.Pipeline 48 } 49 50 // NewServerConn returns a new ServerConn reading and writing c. If r is not 51 // nil, it is the buffer to use when reading c. 52 func NewServerConn(c net.Conn, r *bufio.Reader) *ServerConn { 53 if r == nil { 54 r = bufio.NewReader(c) 55 } 56 return &ServerConn{c: c, r: r, pipereq: make(map[*http.Request]uint)} 57 } 58 59 // Hijack detaches the ServerConn and returns the underlying connection as well 60 // as the read-side bufio which may have some left over data. Hijack may be 61 // called before Read has signaled the end of the keep-alive logic. The user 62 // should not call Hijack while Read or Write is in progress. 63 func (sc *ServerConn) Hijack() (c net.Conn, r *bufio.Reader) { 64 sc.lk.Lock() 65 defer sc.lk.Unlock() 66 c = sc.c 67 r = sc.r 68 sc.c = nil 69 sc.r = nil 70 return 71 } 72 73 // Close calls Hijack and then also closes the underlying connection 74 func (sc *ServerConn) Close() error { 75 c, _ := sc.Hijack() 76 if c != nil { 77 return c.Close() 78 } 79 return nil 80 } 81 82 // Read returns the next request on the wire. An ErrPersistEOF is returned if 83 // it is gracefully determined that there are no more requests (e.g. after the 84 // first request on an HTTP/1.0 connection, or after a Connection:close on a 85 // HTTP/1.1 connection). 86 func (sc *ServerConn) Read() (req *http.Request, err error) { 87 88 // Ensure ordered execution of Reads and Writes 89 id := sc.pipe.Next() 90 sc.pipe.StartRequest(id) 91 defer func() { 92 sc.pipe.EndRequest(id) 93 if req == nil { 94 sc.pipe.StartResponse(id) 95 sc.pipe.EndResponse(id) 96 } else { 97 // Remember the pipeline id of this request 98 sc.lk.Lock() 99 sc.pipereq[req] = id 100 sc.lk.Unlock() 101 } 102 }() 103 104 sc.lk.Lock() 105 if sc.we != nil { // no point receiving if write-side broken or closed 106 defer sc.lk.Unlock() 107 return nil, sc.we 108 } 109 if sc.re != nil { 110 defer sc.lk.Unlock() 111 return nil, sc.re 112 } 113 if sc.r == nil { // connection closed by user in the meantime 114 defer sc.lk.Unlock() 115 return nil, errClosed 116 } 117 r := sc.r 118 lastbody := sc.lastbody 119 sc.lastbody = nil 120 sc.lk.Unlock() 121 122 // Make sure body is fully consumed, even if user does not call body.Close 123 if lastbody != nil { 124 // body.Close is assumed to be idempotent and multiple calls to 125 // it should return the error that its first invocation 126 // returned. 127 err = lastbody.Close() 128 if err != nil { 129 sc.lk.Lock() 130 defer sc.lk.Unlock() 131 sc.re = err 132 return nil, err 133 } 134 } 135 136 req, err = http.ReadRequest(r) 137 sc.lk.Lock() 138 defer sc.lk.Unlock() 139 if err != nil { 140 if err == io.ErrUnexpectedEOF { 141 // A close from the opposing client is treated as a 142 // graceful close, even if there was some unparse-able 143 // data before the close. 144 sc.re = ErrPersistEOF 145 return nil, sc.re 146 } else { 147 sc.re = err 148 return req, err 149 } 150 } 151 sc.lastbody = req.Body 152 sc.nread++ 153 if req.Close { 154 sc.re = ErrPersistEOF 155 return req, sc.re 156 } 157 return req, err 158 } 159 160 // Pending returns the number of unanswered requests 161 // that have been received on the connection. 162 func (sc *ServerConn) Pending() int { 163 sc.lk.Lock() 164 defer sc.lk.Unlock() 165 return sc.nread - sc.nwritten 166 } 167 168 // Write writes resp in response to req. To close the connection gracefully, set the 169 // Response.Close field to true. Write should be considered operational until 170 // it returns an error, regardless of any errors returned on the Read side. 171 func (sc *ServerConn) Write(req *http.Request, resp *http.Response) error { 172 173 // Retrieve the pipeline ID of this request/response pair 174 sc.lk.Lock() 175 id, ok := sc.pipereq[req] 176 delete(sc.pipereq, req) 177 if !ok { 178 sc.lk.Unlock() 179 return ErrPipeline 180 } 181 sc.lk.Unlock() 182 183 // Ensure pipeline order 184 sc.pipe.StartResponse(id) 185 defer sc.pipe.EndResponse(id) 186 187 sc.lk.Lock() 188 if sc.we != nil { 189 defer sc.lk.Unlock() 190 return sc.we 191 } 192 if sc.c == nil { // connection closed by user in the meantime 193 defer sc.lk.Unlock() 194 return ErrClosed 195 } 196 c := sc.c 197 if sc.nread <= sc.nwritten { 198 defer sc.lk.Unlock() 199 return errors.New("persist server pipe count") 200 } 201 if resp.Close { 202 // After signaling a keep-alive close, any pipelined unread 203 // requests will be lost. It is up to the user to drain them 204 // before signaling. 205 sc.re = ErrPersistEOF 206 } 207 sc.lk.Unlock() 208 209 err := resp.Write(c) 210 sc.lk.Lock() 211 defer sc.lk.Unlock() 212 if err != nil { 213 sc.we = err 214 return err 215 } 216 sc.nwritten++ 217 218 return nil 219 } 220 221 // A ClientConn sends request and receives headers over an underlying 222 // connection, while respecting the HTTP keepalive logic. ClientConn 223 // supports hijacking the connection calling Hijack to 224 // regain control of the underlying net.Conn and deal with it as desired. 225 // 226 // ClientConn is low-level and should not be needed by most applications. 227 // See Client. 228 type ClientConn struct { 229 lk sync.Mutex // read-write protects the following fields 230 c net.Conn 231 r *bufio.Reader 232 re, we error // read/write errors 233 lastbody io.ReadCloser 234 nread, nwritten int 235 pipereq map[*http.Request]uint 236 237 pipe textproto.Pipeline 238 writeReq func(*http.Request, io.Writer) error 239 } 240 241 // NewClientConn returns a new ClientConn reading and writing c. If r is not 242 // nil, it is the buffer to use when reading c. 243 func NewClientConn(c net.Conn, r *bufio.Reader) *ClientConn { 244 if r == nil { 245 r = bufio.NewReader(c) 246 } 247 return &ClientConn{ 248 c: c, 249 r: r, 250 pipereq: make(map[*http.Request]uint), 251 writeReq: (*http.Request).Write, 252 } 253 } 254 255 // NewProxyClientConn works like NewClientConn but writes Requests 256 // using Request's WriteProxy method. 257 func NewProxyClientConn(c net.Conn, r *bufio.Reader) *ClientConn { 258 cc := NewClientConn(c, r) 259 cc.writeReq = (*http.Request).WriteProxy 260 return cc 261 } 262 263 // Hijack detaches the ClientConn and returns the underlying connection as well 264 // as the read-side bufio which may have some left over data. Hijack may be 265 // called before the user or Read have signaled the end of the keep-alive 266 // logic. The user should not call Hijack while Read or Write is in progress. 267 func (cc *ClientConn) Hijack() (c net.Conn, r *bufio.Reader) { 268 cc.lk.Lock() 269 defer cc.lk.Unlock() 270 c = cc.c 271 r = cc.r 272 cc.c = nil 273 cc.r = nil 274 return 275 } 276 277 // Close calls Hijack and then also closes the underlying connection 278 func (cc *ClientConn) Close() error { 279 c, _ := cc.Hijack() 280 if c != nil { 281 return c.Close() 282 } 283 return nil 284 } 285 286 // Write writes a request. An ErrPersistEOF error is returned if the connection 287 // has been closed in an HTTP keepalive sense. If req.Close equals true, the 288 // keepalive connection is logically closed after this request and the opposing 289 // server is informed. An ErrUnexpectedEOF indicates the remote closed the 290 // underlying TCP connection, which is usually considered as graceful close. 291 func (cc *ClientConn) Write(req *http.Request) (err error) { 292 293 // Ensure ordered execution of Writes 294 id := cc.pipe.Next() 295 cc.pipe.StartRequest(id) 296 defer func() { 297 cc.pipe.EndRequest(id) 298 if err != nil { 299 cc.pipe.StartResponse(id) 300 cc.pipe.EndResponse(id) 301 } else { 302 // Remember the pipeline id of this request 303 cc.lk.Lock() 304 cc.pipereq[req] = id 305 cc.lk.Unlock() 306 } 307 }() 308 309 cc.lk.Lock() 310 if cc.re != nil { // no point sending if read-side closed or broken 311 defer cc.lk.Unlock() 312 return cc.re 313 } 314 if cc.we != nil { 315 defer cc.lk.Unlock() 316 return cc.we 317 } 318 if cc.c == nil { // connection closed by user in the meantime 319 defer cc.lk.Unlock() 320 return errClosed 321 } 322 c := cc.c 323 if req.Close { 324 // We write the EOF to the write-side error, because there 325 // still might be some pipelined reads 326 cc.we = ErrPersistEOF 327 } 328 cc.lk.Unlock() 329 330 err = cc.writeReq(req, c) 331 cc.lk.Lock() 332 defer cc.lk.Unlock() 333 if err != nil { 334 cc.we = err 335 return err 336 } 337 cc.nwritten++ 338 339 return nil 340 } 341 342 // Pending returns the number of unanswered requests 343 // that have been sent on the connection. 344 func (cc *ClientConn) Pending() int { 345 cc.lk.Lock() 346 defer cc.lk.Unlock() 347 return cc.nwritten - cc.nread 348 } 349 350 // Read reads the next response from the wire. A valid response might be 351 // returned together with an ErrPersistEOF, which means that the remote 352 // requested that this be the last request serviced. Read can be called 353 // concurrently with Write, but not with another Read. 354 func (cc *ClientConn) Read(req *http.Request) (resp *http.Response, err error) { 355 // Retrieve the pipeline ID of this request/response pair 356 cc.lk.Lock() 357 id, ok := cc.pipereq[req] 358 delete(cc.pipereq, req) 359 if !ok { 360 cc.lk.Unlock() 361 return nil, ErrPipeline 362 } 363 cc.lk.Unlock() 364 365 // Ensure pipeline order 366 cc.pipe.StartResponse(id) 367 defer cc.pipe.EndResponse(id) 368 369 cc.lk.Lock() 370 if cc.re != nil { 371 defer cc.lk.Unlock() 372 return nil, cc.re 373 } 374 if cc.r == nil { // connection closed by user in the meantime 375 defer cc.lk.Unlock() 376 return nil, errClosed 377 } 378 r := cc.r 379 lastbody := cc.lastbody 380 cc.lastbody = nil 381 cc.lk.Unlock() 382 383 // Make sure body is fully consumed, even if user does not call body.Close 384 if lastbody != nil { 385 // body.Close is assumed to be idempotent and multiple calls to 386 // it should return the error that its first invocation 387 // returned. 388 err = lastbody.Close() 389 if err != nil { 390 cc.lk.Lock() 391 defer cc.lk.Unlock() 392 cc.re = err 393 return nil, err 394 } 395 } 396 397 resp, err = http.ReadResponse(r, req) 398 cc.lk.Lock() 399 defer cc.lk.Unlock() 400 if err != nil { 401 cc.re = err 402 return resp, err 403 } 404 cc.lastbody = resp.Body 405 406 cc.nread++ 407 408 if resp.Close { 409 cc.re = ErrPersistEOF // don't send any more requests 410 return resp, cc.re 411 } 412 return resp, err 413 } 414 415 // Do is convenience method that writes a request and reads a response. 416 func (cc *ClientConn) Do(req *http.Request) (resp *http.Response, err error) { 417 err = cc.Write(req) 418 if err != nil { 419 return 420 } 421 return cc.Read(req) 422 }