hap

Documentation

Overview

This package is designed for defining and managing HTTP APIs, with a focus on simplifying the API creation process and providing auto-generated API documentation. By using a declarative syntax, users can easily define API endpoints, request parameters, and response formats while automatically generating detailed API documentation.

Key Features

• Declarative API Definition: Define API paths, methods, and handlers using a clean, declarative syntax.
• Automatic API Documentation: Automatically generates documentation based on the API definitions, reducing the need for manual documentation maintenance.
• Parameter Validation: Supports request parameter validation and documentation, ensuring API robustness.
• Error Handling: Built-in error handling mechanism provides friendly responses for invalid requests and errors.

Index

• func AllowCookie(yesno bool)
• func IsCookieAllowed() bool
• func LoadLanguage(tag language.Tag, trans map[string]string)
• func RawReply(code int) *reply
• func Register(a API, mx ...*http.ServeMux)
• func Reply(code int) *reply
• func SetGlobalCORS(enable bool, origin ...string)
• func WithGlobalActions(as ...Action)
• func WithLangSpecifier(lang string)
• func WithPanicLogger(f func(mesg string, trace []string))
• type API
• type Action
  • func AllowRemoteFrom(allowForward bool, nr *NetRange) Action
  • func GlobalActions() []Action
• type ApiSpec
  • func Specs(endPoint, method string, f *message.Printer) (as []ApiSpec)
• type NetRange
  • func NetRangeFunc(f func() []net.IPNet) *NetRange
  • func NewNetRange(ipn ...net.IPNet) *NetRange
  • func (nr *NetRange) Add(ipn ...net.IPNet)
  • func (nr *NetRange) Contains(ip net.IP) bool
  • func (nr *NetRange) Get() []net.IPNet
  • func (nr *NetRange) IsTrustedRequest(r *http.Request, checkForward bool) bool
  • func (nr *NetRange) Set(ipn ...net.IPNet)
• type ParamSpec
• type ReplyDesc
• type ReplySpec

Functions

func AllowCookie

func AllowCookie(yesno bool)

func IsCookieAllowed

func IsCookieAllowed() bool

func LoadLanguage

func LoadLanguage(tag language.Tag, trans map[string]string)

func RawReply

func RawReply(code int) *reply

func Register

func Register(a API, mx ...*http.ServeMux)

func Reply

func Reply(code int) *reply

func SetGlobalCORS

func SetGlobalCORS(enable bool, origin ...string)

func WithGlobalActions

func WithGlobalActions(as ...Action)

func WithLangSpecifier

func WithLangSpecifier(lang string)

func WithPanicLogger

func WithPanicLogger(f func(mesg string, trace []string))

Types

type API

type API interface {
	Endpoint() string
	Spec(*message.Printer) []ApiSpec
	http.Handler
}

type Action

type Action func(*arg.Args, http.ResponseWriter, *http.Request) any

Action represents a function signature used for handling HTTP requests within the hap package. It defines a callback function that takes three parameters:

• *arg.Args: A pointer to the arguments parsed from the request. See the documentation for arg.Args for more details.
• http.ResponseWriter: An interface used to construct the HTTP response.
• *http.Request: A pointer to the HTTP request being handled.

The function returns `any`, which allows it to return various types of responses depending on the logic implemented. This type is typically used to define the logic for processing HTTP requests and generating responses based on the request parameters and other conditions.

func AllowRemoteFrom

func AllowRemoteFrom(allowForward bool, nr *NetRange) Action

func GlobalActions

func GlobalActions() []Action

type ApiSpec

type ApiSpec struct {
	Endpoint string      `json:"endpoint"`
	Method   string      `json:"method"`
	Help     []string    `json:"help,omitempty"`
	Params   []ParamSpec `json:"params,omitempty"`
	Output   []ReplyDesc `json:"output,omitempty"`
	Tags     url.Values  `json:"tags,omitempty"`
}

func Specs

func Specs(endPoint, method string, f *message.Printer) (as []ApiSpec)

type NetRange

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

func NetRangeFunc

func NetRangeFunc(f func() []net.IPNet) *NetRange

func NewNetRange

func NewNetRange(ipn ...net.IPNet) *NetRange

func (*NetRange) Add

func (nr *NetRange) Add(ipn ...net.IPNet)

func (*NetRange) Contains

func (nr *NetRange) Contains(ip net.IP) bool

func (*NetRange) Get

func (nr *NetRange) Get() []net.IPNet

func (*NetRange) IsTrustedRequest

func (nr *NetRange) IsTrustedRequest(r *http.Request, checkForward bool) bool

func (*NetRange) Set

func (nr *NetRange) Set(ipn ...net.IPNet)

type ParamSpec

type ParamSpec struct {
	Name     string     `json:"name"`
	Type     string     `json:"type"`
	Required bool       `json:"required"`
	Default  *string    `json:"default,omitempty"`
	Rules    [][]string `json:"rules,omitempty"`
	Help     []string   `json:"help,omitempty"`
}

type ReplyDesc

type ReplyDesc struct {
	Mime string    `json:"mime"`
	Raw  bool      `json:"raw"`
	Spec ReplySpec `json:"spec"`
}

type ReplySpec

type ReplySpec = *reply