hooks

Documentation

Overview

Package hooks allows you to execute hooks based on events emitted from the tusd handler using the callbacks and notification channels. The actual hook systems are implemented in the subpackages and this package provides the glue betwen the tusd handler and the hook system. For example, to use the HTTP-based hook system:

import (
	"github.com/tus/tusd/v2/pkg/handler"
	"github.com/tus/tusd/v2/pkg/hooks"
	"github.com/tus/tusd/v2/pkg/hooks/http"
)
config := handler.Config{}
hookHandler := http.HttpHook{
	Endpoint: "https://example.com"
}
handler, err = hooks.NewHandlerWithHooks(&config, hookHandler, hooks.AvailableHooks)

More details can be found in the documentation at github.com/tus/tusd/docs/hooks.md

Index

• Variables
• func NewHandlerWithHooks(config *handler.Config, hookHandler HookHandler, enabledHooks []HookType) (*handler.Handler, error)
• func SetupHookMetrics()
• type HookHandler
• type HookRequest
• type HookResponse
• type HookType

Variables

var AvailableHooks []HookType = []HookType{HookPreCreate, HookPostCreate, HookPostReceive, HookPostTerminate, HookPostFinish, HookPreFinish}

AvailableHooks is a slice of all hooks that are implemented by tusd.

var MetricsHookErrorsTotal = prometheus.NewCounterVec(
	prometheus.CounterOpts{
		Name: "tusd_hook_errors_total",
		Help: "Total number of execution errors per hook type.",
	},
	[]string{"hooktype"},
)

var MetricsHookInvocationsTotal = prometheus.NewCounterVec(
	prometheus.CounterOpts{
		Name: "tusd_hook_invocations_total",
		Help: "Total number of invocations per hook type.",
	},
	[]string{"hooktype"},
)

Functions

func NewHandlerWithHooks

func NewHandlerWithHooks(config *handler.Config, hookHandler HookHandler, enabledHooks []HookType) (*handler.Handler, error)

NewHandlerWithHooks creates a tusd request handler, whose notifcation channels and callbacks are configured to emit the hooks on the provided hook handler. NewHandlerWithHooks will overwrite the `config.Notify*` and `config.*Callback` fields depending on the enabled hooks. These can be controlled via the `enabledHooks` slice. Non-enabled hooks will not be emitted.

If you want to create an UnroutedHandler instead of the routed handler, you can first create a routed handler and then extract an unrouted one:

routedHandler := hooks.NewHandlerWithHooks(...)
unroutedHandler := routedHandler.UnroutedHandler

Note: NewHandlerWithHooks sets up a goroutine to consume the notfication channels (CompleteUploads, TerminatedUploads, CreatedUploads, UploadProgress) on the created handler. These channels must not be consumed by the caller or otherwise events might not be passed to the hook handler.

func SetupHookMetrics

func SetupHookMetrics()

Types

type HookHandler

type HookHandler interface {
	// Setup is invoked once the hook backend is initalized.
	Setup() error
	// InvokeHook is invoked for every hook that is executed. req contains the
	// corresponding information about the hook type, the involved upload, and
	// causing HTTP request.
	// The return value res allows to stop or reject an upload, as well as modifying
	// the HTTP response. See the documentation for HookResponse for more details.
	// If err is not nil, the value of res will be ignored. err should only be
	// non-nil if the hook failed to complete successfully.
	InvokeHook(req HookRequest) (res HookResponse, err error)
}

HookHandler is the main inferface to be implemented by all hook backends.

type HookRequest

type HookRequest struct {
	// Type is the name of the hook.
	Type HookType
	// Event contains the involved upload and causing HTTP request.
	Event handler.HookEvent
}

HookRequest contains the information about the hook type, the involved upload, and causing HTTP request.

type HookResponse

type HookResponse struct {
	// HTTPResponse's fields can be filled to modify the HTTP response.
	// This is only possible for pre-create, pre-finish and post-receive hooks.
	// For other hooks this value is ignored.
	// If multiple hooks modify the HTTP response, a later hook may overwrite the
	// modified values from a previous hook (e.g. if multiple post-receive hooks
	// are executed).
	// Example usages: Send an error to the client if RejectUpload/StopUpload are
	// set in the pre-create/post-receive hook. Send more information to the client
	// in the pre-finish hook.
	HTTPResponse handler.HTTPResponse

	// RejectUpload will cause the upload to be rejected and not be created during
	// POST request. This value is only respected for pre-create hooks. For other hooks,
	// it is ignored. Use the HTTPResponse field to send details about the rejection
	// to the client.
	RejectUpload bool

	// ChangeFileInfo can be set to change selected properties of an upload before
	// it has been created. See the handler.FileInfoChanges type for more details.
	// Changes are applied on a per-property basis, meaning that specifying just
	// one property leaves all others unchanged.
	// This value is only respected for pre-create hooks.
	ChangeFileInfo handler.FileInfoChanges

	// StopUpload will cause the upload to be stopped during a PATCH request.
	// This value is only respected for post-receive hooks. For other hooks,
	// it is ignored. Use the HTTPResponse field to send details about the stop
	// to the client.
	StopUpload bool
}

HookResponse is the response after a hook is executed.

type HookType

type HookType string

const (
	HookPostFinish    HookType = "post-finish"
	HookPostTerminate HookType = "post-terminate"
	HookPostReceive   HookType = "post-receive"
	HookPostCreate    HookType = "post-create"
	HookPreCreate     HookType = "pre-create"
	HookPreFinish     HookType = "pre-finish"
)