ETag

Hertz provides Etag middleware that can operate on ETag.

The ETag (or entity tag) HTTP response header is an identifier for a specific version of a resource. It lets caches be more efficient and save bandwidth, as a web server does not need to resend a full response if the content was not changed. Additionally, etags help to prevent simultaneous updates of a resource from overwriting each other (“mid-air collisions”). Hertz also provides Etag middleware that can operate on ETag, inspired by fiber’s implementation.

Install

Download and install

go get github.com/hertz-contrib/etag

Import into your code

import "github.com/hertz-contrib/etag"

Example

package main

import (
    "context"
    "net/http"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/etag"
)

func main() {
    h := server.Default()
    h.Use(etag.New())
    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        c.String(http.StatusOK, "pong")
    })
    h.Spin()
}

Configuration

Configuration Default Description
WithWeak false Enable weak validator
WithNext nil Defines a function to skip etag middleware when return is true
WithGenerator nil Custom etag generation logic

WithWeak

WithWeak will enable weak validator for ETag.

Function Signature:

func WithWeak() Option

Sample Code:

package main

import (
    "context"
    "net/http"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/etag"
)

func main() {
    h := server.Default()
    h.Use(etag.New(etag.WithWeak()))
    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        c.String(http.StatusOK, "pong")
    })
    h.Spin()
}

WithNext

WithNext will skip etag middleware when the defined function returns true.

Function Signature:

func WithNext(next NextFunc) Option

Sample Code:

package main

import (
    "context"
    "net/http"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/etag"
)

func main() {
    h := server.Default()
    h.Use(etag.New(etag.WithNext(
        func(ctx context.Context, c *app.RequestContext) bool {
            if string(c.Method()) == http.MethodPost {
                return true
            } else {
                return false
            }
        },
    )))
    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        c.String(http.StatusOK, "pong")
    })
    h.Spin()
}

WithGenerator

WithGenerator will replace default ETag generation with yours.

Note: you should not add W/ prefix to your custom ETag when used with WithWeak.

Function Signature:

func WithGenerator(gen Generator) Option

Sample Code:

package main

import (
    "context"
    "net/http"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/etag"
)

func main() {
    h := server.Default()
    h.Use(etag.New(etag.WithGenerator(
        func(ctx context.Context, c *app.RequestContext) []byte {
            return []byte("my-custom-etag")
        },
    )))
    h.GET("/ping", func(ctx context.Context, c *app.RequestContext) {
        c.String(http.StatusOK, "pong")
    })
    h.Spin()
}

Full Example

Refer to the etag/example for full usage examples.


Last modified July 24, 2024 : docs: fix error in render (#1110) (34e4f87)