connector

package module
v0.4.5 Latest Latest
Warning

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

 Go to latest Published: Dec 1, 2022 License: MIT Imports: 20 Imported by: 1

README

connctd docs

Connctd SDK for creating and publishing Connectors to the connctd platform.

The SDK implements the connector protocol to handle all communication between a connector and the connctd platform as well as the boilerplate needed by most connectors. It does not assume a specific technology but provides a connector handler implementing the connector protocol, interfaces to use with the handler and a client for the connctd platform. For most technologies the provided default implementations should be sufficient to quickly implement a connector without the need to implement code specific to the connctd platform.

Documentation and usage

Documentation for the SDK can be found here. See the connector documentation and the connctd tutorials for more details on connectors, the connector protocol and the connctd platform.

Most connectors should be able to use the default implementations and embed the default provider to only develop code specific to the connected technology. The default provider gives access to update and action channels which can be used by the connector to listen to updates and actions sent by the connctd platform. It also implements methods to push updates and action results back to the connctd platform. Using the default implementations, developing a new connector therefore breaks down to two basic tasks:

  1. Defining the things to represent the technology at the connctd platform
  2. Implementing the features specific to the technology

A public connector using this SDK including a detailed tutorial can be found at Github.

Structure

The connector SDK is also the default implementation of the connector protocol. If you want to develop a connector in a different language, you can use it together with the connector protocol documentation as a reference for your own implementation. The following gives an overview of the structure of the SDK:

├── connctd
│   └── things.go             # Domain models for the connctd thing abstraction
├── crypto
│   ├── signing.go            # Signature validation
│   └── signing_test.go
├── db
│   └── default_database.go   # Default database implementation (Sqlite, Mysql, Postgres)
├── provider
│   └── default_provider.go   # Default provider implementation used by default service
├── service
│   └── default_service.go    # Default service implementation used by the connector handler
├── vendor                    # Dependencies
├── client.go                 # Client for the connctd connectorhub
├── client_test.go
├── connhandler.go            # Connector handler implementing endpoints for the connector protocol
├── errors.go                 # Error definitions
├── go.mod
├── go.sum
├── handlers.go               # Signature validation handlers for the connector protocol
├── handlers_test.go
├── LICENSE
├── messages.go               # Definitions of messages used in the connector protocol
├── model.go                  # Models specific to connectors
├── provider.go               # Interface definition used by the default service
├── README.md
└── service.go                # Interface definitions for the service used by the connector handler

Contact

Please use the provided templates for bug reports and feature requests and feel free to contact connctd at info@connctd.com.

Documentation

Overview

Package connector implements a SDK for connector development. In most cases it should be sufficient to use the default provider to implement the connector.Provider interface and use it with the default service and the connector handler. For an example connector using this SDK to integrate an external API, see https://github.com/connctd/giphy-connector/.

Index

Constants

View Source 
const (
	// APIBaseURL defines how to reach connctd API.
	APIBaseURL = "https://connectors.connctd.io/api/v1/"
)

Variables

View Source 
var (
	ErrorInvalidBaseURL       = errors.New("the base url needs to end with a slash")
	ErrorMissingLogger        = errors.New("a logger needs to be passed")
	ErrorUnexpectedStatusCode = errors.New("the resulting status code does not match with expectation")
	ErrorUnexpectedResponse   = errors.New("remote site replied with unexpected contents")
)

The following errors can be returned by the API client:

View Source 
var (
	ErrorBadContentType        = NewError("BAD_CONTENT_TYPE", "Expected content type to be application/json", http.StatusBadRequest)
	ErrorMissingInstanceID     = NewError("MISSING_INSTANCE_ID", "Instance ID is missing", http.StatusBadRequest)
	ErrorMissingInstallationID = NewError("MISSING_INSTALLATION_ID", "Installation ID is missing", http.StatusBadRequest)
	ErrorBadRequestBody        = NewError("BAD_REQUEST_BODY", "Empty or malformed request body", http.StatusBadRequest)
	ErrorInvalidJsonBody       = NewError("INVALID_JSON_BODY", "Request body does not contain valid json", http.StatusBadRequest)
	ErrorInstallationNotFound  = NewError("INSTALLATION_NOT_FOUND", "Installation not found", http.StatusNotFound)
	ErrorInstanceNotFound      = NewError("INSTANCE_NOT_FOUND", "Instance not found", http.StatusNotFound)
	ErrorForbidden             = NewError("FORBIDDEN", "Insufficient rights", http.StatusForbidden)
	ErrorUnauthorized          = NewError("NOT_AUTHORIZED", "Not authorized", http.StatusUnauthorized)
	ErrorInternal              = NewError("INTERNAL_SERVER_ERROR", "Internal server error", http.StatusInternalServerError)
	ErrorMappingNotFound       = NewError("MAPPING_NOT_FOUND", "Mapping not found", http.StatusNotFound)
)

Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly. Developers can define new errors using connector.NewError but this should not be necessary for the connector protocol.

View Source 
var (
	ErrorMissingHeader = NewError("MISSING_HEADER", "Signable payload can not be generated since a relevant header is missing", http.StatusBadRequest)
	ErrorBadSignature  = NewError("BAD_SIGNATURE", "Signature seems to be invalid", http.StatusBadRequest)
	ErrorSigningFailed = NewError("SIGNING_FAILED", "Failed to sign the request", http.StatusBadRequest)
	ErrorInvalidBody   = NewError("INVALID_BODY", "Unable to read message body", http.StatusBadRequest)
)

Possible errors returned by NewSignatureValidationHandler:

View Source 
var DefaultLogger = stdr.New(stdlog.New(os.Stderr, "", stdlog.LstdFlags|stdlog.Lshortfile))

DefaultLogger uses go standard logging capabilities.

Functions

func AddInstallation 

func AddInstallation(service ConnectorService) http.HandlerFunc

AddInstallation is called whenever a connector is installed via the connctd platform. It will validate the request and delegate valid requests to the service. It expects an error from errors.go. The status code will be set to one defined in the error and the InstantiationResponse will be returned to the connctd platform.

func AddInstance 

func AddInstance(service ConnectorService) http.HandlerFunc

AddInstance is called whenever a connector is instantiated via the connctd platform. It will validate the request and delegate valid requests to the service. It expects an error from errors.go. The status code will be set to one defined in the error and the InstantiationResponse will be returned to the connctd platform.

func NewSignatureValidationHandler 

func NewSignatureValidationHandler(validationPreProcessor ValidationPreProcessor, publicKey ed25519.PublicKey, next http.HandlerFunc) http.Handler

NewSignatureValidationHandler creates a new handler capable of verifying the signature header. Validation can be influenced by passing a ValidationPreProcessor. Common functionalities are offered by DefaultValidationPreProcessor and ProxiedRequestValidationPreProcessor

func PerformAction 

func PerformAction(service ConnectorService) http.HandlerFunc

PerformAction is called whenever an action is triggered via the connctd platform. It will validate the action request and delegate valid requests to the service. If the action is pending, the service should respond with an ActionResponse. It is then the responsibility of the service to update the action request state as soon as the request is completed. If the action is successfully completed, the service should return nil. In case of an error, the service should respond with an appropriate error from errors.go.

func RemoveInstallation 

func RemoveInstallation(service ConnectorService) http.HandlerFunc

RemoveInstallation is called whenever an installation is removed by the the connctd platform.

func RemoveInstance 

func RemoveInstance(service ConnectorService) http.HandlerFunc

RemoveInstance is called whenever an instance is removed by the the connctd platform.

Types

type APIClient 

type APIClient struct {
	// contains filtered or unexported fields
}

APIClient implements Client interface.

func (*APIClient) CreateThing 

func (a *APIClient) CreateThing(ctx context.Context, token InstantiationToken, thing connctd.Thing) (result connctd.Thing, err error)

CreateThing implements interface definition.

func (*APIClient) DeleteThing 

func (a *APIClient) DeleteThing(ctx context.Context, token InstantiationToken, thingID string) error

DeleteThing implements interface definition.

func (*APIClient) UpdateActionStatus 

func (a *APIClient) UpdateActionStatus(ctx context.Context, token InstantiationToken, actionRequestID string, status ActionRequestStatus, e string) error

UpdateActionStatus implements interface definition.

func (*APIClient) UpdateInstallationState 

func (a *APIClient) UpdateInstallationState(ctx context.Context, token InstallationToken, state InstallationState, details json.RawMessage) error

UpdateInstallationState implements interface definition.

func (*APIClient) UpdateInstanceState 

func (a *APIClient) UpdateInstanceState(ctx context.Context, token InstantiationToken, state InstantiationState, details json.RawMessage) error

UpdateInstanceState implements interface definition.

func (*APIClient) UpdateThingPropertyValue 

func (a *APIClient) UpdateThingPropertyValue(ctx context.Context, token InstantiationToken, thingID string, componentID string, propertyID string, value string, lastUpdate time.Time) error

UpdateThingPropertyValue implements interface definition.

func (*APIClient) UpdateThingStatus 

func (a *APIClient) UpdateThingStatus(ctx context.Context, token InstantiationToken, thingID string, status connctd.StatusType) error

UpdateThingStatus implements interface definition.

type ActionEvent 

type ActionEvent struct {
	InstanceId string
	RequestId  string
	Response   *ActionResponse
}

ActionEvent is used to propagate action request results to the service. See UpdateEvent for details.

type ActionRequest 

type ActionRequest struct {
	ID          string              `json:"id"`
	ThingID     string              `json:"thingId"`
	ComponentID string              `json:"componentId"`
	ActionID    string              `json:"actionId"`
	Status      ActionRequestStatus `json:"status"`
	Parameters  map[string]string   `json:"parameters"`
}

ActionRequest is sent by connctd platform in order to trigger an action.

type ActionRequestStatus 

type ActionRequestStatus string

ActionRequestStatus indicates the status of an action request. 

const (
	ActionRequestStatusPending   ActionRequestStatus = "PENDING"
	ActionRequestStatusCompleted ActionRequestStatus = "COMPLETED"
	ActionRequestStatusFailed    ActionRequestStatus = "FAILED"
	ActionRequestStatusCanceled  ActionRequestStatus = "CANCELED"
)

type ActionRequestStatusUpdate 

type ActionRequestStatusUpdate struct {
	Status ActionRequestStatus `json:"status"`
	Error  string              `json:"error"`
}

ActionRequestStatusUpdate allows a connector to update the status of an action.

type ActionResponse 

type ActionResponse struct {
	Status ActionRequestStatus `json:"status"`
	Error  string              `json:"error"`
}

ActionResponse can be sent in order to inform about the state of an action.

type AddThingRequest 

type AddThingRequest struct {
	Thing connctd.Thing `json:"thing"`
}

AddThingRequest is used to create a new thing on the connctd platform.

type AddThingResponse 

type AddThingResponse struct {
	ID string `json:"id"`
}

AddThingResponse describes the response sent by connctd when thing creation was successful.

type Client 

type Client interface {
	// CreateThing can be used to create a thing.
	// The ID of the newly created thing is returned if the operation was successful.
	// Otherwise an error is returned.
	CreateThing(ctx context.Context, token InstantiationToken, thing connctd.Thing) (result connctd.Thing, err error)

	// UpdateThingPropertyValue returns an error if the update was not successful.
	UpdateThingPropertyValue(ctx context.Context, token InstantiationToken, thingID string, componentID string, propertyID string, value string, lastUpdate time.Time) error

	// UpdateThingStatus updates the status of a thing.
	// It can be used to set the availability of a thing.
	UpdateThingStatus(ctx context.Context, token InstantiationToken, thingID string, status connctd.StatusType) error

	// UpdateActionStatus can be used to inform the connctd platform about the new state of an action request.
	// It must be used to finish pending action request.
	// If the action request was not successful, an optional error can be set for additional error details.
	UpdateActionStatus(ctx context.Context, token InstantiationToken, actionRequestID string, status ActionRequestStatus, err string) error

	// UpdateInstallationState can be used to inform the connctd platform about the new state of an installation.
	// It must be called if the installation requires multiple steps, after it is finished.
	UpdateInstallationState(ctx context.Context, token InstallationToken, state InstallationState, details json.RawMessage) error

	// UpdateInstanceState can be used to inform the connctd platform about the new state of an instance creation.
	// It must be called if the instantiation requires multiple steps.
	UpdateInstanceState(ctx context.Context, token InstantiationToken, state InstantiationState, details json.RawMessage) error

	// DeleteThing can be used to delete a thing.
	DeleteThing(ctx context.Context, token InstantiationToken, thingID string) error
}

Client interface defines API client functionalities for the connctd platform. For more details about API see https://docs.connctd.io/connector/connector_protocol/#connctd-api.

func NewClient 

func NewClient(opts *ClientOptions, logger logr.Logger) (Client, error)

NewClient creates a new API client.

type ClientOptions 

type ClientOptions struct {
	ConnctdBaseURL *url.URL
	HTTPClient     *http.Client
}

ClientOptions allow modification of API client behaviour.

func DefaultOptions 

func DefaultOptions() *ClientOptions

DefaultOptions returns default client options.

type Configuration 

type Configuration struct {
	ID    string `json:"id"`
	Value string `json:"value"`
}

Configuration is key value pair

type ConnectorHandler 

type ConnectorHandler struct {
	// contains filtered or unexported fields
}

ConnectorHandler implements all endpoints used in the connector protocol and validates all incoming requests with the SignatureValidationHandler. Connector developers ususally do not need to modify any of the handlers.

func NewConnectorHandler 

func NewConnectorHandler(subrouter *mux.Router, service ConnectorService, publicKey ed25519.PublicKey) *ConnectorHandler

NewConnectorHandler returns a connector handler that detects proxies and modifies the validation parameters for the signature validation. This should be used by default and should also work without any proxies in place. Note that the proxy has to set the correct headers for this to work. See AutoProxyRequestValidationPreProcessor for more information.

func NewProxiedConnectorHandler 

func NewProxiedConnectorHandler(subrouter *mux.Router, service ConnectorService, host string, publicKey ed25519.PublicKey) *ConnectorHandler

NewProxiedConnectorHandler lets you manually set the host used for the signature validation. This can be usefull if you are behind a proxy that doesn't set the correct headers. Note that we set the protocol to "https" since this is the only protocol supported by connctd.

func (*ConnectorHandler) ServeHTTP 

func (c *ConnectorHandler) ServeHTTP(w http.ResponseWriter, request *http.Request)

ServeHTTP implements the http.Handler interface by delegating to the router

type ConnectorService 

type ConnectorService interface {
	// AddInstallation is called by the ConnectorHandler when it received an installation request.
	// The request is validated before calling AddInstallation but the connector can implemnet additional validation.
	// If the installation is completed successfully, the service should return nil and no error.
	// If the installation needs further steps, the service should respond with an InstallationResponse and no error.
	// It is then the responsibility of the service to update the installation state as soon as the installation is completed.
	// In case of an error, the service should respond with an appropriate error from errors.go and can also return an InstallationResponse.
	// The status code will be set to one defined in the error and the InstallationResponse will be returned to the connctd platform.
	AddInstallation(ctx context.Context, request InstallationRequest) (*InstallationResponse, error)

	// RemoveInstallation is called whenever an installation is removed by the the connctd platform.
	// The connector should remove the installation and can return an error if needed.
	// Regardless of the return value, the installation is removed from the connctd platform.
	RemoveInstallation(ctx context.Context, installationId string) error

	// AddInstance is called by the ConnectorHandler whenever a connector is instantiated via the connctd platform.
	// The request is validated before calling AddInstance but the connector can implemnet additional validation.
	// If the instantiation is completed successfully, the service should return nil and no error.
	// If the instantiation needs further steps, the service should respond with an InstantiationResponse and no error.
	// It is then the responsibility of the service to update the instantiation state as soon as the instantiation is completed.
	// In case of an error, the service should respond with an appropriate error from errors.go and can also return an InstantiationResponse.
	// The status code will be set to one defined in the error and the InstantiationResponse will be returned to the connctd platform.
	AddInstance(ctx context.Context, request InstantiationRequest) (*InstantiationResponse, error)

	//RemoveInstance is called whenever an instance is removed by the the connctd platform.
	RemoveInstance(ctx context.Context, instanceId string) error

	// PerformAction is called by the ConnectorHandler whenever an action is triggered via the connctd platform.
	// The request is validated before calling PerformAction but the connector can implement additional validation.
	// If the action is pending, the service should respond with an ActionResponse.
	// It is then the responsibility of the service to update the action request state as soon as the request is completed.
	// If the action is successfully completed, the service should return nil.
	// In case of an error, the service should respond with an appropriate error from errors.go.
	PerformAction(ctx context.Context, request ActionRequest) (*ActionResponse, error)
}

ConnectorService interface is used by the ConnectorHandler and will be called to process the validated requests used in the connector protocol. The SDK provides a default implementation for the ConnectorService interface that should be sufficient for most connector developments.

type Database 

type Database interface {
	AddInstallation(ctx context.Context, installationRequest InstallationRequest) error
	AddInstallationConfiguration(ctx context.Context, installationId string, config []Configuration) error
	GetInstallations(ctx context.Context) ([]*Installation, error)
	RemoveInstallation(ctx context.Context, installationId string) error
	GetInstancesInstallationConfiguration(ctx context.Context, instanceID string) ([]*Configuration, error)

	AddInstance(ctx context.Context, instantiationRequest InstantiationRequest) error
	AddInstanceConfiguration(ctx context.Context, instanceId string, config []Configuration) error
	GetInstance(ctx context.Context, instanceId string) (*Instance, error)
	GetInstances(ctx context.Context) ([]*Instance, error)
	GetInstanceByThingId(ctx context.Context, thingId string) (*Instance, error)
	GetInstanceConfiguration(ctx context.Context, instanceId string) ([]Configuration, error)
	GetMappingByInstanceId(ctx context.Context, instanceId string) ([]ThingMapping, error)
	GetMappingByExternalId(ctx context.Context, instanceId string, externalID string) (*ThingMapping, error)
	RemoveInstance(ctx context.Context, instanceId string) error

	AddThingMapping(ctx context.Context, instanceID string, thingID string, externalId string) error
	RemoveThingMapping(ctx context.Context, instanceID string, thingID string) error
}

Database interface is used in the default service to persist new installations, instances, configurations and external device mappings. The SDK provides a default implementation supporting Postgresql, Mysql and Sqlite3.

type Error 

type Error struct {
	APIError    string `json:"error"`
	Description string `json:"description"`
	Status      int    `json:"status"`
}

Error defines an error

func NewError 

func NewError(err string, description string, status int) *Error

NewError constructs an error

func (*Error) Error 

func (e *Error) Error() string

Error returns the errors description

func (*Error) Write 

func (e *Error) Write(w http.ResponseWriter)

Write uses given response writer to write an error

type Installation 

type Installation struct {
	ID            string            `db:"id" json:"id"`
	Token         InstallationToken `db:"token" json:"token"`
	Configuration []Configuration   `json:"configuration"`
}

Installation represents connector installationa and their configuration. We store it in the database to be able to access the configuration and to map instances to specific installations. Also we need to store the installation token, to be able to manage the installation with the platform. The installation token must be kept secret.

func (*Installation) GetConfig 

func (i *Installation) GetConfig(id string) (*Configuration, bool)

GetConfig returns the configuration parameter with the given ID. If the parameter was not found it returns false.

type InstallationRequest 

type InstallationRequest struct {
	ID            string            `json:"id"`
	Token         InstallationToken `json:"token"`
	State         InstallationState `json:"state"`
	Configuration []Configuration   `json:"configuration"`
}

InstallationRequest sent by connctd in order to signalise a new installation.

func (*InstallationRequest) GetConfig added in v0.2.1 

func (i *InstallationRequest) GetConfig(id string) (*Configuration, bool)

GetConfig returns the configuration parameter with the given ID. If the parameter was not found it returns false.

type InstallationResponse 

type InstallationResponse struct {
	Details     json.RawMessage `json:"details,omitempty"`
	FurtherStep Step            `json:"furtherStep,omitempty"`
}

InstallationResponse defines the optional response to an installation request.

type InstallationState 

type InstallationState int

InstallationState reflects the current state of an installation. 

const (
	InstallationStateInitialized InstallationState = 1
	InstallationStateComplete    InstallationState = 2
	InstallationStateOngoing     InstallationState = 3
	InstallationStateFailed      InstallationState = 4
)

Valid installations states:

type InstallationStateUpdateRequest 

type InstallationStateUpdateRequest struct {
	State   InstallationState `json:"state"`
	Details json.RawMessage   `json:"details,omitempty"`
}

InstallationStateUpdateRequest can be sent by a connector to indicate new state.

type InstallationToken 

type InstallationToken string

InstallationToken can be used by a connector installation to propagte e.g. state changes

type Instance 

type Instance struct {
	ID             string             `db:"id" json:"id"`
	InstallationID string             `db:"installation_id" json:"installationId"`
	Token          InstantiationToken `db:"token" json:"token"`
	ThingMapping   []ThingMapping     `json:"things"`
	Configuration  []Configuration    `json:"configuration"`
}

Instance represents connector instances. We store it in the database to be able to map a instance to a specific thing and installation. We also store its token to be able to manage the instance with the platform. The instance token must be kept secret.

func (*Instance) ExternalIdByThingId added in v0.3.0 

func (i *Instance) ExternalIdByThingId(thingID string) (string, bool)

ExternalIdByThingId returns the ExternalID that is mapped to the given ThingID or false if no such mapping exists.

func (*Instance) GetConfig 

func (i *Instance) GetConfig(id string) (*Configuration, bool)

GetConfig returns the configuration parameter with the given ID. If the parameter was not found it returns false.

func (*Instance) ThingIdByExternalId added in v0.2.2 

func (i *Instance) ThingIdByExternalId(externalID string) (string, bool)

ThingIdByExternalId returns the ThingId that is mapped to the given externalID or false if no such mapping exists.

type InstanceStateUpdateRequest 

type InstanceStateUpdateRequest struct {
	State   InstantiationState `json:"state"`
	Details json.RawMessage    `json:"details,omitempty"`
}

InstanceStateUpdateRequest can be sent by a connector to indicate a new state.

type InstantiationRequest 

type InstantiationRequest struct {
	ID             string             `json:"id"`
	InstallationID string             `json:"installation_id"`
	Token          InstantiationToken `json:"token"`
	State          InstantiationState `json:"state"`
	Configuration  []Configuration    `json:"configuration"`
}

InstantiationRequest sent by connctd in order to signalise a new instantiation.

func (*InstantiationRequest) GetConfig added in v0.2.1 

func (i *InstantiationRequest) GetConfig(id string) (*Configuration, bool)

GetConfig returns the configuration parameter with the given ID. If the parameter was not found it returns false.

type InstantiationResponse 

type InstantiationResponse struct {
	Details     json.RawMessage `json:"details,omitempty"`
	FurtherStep Step            `json:"furtherStep,omitempty"`
}

InstantiationResponse defines the optional response to an instantiation request.

type InstantiationState 

type InstantiationState int

InstantiationState reflects the current state of an instantiation. 

const (
	InstantiationStateInitialized InstantiationState = 1
	InstantiationStateComplete    InstantiationState = 2
	InstantiationStateOngoing     InstantiationState = 3
	InstantiationStateFailed      InstantiationState = 4
)

Valid instantiations states:

type InstantiationToken 

type InstantiationToken string

InstantiationToken can be used by a connector instance to send things or updates

type PropertyUpdateEvent 

type PropertyUpdateEvent struct {
	ThingId     string
	InstanceId  string
	ComponentId string
	PropertyId  string
	Value       string
}

ActionEvent is used to propagate property updates to the service. See UpdateEvent for details.

type Provider 

type Provider interface {
	// UpdateChannel is used by the connector service to receive update event.
	// The provider can push updates to the underlying channel or use directly use the connctd API client.
	UpdateChannel() <-chan UpdateEvent

	// RequestAction is called by the connector service when it received an action request.
	// The provider can execute the action synchronously and return an ActionRequestStatusCompleted or ActionRequestStatusFailed.
	// If it returns ActionRequestStatusFailed it is expected to also return an error with details on the failing condition.
	// In both cases an appropriate connector.ActionResponse is returned to the platform.
	// The provider can also decide to execute the action request asynchronously and return an ActionRequestStatusPending.
	// It is then the responsibility of the provider to update the action request as soon as it is finished.
	RequestAction(ctx context.Context, instance *Instance, actionRequest ActionRequest) (ActionRequestStatus, error)

	// RegisterInstallations is called by the connector service to register new installations
	// Installations are registered whenever the service received an successful installation request or when the connector is started.
	RegisterInstallations(installations ...*Installation) error

	// RemoveInstance is called by the service if it received an installation removal request.
	RemoveInstallation(installationId string) error

	// RegisterInstances is called by the connector service to register new instances.
	// Instances are registered whenever the service received an successful instantiation request or when the connector is started.
	RegisterInstances(instances ...*Instance) error

	// RemoveInstance is called by the service if it received an instance removal request.
	RemoveInstance(instanceId string) error
}

The Provider interface is used in the default service to implement all technology specific details. It is the only interface most connectors should need to implement. A default implementation meant to be embedded in new connectors is provided by the SDK. It implements registration and removal of installations and instances, as well as an update channel and asynchronous action request. Connectors can use the update channel to push thing and action request updates to the connctd platform and should implemnet an action handler if they implement actions.

type Step 

type Step struct {
	Type    StepType `json:"type"`
	Content string   `json:"content"`
}

Step defines a further installation or instantiation step

type StepType 

type StepType int

StepType defines the type of a further installation or instantiation step. 

const (
	StepText     StepType = 1
	StepMarkdown StepType = 2
	StepRedirect StepType = 3
)

Possible step types:

type ThingMapping 

type ThingMapping struct {
	InstanceID string `db:"instance_id" json:"-"`
	ThingID    string `db:"thing_id" json:"thing_id"`
	ExternalID string `db:"external_id" json:"external_id"`
}

ThinkMapping represents a mapping of instances to things and external ID.

type ThingTemplate added in v0.2.0 

type ThingTemplate struct {
	Thing      connctd.Thing
	ExternalID string
}

ThingTemplate describes the thing together with an external ID that is created for each new instance. If the connector doesn't need an external ID it can be left blank.

type ThingTemplates 

type ThingTemplates func(request InstantiationRequest) []ThingTemplate

ThingTemplates is used by the default connector service to create a set of connctd.Thing for each new instantiation request. For each template in the returned slice, the default service will: - create the connctd.Thing with the connctd platform - store a connector.ThingMapping{} with the instantiation request ID, the ID of the created thing and the external ID - register the new thing with the provider

type UpdateEvent 

type UpdateEvent struct {
	ActionEvent         *ActionEvent
	PropertyUpdateEvent *PropertyUpdateEvent
}

UpdateEvents are pushed to the UpdateChannel. The default service will listen to the channel. If it receives an UpdateEvent with only a PropertyEventUpdate it will update the specified property with the new value. If it receives an ActionEvent it will update the the state of the specified action request to the state in the ActionResponse. If the same UpdateEvent contains a PropertyUpateEvent it will first update the property and then the action request. If the property update fails it will set the action request state to failed.

type UpdateThingPropertyValueRequest 

type UpdateThingPropertyValueRequest struct {
	Value      string    `json:"value"`
	LastUpdate time.Time `json:"lastUpdate"`
}

UpdateThingPropertyValueRequest can be used to propagate a new property value.

type UpdateThingStatusRequest 

type UpdateThingStatusRequest struct {
	Status connctd.StatusType `json:"status"`
}

UpdateThingStatusRequest allows updating the status of a thing.

type ValidationParameters 

type ValidationParameters struct {
	Scheme     string
	Host       string
	RequestURI string
}

ValidationParameters reflects a list of parameters that are relevant for request signature validation.

type ValidationPreProcessor 

type ValidationPreProcessor func(r *http.Request) ValidationParameters

ValidationPreProcessor can be used to influence the signature validation algorithm by returning a modified url struct. This becomes handy if your service is sitting behind a proxy that modifies the original request headers which normally would lead to a validation error.

func AutoProxyRequestValidationPreProcessor 

func AutoProxyRequestValidationPreProcessor() ValidationPreProcessor

AutoProxyRequestValidationPreProcessor is used to set the signature validation parameters to header values provided by a reverse proxy. Your proxy must set the header X-Forwarded-Proto to the original protocol used by the client and X-Forwarded-Host to the original host requested by the client.

func DefaultValidationPreProcessor 

func DefaultValidationPreProcessor() ValidationPreProcessor

DefaultValidationPreProcessor extracts all relevant values from request fields. Use this processor if there are no proxies between connctd platform and your connector.

func ProxiedRequestValidationPreProcessor 

func ProxiedRequestValidationPreProcessor(scheme string, host string) ValidationPreProcessor

ProxiedRequestValidationPreProcessor allows passing modified headers to the validate signature function. This is necessary when received request headers do not match up with sent request headers because of e.g. proxies in between.

Source Files

View all Source files

Directories

Path Synopsis
Package db implements default implementations for the database interface used by the default service.
 Package db implements default implementations for the database interface used by the default service.
Package provider implements the basic bookeeping needed by most providers.
 Package provider implements the basic bookeeping needed by most providers.
Package service implements a default service that can be used to quickly implement a connector.
 Package service implements a default service that can be used to quickly implement a connector.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.