Outdated documentation

You are reading documentation for v3, which is an outdated version. Click here to go to the latest documentation.

# Responses

# Introduction

Handlers receive a goyave.Response and a goyave.Request as parameters.

goyave.Response implements http.ResponseWriter. This object brings a number of convenient methods to write HTTP responses.

If you didn't write anything before the request lifecycle ends, 204 No Content is automatically written.

# Reference

All functions below require the goyave package to be imported.

import "goyave.dev/goyave/v3"

List of response methods:

# Response.GetStatus

Returns the response code for this request or 0 if not yet set.

Parameters Return
int

Example:

fmt.Println(response.GetStatus()) // 200

# Response.GetError

Returns the value which caused a panic in the request's handling, or nil. The response error is also set when Error() is called.

This method is mainly used in status handlers.

Parameters Return
interface{}

Example:

fmt.Println(response.GetError()) // "panic: something wrong happened"

# Response.GetStacktrace

Return the stacktrace of when the error occurred, or an empty string. The stacktrace is captured by the recovery middleware.

Parameters Return
string

Example:

fmt.Println(response.GetStacktrace()) // "goroutine 1 [running]:
									  //  main.main()
									  //	/tmp/sandbox930868764/prog.go:8 +0x39"

# Response.IsEmpty

Return true if nothing has been written to the response body yet.

Parameters Return
bool

Example:

fmt.Println(response.IsEmpty()) // true

# Response.IsHeaderWritten

return true if the response header has been written. Once the response header is written, you cannot change the response status and headers anymore.

Parameters Return
bool

Example:

fmt.Println(response.IsHeaderWritten()) // false

# Response.Header

Returns the Header map that will be sent.

Parameters Return
http.Header

Example:

header := response.Header()
header.Set("Content-Type", "application/json")

# Response.Status

Set the response status code. Calling this method a second time will have no effect.

Parameters Return
status int void

Example:

response.Status(http.StatusOK)

# Response.JSON

Write JSON data as a response. This method automatically sets the Content-Type header.

Parameters Return
responseCode int error
data interface{}

Example:

response.JSON(http.StatusOK, map[string]interface{}{
    "name": "John Doe",
    "tags": []string{"tag1", "tag2"},
})

# Response.String

Write a string as a response.

Parameters Return
responseCode int error
message string

Example:

response.String(http.StatusOK, "Hello there!")

# Response.Write

Write the data as a response. Can be used to write in-memory files. This method can be called successively.

Returns the number of bytes written.

Parameters Return
data []byte int
error

Example:

response.Write([]byte("Hello there!"))

# Response.File

Write a file as an inline element.

Automatically detects the file MIME type and sets the "Content-Type" header accordingly. If the file doesn't exist, respond with status 404 Not Found. The given path can be relative or absolute.

If you want the file to be sent as a download ("Content-Disposition: attachment"), use the Download function instead.

Parameters Return
file string error

Example:

response.File("/path/to/file")

# Response.Download

Write a file as an attachment element.

Automatically detects the file MIME type and sets the "Content-Type" header accordingly. If the file doesn't exist, respond with status 404 Not Found. The given path can be relative or absolute.

The fileName parameter defines the name the client will see. In other words, it sets the header "Content-Disposition" to "attachment; filename="${fileName}""

If you want the file to be sent as an inline element ("Content-Disposition: inline"), use the File function instead.

Parameters Return
file string error
fileName string

Example:

response.Download("/path/to/file", "awesome.txt")

# Response.Error

Print the error in the console and return it with an error code 500.

If debugging is enabled in the config, the error is also written in the response using the JSON format, and the stacktrace is printed in the console. If debugging is not enabled, only the stauts code is set, which means you can still write to the response, or use your error status handler.

Parameters Return
err interface{} error

Example:

v, err := strconv.Atoi("-42")
response.Error(err)

Add a Set-Cookie header to the response. The provided cookie must have a valid Name. Invalid cookies may be silently dropped.

Parameters Return
cookie *http.Cookie* void

Example:

cookie := &http.Cookie{
    Name:  "cookie-name",
    Value: "value",
}
response.Cookie(cookie)

WARNING

Protect yourself from CSRF attacks (opens new window) when using cookies!

# Response.Redirect

Send a permanent redirect response. (HTTP 308)

Parameters Return
url string void

Example:

response.Redirect("/login")

# Response.TemporaryRedirect

Send a temporary redirect response. (HTTP 307)

Parameters Return
url string void

Example:

response.TemporaryRedirect("/maintenance")

# Response.Render

Render a text template with the given data. This method uses the Go's template API (opens new window).

The template path is relative to the resources/template directory.

Parameters Return
responseCode int error
templatePath string
data interface{}

Example:

type Inventory struct {
	Material string
	Count    uint
}

sweaters := Inventory{"wool", 17}

// data can also be a map[string]interface{}
// Here, "resources/template/template.txt" will be used.
if err := response.Render(http.StatusOK, "template.txt", sweaters); err != nil {
	response.Error(err)
}

# Response.RenderHTML

Render an HTML template with the given data. This method uses the Go's template API (opens new window).

The template path is relative to the resources/template directory.

Parameters Return
responseCode int error
templatePath string
data interface{}

Example:

type Inventory struct {
	Material string
	Count    uint
}

sweaters := Inventory{"wool", 17}

// data can also be a map[string]interface{}
// Here, "resources/template/inventory.html" will be used.
if err := response.RenderHTML(http.StatusOK, "inventory.html", sweaters); err != nil {
	response.Error(err)
}

# Response.HandleDatabaseError

Takes a database query result and checks if any error has occurred.

Automatically writes HTTP status code 404 Not Found if the error is a "Not found" error. Calls Response.Error() if there is another type of error.

Returns true if there is no error.

Parameters Return
db *gorm.DB bool

Example:

product := model.Product{}
result := database.Conn().First(&product, id)
if response.HandleDatabaseError(result) {
    response.JSON(http.StatusOK, product)
}

# Chained writers

Since v2.7.0

It is possible to replace the io.Writer used by the Response object. This allows for more flexibility when manipulating the data you send to the client. It makes it easier to compress your response, write it to logs, etc. You can chain as many writers as you want.

Note that at the time your writer's Write() method is called, the request header is already written, therefore, changing headers or status doesn't have any effect. If you want to alter the headers, do so in a PreWrite(b []byte) function (from the goyave.PreWriter interface).

The writer replacement is most often done in a middleware. If your writer implements io.Closer, it will be automatically closed at the end of the request's lifecycle.

The following example is a simple implementation of a middleware logging everything sent by the server to the client.

import (
	"io"
	"log"

	"goyave.dev/goyave/v3"
)

type LogWriter struct {
	writer   io.Writer
	response *goyave.Response
	body     []byte
}

func (w *LogWriter) PreWrite(b []byte) {
	// All chained writers should implement goyave.PreWriter
	// to allow the modification of headers and status before
	// they are written.
	if pr, ok := w.writer.(goyave.PreWriter); ok {
		pr.PreWrite(b)
	}
}

func (w *LogWriter) Write(b []byte) (int, error) {
	w.body = append(w.body, b...)
	return w.writer.Write(b)
}

func (w *LogWriter) Close() error {
    // The chained writer MUST be closed if it's closeable.
	// Therefore, all chained writers should implement io.Closer.

	goyave.Logger.Println("RESPONSE", w.response.GetStatus(), string(w.body))

	if wr, ok := w.writer.(io.Closer); ok {
		return wr.Close()
	}
	return nil
}

func LogMiddleware(next goyave.Handler) goyave.Handler {
	return func(response *goyave.Response, request *goyave.Request) {
		logWriter := &LogWriter{
			writer:   response.Writer(),
			response: response,
		}
		response.SetWriter(logWriter)

		next(response, request)
	}
}

# Response.Writer

Return the current writer used to write the response.

Note that the returned writer is not necessarily a http.ResponseWriter, as it can be replaced using SetWriter.

Parameters Return
io.Writer

# Response.SetWriter

Set the writer used to write the response.

This can be used to chain writers, for example to enable gzip compression, or for logging. The original http.ResponseWriter is always kept.

Parameters Return
writer io.Writer

# Hijack

Since v3.7.0

Goyave responses implement http.Hijacker (opens new window).

# Response.Hijack

Hijack lets the caller take over the connection.

Returns goyave.ErrNotHijackable if the underlying http.ResponseWriter doesn't implement http.Hijacker. This can happen with HTTP/2 connections.

Middleware executed after controller handlers, as well as status handlers, keep working as usual after a connection has been hijacked. Callers should properly set the response status to ensure middleware and status handler execute correctly. Usually, callers of the Hijack method set the HTTP status to http.StatusSwitchingProtocols.

If no status is set, the regular behavior will be kept and 204 No Content will be set as the response status.

Parameters Return
net.Conn
*bufio.ReadWriter
error

# Response.Hijacked

Returns true if the underlying connection has been successfully hijacked via the Hijack method.

Parameters Return
bool