doorbadge

package
v0.0.0-...-da2a1ef Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 15, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

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

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

func GetOpenAPISpecJSON() ([]byte, error)

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

func NewExitEventWebhookRequestWithBody

func NewExitEventWebhookRequestWithBody(targetURL string, contentType string, body io.Reader) (*http.Request, error)

NewExitEventWebhookRequestWithBody creates a POST request for the webhook with any 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

type HttpRequestDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HttpRequestDoer performs HTTP requests. The standard http.Client implements this interface.

type InvalidParamFormatError

type InvalidParamFormatError struct {
	ParamName string
	Err       error
}

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

type MiddlewareFunc func(http.Handler) http.Handler

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

type RequestEditorFn func(ctx context.Context, req *http.Request) error

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

type RequiredHeaderError struct {
	ParamName string
	Err       error
}

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

type TooManyValuesForParamError struct {
	ParamName string
	Count     int
}

TooManyValuesForParamError is returned when a parameter has too many values.

func (*TooManyValuesForParamError) Error

type UnescapedCookieParamError

type UnescapedCookieParamError struct {
	ParamName string
	Err       error
}

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

type UnmarshalingParamError struct {
	ParamName string
	Err       error
}

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

type WebhookHttpError[E any] struct {
	StatusCode int
	Body       E
	RawBody    []byte
}

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

type WebhookReceiverMiddlewareFunc func(http.Handler) http.Handler

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.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL