Documentation
¶
Overview ¶
Package doorbadge provides an example of OpenAPI 3.1 webhooks. A door badge reader server generates random enter/exit events and notifies registered webhook listeners.
You can run the example by running these two commands in parallel:
go run ./server --port 8080 go run ./client --server http://localhost:8080
You can run multiple clients and they will all get the notifications
Index ¶
- func EnterEventWebhookHandler(si WebhookReceiverInterface, ...) http.Handler
- func ExitEventWebhookHandler(si WebhookReceiverInterface, ...) http.Handler
- func GetOpenAPISpecJSON() ([]byte, error)
- func Handler(si ServerInterface) http.Handler
- func HandlerFromMux(si ServerInterface, m ServeMux) http.Handler
- func HandlerFromMuxWithBaseURL(si ServerInterface, m ServeMux, baseURL string) http.Handler
- func HandlerWithOptions(si ServerInterface, options StdHTTPServerOptions) http.Handler
- func NewEnterEventWebhookRequest(targetURL string, body EnterEventJSONRequestBody) (*http.Request, error)
- func NewEnterEventWebhookRequestWithBody(targetURL string, contentType string, body io.Reader) (*http.Request, error)
- func NewExitEventWebhookRequest(targetURL string, body ExitEventJSONRequestBody) (*http.Request, error)
- func NewExitEventWebhookRequestWithBody(targetURL string, contentType string, body io.Reader) (*http.Request, error)
- type EnterEventJSONRequestBody
- type Error
- type ExitEventJSONRequestBody
- type HttpRequestDoer
- type InvalidParamFormatError
- type MiddlewareFunc
- type Person
- type PostAPIWebhookKindParameter
- type RequestEditorFn
- type RequiredHeaderError
- type RequiredParamError
- type ServeMux
- type ServerInterface
- type ServerInterfaceWrapper
- type SimpleWebhookInitiator
- type StdHTTPServerOptions
- type TooManyValuesForParamError
- type UnescapedCookieParamError
- type UnmarshalingParamError
- type WebhookHttpError
- type WebhookInitiator
- func (p *WebhookInitiator) EnterEvent(ctx context.Context, targetURL string, body EnterEventJSONRequestBody, ...) (*http.Response, error)
- func (p *WebhookInitiator) EnterEventWithBody(ctx context.Context, targetURL string, contentType string, body io.Reader, ...) (*http.Response, error)
- func (p *WebhookInitiator) ExitEvent(ctx context.Context, targetURL string, body ExitEventJSONRequestBody, ...) (*http.Response, error)
- func (p *WebhookInitiator) ExitEventWithBody(ctx context.Context, targetURL string, contentType string, body io.Reader, ...) (*http.Response, error)
- type WebhookInitiatorInterface
- type WebhookInitiatorOption
- type WebhookReceiverInterface
- type WebhookReceiverMiddlewareFunc
- type WebhookRegistration
- type WebhookRegistrationResponse
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnterEventWebhookHandler ¶
func EnterEventWebhookHandler(si WebhookReceiverInterface, errHandler func(w http.ResponseWriter, r *http.Request, err error), middlewares ...WebhookReceiverMiddlewareFunc) http.Handler
EnterEventWebhookHandler returns an http.Handler for the EnterEvent webhook. The caller is responsible for registering this handler at the appropriate path.
func ExitEventWebhookHandler ¶
func ExitEventWebhookHandler(si WebhookReceiverInterface, errHandler func(w http.ResponseWriter, r *http.Request, err error), middlewares ...WebhookReceiverMiddlewareFunc) http.Handler
ExitEventWebhookHandler returns an http.Handler for the ExitEvent webhook. The caller is responsible for registering this handler at the appropriate path.
func GetOpenAPISpecJSON ¶
GetOpenAPISpecJSON returns the raw OpenAPI spec as JSON bytes.
func Handler ¶
func Handler(si ServerInterface) http.Handler
Handler creates http.Handler with routing matching OpenAPI spec.
func HandlerFromMux ¶
func HandlerFromMux(si ServerInterface, m ServeMux) http.Handler
HandlerFromMux creates http.Handler with routing matching OpenAPI spec based on the provided mux.
func HandlerFromMuxWithBaseURL ¶
func HandlerFromMuxWithBaseURL(si ServerInterface, m ServeMux, baseURL string) http.Handler
HandlerFromMuxWithBaseURL creates http.Handler with routing and a base URL.
func HandlerWithOptions ¶
func HandlerWithOptions(si ServerInterface, options StdHTTPServerOptions) http.Handler
HandlerWithOptions creates http.Handler with additional options.
func NewEnterEventWebhookRequest ¶
func NewEnterEventWebhookRequest(targetURL string, body EnterEventJSONRequestBody) (*http.Request, error)
NewEnterEventWebhookRequest creates a POST request for the webhook with application/json body
func NewEnterEventWebhookRequestWithBody ¶
func NewEnterEventWebhookRequestWithBody(targetURL string, contentType string, body io.Reader) (*http.Request, error)
NewEnterEventWebhookRequestWithBody creates a POST request for the webhook with any body
func NewExitEventWebhookRequest ¶
func NewExitEventWebhookRequest(targetURL string, body ExitEventJSONRequestBody) (*http.Request, error)
NewExitEventWebhookRequest creates a POST request for the webhook with application/json body
Types ¶
type EnterEventJSONRequestBody ¶
type EnterEventJSONRequestBody = Person
type Error ¶
type Error struct {
// Error code
Code int32 `json:"code" form:"code"`
// Error message
Message string `json:"message" form:"message"`
}
#/components/schemas/Error
func (*Error) ApplyDefaults ¶
func (s *Error) ApplyDefaults()
ApplyDefaults sets default values for fields that are nil.
type ExitEventJSONRequestBody ¶
type ExitEventJSONRequestBody = Person
type HttpRequestDoer ¶
HttpRequestDoer performs HTTP requests. The standard http.Client implements this interface.
type InvalidParamFormatError ¶
InvalidParamFormatError is returned when a parameter has an invalid format.
func (*InvalidParamFormatError) Error ¶
func (e *InvalidParamFormatError) Error() string
func (*InvalidParamFormatError) Unwrap ¶
func (e *InvalidParamFormatError) Unwrap() error
type MiddlewareFunc ¶
MiddlewareFunc is a middleware function type.
type Person ¶
type Person struct {
// Name of the person who badged in or out
Name string `json:"name" form:"name"`
}
#/components/schemas/Person
func (*Person) ApplyDefaults ¶
func (s *Person) ApplyDefaults()
ApplyDefaults sets default values for fields that are nil.
type PostAPIWebhookKindParameter ¶
type PostAPIWebhookKindParameter string
#/paths//api/webhook/{kind}/post/parameters/0/schema
const ( EnterEvent PostAPIWebhookKindParameter = "enterEvent" ExitEvent PostAPIWebhookKindParameter = "exitEvent" )
type RequestEditorFn ¶
RequestEditorFn is the function signature for the RequestEditor callback function. It may already be defined if client code is also generated; this is a compatible redeclaration.
type RequiredHeaderError ¶
RequiredHeaderError is returned when a required header is missing.
func (*RequiredHeaderError) Error ¶
func (e *RequiredHeaderError) Error() string
func (*RequiredHeaderError) Unwrap ¶
func (e *RequiredHeaderError) Unwrap() error
type RequiredParamError ¶
type RequiredParamError struct {
ParamName string
}
RequiredParamError is returned when a required parameter is missing.
func (*RequiredParamError) Error ¶
func (e *RequiredParamError) Error() string
type ServeMux ¶
type ServeMux interface {
HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
ServeHTTP(w http.ResponseWriter, r *http.Request)
}
ServeMux is an abstraction of http.ServeMux.
type ServerInterface ¶
type ServerInterface interface {
// Deregister a webhook
// (DELETE /api/webhook/{id})
DeregisterWebhook(w http.ResponseWriter, r *http.Request, id oapiCodegenTypesPkg.UUID)
// Register a webhook
// (POST /api/webhook/{kind})
RegisterWebhook(w http.ResponseWriter, r *http.Request, kind string)
}
ServerInterface represents all server handlers.
type ServerInterfaceWrapper ¶
type ServerInterfaceWrapper struct {
Handler ServerInterface
HandlerMiddlewares []MiddlewareFunc
ErrorHandlerFunc func(w http.ResponseWriter, r *http.Request, err error)
}
ServerInterfaceWrapper converts HTTP requests to parameters.
func (*ServerInterfaceWrapper) DeregisterWebhook ¶
func (siw *ServerInterfaceWrapper) DeregisterWebhook(w http.ResponseWriter, r *http.Request)
DeregisterWebhook operation middleware
func (*ServerInterfaceWrapper) RegisterWebhook ¶
func (siw *ServerInterfaceWrapper) RegisterWebhook(w http.ResponseWriter, r *http.Request)
RegisterWebhook operation middleware
type SimpleWebhookInitiator ¶
type SimpleWebhookInitiator struct {
*WebhookInitiator
}
SimpleWebhookInitiator wraps WebhookInitiator with typed responses for operations that have unambiguous response types. Methods return the success type directly, and HTTP errors are returned as *WebhookHttpError[E] where E is the error type.
func NewSimpleWebhookInitiator ¶
func NewSimpleWebhookInitiator(opts ...WebhookInitiatorOption) (*SimpleWebhookInitiator, error)
NewSimpleWebhookInitiator creates a new SimpleWebhookInitiator which wraps a WebhookInitiator.
type StdHTTPServerOptions ¶
type StdHTTPServerOptions struct {
BaseURL string
BaseRouter ServeMux
Middlewares []MiddlewareFunc
ErrorHandlerFunc func(w http.ResponseWriter, r *http.Request, err error)
}
StdHTTPServerOptions configures the StdHTTP server.
type TooManyValuesForParamError ¶
TooManyValuesForParamError is returned when a parameter has too many values.
func (*TooManyValuesForParamError) Error ¶
func (e *TooManyValuesForParamError) Error() string
type UnescapedCookieParamError ¶
UnescapedCookieParamError is returned when a cookie parameter cannot be unescaped.
func (*UnescapedCookieParamError) Error ¶
func (e *UnescapedCookieParamError) Error() string
func (*UnescapedCookieParamError) Unwrap ¶
func (e *UnescapedCookieParamError) Unwrap() error
type UnmarshalingParamError ¶
UnmarshalingParamError is returned when a parameter cannot be unmarshaled.
func (*UnmarshalingParamError) Error ¶
func (e *UnmarshalingParamError) Error() string
func (*UnmarshalingParamError) Unwrap ¶
func (e *UnmarshalingParamError) Unwrap() error
type WebhookHttpError ¶
WebhookHttpError represents an HTTP error response from the webhook. The type parameter E is the type of the parsed error body.
func (*WebhookHttpError[E]) Error ¶
func (e *WebhookHttpError[E]) Error() string
type WebhookInitiator ¶
type WebhookInitiator struct {
// Doer for performing requests, typically a *http.Client with any
// customized settings, such as certificate chains.
Client HttpRequestDoer
// A list of callbacks for modifying requests which are generated before sending over
// the network.
RequestEditors []RequestEditorFn
}
WebhookInitiator sends webhook requests to target URLs. Unlike Client, it has no stored base URL — the full target URL is provided per-call.
func NewWebhookInitiator ¶
func NewWebhookInitiator(opts ...WebhookInitiatorOption) (*WebhookInitiator, error)
NewWebhookInitiator creates a new WebhookInitiator with reasonable defaults.
func (*WebhookInitiator) EnterEvent ¶
func (p *WebhookInitiator) EnterEvent(ctx context.Context, targetURL string, body EnterEventJSONRequestBody, reqEditors ...RequestEditorFn) (*http.Response, error)
EnterEvent sends a POST webhook request with application/json body
func (*WebhookInitiator) EnterEventWithBody ¶
func (p *WebhookInitiator) EnterEventWithBody(ctx context.Context, targetURL string, contentType string, body io.Reader, reqEditors ...RequestEditorFn) (*http.Response, error)
EnterEventWithBody sends a POST webhook request Person entered the building
func (*WebhookInitiator) ExitEvent ¶
func (p *WebhookInitiator) ExitEvent(ctx context.Context, targetURL string, body ExitEventJSONRequestBody, reqEditors ...RequestEditorFn) (*http.Response, error)
ExitEvent sends a POST webhook request with application/json body
func (*WebhookInitiator) ExitEventWithBody ¶
func (p *WebhookInitiator) ExitEventWithBody(ctx context.Context, targetURL string, contentType string, body io.Reader, reqEditors ...RequestEditorFn) (*http.Response, error)
ExitEventWithBody sends a POST webhook request Person exited the building
type WebhookInitiatorInterface ¶
type WebhookInitiatorInterface interface {
// EnterEventWithBody sends a POST webhook request
EnterEventWithBody(ctx context.Context, targetURL string, contentType string, body io.Reader, reqEditors ...RequestEditorFn) (*http.Response, error)
EnterEvent(ctx context.Context, targetURL string, body EnterEventJSONRequestBody, reqEditors ...RequestEditorFn) (*http.Response, error)
// ExitEventWithBody sends a POST webhook request
ExitEventWithBody(ctx context.Context, targetURL string, contentType string, body io.Reader, reqEditors ...RequestEditorFn) (*http.Response, error)
ExitEvent(ctx context.Context, targetURL string, body ExitEventJSONRequestBody, reqEditors ...RequestEditorFn) (*http.Response, error)
}
WebhookInitiatorInterface is the interface specification for the webhook initiator.
type WebhookInitiatorOption ¶
type WebhookInitiatorOption func(*WebhookInitiator) error
WebhookInitiatorOption allows setting custom parameters during construction.
func WithWebhookHTTPClient ¶
func WithWebhookHTTPClient(doer HttpRequestDoer) WebhookInitiatorOption
WithWebhookHTTPClient allows overriding the default Doer, which is automatically created using http.Client. This is useful for tests.
func WithWebhookRequestEditorFn ¶
func WithWebhookRequestEditorFn(fn RequestEditorFn) WebhookInitiatorOption
WithWebhookRequestEditorFn allows setting up a callback function, which will be called right before sending the request. This can be used to mutate the request.
type WebhookReceiverInterface ¶
type WebhookReceiverInterface interface {
// Person entered the building
// HandleEnterEventWebhook handles the POST webhook request.
HandleEnterEventWebhook(w http.ResponseWriter, r *http.Request)
// Person exited the building
// HandleExitEventWebhook handles the POST webhook request.
HandleExitEventWebhook(w http.ResponseWriter, r *http.Request)
}
WebhookReceiverInterface represents handlers for receiving webhook requests.
type WebhookReceiverMiddlewareFunc ¶
WebhookReceiverMiddlewareFunc is a middleware function for webhook receiver handlers.
type WebhookRegistration ¶
type WebhookRegistration struct {
// URL to receive webhook events
URL string `json:"url" form:"url"`
}
#/components/schemas/WebhookRegistration
func (*WebhookRegistration) ApplyDefaults ¶
func (s *WebhookRegistration) ApplyDefaults()
ApplyDefaults sets default values for fields that are nil.
type WebhookRegistrationResponse ¶
type WebhookRegistrationResponse struct {
// Unique identifier for this webhook registration
ID oapiCodegenTypesPkg.UUID `json:"id" form:"id"`
}
#/components/schemas/WebhookRegistrationResponse
func (*WebhookRegistrationResponse) ApplyDefaults ¶
func (s *WebhookRegistrationResponse) ApplyDefaults()
ApplyDefaults sets default values for fields that are nil.