Improve return value reusability documentation

args.go

@@ -110,7 +110,8 @@ func (a *Args) String() string {
 
 // QueryString returns query string for the args.
 //
-// The returned value is valid until the next call to Args methods.
+// The returned value is valid until the Args is reused or released (ReleaseArgs).
+// Do not store references to the returned value. Make copies instead.
 func (a *Args) QueryString() []byte {
 	a.buf = a.AppendBytes(a.buf[:0])
 	return a.buf
@@ -241,14 +242,16 @@ func (a *Args) SetBytesKNoValue(key []byte) {
 
 // Peek returns query arg value for the given key.
 //
-// Returned value is valid until the next Args call.
+// The returned value is valid until the Args is reused or released (ReleaseArgs).
+// Do not store references to the returned value. Make copies instead.
 func (a *Args) Peek(key string) []byte {
 	return peekArgStr(a.args, key)
 }
 
 // PeekBytes returns query arg value for the given key.
 //
-// Returned value is valid until the next Args call.
+// The returned value is valid until the Args is reused or released (ReleaseArgs).
+// Do not store references to the returned value. Make copies instead.
 func (a *Args) PeekBytes(key []byte) []byte {
 	return peekArgBytes(a.args, key)
 }

cookie.go

@@ -149,7 +149,8 @@ func (c *Cookie) SetPathBytes(path []byte) {
 
 // Domain returns cookie domain.
 //
-// The returned domain is valid until the next Cookie modification method call.
+// The returned value is valid until the Cookie reused or released (ReleaseCookie).
+// Do not store references to the returned value. Make copies instead.
 func (c *Cookie) Domain() []byte {
 	return c.domain
 }
@@ -201,7 +202,8 @@ func (c *Cookie) SetExpire(expire time.Time) {
 
 // Value returns cookie value.
 //
-// The returned value is valid until the next Cookie modification method call.
+// The returned value is valid until the Cookie reused or released (ReleaseCookie).
+// Do not store references to the returned value. Make copies instead.
 func (c *Cookie) Value() []byte {
 	return c.value
 }
@@ -218,7 +220,8 @@ func (c *Cookie) SetValueBytes(value []byte) {
 
 // Key returns cookie name.
 //
-// The returned value is valid until the next Cookie modification method call.
+// The returned value is valid until the Cookie reused or released (ReleaseCookie).
+// Do not store references to the returned value. Make copies instead.
 func (c *Cookie) Key() []byte {
 	return c.key
 }
@@ -306,7 +309,8 @@ func (c *Cookie) AppendBytes(dst []byte) []byte {
 
 // Cookie returns cookie representation.
 //
-// The returned value is valid until the next call to Cookie methods.
+// The returned value is valid until the Cookie reused or released (ReleaseCookie).
+// Do not store references to the returned value. Make copies instead.
 func (c *Cookie) Cookie() []byte {
 	c.buf = c.AppendBytes(c.buf[:0])
 	return c.buf

fs_test.go

@@ -60,7 +60,7 @@ func TestNewVHostPathRewriterMaliciousHost(t *testing.T) {
 
 	f := NewVHostPathRewriter(0)
 	path := f(&ctx)
-	expectedPath := "/invalid-host/foo/bar/baz"
+	expectedPath := "/invalid-host/"
 	if string(path) != expectedPath {
 		t.Fatalf("unexpected path %q. Expecting %q", path, expectedPath)
 	}

header.go

@@ -1306,16 +1306,18 @@ func (h *RequestHeader) SetCanonical(key, value []byte) {
 
 // Peek returns header value for the given key.
 //
-// Returned value is valid until the next call to ResponseHeader.
-// Do not store references to returned value. Make copies instead.
+// The returned value is valid until the response is released,
+// either though ReleaseResponse or your request handler returning.
+// Do not store references to the returned value. Make copies instead.
 func (h *ResponseHeader) Peek(key string) []byte {
 	k := getHeaderKeyBytes(&h.bufKV, key, h.disableNormalizing)
 	return h.peek(k)
 }
 
 // PeekBytes returns header value for the given key.
 //
-// Returned value is valid until the next call to ResponseHeader.
+// The returned value is valid until the response is released,
+// either though ReleaseResponse or your request handler returning.
 // Do not store references to returned value. Make copies instead.
 func (h *ResponseHeader) PeekBytes(key []byte) []byte {
 	h.bufKV.key = append(h.bufKV.key[:0], key...)
@@ -1325,7 +1327,8 @@ func (h *ResponseHeader) PeekBytes(key []byte) []byte {
 
 // Peek returns header value for the given key.
 //
-// Returned value is valid until the next call to RequestHeader.
+// The returned value is valid until the request is released,
+// either though ReleaseRequest or your request handler returning.
 // Do not store references to returned value. Make copies instead.
 func (h *RequestHeader) Peek(key string) []byte {
 	k := getHeaderKeyBytes(&h.bufKV, key, h.disableNormalizing)
@@ -1334,7 +1337,8 @@ func (h *RequestHeader) Peek(key string) []byte {
 
 // PeekBytes returns header value for the given key.
 //
-// Returned value is valid until the next call to RequestHeader.
+// The returned value is valid until the request is released,
+// either though ReleaseRequest or your request handler returning.
 // Do not store references to returned value. Make copies instead.
 func (h *RequestHeader) PeekBytes(key []byte) []byte {
 	h.bufKV.key = append(h.bufKV.key[:0], key...)
@@ -1615,7 +1619,9 @@ func (h *ResponseHeader) WriteTo(w io.Writer) (int64, error) {
 
 // Header returns response header representation.
 //
-// The returned value is valid until the next call to ResponseHeader methods.
+// The returned value is valid until the request is released,
+// either though ReleaseRequest or your request handler returning.
+// Do not store references to returned value. Make copies instead.
 func (h *ResponseHeader) Header() []byte {
 	h.bufKV.value = h.AppendBytes(h.bufKV.value[:0])
 	return h.bufKV.value
@@ -1697,7 +1703,9 @@ func (h *RequestHeader) WriteTo(w io.Writer) (int64, error) {
 
 // Header returns request header representation.
 //
-// The returned representation is valid until the next call to RequestHeader methods.
+// The returned value is valid until the request is released,
+// either though ReleaseRequest or your request handler returning.
+// Do not store references to returned value. Make copies instead.
 func (h *RequestHeader) Header() []byte {
 	h.bufKV.value = h.AppendBytes(h.bufKV.value[:0])
 	return h.bufKV.value

http.go

@@ -320,7 +320,9 @@ func (resp *Response) LocalAddr() net.Addr {
 
 // Body returns response body.
 //
-// The returned body is valid until the response modification.
+// The returned value is valid until the response is released,
+// either though ReleaseResponse or your request handler returning.
+// Do not store references to returned value. Make copies instead.
 func (resp *Response) Body() []byte {
 	if resp.bodyStream != nil {
 		bodyBuf := resp.bodyBuffer()
@@ -638,7 +640,9 @@ func (req *Request) SwapBody(body []byte) []byte {
 
 // Body returns request body.
 //
-// The returned body is valid until the request modification.
+// The returned value is valid until the request is released,
+// either though ReleaseRequest or your request handler returning.
+// Do not store references to returned value. Make copies instead.
 func (req *Request) Body() []byte {
 	if req.bodyRaw != nil {
 		return req.bodyRaw

server.go

@@ -859,40 +859,42 @@ func (ctx *RequestCtx) SetContentTypeBytes(contentType []byte) {
 
 // RequestURI returns RequestURI.
 //
-// This uri is valid until returning from RequestHandler.
+// The returned bytes are valid until your request handler returns.
 func (ctx *RequestCtx) RequestURI() []byte {
 	return ctx.Request.Header.RequestURI()
 }
 
 // URI returns requested uri.
 //
-// The uri is valid until returning from RequestHandler.
+// This uri is valid until your request handler returns.
 func (ctx *RequestCtx) URI() *URI {
 	return ctx.Request.URI()
 }
 
 // Referer returns request referer.
 //
-// The referer is valid until returning from RequestHandler.
+// The returned bytes are valid until your request handler returns.
 func (ctx *RequestCtx) Referer() []byte {
 	return ctx.Request.Header.Referer()
 }
 
 // UserAgent returns User-Agent header value from the request.
+//
+// The returned bytes are valid until your request handler returns.
 func (ctx *RequestCtx) UserAgent() []byte {
 	return ctx.Request.Header.UserAgent()
 }
 
 // Path returns requested path.
 //
-// The path is valid until returning from RequestHandler.
+// The returned bytes are valid until your request handler returns.
 func (ctx *RequestCtx) Path() []byte {
 	return ctx.URI().Path()
 }
 
 // Host returns requested host.
 //
-// The host is valid until returning from RequestHandler.
+// The returned bytes are valid until your request handler returns.
 func (ctx *RequestCtx) Host() []byte {
 	return ctx.URI().Host()
 }
@@ -901,9 +903,9 @@ func (ctx *RequestCtx) Host() []byte {
 //
 // It doesn't return POST'ed arguments - use PostArgs() for this.
 //
-// Returned arguments are valid until returning from RequestHandler.
-//
 // See also PostArgs, FormValue and FormFile.
+//
+// These args are valid until your request handler returns.
 func (ctx *RequestCtx) QueryArgs() *Args {
 	return ctx.URI().QueryArgs()
 }
@@ -912,9 +914,9 @@ func (ctx *RequestCtx) QueryArgs() *Args {
 //
 // It doesn't return query arguments from RequestURI - use QueryArgs for this.
 //
-// Returned arguments are valid until returning from RequestHandler.
-//
 // See also QueryArgs, FormValue and FormFile.
+//
+// These args are valid until your request handler returns.
 func (ctx *RequestCtx) PostArgs() *Args {
 	return ctx.Request.PostArgs()
 }
@@ -930,7 +932,7 @@ func (ctx *RequestCtx) PostArgs() *Args {
 //
 // Use SaveMultipartFile function for permanently saving uploaded file.
 //
-// The returned form is valid until returning from RequestHandler.
+// The returned form is valid until your request handler returns.
 //
 // See also FormFile and FormValue.
 func (ctx *RequestCtx) MultipartForm() (*multipart.Form, error) {
@@ -944,7 +946,7 @@ func (ctx *RequestCtx) MultipartForm() (*multipart.Form, error) {
 //
 // Use SaveMultipartFile function for permanently saving uploaded file.
 //
-// The returned file header is valid until returning from RequestHandler.
+// The returned file header is valid until your request handler returns.
 func (ctx *RequestCtx) FormFile(key string) (*multipart.FileHeader, error) {
 	mf, err := ctx.MultipartForm()
 	if err != nil {
@@ -1028,7 +1030,7 @@ func SaveMultipartFile(fh *multipart.FileHeader, path string) (err error) {
 //   * MultipartForm for obtaining values from multipart form.
 //   * FormFile for obtaining uploaded files.
 //
-// The returned value is valid until returning from RequestHandler.
+// The returned value is valid until your request handler returns.
 func (ctx *RequestCtx) FormValue(key string) []byte {
 	v := ctx.QueryArgs().Peek(key)
 	if len(v) > 0 {
@@ -1090,7 +1092,7 @@ func (ctx *RequestCtx) IsPatch() bool {
 
 // Method return request method.
 //
-// Returned value is valid until returning from RequestHandler.
+// Returned value is valid until your request handler returns.
 func (ctx *RequestCtx) Method() []byte {
 	return ctx.Request.Header.Method()
 }
@@ -1336,7 +1338,7 @@ func (ctx *RequestCtx) WriteString(s string) (int, error) {
 
 // PostBody returns POST request body.
 //
-// The returned value is valid until RequestHandler return.
+// The returned bytes are valid until your request handler returns.
 func (ctx *RequestCtx) PostBody() []byte {
 	return ctx.Request.Body()
 }
@@ -1386,7 +1388,7 @@ func (ctx *RequestCtx) IsBodyStream() bool {
 // It is safe re-using returned logger for logging multiple messages
 // for the current request.
 //
-// The returned logger is valid until returning from RequestHandler.
+// The returned logger is valid until your request handler returns.
 func (ctx *RequestCtx) Logger() Logger {
 	if ctx.logger.ctx == nil {
 		ctx.logger.ctx = ctx

uri.go

@@ -89,7 +89,7 @@ func (u *URI) CopyTo(dst *URI) {
 
 // Hash returns URI hash, i.e. qwe of http://aaa.com/foo/bar?baz=123#qwe .
 //
-// The returned value is valid until the next URI method call.
+// The returned bytes are valid until the next URI method call.
 func (u *URI) Hash() []byte {
 	return u.hash
 }
@@ -105,6 +105,8 @@ func (u *URI) SetHashBytes(hash []byte) {
 }
 
 // Username returns URI username
+//
+// The returned bytes are valid until the next URI method call.
 func (u *URI) Username() []byte {
 	return u.username
 }
@@ -120,6 +122,8 @@ func (u *URI) SetUsernameBytes(username []byte) {
 }
 
 // Password returns URI password
+//
+// The returned bytes are valid until the next URI method call.
 func (u *URI) Password() []byte {
 	return u.password
 }
@@ -137,7 +141,7 @@ func (u *URI) SetPasswordBytes(password []byte) {
 // QueryString returns URI query string,
 // i.e. baz=123 of http://aaa.com/foo/bar?baz=123#qwe .
 //
-// The returned value is valid until the next URI method call.
+// The returned bytes are valid until the next URI method call.
 func (u *URI) QueryString() []byte {
 	return u.queryString
 }
@@ -159,7 +163,7 @@ func (u *URI) SetQueryStringBytes(queryString []byte) {
 // The returned path is always urldecoded and normalized,
 // i.e. '//f%20obar/baz/../zzz' becomes '/f obar/zzz'.
 //
-// The returned value is valid until the next URI method call.
+// The returned bytes are valid until the next URI method call.
 func (u *URI) Path() []byte {
 	path := u.path
 	if len(path) == 0 {
@@ -182,7 +186,7 @@ func (u *URI) SetPathBytes(path []byte) {
 
 // PathOriginal returns the original path from requestURI passed to URI.Parse().
 //
-// The returned value is valid until the next URI method call.
+// The returned bytes are valid until the next URI method call.
 func (u *URI) PathOriginal() []byte {
 	return u.pathOriginal
 }
@@ -191,7 +195,7 @@ func (u *URI) PathOriginal() []byte {
 //
 // Returned scheme is always lowercased.
 //
-// The returned value is valid until the next URI method call.
+// The returned bytes are valid until the next URI method call.
 func (u *URI) Scheme() []byte {
 	scheme := u.scheme
 	if len(scheme) == 0 {
@@ -237,6 +241,8 @@ func (u *URI) Reset() {
 // Host returns host part, i.e. aaa.com of http://aaa.com/foo/bar?baz=123#qwe .
 //
 // Host is always lowercased.
+//
+// The returned bytes are valid until the next URI method call.
 func (u *URI) Host() []byte {
 	return u.host
 }
@@ -645,6 +651,8 @@ func (u *URI) RequestURI() []byte {
 //    * For /foo/bar/baz.html path returns baz.html.
 //    * For /foo/bar/ returns empty byte slice.
 //    * For /foobar.js returns foobar.js.
+//
+// The returned bytes are valid until the next URI method call.
 func (u *URI) LastPathSegment() []byte {
 	path := u.Path()
 	n := bytes.LastIndexByte(path, '/')
@@ -746,6 +754,8 @@ func (u *URI) updateBytes(newURI, buf []byte) []byte {
 }
 
 // FullURI returns full uri in the form {Scheme}://{Host}{RequestURI}#{Hash}.
+//
+// The returned bytes are valid until the next URI method call.
 func (u *URI) FullURI() []byte {
 	u.fullURI = u.AppendBytes(u.fullURI[:0])
 	return u.fullURI
@@ -812,6 +822,8 @@ func splitHostURI(host, uri []byte) ([]byte, []byte, []byte) {
 }
 
 // QueryArgs returns query args.
+//
+// The returned args are valid until the next URI method call.
 func (u *URI) QueryArgs() *Args {
 	u.parseQueryArgs()
 	return &u.queryArgs