interfaces

Documentation

Index

• Constants
• type AppFunction
• type AppFunctionContext
• type ApplicationService
• type BackgroundMessage
• type BackgroundPublisher
• type FunctionPipeline
• type PipelineResponseHandler
• 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, topic string)
	// GetSecret returns the secret data from the secret store (secure or insecure) for the specified path.
	// An error is returned if the path is not found or any of the keys (if specified) are not found.
	// Omit keys if all secret data for the specified path is required.
	GetSecret(path string, keys ...string) (map[string]string, error)
	// SecretsLastUpdated returns that timestamp for when the secrets in the SecretStore where last updated.
	// Useful when a connection to external source needs to be redone when the credentials have been updated.
	SecretsLastUpdated() time.Time
	// 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
	// CommandClient returns the Command client. Note if Support 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
	// PushToCore pushes a new event to Core Data.
	PushToCore(event dtos.Event) (common.BaseWithIdResponse, error)
	// 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
}

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 {
	// AddRoute 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
	AddRoute(route string, handler func(http.ResponseWriter, *http.Request), methods ...string) error
	// 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)
	// SetFunctionsPipeline has been deprecated (Replaced by SetDefaultFunctionsPipeline) and will be removed in a future release
	// Functions the same as SetDefaultFunctionsPipeline.
	SetFunctionsPipeline(transforms ...AppFunction) 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
	// MakeItRun 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 MakeItStop() is called.
	// An error is returned if the trigger can not be create or initialized or if the internal webserver
	// encounters an error.
	MakeItRun() error
	// MakeItStop stops the configured trigger so that the functions pipeline no longer executes.
	// An error is returned
	MakeItStop()
	// RegisterCustomTriggerFactory registers a trigger factory for a custom trigger to be used.
	RegisterCustomTriggerFactory(name string, factory func(TriggerConfig) (Trigger, 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
	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)
	// GetSecret returns the secret data from the secret store (secure or insecure) for the specified path.
	// An error is returned if the path is not found or any of the keys (if specified) are not found.
	// Omit keys if all secret data for the specified path is required.
	GetSecret(path string, keys ...string) (map[string]string, error)
	// StoreSecret stores the specified secret data into the secret store (secure only) for the specified path
	// An error is returned if:
	//   - Specified secret data is empty
	//   - Not using the secure secret store, i.e. not valid with InsecureSecrets configuration
	//   - Secure secret provider is not properly initialized
	//   - Connection issues with Secret Store service.
	StoreSecret(path string, secretData map[string]string) error // 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
	// CommandClient returns the Command client. Note if Support 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
	// LoadConfigurablePipeline loads the default function pipeline 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 from configuration is always defined in configuration as in App Service Configurable.
	// Note this API is deprecated, replaced by LoadConfigurableFunctionPipelines and will be removed in a future release
	LoadConfigurablePipeline() ([]AppFunction, error)
	// 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
}

ApplicationService defines the interface for an edgex Application Service

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
}

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 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
	// MessageProcessor processes a message on the services default pipeline
	// Deprecated: use MessageReceived for multi-pipeline support
	MessageProcessor TriggerMessageProcessor
	// 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 Consul). 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.