ancla

README

ancla

Provides a configurable webhook registry component for XMiDT services. Application code can use the registry directly or as a plug-in for ancla's helper HTTP handlers.

Code of Conduct

This project and everyone participating in it are governed by the XMiDT Code Of Conduct. By participating, you agree to this Code.

Contributing

Refer to CONTRIBUTING.md.

Documentation

Overview

Package ancla contains the XMiDT event webhook registry. In addition to the main service, ancla provides off the shelf HTTP handlers for both adding and retrieving webhooks.

Index

• Constants
• func Metrics() []xmetrics.Metric
• func NewAddWebhookHandler(s Service, config HandlerConfig) http.Handler
• func NewGetAllWebhooksHandler(s Service) http.Handler
• type Config
• type DeliveryConfig
• type HandlerConfig
• type MetadataMatcherConfig
• type Service
  • func Initialize(cfg Config, logger func(ctx context.Context) bascule.Logger, watches ...Watch) (Service, func(), error)
• type Watch
• type WatchFunc
  • func (f WatchFunc) Update(update []Webhook)
• type Webhook

Constants

const (
	WebhookListSizeGauge     = "webhook_list_size_value"
	WebhookLegacyDecodeCount = "webhook_legacy_decodings_total"
)

Names

const (
	OutcomeLabel = "outcome"
	URLLabel     = "url"
)

Labels

const (
	SuccessOutcome = "success"
	FailureOutcome = "failure"
)

Label Values

Functions

func Metrics

func Metrics() []xmetrics.Metric

Metrics returns the Metrics relevant to this package.

func NewAddWebhookHandler

func NewAddWebhookHandler(s Service, config HandlerConfig) http.Handler

NewAddWebhookHandler returns an HTTP handler for adding a webhook registration.

func NewGetAllWebhooksHandler

func NewGetAllWebhooksHandler(s Service) http.Handler

NewGetAllWebhooksHandler returns an HTTP handler for fetching all the currently registered webhooks.

Types

type Config

type Config struct {
	// Argus contains configuration to initialize an Argus client.
	Argus chrysom.ClientConfig

	// Logger for this package.
	// Gets passed to Argus config before initializing the client.
	// (Optional). Defaults to a no op logger.
	Logger log.Logger

	// MetricsProvider for instrumenting this package.
	// Gets passed to Argus config before initializing the client.
	// (Optional). Defaults to a no op provider.
	MetricsProvider provider.Provider
}

Config contains information needed to initialize the webhook service.

type DeliveryConfig

type DeliveryConfig struct {
	// URL is the HTTP URL to deliver messages to.
	URL string `json:"url"`

	// ContentType is content type value to set WRP messages to (unless already specified in the WRP).
	ContentType string `json:"content_type"`

	// Secret is the string value for the SHA1 HMAC.
	// (Optional, set to "" to disable behavior).
	Secret string `json:"secret,omitempty"`

	// AlternativeURLs is a list of explicit URLs that should be round robin through on failure cases to the main URL.
	AlternativeURLs []string `json:"alt_urls,omitempty"`
}

DeliveryConfig is a Webhook substructure with data related to event delivery.

type HandlerConfig

type HandlerConfig struct {
	MetricsProvider provider.Provider
}

HandlerConfig contains configuration for all components that handlers depend on from the service to the transport layers.

type MetadataMatcherConfig

type MetadataMatcherConfig struct {
	// DeviceID is the list of regular expressions to match device id type against.
	DeviceID []string `json:"device_id"`
}

MetadataMatcherConfig is Webhook substructure with config to match event metadata.

type Service

type Service interface {
	// Add adds the given owned webhook to the current list of webhooks. If the operation
	// succeeds, a non-nil error is returned.
	Add(ctx context.Context, owner string, w Webhook) error

	// AllWebhooks lists all the current registered webhooks.
	AllWebhooks(ctx context.Context) ([]Webhook, error)
}

Service describes the core operations around webhook subscriptions. Initialize() provides a service ready to use and the controls around watching for updates.

func Initialize

func Initialize(cfg Config, logger func(ctx context.Context) bascule.Logger, watches ...Watch) (Service, func(), error)

Initialize builds the webhook service from the given configuration. It allows adding watchers for the internal subscription state. Call the returned function when you are done watching for updates.

type Watch

type Watch interface {
	Update([]Webhook)
}

Watch is the interface for listening for webhook subcription updates. Updates represent the latest known list of subscriptions.

type WatchFunc

type WatchFunc func([]Webhook)

WatchFunc allows bare functions to pass as Watches.

func (WatchFunc) Update

func (f WatchFunc) Update(update []Webhook)

type Webhook

type Webhook struct {
	// Address is the subscription request origin HTTP Address.
	Address string `json:"registered_from_address"`

	// Config contains data to inform how events are delivered.
	Config DeliveryConfig `json:"config"`

	// FailureURL is the URL used to notify subscribers when they've been cut off due to event overflow.
	// Optional, set to "" to disable notifications.
	FailureURL string `json:"failure_url"`

	// Events is the list of regular expressions to match an event type against.
	Events []string `json:"events"`

	// Matcher type contains values to match against the metadata.
	Matcher MetadataMatcherConfig `json:"matcher,omitempty"`

	// Duration describes how long the subscription lasts once added.
	// Deprecated. User input is ignored and value is always 5m.
	Duration time.Duration `json:"duration"`

	// Until describes the time this subscription expires.
	Until time.Time `json:"until"`
}

Webhook contains all the information needed to serve events to webhook listeners.