interfaces

Documentation

Overview

interfaces establishes the contract required for any implementation of the export store functionality in a database provider.

contracts are implementation agnostic data storage models.

Index

• Constants
• type AppFunction
• type AppFunctionContext
• type ApplicationService
• type Authentication
• type BackgroundMessage
• type BackgroundPublisher
• type FunctionPipeline
• type PipelineResponseHandler
• type StoreClient
• type StoredObject
  • func NewStoredObject(appServiceKey string, payload []byte, pipelineId string, pipelinePosition int, ...) StoredObject
  • func (o *StoredObject) ValidateContract(IDRequired bool) error
• type Trigger
• type TriggerConfig
• type TriggerConfigLoader
• type TriggerContextBuilder
• type TriggerMessageHandler
• type TriggerMessageProcessor
• type UpdatableConfig

Constants

const (
	DEVICENAME    = "devicename"
	PROFILENAME   = "profilename"
	SOURCENAME    = "sourcename"
	RECEIVEDTOPIC = "receivedtopic"
	PIPELINEID    = "pipelineid"
)

const (
	// AppServiceContextKey is the context key for getting the reference to the ApplicationService from the context passed to
	// a custom REST Handler
	// TODO: use custom type for this key in v3.0
	AppServiceContextKey = "AppService"

	// ProfileSuffixPlaceholder is the placeholder text to use in an application service's service key if the
	// the name of the configuration profile used is to be used in the service's service key.
	// Only useful if the service has multiple configuration profiles to choose from at runtime.
	// Example:
	//    const (
	//		serviceKey = "MyServiceName-" + interfaces.ProfileSuffixPlaceholder
	//	  )
	ProfileSuffixPlaceholder = "<profile>"

	// DefaultPipelineId is the ID used for the default pipeline create by SetFunctionsPipeline
	DefaultPipelineId = "default-pipeline"
)

Types

type AppFunction

type AppFunction = func(appCxt AppFunctionContext, data interface{}) (bool, interface{})

AppFunction is a type alias for a application pipeline function. appCtx is a reference to the AppFunctionContext below. data is the data to be operated on by the function. bool return value indicates if the pipeline should continue executing (true) or not (false) interface{} is either the data to pass to the next function (continue executing) or an error (stop executing due to error) or nil (done executing)

type AppFunctionContext

type AppFunctionContext interface {
	// Clone returns a copy of the context that can be manipulated independently.
	Clone() AppFunctionContext
	// CorrelationID returns the correlation ID associated with the context.
	CorrelationID() string
	// InputContentType returns the content type of the data that initiated the pipeline execution. Only useful when
	// the TargetType for the pipeline is []byte, otherwise the data with be the type specified by TargetType.
	InputContentType() string
	// SetResponseData sets the response data that will be returned to the trigger when pipeline execution is complete.
	SetResponseData(data []byte)
	// ResponseData returns the data that will be returned to the trigger when pipeline execution is complete.
	ResponseData() []byte
	// SetResponseContentType sets the content type that will be returned to the trigger when pipeline
	// execution is complete.
	SetResponseContentType(string)
	// ResponseContentType returns the content type that will be returned to the trigger when pipeline
	// execution is complete.
	ResponseContentType() string
	// SetRetryData set the data that is to be retried later as part of the Store and Forward capability.
	// Used when there was failure sending the data to an external source.
	SetRetryData(data []byte)
	// TriggerRetryFailedData sets the flag to trigger the retry of any stored failed export data.
	TriggerRetryFailedData()
	// SecretProvider returns the SecretProvider instance
	SecretProvider() bootstrapInterfaces.SecretProvider
	// LoggingClient returns the Logger client
	LoggingClient() logger.LoggingClient
	// EventClient returns the Event client. Note if Core Data is not specified in the Clients configuration,
	// this will return nil.
	EventClient() interfaces.EventClient
	// ReadingClient returns the Reading client. Note if Core Data is not specified in the Clients configuration,
	// this will return nil.
	ReadingClient() interfaces.ReadingClient
	// CommandClient returns the Command client. Note if Core Command is not specified in the Clients configuration,
	// this will return nil.
	CommandClient() interfaces.CommandClient
	// NotificationClient returns the Notification client. Note if Support Notifications is not specified in the
	// Clients configuration, this will return nil.
	NotificationClient() interfaces.NotificationClient
	// SubscriptionClient returns the Subscription client. Note if Support Notifications is not specified in the
	// Clients configuration, this will return nil.
	SubscriptionClient() interfaces.SubscriptionClient
	// DeviceServiceClient returns the DeviceService client. Note if Core Metadata is not specified in the
	// Clients configuration, this will return nil.
	DeviceServiceClient() interfaces.DeviceServiceClient
	// DeviceProfileClient returns the DeviceProfile client. Note if Core Metadata is not specified in the
	// Clients configuration, this will return nil.
	DeviceProfileClient() interfaces.DeviceProfileClient
	// DeviceClient returns the Device client. Note if Core Metadata is not specified in the
	// Clients configuration, this will return nil.
	DeviceClient() interfaces.DeviceClient
	// MetricsManager returns the Metrics Manager used to register counter, gauge, gaugeFloat64 or timer metric types from
	// github.com/rcrowley/go-metrics
	MetricsManager() bootstrapInterfaces.MetricsManager
	// GetDeviceResource retrieves the DeviceResource for given profileName and resourceName.
	// Resources retrieved are cached so multiple calls for same profileName and resourceName don't result in multiple
	// unneeded HTTP calls to Core Metadata
	GetDeviceResource(profileName string, resourceName string) (dtos.DeviceResource, error)
	// AddValue stores a value for access within other functions in pipeline
	AddValue(key string, value string)
	// RemoveValue deletes a value stored in the context at the given key
	RemoveValue(key string)
	// GetValue attempts to retrieve a value stored in the context at the given key
	GetValue(key string) (string, bool)
	// GetAllValues returns a read-only copy of all data stored in the context
	GetAllValues() map[string]string
	// ApplyValues looks in the provided string for placeholders of the form
	// '{any-value-key}' and attempts to replace with the value stored under
	// the key in context storage.  An error will be returned if any placeholders
	// are not matched to a value in the context.
	ApplyValues(format string) (string, error)
	// PipelineId returns the ID of the pipeline that is executing
	PipelineId() string
	// Publish pushes data to the MessageBus using configured topic
	Publish(data any, contentType string) error
	// PublishWithTopic pushes data to the MessageBus using given topic
	PublishWithTopic(topic string, data any, contentType string) error
}

AppFunctionContext defines the interface for an Edgex Application Service Context provided to App Functions when executing in the Functions Pipeline.

type ApplicationService

type ApplicationService interface {
	// AppContext returns the application service context used to detect cancelled context when the service is terminating.
	// Used by custom app service to appropriately exit any long-running functions.
	AppContext() context.Context
	// AddRoute adds a custom REST route to the application service's internal webserver
	// A reference to this ApplicationService is add the the context that is passed to the handler, which
	// can be retrieved using the `AppService` key
	// Deprecated: It is recommended to use AddCustomRoute() instead and enable authentication for custom routes
	// TODO: Remove in 4.0
	AddRoute(route string, handler func(http.ResponseWriter, *http.Request), methods ...string) error
	// AddCustomRoute adds a custom REST route to the application service's internal webserver
	// A reference to this ApplicationService is add the the context that is passed to the handler, which
	// can be retrieved using the `AppService` key
	// TODO: Change signature in 4.0 to use "handler echo.HandlerFunc"
	AddCustomRoute(route string, authentication Authentication, handler echo.HandlerFunc, methods ...string) error
	// RequestTimeout returns the configured request timeout value from [Service] section.
	RequestTimeout() time.Duration
	// ApplicationSettings returns the key/value map of custom settings
	ApplicationSettings() map[string]string
	// GetAppSetting is a convenience function return a setting from the ApplicationSetting
	// section of the service configuration.
	// An error is returned if the specified setting is not found.
	GetAppSetting(setting string) (string, error)
	// GetAppSettingStrings is a convenience function that parses the value for the specified custom
	// application setting as a comma separated list. It returns the list of strings.
	// An error is returned if the specified setting is not found.
	GetAppSettingStrings(setting string) ([]string, error)
	// SetDefaultFunctionsPipeline sets the default functions pipeline with the specified list of Application Functions.
	// This pipeline is executed for all message received from the configured trigger.
	// Note that the functions are executed in the order provided in the list.
	// An error is returned if the list is empty.
	SetDefaultFunctionsPipeline(transforms ...AppFunction) error
	// AddFunctionsPipelineForTopics adds a functions pipeline with the specified unique id and list of Application Functions
	// to be executed when the incoming topic matches any of the specified topics. The specified topic may contain the '#' wildcard
	// so that it matches multiple incoming topics. If just "#" is used for the specified topic it will match all incoming
	// topics and the specified functions pipeline will execute on every message received.
	AddFunctionsPipelineForTopics(id string, topic []string, transforms ...AppFunction) error
	// RemoveAllFunctionPipelines removes all existing function pipelines
	RemoveAllFunctionPipelines()
	// Run starts the configured trigger to allow the functions pipeline to execute when the trigger
	// receives data and starts the internal webserver. This is a long-running function which does not return until
	// the service is stopped or Stop() is called.
	// An error is returned if the trigger can not be created or initialized or if the internal webserver
	// encounters an error.
	Run() error
	// Stop stops the configured trigger so that the functions pipeline no longer executes.
	// An error is returned
	Stop()
	// RegisterCustomTriggerFactory registers a trigger factory for a custom trigger to be used.
	RegisterCustomTriggerFactory(name string, factory func(TriggerConfig) (Trigger, error)) error
	// RegisterCustomStoreFactory registers a factory function that can be used to create a custom storage client for the Store & Forward loop.
	RegisterCustomStoreFactory(name string, factory func(cfg config.Database, cred config.Credentials) (StoreClient, error)) error
	// AddBackgroundPublisher Adds and returns a BackgroundPublisher which is used to publish
	// asynchronously to the Edgex MessageBus.
	// Not valid for use with the HTTP or External MQTT triggers *DEPRECATED*
	AddBackgroundPublisher(capacity int) (BackgroundPublisher, error)
	// AddBackgroundPublisherWithTopic Adds and returns a BackgroundPublisher which is used to publish
	// asynchronously to the Edgex MessageBus on the specified topic.
	// Not valid for use with the HTTP or External MQTT triggers
	AddBackgroundPublisherWithTopic(capacity int, topic string) (BackgroundPublisher, error)
	// SecretProvider returns the SecretProvider instance
	SecretProvider() bootstrapInterfaces.SecretProvider
	// LoggingClient returns the Logger client
	LoggingClient() logger.LoggingClient
	// EventClient returns the Event client. Note if Core Data is not specified in the Clients configuration,
	// this will return nil.
	EventClient() interfaces.EventClient
	// ReadingClient returns the Reading client. Note if Core Data is not specified in the Clients configuration,
	// this will return nil.
	ReadingClient() interfaces.ReadingClient
	// CommandClient returns the Command client. Note if Core Command is not specified in the Clients configuration,
	// this will return nil.
	CommandClient() interfaces.CommandClient
	// NotificationClient returns the Notification client. Note if Support Notifications is not specified in the
	// Clients configuration, this will return nil.
	NotificationClient() interfaces.NotificationClient
	// SubscriptionClient returns the Subscription client. Note if Support Notifications is not specified in the
	// Clients configuration, this will return nil.
	SubscriptionClient() interfaces.SubscriptionClient
	// DeviceServiceClient returns the DeviceService client. Note if Core Metadata is not specified in the
	// Clients configuration, this will return nil.
	DeviceServiceClient() interfaces.DeviceServiceClient
	// DeviceProfileClient returns the DeviceProfile client. Note if Core Metadata is not specified in the
	// Clients configuration, this will return nil.
	DeviceProfileClient() interfaces.DeviceProfileClient
	// DeviceClient returns the Device client. Note if Core Metadata is not specified in the
	// Clients configuration, this will return nil.
	DeviceClient() interfaces.DeviceClient
	// RegistryClient returns the Registry client. Note the registry must been enable, otherwise this will return nil.
	// Useful if service needs to add additional health checks or needs to get endpoint of another registered service
	RegistryClient() registry.Client
	// MetricsManager returns the Metrics Manager used to register counter, gauge, gaugeFloat64 or timer metric types from
	// github.com/rcrowley/go-metrics
	MetricsManager() bootstrapInterfaces.MetricsManager
	// LoadConfigurableFunctionPipelines loads the function pipelines (default and per topic) from configuration.
	// An error is returned if the configuration is not valid, i.e. missing required function parameters,
	// invalid function name, etc.
	// Only useful if pipeline is always defined in configuration as is with App Service Configurable.
	LoadConfigurableFunctionPipelines() (map[string]FunctionPipeline, error)
	// LoadCustomConfig loads the service's custom configuration from local file or the Configuration Provider (if enabled)
	// Configuration Provider will also be seeded with the custom configuration if service is using the Configuration Provider.
	// UpdateFromRaw interface will be called on the custom configuration when the configuration is loaded from the
	// Configuration Provider.
	LoadCustomConfig(config UpdatableConfig, sectionName string) error
	// ListenForCustomConfigChanges starts a listener on the Configuration Provider for changes to the specified
	// section of the custom configuration. When changes are received from the Configuration Provider the
	// UpdateWritableFromRaw interface will be called on the custom configuration to apply the updates and then signal
	// that the changes occurred via writableChanged.
	ListenForCustomConfigChanges(configToWatch interface{}, sectionName string, changedCallback func(interface{})) error
	// BuildContext allows external callers that may need a context (eg background publishers) to easily create one
	BuildContext(correlationId string, contentType string) AppFunctionContext
	// Publish pushes data to the MessageBus using configured topic
	Publish(data any, contentType string) error
	// PublishWithTopic pushes data to the MessageBus using given topic
	PublishWithTopic(topic string, data any, contentType string) error
}

ApplicationService defines the interface for an edgex Application Service

type Authentication

type Authentication bool

Authentication is a typed boolean for AddRoute calls

const (
	Unauthenticated Authentication = false
	Authenticated   Authentication = true
)

type BackgroundMessage

type BackgroundMessage interface {
	Message() types.MessageEnvelope
	Topic() string
}

type BackgroundPublisher

type BackgroundPublisher interface {
	// Publish provided message through the configured MessageBus output
	Publish(payload []byte, context AppFunctionContext) error
}

BackgroundPublisher provides an interface to send messages from background processes through the service's configured MessageBus output

type FunctionPipeline

type FunctionPipeline struct {
	// Unique identifier for the pipeline.
	Id string
	// Collection of App Functions to execute
	Transforms []AppFunction
	// Topics to match against the incoming topic to determine if the pipeline will execute on the incoming message
	Topics []string
	// Hash of the list of transforms set and used internally for Store and Forward
	Hash string

	MessagesProcessed     gometrics.Counter
	MessageProcessingTime gometrics.Timer
	ProcessingErrors      gometrics.Counter
}

FunctionPipeline defines an instance of a Functions Pipeline

type PipelineResponseHandler

type PipelineResponseHandler func(ctx AppFunctionContext, pipeline *FunctionPipeline) error

PipelineResponseHandler provides a function signature that can be passed to MessageProcessor to handle pipeline output(s)

type StoreClient

type StoreClient interface {
	// Store persists a stored object to the data store and returns the assigned UUID.
	Store(o StoredObject) (id string, err error)

	// RetrieveFromStore gets an object from the data store.
	RetrieveFromStore(appServiceKey string) (objects []StoredObject, err error)

	// Update replaces the data currently in the store with the provided data.
	Update(o StoredObject) error

	// RemoveFromStore removes an object from the data store.
	RemoveFromStore(o StoredObject) error

	// Disconnect ends the connection.
	Disconnect() error
}

StoreClient establishes the contracts required to persist exported data before being forwarded.

type StoredObject

type StoredObject struct {
	// ID uniquely identifies this StoredObject
	ID string
	// AppServiceKey identifies the app to which this data belongs.
	AppServiceKey string
	// Payload is the data to be exported
	Payload []byte
	// RetryCount is how many times this has tried to be exported
	RetryCount int
	// PipelineId is the ID of the pipeline that needs to be restarted.
	PipelineId string
	// PipelinePosition is where to pickup in the pipeline
	PipelinePosition int
	// Version is a hash of the functions to know if the pipeline has changed.
	Version string
	// CorrelationID is an identifier provided by EdgeX to track this record as it moves
	CorrelationID string
	// ContextData is a snapshot of data used by the pipeline at runtime
	ContextData map[string]string
}

StoredObject is the atomic and most abstract description of what is collected by the export store system.

func NewStoredObject

func NewStoredObject(appServiceKey string, payload []byte, pipelineId string, pipelinePosition int,
	version string, contextData map[string]string) StoredObject

NewStoredObject creates a new instance of StoredObject and is the preferred way to create one.

func (*StoredObject) ValidateContract

func (o *StoredObject) ValidateContract(IDRequired bool) error

ValidateContract ensures that the required fields are present on the object.

type Trigger

type Trigger interface {
	// Initialize performs post creation initializations
	Initialize(wg *sync.WaitGroup, ctx context.Context, background <-chan BackgroundMessage) (bootstrap.Deferred, error)
}

Trigger provides an abstract means to pass messages to the function pipeline

type TriggerConfig

type TriggerConfig struct {
	// Logger exposes the logging client passed from the service
	Logger logger.LoggingClient
	// ContextBuilder contructs a context the trigger can specify for processing the received message
	ContextBuilder TriggerContextBuilder
	// MessageReceived sends a message to the runtime for processing.
	MessageReceived TriggerMessageHandler
	// ConfigLoader is a function of type TriggerConfigLoader that can be used to load custom configuration sections for the trigger.s
	ConfigLoader TriggerConfigLoader
}

type TriggerConfigLoader

type TriggerConfigLoader func(config UpdatableConfig, sectionName string) error

TriggerConfigLoader provides an interface that can be used by custom triggers to load custom configuration elements

type TriggerContextBuilder

type TriggerContextBuilder func(env types.MessageEnvelope) AppFunctionContext

TriggerContextBuilder provides an interface to construct an AppFunctionContext for message

type TriggerMessageHandler

type TriggerMessageHandler func(ctx AppFunctionContext, envelope types.MessageEnvelope, responseHandler PipelineResponseHandler) error

TriggerMessageHandler provides an interface that can be used by custom triggers to invoke the runtime

type TriggerMessageProcessor

type TriggerMessageProcessor func(ctx AppFunctionContext, envelope types.MessageEnvelope) error

TriggerMessageProcessor provides an interface that can be used by custom triggers to invoke the runtime

type UpdatableConfig

type UpdatableConfig interface {
	bootstrapInterfaces.UpdatableConfig
}

UpdatableConfig interface allows services to have custom configuration populated from configuration stored in the Configuration Provider (aka keeper). Services using custom configuration must implement this interface on their custom configuration, even if they do not use Configuration Provider. If they do not use the Configuration Provider they can have dummy implementation of this interface. This wraps the actual interface from go-mod-bootstrap so app service code doesn't have to have the additional direct import of go-mod-bootstrap.