discovery_kit_sdk

README

DsicoveryKit Go SDK

This module contains helpers and interfaces which will help you to implement discoveries using the discovery_kit go api.

The module encapsulates the following technical aspects and provides helpers for the following elements:

• The SDK will wrap around your describe call and provide meaningful defaults for your endpoint definitions.
• Caching and async discovery execution to decouple the discovery execution from the HTTP requests.

Installation

Add the following to your go.mod file:

go get github.com/steadybit/discovery-kit/go/discovery_kit_sdk

Usage

1. Implement at least the discovery_kit_sdk.TargetDiscovery or discovery_kit_sdk.EnrichmentDataDisocvery interface

2. Implement other interfaces if you need them:

   • discovery_kit_sdk.TargetDescriber
   • discovery_kit_sdk.AttributesDescriber
   • discovery_kit_sdk.EnrichmentRuleContributor

3. Register your discovery:

   discovery_kit_sdk.Register(NewMyCustomDiscovery())
   

4. Add your registered discoveries to the index endpoint of your extension:

   exthttp.RegisterHttpHandler("/discoveries", exthttp.GetterAsHandler(discovery_kit_sdk.GetDiscoveryList))
   

Caching / Async Discovery

If you implement the TargetDiscovery / EnrichmentDataDiscovery in a straightforward fashion, then the discovery is executed synchronously for each HTTP request. You can decouple this by decorating your discovery using the NewCachedTargetDiscovery / NewCachedEnrichmentDataDiscovery functions. You pass your discovery and options to control the refreshing of the data.

	discovery := &jvmDiscovery{}
	return discovery_kit_sdk.NewCachedTargetDiscovery(discovery,
		discovery_kit_sdk.WithRefreshTargetsNow(),
		discovery_kit_sdk.WithRefreshTargetsInterval(context.Background(), 30*time.Second),
	)

You have various options to refresh periodically once on the trigger. Also, it will help recover from any panic upon discovery.

Documentation

Index

• Variables
• func ClearRegisteredDiscoveries()
• func GetDiscoveryList() discovery_kit_api.DiscoveryList
• func Register(o interface{})
• type AttributeDescriber
• type CachedDataEnrichmentDiscovery
  • func NewCachedEnrichmentDataDiscovery(d EnrichmentDataDiscovery, ...) *CachedDataEnrichmentDiscovery
  • func (c *CachedDataEnrichmentDiscovery) DiscoverEnrichmentData(_ context.Context) ([]discovery_kit_api.EnrichmentData, error)
• type CachedDiscovery
  • func (c *CachedDiscovery[T]) Get() ([]T, error)
  • func (c *CachedDiscovery[T]) LastModified() time.Time
  • func (c *CachedDiscovery[T]) Refresh(ctx context.Context)
  • func (c *CachedDiscovery[T]) Unwrap() interface{}
  • func (c *CachedDiscovery[T]) Update(fn UpdateFn[[]T])
• type CachedDiscoveryOpt
  • func WithEnrichmentDataRefreshTimeout(timeout time.Duration) CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]
  • func WithEnrichmentDataUpdate[U any](ctx context.Context, ch <-chan U, ...) CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]
  • func WithRefreshEnrichmentDataInterval(ctx context.Context, interval time.Duration) CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]
  • func WithRefreshEnrichmentDataNow() CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]
  • func WithRefreshEnrichmentDataTrigger(ctx context.Context, ch <-chan struct{}, throttlePeriod time.Duration) CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]
  • func WithRefreshInterval[T any](ctx context.Context, interval time.Duration) CachedDiscoveryOpt[T]
  • func WithRefreshNow[T any]() CachedDiscoveryOpt[T]
  • func WithRefreshTargetsInterval(ctx context.Context, interval time.Duration) CachedDiscoveryOpt[discovery_kit_api.Target]
  • func WithRefreshTargetsNow() CachedDiscoveryOpt[discovery_kit_api.Target]
  • func WithRefreshTargetsTrigger(ctx context.Context, ch <-chan struct{}, throttlePeriod time.Duration) CachedDiscoveryOpt[discovery_kit_api.Target]
  • func WithRefreshTimeout[T any](timeout time.Duration) CachedDiscoveryOpt[T]
  • func WithRefreshTrigger[T any](ctx context.Context, ch <-chan struct{}, throttlePeriod time.Duration) CachedDiscoveryOpt[T]
  • func WithTargetsRefreshTimeout(timeout time.Duration) CachedDiscoveryOpt[discovery_kit_api.Target]
  • func WithTargetsUpdate[U any](ctx context.Context, ch <-chan U, fn UpdateFunc[[]discovery_kit_api.Target, U]) CachedDiscoveryOpt[discovery_kit_api.Target]
  • func WithUpdate[T, U any](ctx context.Context, ch <-chan U, fn UpdateFunc[[]T, U]) CachedDiscoveryOpt[T]
• type CachedTargetDiscovery
  • func NewCachedTargetDiscovery(d TargetDiscovery, opts ...CachedDiscoveryOpt[discovery_kit_api.Target]) *CachedTargetDiscovery
  • func (c *CachedTargetDiscovery) DiscoverTargets(_ context.Context) ([]discovery_kit_api.Target, error)
• type Discovery
• type EnrichmentDataDiscovery
• type EnrichmentRulesDescriber
• type HttpRequestContextKey
• type TargetDescriber
• type TargetDiscovery
• type Unwrapper
• type UpdateFn
• type UpdateFunc

Variables

var (
	ErrDiscoveryTimeout = errors.New("discovery timed out")
)

Functions

func ClearRegisteredDiscoveries

func ClearRegisteredDiscoveries()

func GetDiscoveryList

func GetDiscoveryList() discovery_kit_api.DiscoveryList

func Register

func Register(o interface{})

Types

type AttributeDescriber

type AttributeDescriber interface {
	// DescribeAttributes returns the target attribute description.
	DescribeAttributes() []discovery_kit_api.AttributeDescription
}

type CachedDataEnrichmentDiscovery

type CachedDataEnrichmentDiscovery struct {
	CachedDiscovery[discovery_kit_api.EnrichmentData]
}

func NewCachedEnrichmentDataDiscovery

func NewCachedEnrichmentDataDiscovery(d EnrichmentDataDiscovery, opts ...CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]) *CachedDataEnrichmentDiscovery

NewCachedEnrichmentDataDiscovery returns a caching enrichment data discovery.

func (*CachedDataEnrichmentDiscovery) DiscoverEnrichmentData

func (c *CachedDataEnrichmentDiscovery) DiscoverEnrichmentData(_ context.Context) ([]discovery_kit_api.EnrichmentData, error)

type CachedDiscovery

type CachedDiscovery[T any] struct {
	Discovery
	// contains filtered or unexported fields
}

func (*CachedDiscovery[T]) Get

func (c *CachedDiscovery[T]) Get() ([]T, error)

func (*CachedDiscovery[T]) LastModified

func (c *CachedDiscovery[T]) LastModified() time.Time

func (*CachedDiscovery[T]) Refresh

func (c *CachedDiscovery[T]) Refresh(ctx context.Context)

func (*CachedDiscovery[T]) Unwrap

func (c *CachedDiscovery[T]) Unwrap() interface{}

func (*CachedDiscovery[T]) Update

func (c *CachedDiscovery[T]) Update(fn UpdateFn[[]T])

type CachedDiscoveryOpt

type CachedDiscoveryOpt[T any] func(m *CachedDiscovery[T])

func WithEnrichmentDataRefreshTimeout

func WithEnrichmentDataRefreshTimeout(timeout time.Duration) CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]

WithEnrichmentDataRefreshTimeout decorates the supplier with a timeout.

func WithEnrichmentDataUpdate

func WithEnrichmentDataUpdate[U any](ctx context.Context, ch <-chan U, fn UpdateFunc[[]discovery_kit_api.EnrichmentData, U]) CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]

WithEnrichmentDataUpdate triggers an updates the cache using the given function when an item on the channel is received and will stop when the context is canceled.

func WithRefreshEnrichmentDataInterval

func WithRefreshEnrichmentDataInterval(ctx context.Context, interval time.Duration) CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]

WithRefreshEnrichmentDataInterval triggers a refresh of the cache at the given interval and will stop when the context is canceled.

func WithRefreshEnrichmentDataNow

func WithRefreshEnrichmentDataNow() CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]

WithRefreshEnrichmentDataNow triggers a refresh of the cache immediately at creation time.

func WithRefreshEnrichmentDataTrigger

func WithRefreshEnrichmentDataTrigger(ctx context.Context, ch <-chan struct{}, throttlePeriod time.Duration) CachedDiscoveryOpt[discovery_kit_api.EnrichmentData]

WithRefreshEnrichmentDataTrigger triggers a refresh of the cache when an item on the channel is received and will stop when the context is canceled. The refreshes will be throttled by the given throttlePeriod.

func WithRefreshInterval

func WithRefreshInterval[T any](ctx context.Context, interval time.Duration) CachedDiscoveryOpt[T]

WithRefreshInterval triggers a refresh of the cache at the given interval and will stop when the context is canceled.

func WithRefreshNow

func WithRefreshNow[T any]() CachedDiscoveryOpt[T]

WithRefreshNow triggers a refresh of the cache immediately at creation time.

func WithRefreshTargetsInterval

func WithRefreshTargetsInterval(ctx context.Context, interval time.Duration) CachedDiscoveryOpt[discovery_kit_api.Target]

WithRefreshTargetsInterval triggers a refresh of the cache at the given interval and will stop when the context is canceled.

func WithRefreshTargetsNow

func WithRefreshTargetsNow() CachedDiscoveryOpt[discovery_kit_api.Target]

WithRefreshTargetsNow triggers a refresh of the cache immediately at creation time.

func WithRefreshTargetsTrigger

func WithRefreshTargetsTrigger(ctx context.Context, ch <-chan struct{}, throttlePeriod time.Duration) CachedDiscoveryOpt[discovery_kit_api.Target]

WithRefreshTargetsTrigger triggers a refresh of the cache when an item on the channel is received and will stop when the context is canceled. The refreshes will be throttled by the given throttlePeriod.

func WithRefreshTimeout

func WithRefreshTimeout[T any](timeout time.Duration) CachedDiscoveryOpt[T]

func WithRefreshTrigger

func WithRefreshTrigger[T any](ctx context.Context, ch <-chan struct{}, throttlePeriod time.Duration) CachedDiscoveryOpt[T]

WithRefreshTrigger triggers a refresh of the cache when an item on the channel is received and will stop when the context is canceled.

func WithTargetsRefreshTimeout

func WithTargetsRefreshTimeout(timeout time.Duration) CachedDiscoveryOpt[discovery_kit_api.Target]

WithTargetsRefreshTimeout decorates the supplier with a timeout.

func WithTargetsUpdate

func WithTargetsUpdate[U any](ctx context.Context, ch <-chan U, fn UpdateFunc[[]discovery_kit_api.Target, U]) CachedDiscoveryOpt[discovery_kit_api.Target]

WithTargetsUpdate triggers an updates the cache using the given function when an item on the channel is received and will stop when the context is canceled.

func WithUpdate

func WithUpdate[T, U any](ctx context.Context, ch <-chan U, fn UpdateFunc[[]T, U]) CachedDiscoveryOpt[T]

type CachedTargetDiscovery

type CachedTargetDiscovery struct {
	CachedDiscovery[discovery_kit_api.Target]
}

func NewCachedTargetDiscovery

func NewCachedTargetDiscovery(d TargetDiscovery, opts ...CachedDiscoveryOpt[discovery_kit_api.Target]) *CachedTargetDiscovery

NewCachedTargetDiscovery returns a caching target discovery.

func (*CachedTargetDiscovery) DiscoverTargets

func (c *CachedTargetDiscovery) DiscoverTargets(_ context.Context) ([]discovery_kit_api.Target, error)

type Discovery

type Discovery interface {
	// Describe returns the discovery description.
	Describe() discovery_kit_api.DiscoveryDescription
}

type EnrichmentDataDiscovery

type EnrichmentDataDiscovery interface {
	Discovery
	// DiscoverEnrichmentData returns a list of enrichment data.
	DiscoverEnrichmentData(ctx context.Context) ([]discovery_kit_api.EnrichmentData, error)
}

type EnrichmentRulesDescriber

type EnrichmentRulesDescriber interface {
	// DescribeEnrichmentRules returns a list of target enrichment rules.
	DescribeEnrichmentRules() []discovery_kit_api.TargetEnrichmentRule
}

type HttpRequestContextKey

type HttpRequestContextKey string

type TargetDescriber

type TargetDescriber interface {
	// DescribeTarget returns the target description.
	DescribeTarget() discovery_kit_api.TargetDescription
}

type TargetDiscovery

type TargetDiscovery interface {
	Discovery
	// DiscoverTargets returns a list of targets.
	DiscoverTargets(ctx context.Context) ([]discovery_kit_api.Target, error)
}

type Unwrapper

type Unwrapper interface {
	Unwrap() interface{}
}

type UpdateFn

type UpdateFn[U any] func(U) (U, error)

type UpdateFunc

type UpdateFunc[D, U any] func(data D, update U) (D, error)