Documentation
¶
Overview ¶
Defines HTTP handlers.
Index ¶
- type 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) []internal.ParametricMessage
- 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) WithRawReply() *Handler
- func (h *Handler) WithReplySpec(rs ...hap.ReplySpec) *Handler
- func (h *Handler) WithTags(tags ...tag.Tag) *Handler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ANY ¶
func ANY() *Handler
Define a "catch-all" handler that is used when no specific handler matches the HTTP request method. This handler serves as a fallback for all unmatched HTTP methods. If a request comes in with a method that does not have a corresponding specific handler (e.g. GET, POST), the framework will use this catch-all handler to process the request. If neither a specific handler nor a catch-all handler is defined, the framework will return a 405 Method Not Allowed response.
func New ¶
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 'HAP-API' format and uses internal.ApiPanicHandler for error handling. To switch the handler's reply mode to 'raw', use the [WithRawReply] method.
For more information on the different reply modes, see the HAP specification.
func (Handler) Exec ¶
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:
- Generates a call stack trace.
- Calls internal.LogPanic to log the error message and call stack trace.
- Uses the PanicHandler defined in the Handler to send the error message to the client.
func (Handler) Help ¶
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 ¶
A hidden Handler will not be shown in the documentation.
func (Handler) IsRaw ¶
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.WithRawReply for more details.
func (Handler) Method ¶
Returns the HTTP verb of the Handler, which is used in auto-generated API documentation.
func (Handler) 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 ¶
Tags are used to categorize APIs in the documentation. See tag.Tag for details.
func (Handler) ValidateArgs ¶
Called by the framework internally during argument processing. See "Arguments" section in the HAP specification for details.
func (*Handler) WithActions ¶
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 ¶
Documents the Handler with information about its purpose and usage.
func (*Handler) WithParams ¶
Defines parameters of the Handler. See param.Param for details.
func (*Handler) WithRawReply ¶
Sets the handler's error reply mode to 'raw'. The default error reply mode is 'HAP-API' format. This setting only affects the error replies generated by the framework, such as when there are invalid input parameters or when a panic occurs within the handler. In these cases, the framework captures the error or panic and formats the response accordingly. Errors returned by the handler during its normal processing are not affected by this setting, and the implementer can choose any desired reply style.
For example, to send an API style reply:
return hap.Reply(http.StatusOK)
And for a raw reply:
return hap.RawReply(http.StatusOK)
A single API handler can freely mix these two styles of responses.
For more information about the different reply modes, see HAP Specification.
func (*Handler) WithReplySpec ¶
Add reply samples to the handler. See hap.ReplySpec for details.
Source Files