diff options
| -rw-r--r-- | args.go | 16 | ||||
| -rw-r--r-- | client.go | 26 | ||||
| -rw-r--r-- | cookie.go | 2 | ||||
| -rw-r--r-- | header.go | 40 | ||||
| -rw-r--r-- | http.go | 8 | ||||
| -rw-r--r-- | server.go | 44 | ||||
| -rw-r--r-- | uri.go | 2 |
7 files changed, 30 insertions, 108 deletions
@@ -51,8 +51,6 @@ func (a *Args) Parse(s string) { } // ParseBytes parses the given b containing query args. -// -// It is safe modifying b buffer contents after ParseBytes return. func (a *Args) ParseBytes(b []byte) { a.Reset() @@ -114,8 +112,6 @@ func (a *Args) Del(key string) { } // DelBytes deletes argument with the given key from query args. -// -// It is safe modifying key buffer after DelBytes return. func (a *Args) DelBytes(key []byte) { a.args = delArg(a.args, key) } @@ -127,24 +123,18 @@ func (a *Args) Set(key, value string) { } // SetBytesK sets 'key=value' argument. -// -// It is safe modifying key buffer after SetBytesK return. func (a *Args) SetBytesK(key []byte, value string) { a.bufKV.value = AppendBytesStr(a.bufKV.value[:0], value) a.SetBytesKV(key, a.bufKV.value) } // SetBytesV sets 'key=value' argument. -// -// It is safe modifying value buffer after SetBytesV return. func (a *Args) SetBytesV(key string, value []byte) { a.bufKV.key = AppendBytesStr(a.bufKV.key[:0], key) a.SetBytesKV(a.bufKV.key, value) } // SetBytesKV sets 'key=value' argument. -// -// It is safe modifying key and value buffers after SetBytesKV return. func (a *Args) SetBytesKV(key, value []byte) { a.args = setArg(a.args, key, value) } @@ -159,8 +149,6 @@ func (a *Args) Peek(key string) []byte { // PeekBytes returns query arg value for the given key. // // Returned value is valid until the next Args call. -// -// It is safe modifying key buffer after PeekBytes return. func (a *Args) PeekBytes(key []byte) []byte { return peekArgBytes(a.args, key) } @@ -176,8 +164,8 @@ func (a *Args) HasBytes(key []byte) bool { return hasArg(a.args, key) } -// ErrNoArgValue is returned when value with the given key is missing. -var ErrNoArgValue = errors.New("No value for the given key") +// ErrNoArgValue is returned when Args value with the given key is missing. +var ErrNoArgValue = errors.New("no Args value for the given key") // GetUint returns uint value for the given key. func (a *Args) GetUint(key string) (int, error) { @@ -50,18 +50,16 @@ func DoTimeout(req *Request, resp *Response, timeout time.Duration) error { return defaultClient.DoTimeout(req, resp, timeout) } -// Get fetches url contents into dst. -// -// Use Do for request customization. +// Get fetches url contents into dst and returns it as body. func Get(dst []byte, url string) (statusCode int, body []byte, err error) { return defaultClient.Get(dst, url) } // Post sends POST request to the given url with the given POST arguments. // -// Empty POST body is sent if postArgs is nil. +// Response body is written to dst, which is returned as body. // -// Use Do for request customization. +// Empty POST body is sent if postArgs is nil. func Post(dst []byte, url string, postArgs *Args) (statusCode int, body []byte, err error) { return defaultClient.Post(dst, url, postArgs) } @@ -111,18 +109,16 @@ type Client struct { ms map[string]*HostClient } -// Get fetches url contents into dst. -// -// Use Do for request customization. +// Get fetches url contents into dst and returns it as body. func (c *Client) Get(dst []byte, url string) (statusCode int, body []byte, err error) { return clientGetURL(dst, url, c) } // Post sends POST request to the given url with the given POST arguments. // -// Empty POST body is sent if postArgs is nil. +// Response body is written to dst, which is returned as body. // -// Use Do for request customization. +// Empty POST body is sent if postArgs is nil. func (c *Client) Post(dst []byte, url string, postArgs *Args) (statusCode int, body []byte, err error) { return clientPostURL(dst, url, postArgs, c) } @@ -245,7 +241,7 @@ const DefaultMaxConnsPerHost = 100 // The client automatically converts connection to TLS // if HostClient.IsTLS is set. // -// TCP address passed to DialFunc always contain host and port. +// TCP address passed to DialFunc always contains host and port. // Example TCP addr values: // // - foobar.com:80 @@ -332,18 +328,16 @@ func (c *HostClient) LastUseTime() time.Time { return time.Unix(int64(n), 0) } -// Get fetches url contents into dst. -// -// Use Do for request customization. +// Get fetches url contents into dst and returns it as body. func (c *HostClient) Get(dst []byte, url string) (statusCode int, body []byte, err error) { return clientGetURL(dst, url, c) } // Post sends POST request to the given url with the given POST arguments. // -// Empty POST body is sent if postArgs is nil. +// Response body is written to dst, which is returned as body. // -// Use Do for request customization. +// Empty POST body is sent if postArgs is nil. func (c *HostClient) Post(dst []byte, url string, postArgs *Args) (statusCode int, body []byte, err error) { return clientPostURL(dst, url, postArgs, c) } @@ -106,8 +106,6 @@ func (c *Cookie) Parse(src string) error { } // ParseBytes parses Set-Cookie header. -// -// It is safe modifying src buffer after function return. func (c *Cookie) ParseBytes(src []byte) error { c.Reset() @@ -86,7 +86,7 @@ func (h *RequestHeader) ConnectionClose() bool { // ConnectionCloseReal returns true if 'Connection: close' header is set. // -// This method tirgger full (slow) request headers' parsing +// This method triggers full (slow) request headers' parsing // unlike ConnectionClose, so use it only if you really want determining // whether 'Connection: close' header is really set on the wire. func (h *RequestHeader) ConnectionCloseReal() bool { @@ -172,8 +172,6 @@ func (h *ResponseHeader) SetContentType(contentType string) { } // SetContentTypeBytes sets Content-Type header value. -// -// It is safe modifying contentType buffer after function return. func (h *ResponseHeader) SetContentTypeBytes(contentType []byte) { h.contentType = append(h.contentType[:0], contentType...) } @@ -189,8 +187,6 @@ func (h *ResponseHeader) SetServer(server string) { } // SetServerBytes sets Server header value. -// -// It is safe modifying server buffer after function return. func (h *ResponseHeader) SetServerBytes(server []byte) { h.server = append(h.server[:0], server...) } @@ -208,8 +204,6 @@ func (h *RequestHeader) SetContentType(contentType string) { } // SetContentTypeBytes sets Content-Type header value. -// -// It is safe modifying contentType buffer after function return. func (h *RequestHeader) SetContentTypeBytes(contentType []byte) { h.parseRawHeaders() h.contentType = append(h.contentType[:0], contentType...) @@ -241,8 +235,6 @@ func (h *RequestHeader) SetHost(host string) { } // SetHostBytes sets Host header value. -// -// It is safe modifying host buffer after function return. func (h *RequestHeader) SetHostBytes(host []byte) { h.parseRawHeaders() h.host = append(h.host[:0], host...) @@ -261,8 +253,6 @@ func (h *RequestHeader) SetUserAgent(userAgent string) { } // SetUserAgentBytes sets User-Agent header value. -// -// It is safe modifying userAgent buffer after function return. func (h *RequestHeader) SetUserAgentBytes(userAgent []byte) { h.parseRawHeaders() h.userAgent = append(h.userAgent[:0], userAgent...) @@ -279,8 +269,6 @@ func (h *RequestHeader) SetReferer(referer string) { } // SetRefererBytes sets Referer header value. -// -// It is safe modifying referer buffer after function return. func (h *RequestHeader) SetRefererBytes(referer []byte) { h.SetCanonical(strReferer, referer) } @@ -299,8 +287,6 @@ func (h *RequestHeader) SetMethod(method string) { } // SetMethod sets HTTP request method. -// -// It is safe modifying method buffer after function return. func (h *RequestHeader) SetMethodBytes(method []byte) { h.method = append(h.method[:0], method...) } @@ -324,8 +310,6 @@ func (h *RequestHeader) SetRequestURI(requestURI string) { // SetRequestURI sets RequestURI for the first HTTP request line. // RequestURI must be properly encoded. // Use URI.RequestURI for constructing proper RequestURI if unsure. -// -// It is safe modifying requestURI buffer after function return. func (h *RequestHeader) SetRequestURIBytes(requestURI []byte) { h.requestURI = append(h.requestURI[:0], requestURI...) } @@ -543,24 +527,18 @@ func (h *ResponseHeader) Set(key, value string) { } // SetBytesK sets the given 'key: value' header. -// -// It is safe modifying key buffer after SetBytesK return. func (h *ResponseHeader) SetBytesK(key []byte, value string) { h.bufKV.value = AppendBytesStr(h.bufKV.value[:0], value) h.SetBytesKV(key, h.bufKV.value) } // SetBytesV sets the given 'key: value' header. -// -// It is safe modifying value buffer after SetBytesV return. func (h *ResponseHeader) SetBytesV(key string, value []byte) { k := getHeaderKeyBytes(&h.bufKV, key) h.SetCanonical(k, value) } // SetBytesKV sets the given 'key: value' header. -// -// It is safe modifying key and value buffers after SetBytesKV return. func (h *ResponseHeader) SetBytesKV(key, value []byte) { h.bufKV.key = append(h.bufKV.key[:0], key...) normalizeHeaderKey(h.bufKV.key) @@ -569,8 +547,6 @@ func (h *ResponseHeader) SetBytesKV(key, value []byte) { // SetCanonical sets the given 'key: value' header assuming that // key is in canonical form. -// -// It is safe modifying key and value buffers after SetCanonical return. func (h *ResponseHeader) SetCanonical(key, value []byte) { switch { case bytes.Equal(strContentType, key): @@ -602,8 +578,6 @@ func (h *ResponseHeader) SetCanonical(key, value []byte) { } // SetCookie sets the given response cookie. -// -// It is safe modifying cookie instance after the call. func (h *ResponseHeader) SetCookie(cookie *Cookie) { h.cookies = setArg(h.cookies, cookie.Key, cookie.Cookie()) } @@ -615,16 +589,12 @@ func (h *RequestHeader) SetCookie(key, value string) { } // SetCookieBytesK sets 'key: value' cookies. -// -// It is safe modifying key buffer after SetCookieBytesK call. func (h *RequestHeader) SetCookieBytesK(key []byte, value string) { h.bufKV.value = AppendBytesStr(h.bufKV.value[:0], value) h.SetCookieBytesKV(key, h.bufKV.value) } // SetCookieBytesKV sets 'key: value' cookies. -// -// It is safe modifying key and value buffers after SetCookieBytesKV call. func (h *RequestHeader) SetCookieBytesKV(key, value []byte) { h.parseRawHeaders() h.collectCookies() @@ -638,24 +608,18 @@ func (h *RequestHeader) Set(key, value string) { } // SetBytesK sets the given 'key: value' header. -// -// It is safe modifying key buffer after SetBytesK return. func (h *RequestHeader) SetBytesK(key []byte, value string) { h.bufKV.value = AppendBytesStr(h.bufKV.value[:0], value) h.SetBytesKV(key, h.bufKV.value) } // SetBytesV sets the given 'key: value' header. -// -// It is safe modifying value buffer after SetBytesV return. func (h *RequestHeader) SetBytesV(key string, value []byte) { k := getHeaderKeyBytes(&h.bufKV, key) h.SetCanonical(k, value) } // SetBytesKV sets the given 'key: value' header. -// -// It is safe modifying key and value buffers after SetBytesKV return. func (h *RequestHeader) SetBytesKV(key, value []byte) { h.bufKV.key = append(h.bufKV.key[:0], key...) normalizeHeaderKey(h.bufKV.key) @@ -664,8 +628,6 @@ func (h *RequestHeader) SetBytesKV(key, value []byte) { // SetCanonical sets the given 'key: value' header assuming that // key is in canonical form. -// -// It is safe modifying key and value buffers after SetCanonical return. func (h *RequestHeader) SetCanonical(key, value []byte) { h.parseRawHeaders() switch { @@ -51,8 +51,6 @@ func (req *Request) SetRequestURI(requestURI string) { } // SetRequestURIBytes sets RequestURI. -// -// It is safe using requestURI buffer after the function return. func (req *Request) SetRequestURIBytes(requestURI []byte) { req.Header.SetRequestURIBytes(requestURI) } @@ -137,8 +135,6 @@ func (resp *Response) Body() []byte { } // SetBody sets response body. -// -// It is safe modifying body buffer after function return. func (resp *Response) SetBody(body []byte) { resp.body = append(resp.body[:0], body...) } @@ -149,8 +145,6 @@ func (req *Request) Body() []byte { } // SetBody sets request body. -// -// It is safe modifying body buffer after function return. func (req *Request) SetBody(body []byte) { req.body = append(req.body[:0], body...) } @@ -287,7 +281,7 @@ func isSkipResponseBody(statusCode int) bool { var errRequestHostRequired = errors.New("Missing required Host header in request") -// Write write request to w. +// Write writes request to w. // // Write doesn't flush request to w for performance reasons. func (req *Request) Write(w *bufio.Writer) error { @@ -25,9 +25,6 @@ import ( // to the client. Otherwise requests' processing may hang. // // ServeConn closes c before returning. -// -// ServeConn uses default Server settings. Use Server.ServeConn -// for custom server tuning. func ServeConn(c net.Conn, handler RequestHandler) error { v := serverPool.Get() if v == nil { @@ -47,9 +44,6 @@ var serverPool sync.Pool // using the given handler. // // Serve blocks until the given listener returns permanent error. -// -// Serve uses default Server settings. Use Server.Serve -// for custom server tuning. func Serve(ln net.Listener, handler RequestHandler) error { s := &Server{ Handler: handler, @@ -59,9 +53,6 @@ func Serve(ln net.Listener, handler RequestHandler) error { // ListenAndServe serves HTTP requests from the given TCP addr // using the given handler. -// -// ListenAndServe uses default Server settings. Use Server.ListenAndServe -// for custom server tuning. func ListenAndServe(addr string, handler RequestHandler) error { s := &Server{ Handler: handler, @@ -73,9 +64,6 @@ func ListenAndServe(addr string, handler RequestHandler) error { // using the given handler. // // certFile and keyFile are paths to TLS certificate and key files. -// -// ListenAndServeTLS uses default Server settings. Use Server.ListenAndServeTLS -// for custom server tuning. func ListenAndServeTLS(addr, certFile, keyFile string, handler RequestHandler) error { s := &Server{ Handler: handler, @@ -85,7 +73,7 @@ func ListenAndServeTLS(addr, certFile, keyFile string, handler RequestHandler) e // RequestHandler must process incoming requests. // -// RequestHandler must call ctx.TimeoutError() before return +// RequestHandler must call ctx.TimeoutError() before returning // if it keeps references to ctx and/or its' members after the return. // Consider wrapping RequestHandler into TimeoutHandler if response time // must be limited. @@ -159,8 +147,8 @@ type Server struct { } // TimeoutHandler creates RequestHandler, which returns StatusRequestTimeout -// error with the given msg in the body to the client if h didn't return -// during the given duration. +// error with the given msg to the client if h didn't return during +// the given duration. func TimeoutHandler(h RequestHandler, timeout time.Duration, msg string) RequestHandler { if timeout <= 0 { return h @@ -193,9 +181,9 @@ func TimeoutHandler(h RequestHandler, timeout time.Duration, msg string) Request // RequestHandler should avoid holding references to incoming RequestCtx and/or // its' members after the return. // If holding RequestCtx references after the return is unavoidable -// (for instance, ctx is passed to a separate goroutine and we cannot control -// ctx lifetime in this goroutine), then the RequestHandler MUST call -// ctx.TimeoutError() before return. +// (for instance, ctx is passed to a separate goroutine and ctx lifetime cannot +// be controlled), then the RequestHandler MUST call ctx.TimeoutError() +// before return. type RequestCtx struct { // Incoming request. Request Request @@ -325,6 +313,8 @@ func (ctx *RequestCtx) RequestURI() []byte { } // URI returns requested uri. +// +// The uri is valid until returning from RequestHandler. func (ctx *RequestCtx) URI() *URI { return ctx.Request.URI() } @@ -425,8 +415,6 @@ func (ctx *RequestCtx) RemoteIP() net.IP { // Error sets response status code to the given value and sets response body // to the given message. -// -// Error calls are ignored after TimeoutError call. func (ctx *RequestCtx) Error(msg string, statusCode int) { resp := &ctx.Response resp.Reset() @@ -436,18 +424,12 @@ func (ctx *RequestCtx) Error(msg string, statusCode int) { } // Success sets response Content-Type and body to the given values. -// -// It is safe modifying body buffer after the Success() call. -// -// Success calls are ignored after TimeoutError call. func (ctx *RequestCtx) Success(contentType string, body []byte) { ctx.SetContentType(contentType) ctx.SetBody(body) } // SetBody sets response body to the given value. -// -// It is safe modifying body buffer after the function return. func (ctx *RequestCtx) SetBody(body []byte) { ctx.Response.SetBody(body) } @@ -482,9 +464,13 @@ func (ctx *RequestCtx) SetBodyStream(bodyStream io.Reader, bodySize int) { // request-specific messages inside RequestHandler. // // Each message logged via returned logger contains request-specific information -// such as request id, remote address, request method and request url. +// such as request id, request duration, local address, remote address, +// request method and request url. // -// It is safe re-using returned logger for logging multiple messages. +// It is safe re-using returned logger for logging multiple messages +// for the current request. +// +// The returned logger is valid until returning from RequestHandler. func (ctx *RequestCtx) Logger() Logger { if ctx.logger.ctx == nil { ctx.logger.ctx = ctx @@ -790,6 +776,8 @@ func (s *Server) serveConn(c net.Conn) error { } // TimeoutErrMsg returns last error message set via TimeoutError call. +// +// This function is intended for custom server implementations. func (ctx *RequestCtx) TimeoutErrMsg() string { return ctx.timeoutErrMsg } @@ -69,8 +69,6 @@ func (x *URI) Host() []byte { } // Parse initializes URI from the given host and uri. -// -// It is safe modifying host and uri buffers after the Parse call. func (x *URI) Parse(host, uri []byte) { x.parse(host, uri, nil) } |