Categorygithub.com/connctd/connector-go
modulepackage
0.4.5
Repository: https://github.com/connctd/connector-go.git
Documentation: pkg.go.dev

# 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 [email protected].

# Packages

No description provided by the author
No description provided by the author
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 service implements a default service that can be used to quickly implement a connector.

# Functions

AddInstallation is called whenever a connector is installed via the connctd platform.
AddInstance is called whenever a connector is instantiated via the connctd platform.
AutoProxyRequestValidationPreProcessor is used to set the signature validation parameters to header values provided by a reverse proxy.
DefaultOptions returns default client options.
DefaultValidationPreProcessor extracts all relevant values from request fields.
NewClient creates a new API client.
NewConnectorHandler returns a connector handler that detects proxies and modifies the validation parameters for the signature validation.
NewError constructs an error.
NewProxiedConnectorHandler lets you manually set the host used for the signature validation.
NewSignatureValidationHandler creates a new handler capable of verifying the signature header.
PerformAction is called whenever an action is triggered via the connctd platform.
ProxiedRequestValidationPreProcessor allows passing modified headers to the validate signature function.
RemoveInstallation is called whenever an installation is removed by the the connctd platform.
RemoveInstance is called whenever an instance is removed by the the connctd platform.

# Constants

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
APIBaseURL defines how to reach connctd API.
Valid installations states:.
Valid installations states:.
Valid installations states:.
Valid installations states:.
Valid instantiations states:.
Valid instantiations states:.
Valid instantiations states:.
Valid instantiations states:.
Possible step types:.
Possible step types:.
Possible step types:.

# Variables

DefaultLogger uses go standard logging capabilities.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
Possible errors returned by NewSignatureValidationHandler:.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
The following errors can be returned by the API client:.
Possible errors returned by NewSignatureValidationHandler:.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
Possible errors returned by NewSignatureValidationHandler:.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
The following errors can be returned by the API client:.
Possible errors returned by NewSignatureValidationHandler:.
Errors used in the service and ConnectorHandler The ConnectorHandler expects errors of the type connector.Error and will set the status code accordingly.
The following errors can be returned by the API client:.
The following errors can be returned by the API client:.

# Structs

ActionEvent is used to propagate action request results to the service.
ActionRequest is sent by connctd platform in order to trigger an action.
ActionRequestStatusUpdate allows a connector to update the status of an action.
ActionResponse can be sent in order to inform about the state of an action.
AddThingRequest is used to create a new thing on the connctd platform.
AddThingResponse describes the response sent by connctd when thing creation was successful.
APIClient implements Client interface.
ClientOptions allow modification of API client behaviour.
Configuration is key value pair.
ConnectorHandler implements all endpoints used in the connector protocol and validates all incoming requests with the SignatureValidationHandler.
Error defines an error.
Installation represents connector installationa and their configuration.
InstallationRequest sent by connctd in order to signalise a new installation.
InstallationResponse defines the optional response to an installation request.
InstallationStateUpdateRequest can be sent by a connector to indicate new state.
Instance represents connector instances.
InstanceStateUpdateRequest can be sent by a connector to indicate a new state.
InstantiationRequest sent by connctd in order to signalise a new instantiation.
InstantiationResponse defines the optional response to an instantiation request.
ActionEvent is used to propagate property updates to the service.
Step defines a further installation or instantiation step.
ThinkMapping represents a mapping of instances to things and external ID.
ThingTemplate describes the thing together with an external ID that is created for each new instance.
UpdateEvents are pushed to the UpdateChannel.
UpdateThingPropertyValueRequest can be used to propagate a new property value.
UpdateThingStatusRequest allows updating the status of a thing.
ValidationParameters reflects a list of parameters that are relevant for request signature validation.

# Interfaces

Client interface defines API client functionalities for the connctd platform.
ConnectorService interface is used by the ConnectorHandler and will be called to process the validated requests used in the connector protocol.
Database interface is used in the default service to persist new installations, instances, configurations and external device mappings.
The Provider interface is used in the default service to implement all technology specific details.

# Type aliases

ActionRequestStatus indicates the status of an action request.
InstallationState reflects the current state of an installation.
InstallationToken can be used by a connector installation to propagte e.g.
InstantiationState reflects the current state of an instantiation.
InstantiationToken can be used by a connector instance to send things or updates.
StepType defines the type of a further installation or instantiation step.
ThingTemplates is used by the default connector service to create a set of connctd.Thing for each new instantiation request.
ValidationPreProcessor can be used to influence the signature validation algorithm by returning a modified url struct.