add transform fns to allow generalized plugins to manipulate reading …

…values (#399)

sdk/config/device.go

@@ -136,6 +136,13 @@ type DeviceInstance struct {
 	// e.g. "1e-2".
 	ScalingFactor string `yaml:"scalingFactor,omitempty"`
 
+	// Apply defines a list of functions which are to be applied to the device
+	// reading values, in the order in which they are defined.
+	//
+	// There are some built-in functions that the SDK provides. A plugin can also
+	// register their own functions.
+	Apply []string `yaml:"apply,omitempty"`
+
 	// WriteTimeout defines a custom write timeout for the device instance. This
 	// is the time within which the write transaction will remain valid. If left
 	// unspecified, it will fall back to the default value of 30s.

sdk/device.go

@@ -27,6 +27,7 @@ import (
 	log "github.com/sirupsen/logrus"
 	"github.com/vapor-ware/synse-sdk/sdk/config"
 	"github.com/vapor-ware/synse-sdk/sdk/errors"
+	"github.com/vapor-ware/synse-sdk/sdk/funcs"
 	"github.com/vapor-ware/synse-sdk/sdk/output"
 	"github.com/vapor-ware/synse-sdk/sdk/utils"
 	synse "github.com/vapor-ware/synse-server-grpc/go"
@@ -99,6 +100,10 @@ type Device struct {
 	// populated via the SDK on device loading and parsing and uses the Handler
 	// field to match the name of the handler to the actual instance.
 	handler *DeviceHandler
+
+	// fns defines a list of functions which should be applied to the reading value(s)
+	// for the device. This is called internally, if any fns are defined.
+	fns []*funcs.Func
 }
 
 // NewDeviceFromConfig creates a new instance of a Device from its device prototype
@@ -179,6 +184,16 @@ func NewDeviceFromConfig(proto *config.DeviceProto, instance *config.DeviceInsta
 		}
 	}
 
+	var fns []*funcs.Func
+	for _, fn := range instance.Apply {
+		f := funcs.Get(fn)
+		if f == nil {
+			// fixme: err message
+			return nil, fmt.Errorf("device specified unknown transform function")
+		}
+		fns = append(fns, f)
+	}
+
 	// Override write timeout, if set.
 	if instance.WriteTimeout != 0 {
 		writeTimeout = instance.WriteTimeout
@@ -200,6 +215,7 @@ func NewDeviceFromConfig(proto *config.DeviceProto, instance *config.DeviceInsta
 		ScalingFactor: instance.ScalingFactor,
 		WriteTimeout:  writeTimeout,
 		Output:        instance.Output,
+		fns:           fns,
 	}
 
 	if err := d.setAlias(instance.Alias); err != nil {

sdk/device_test.go

@@ -91,6 +91,7 @@ func TestNewDeviceFromConfig(t *testing.T) {
 	assert.Equal(t, "2", device.ScalingFactor)
 	assert.Equal(t, 5*time.Second, device.WriteTimeout)
 	assert.Equal(t, "temperature", device.Output)
+	assert.Equal(t, 0, len(device.fns))
 }
 
 func TestNewDeviceFromConfig2(t *testing.T) {
@@ -115,6 +116,7 @@ func TestNewDeviceFromConfig2(t *testing.T) {
 			"address": "localhost",
 		},
 		Output:    "temperature",
+		Apply:     []string{"FtoC"},
 		SortIndex: 1,
 		Alias: &config.DeviceAlias{
 			Name: "foo",
@@ -136,6 +138,7 @@ func TestNewDeviceFromConfig2(t *testing.T) {
 	assert.Equal(t, "2", device.ScalingFactor)
 	assert.Equal(t, 3*time.Second, device.WriteTimeout)
 	assert.Equal(t, "temperature", device.Output)
+	assert.Equal(t, 1, len(device.fns))
 }
 
 func TestNewDeviceFromConfig3(t *testing.T) {
@@ -211,6 +214,7 @@ func TestNewDeviceFromConfig4(t *testing.T) {
 	assert.Equal(t, "2", device.ScalingFactor)
 	assert.Equal(t, 30*time.Second, device.WriteTimeout) // takes the default value
 	assert.Equal(t, "", device.Output)
+	assert.Equal(t, 0, len(device.fns))
 }
 
 func TestNewDeviceFromConfig5(t *testing.T) {
@@ -255,6 +259,7 @@ func TestNewDeviceFromConfig5(t *testing.T) {
 	assert.Equal(t, "2", device.ScalingFactor)
 	assert.Equal(t, 30*time.Second, device.WriteTimeout) // takes the default value
 	assert.Equal(t, "", device.Output)
+	assert.Equal(t, 0, len(device.fns))
 }
 
 func TestNewDeviceFromConfig6(t *testing.T) {
@@ -401,6 +406,40 @@ func TestNewDeviceFromConfig9(t *testing.T) {
 	assert.Nil(t, device)
 }
 
+func TestNewDeviceFromConfig10(t *testing.T) {
+	// Unknown transformation function specified
+	proto := &config.DeviceProto{
+		Type: "type1",
+		Metadata: map[string]string{
+			"a": "b",
+		},
+		Data: map[string]interface{}{
+			"port": 5000,
+		},
+		Tags:         []string{"default/foo"},
+		Handler:      "testhandler",
+		WriteTimeout: 3 * time.Second,
+	}
+	instance := &config.DeviceInstance{
+		Type: "type2",
+		Info: "testdata",
+		Tags: []string{"vapor/io"},
+		Data: map[string]interface{}{
+			"address": "localhost",
+		},
+		SortIndex:          1,
+		Handler:            "testhandler2",
+		Apply:              []string{"unknown-fn"},
+		ScalingFactor:      "2",
+		WriteTimeout:       5 * time.Second,
+		DisableInheritance: false,
+	}
+
+	device, err := NewDeviceFromConfig(proto, instance)
+	assert.Error(t, err)
+	assert.Nil(t, device)
+}
+
 func TestDevice_setAlias_noConf(t *testing.T) {
 	device := Device{}
 

sdk/funcs/builtins.go

@@ -0,0 +1,40 @@
+// Synse SDK
+// Copyright (c) 2019 Vapor IO
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+package funcs
+
+import "github.com/vapor-ware/synse-sdk/sdk/utils"
+
+// GetBuiltins returns all of the built-in Funcs supplied by the SDK.
+func GetBuiltins() []*Func {
+	return []*Func{
+		&FtoC,
+	}
+}
+
+// FtoC is a Func which converts a value from degrees Fahrenheit to
+// degrees Celsius.
+var FtoC = Func{
+	Name: "FtoC",
+	Fn: func(value interface{}) (interface{}, error) {
+		f, err := utils.ConvertToFloat64(value)
+		if err != nil {
+			return nil, err
+		}
+		c := float64((f - 32.0) * 5.0 / 9.0)
+		return c, nil
+	},
+}

sdk/funcs/builtins_test.go

@@ -0,0 +1,79 @@
+// Synse SDK
+// Copyright (c) 2019 Vapor IO
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+package funcs
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestGetBuiltins(t *testing.T) {
+	fns := GetBuiltins()
+	assert.NotEmpty(t, fns)
+}
+
+func TestFtoC_Fn(t *testing.T) {
+	cases := []struct {
+		f float64
+		c float64
+	}{
+		{f: -459.67, c: -273.15},
+		{f: -50, c: -45.56},
+		{f: -40, c: -40.00},
+		{f: -30, c: -34.44},
+		{f: -20, c: -28.89},
+		{f: -10, c: -23.33},
+		{f: 0, c: -17.78},
+		{f: 10, c: -12.22},
+		{f: 20, c: -6.67},
+		{f: 30, c: -1.11},
+		{f: 32, c: 0},
+		{f: 40, c: 4.44},
+		{f: 50, c: 10.00},
+		{f: 60, c: 15.56},
+		{f: 70, c: 21.11},
+		{f: 80, c: 26.67},
+		{f: 90, c: 32.22},
+		{f: 100, c: 37.78},
+		{f: 110, c: 43.33},
+		{f: 120, c: 48.89},
+		{f: 130, c: 54.44},
+		{f: 140, c: 60.00},
+		{f: 150, c: 65.56},
+		{f: 160, c: 71.11},
+		{f: 170, c: 76.67},
+		{f: 180, c: 82.22},
+		{f: 190, c: 87.78},
+		{f: 200, c: 93.33},
+		{f: 212, c: 100},
+		{f: 300, c: 148.89},
+		{f: 400, c: 204.44},
+		{f: 500, c: 260.00},
+		{f: 600, c: 315.56},
+		{f: 700, c: 371.11},
+		{f: 800, c: 426.67},
+		{f: 900, c: 482.22},
+		{f: 1000, c: 537.78},
+	}
+
+	for _, c := range cases {
+		val, err := FtoC.Fn(c.f)
+		assert.NoError(t, err)
+		assert.InDelta(t, c.c, val, 0.01)
+	}
+}

sdk/funcs/functions.go

@@ -0,0 +1,67 @@
+// Synse SDK
+// Copyright (c) 2019 Vapor IO
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+package funcs
+
+import (
+	"fmt"
+
+	"github.com/vapor-ware/synse-sdk/sdk/errors"
+)
+
+var registeredFuncs map[string]*Func
+
+func init() {
+	registeredFuncs = make(map[string]*Func)
+	for _, f := range GetBuiltins() {
+		registeredFuncs[f.Name] = f
+	}
+}
+
+// Get gets a Func by its name. If a func with the specified name
+// is not found, nil is returned.
+func Get(name string) *Func {
+	return registeredFuncs[name]
+}
+
+// Register registers new funcs to the tracked funcs.
+func Register(funcs ...*Func) error {
+	multiErr := errors.NewMultiError("func registration")
+
+	for _, f := range funcs {
+		if _, exists := registeredFuncs[f.Name]; exists {
+			multiErr.Add(fmt.Errorf("conflict: Func with name '%s' already exists", f.Name))
+			continue
+		}
+		registeredFuncs[f.Name] = f
+	}
+	return multiErr.Err()
+}
+
+// Func is a function that can be applied to a device reading.
+type Func struct {
+	// Name is the name of the function. This is how it is identified
+	// and referenced.
+	Name string
+
+	// Fn is the function which will be called on the reading value.
+	Fn func(value interface{}) (interface{}, error)
+}
+
+// Call calls the function defined for the Func.
+func (fn *Func) Call(value interface{}) (interface{}, error) {
+	return fn.Fn(value)
+}