Handler is a middleware for HTTP/2 server push. Note that HTTP/2 server push has been deprecated by some clients and its use is discouraged unless you can accurately predict which resources actually need to be pushed to the client; it can be difficult to know what the client already has cached. Pushing unnecessary resources results in worse performance. Consider using HTTP 103 Early Hints instead.

This handler supports pushing from Link headers; in other words, if the eventual response has Link headers, this handler will push the resources indicated by those headers, even without specifying any resources in its config.

type Handler struct {
	// The resources to push.
	Resources	[]Resource	`json:"resources,omitempty"`

	// Headers to modify for the push requests.
	Headers	*HeaderConfig	`json:"headers,omitempty"`

	logger	*zap.Logger
}

HeaderConfig configures headers for synthetic push requests.

type HeaderConfig struct {
	headers.HeaderOps
}

Resource represents a request for a resource to push.

type Resource struct {
	// Method is the request method, which must be GET or HEAD.
	// Default is GET.
	Method	string	`json:"method,omitempty"`

	// Target is the path to the resource being pushed.
	Target	string	`json:"target,omitempty"`
}

linkPusher is a http.ResponseWriter that intercepts the WriteHeader() call to ensure that any resources described by Link response headers get pushed before the response is allowed to be written.

type linkPusher struct {
	*caddyhttp.ResponseWriterWrapper
	handler	Handler
	pusher	http.Pusher
	header	http.Header
	request	*http.Request
}

linkResource contains the results of a parsed Link header.

type linkResource struct {
	uri	string
	params	map[string]string
}

Provision sets up h.

func (h *Handler) Provision(ctx caddy.Context) error {
	h.logger = ctx.Logger()
	if h.Headers != nil {
		err := h.Headers.Provision(ctx)
		if err != nil {
			return fmt.Errorf("provisioning header operations: %v", err)
		}
	}
	return nil
}

Cognitive complexity: 4, Cyclomatic complexity: 3

CaddyModule returns the Caddy module information.

func (Handler) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:	"http.handlers.push",
		New:	func() caddy.Module { return new(Handler) },
	}
}

Cognitive complexity: 2, Cyclomatic complexity: 1

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error {
	pusher, ok := w.(http.Pusher)
	if !ok {
		return next.ServeHTTP(w, r)
	}

	// short-circuit recursive pushes
	if _, ok := r.Header[pushHeader]; ok {
		return next.ServeHTTP(w, r)
	}

	repl := r.Context().Value(caddy.ReplacerCtxKey).(*caddy.Replacer)
	server := r.Context().Value(caddyhttp.ServerCtxKey).(*caddyhttp.Server)
	shouldLogCredentials := server.Logs != nil && server.Logs.ShouldLogCredentials

	// create header for push requests
	hdr := h.initializePushHeaders(r, repl)

	// push first!
	for _, resource := range h.Resources {
		if c := h.logger.Check(zapcore.DebugLevel, "pushing resource"); c != nil {
			c.Write(
				zap.String("uri", r.RequestURI),
				zap.String("push_method", resource.Method),
				zap.String("push_target", resource.Target),
				zap.Object("push_headers", caddyhttp.LoggableHTTPHeader{
					Header:			hdr,
					ShouldLogCredentials:	shouldLogCredentials,
				}),
			)
		}
		err := pusher.Push(repl.ReplaceAll(resource.Target, "."), &http.PushOptions{
			Method:	resource.Method,
			Header:	hdr,
		})
		if err != nil {
			// usually this means either that push is not
			// supported or concurrent streams are full
			break
		}
	}

	// wrap the response writer so that we can initiate push of any resources
	// described in Link header fields before the response is written
	lp := linkPusher{
		ResponseWriterWrapper:	&caddyhttp.ResponseWriterWrapper{ResponseWriter: w},
		handler:		h,
		pusher:			pusher,
		header:			hdr,
		request:		r,
	}

	// serve only after pushing!
	if err := next.ServeHTTP(lp, r); err != nil {
		return err
	}

	return nil
}

Cognitive complexity: 17, Cyclomatic complexity: 8

func (lp linkPusher) WriteHeader(statusCode int) {
	if links, ok := lp.ResponseWriter.Header()["Link"]; ok {
		// only initiate these pushes if it hasn't been done yet
		if val := caddyhttp.GetVar(lp.request.Context(), pushedLink); val == nil {
			if c := lp.handler.logger.Check(zapcore.DebugLevel, "pushing Link resources"); c != nil {
				c.Write(zap.Strings("linked", links))
			}
			caddyhttp.SetVar(lp.request.Context(), pushedLink, true)
			lp.handler.servePreloadLinks(lp.pusher, lp.header, links)
		}
	}
	lp.ResponseWriter.WriteHeader(statusCode)
}

Cognitive complexity: 6, Cyclomatic complexity: 4