handler

Documentation

Overview

Defines HTTP handlers.

Index

• type Handler
  • func DELETE() *Handler
  • func GET() *Handler
  • func New(verb string) *Handler
  • func POST() *Handler
  • func (h Handler) Exec(a *arg.Args, w http.ResponseWriter, r *http.Request)
  • func (h Handler) HandlePanic(w http.ResponseWriter, err any)
  • func (h Handler) Help(p *message.Printer) []string
  • func (h Handler) Hidden() bool
  • func (h *Handler) IsHidden() *Handler
  • func (h Handler) IsRaw() bool
  • func (h Handler) Method() string
  • func (h Handler) ParamSpec(f *message.Printer) []hap.ParamSpec
  • func (h Handler) ReplySpec() []hap.ReplySpec
  • func (h Handler) Tags() url.Values
  • func (h Handler) ValidateArgs(raw url.Values, arg *arg.Args) (string, []any)
  • func (h *Handler) WithActions(acts ...hap.Action) *Handler
  • func (h *Handler) WithHelp(text string, args ...any) *Handler
  • func (h *Handler) WithParams(ps ...param.Param) *Handler
  • func (h *Handler) WithReplySpec(rs ...hap.ReplySpec) *Handler
  • func (h *Handler) WithTags(tags ...tag.Tag) *Handler

Types

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler handles HTTP requests. In HAP terminology, an HTTP endpoint is called an API. An API can have one or more handlers, each associated with an HTTP verb such as GET or POST.

func DELETE

func DELETE() *Handler

Shortcut for New("DELETE")

func GET

func GET() *Handler

Shortcut for New("GET")

func New

func New(verb string) *Handler

New creates and returns a new Handler with the specified HTTP verb. The `verb` parameter should be a standard HTTP action name, such as GET or POST.

By default, the handler is configured to reply in raw format and uses the internal.RawPanicHandler for error management.

func POST

func POST() *Handler

Shortcut for New("POST")

func (Handler) Exec

func (h Handler) Exec(a *arg.Args, w http.ResponseWriter, r *http.Request)

Exec is the core of Handler, which is called by the framework directly to handle requests. See "Actions" section in the HAP specification for details.

func (Handler) HandlePanic

func (h Handler) HandlePanic(w http.ResponseWriter, err any)

When a panic (exception) occurs in the business code, the framework calls the HandlePanic function. This function performs the following steps:

1. Generates a call stack trace.
2. Calls internal.LogPanic to log the error message and call stack trace.
3. Uses the PanicHandler defined in the Handler to send the error message to the client.

func (Handler) Help

func (h Handler) Help(p *message.Printer) []string

Returns a localized help message for the Handler. The message is returned as a slice of strings, where each string represents a paragraph.

If a message.Printer is provided, the help message is localized using it. Otherwise, it is formatted using fmt.Sprintf. The result is then split into paragraphs.

func (Handler) Hidden

func (h Handler) Hidden() bool

A hidden Handler will not be shown in the documentation.

func (*Handler) IsHidden

func (h *Handler) IsHidden() *Handler

Set a Handler to be hidden.

func (Handler) IsRaw

func (h Handler) IsRaw() bool

IsRaw returns whether the Handler is in RAW mode. If the Handler is defined as RAW mode, it can return any data type. Otherwise, it can only return JSON-formatted content as per HAP specification. See Handler.WithReplySpec for more details.

func (Handler) Method

func (h Handler) Method() string

Returns the HTTP verb of the Handler, which is used in auto-generated API documentation.

func (Handler) ParamSpec

func (h Handler) ParamSpec(f *message.Printer) []hap.ParamSpec

Generates a slice of hap.ParamSpec used to generate API documentation. If a message.Printer is provided, it is used to localize the documentation.

func (Handler) ReplySpec

func (h Handler) ReplySpec() []hap.ReplySpec

Returns a slice of hap.ReplySpec used to provide sample responses in the API documentation.

func (Handler) Tags

func (h Handler) Tags() url.Values

Tags are used to categorize APIs in the documentation. See tag.Tag for details.

func (Handler) ValidateArgs

func (h Handler) ValidateArgs(raw url.Values, arg *arg.Args) (string, []any)

Called by the framework internally during argument processing. See "Arguments" section in the HAP specification for details.

func (*Handler) WithActions

func (h *Handler) WithActions(acts ...hap.Action) *Handler

Add business logic functions to the Handler. A handler can have multiple actions which are executed one after another. The output of the previous action affects whether the next action is executed. See hap.Action for details.

func (*Handler) WithHelp

func (h *Handler) WithHelp(text string, args ...any) *Handler

Documents the Handler with information about its purpose and usage.

func (*Handler) WithParams

func (h *Handler) WithParams(ps ...param.Param) *Handler

Defines parameters of the Handler. See param.Param for details.

func (*Handler) WithReplySpec

func (h *Handler) WithReplySpec(rs ...hap.ReplySpec) *Handler

Add reply samples to the handler. See hap.ReplySpec for details.

func (*Handler) WithTags

func (h *Handler) WithTags(tags ...tag.Tag) *Handler

Add tags to the Handler. Tags are used to categorize APIs in the documentation. See tag.Tag for details.