Headers

ctx.Response.Headers allows to consult, add, modify and remove HTTP headers that will be sent to the client.

The headers allow to control the behavior of the response, such as the type of content, cache storage or any custom header. Redirect, To manipulate cookies, use the API Cookies..

This object only manages the headers of the current response. To consult the headers sent by the client use Request Headers.

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Set("Content-Type", "text/plain")

    return "Hola George"
}

In this example the page returns a string of text. To know all the types of values that a page can return query Return values.

Structure

ctx.Response.Headers implement the following API:

Headers
{
    Get(key string) (string, bool)
    GetAll(key string) ([]string, bool)
    Set(key, value string)
    Append(key, value string)
    Delete(key string)
    Has(key string) bool
    Contains(key, value string) bool
    IsEmpty() bool
    Count() int
    Keys() []string
    Values() []string
    Entries() map[string][]string
}

Methods

Get()

Firma:func (Headers) Get(key string) (string, bool)

Get() returns the first value associated with a header and indicates whether the header exists.

func GET(ctx *gox.Context) gox.Page {
    contentType, ok := ctx.Response.Headers.Get("Content-Type")

    if !ok {
        return <p>Content-Type not configured</p>
    }

    return <p>{{ contentType }}</p>
}

When the header does not exist, it returns an empty string and false.

When a header contains several values, Get() return only the first one.

Use Get() when you only need the first value associated with a header.

GetAll()

Firma:func (Headers) GetAll(key string) ([]string, bool)

GetAll() returns all the values associated with a header and indicates whether the header exists.

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Append("Vary", "Accept-Encoding")
    ctx.Response.Headers.Append("Vary", "Accept-Language")

    vary, ok := ctx.Response.Headers.GetAll("Vary")

    if !ok {
        return <p>Vary header not configured</p>
    }

    return <ul>
        <:for value range={{ vary }}>
            <li>{{ value }}</li>
        </:for>
    </ul>
}

When the header does not exist or contains values, it returns nil and false.

The returned slice is an independent copy. Modifying it does not change the response headers.

Use GetAll() when you need to access all the values associated with a header.

Set()

Firma:func (Headers) Set(key, value string)

Set() sets the value of a header.

If the header already exists, all its previous values are replaced by the new value.

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Set("Content-Type", "text/plain")
    ctx.Response.Headers.Set("Content-Type", "text/html")

    return <p>Hello George</p>
}

The header contains only the last established value.

Content-Type: text/html

Use Set() where a header must contain a single value.

Append()

Firma:func (Headers) Append(key, value string)

Append() add a new value to a header without removing existing values.

If the header does not exist, it is created automatically.

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Append("Vary", "Accept-Encoding")
    ctx.Response.Headers.Append("Vary", "Accept-Language")

    return <p>Hello George</p>
}

The header contains both values after running the two operations.

Vary: Accept-Encoding
Vary: Accept-Language

Use Append() where a header can contain several values.

If you need to replace all existing values, use Set().

Delete()

Firma:func (Headers) Delete(key string)

Delete() removes a header along with all its associated values.

If the header does not exist, the operation does not produce any effect.

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Set("Cache-Control", "public")
    ctx.Response.Headers.Delete("Cache-Control")

    return <p>Hello George</p>
}

After running Delete()the header is no longer part of the response.

Use Delete() when you need to remove a previously configured header.

Has()

Firma:func (Headers) Has(key string) bool

Has() indicates if a header exists.

func GET(ctx *gox.Context) gox.Page {
    if ctx.Response.Headers.Has("Location") {
        return <p>Redirect configured</p>
    }

    return <p>No redirect configured</p>
}

Use Has() when you only need to check if a header exists.

Contains()

Firma:func (Headers) Contains(key, value string) bool

Contains() indicates whether a header contains a certain value.

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Append("Vary", "Accept-Encoding")
    ctx.Response.Headers.Append("Vary", "Accept-Language")

    if ctx.Response.Headers.Contains("Vary", "Accept-Language") {
        return <p>Header found</p>
    }

    return <p>Header not found</p>
}

Use Contains() when you need to check if a header contains a specific value.

IsEmpty()

Firma:func (Headers) IsEmpty() bool

IsEmpty() indicates whether the collection contains headers.

func GET(ctx *gox.Context) gox.Page {
    if ctx.Response.Headers.IsEmpty() {
        return <p>No headers configured</p>
    }

    return <p>Headers configured</p>
}

Returns true when there is no header and false otherwise.

Count()

Firma:func (Headers) Count() int

Count() returns the number of headers available.

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Set("Content-Type", "text/html")
    ctx.Response.Headers.Set("Cache-Control", "no-store")
    ctx.Response.Headers.Append("Vary", "Accept-Encoding")

    total := ctx.Response.Headers.Count()

    return <p>{{ total }}</p>
}

Each header is counted once, regardless of the number of associated values.

Keys()

Firma:func (Headers) Keys() []string

Keys() returns all the keys to the collection.

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Set("Content-Type", "text/html")
    ctx.Response.Headers.Set("Cache-Control", "no-store")
    ctx.Response.Headers.Append("Vary", "Accept-Encoding")

    keys := ctx.Response.Headers.Keys()

    return <ul>
        <:for key range={{ keys }}>
            <li>{{ key }}</li>
        </:for>
    </ul>
}

The returned slice is an independent copy. Modifying it does not change the response headers.

Values()

Firma:func (Headers) Values() []string

Values() returns the first value associated with each header.

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Set("Content-Type", "text/html")
    ctx.Response.Headers.Set("Cache-Control", "no-store")
    ctx.Response.Headers.Append("Vary", "Accept-Encoding")
    ctx.Response.Headers.Append("Vary", "Accept-Language")

    values := ctx.Response.Headers.Values()

    return <ul>
        <:for value range={{ values }}>
            <li>{{ value }}</li>
        </:for>
    </ul>
}

When a header contains several values, only the first one is returned.

The returned slice is an independent copy. Modifying it does not change the response headers.

Entries()

Firma:func (Headers) Entries() map[string][]string

Entries() returns all headers along with all their associated values.

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Set("Content-Type", "text/html")
    ctx.Response.Headers.Set("Cache-Control", "no-store")
    ctx.Response.Headers.Append("Vary", "Accept-Encoding")
    ctx.Response.Headers.Append("Vary", "Accept-Language")

    headers := ctx.Response.Headers.Entries()

    return <pre>{{ headers }}</pre>
}

The returned map is a separate copy. Modifying it does not change the response headers.

Use Entries() when you need access to the whole header collection.

Full example

func GET(ctx *gox.Context) gox.Page {
    ctx.Response.Headers.Set("Content-Type", "text/html")
    ctx.Response.Headers.Set("Cache-Control", "no-store")
    ctx.Response.Headers.Append("Vary", "Accept-Encoding")
    ctx.Response.Headers.Append("Vary", "Accept-Language")

    if ctx.Response.Headers.Contains("Vary", "Accept-Language") {
        ctx.Response.Headers.Set("X-Example", "true")
    }

    return <h1>Hello George</h1>
}

Best practices

• Use Set() for headers which only have to contain a value.
• Use Append() where a header can contain several values.
• It checks the existence of a header with Has() before using its value when necessary.
• Use GetAll() when you need to access all the values of a header.
• Use GetAll() when you need to access all the values of a header.
• Avoid changing the same header from different parts of the application.
• Avoid using the header Location to redirect. Instead, use the API Redirect.
• Avoid modifying cookies using the API Headers. To do this, use the API Cookies.

See also

• Request Headers
• Cookies
• Redirect