bigiot

package module
v0.10.1 Latest Latest
Warning

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

 Go to latest Published: Feb 9, 2018 License: Apache-2.0 Imports: 12 Imported by: 0

README

bigiot Build Status Go Report Card GoDoc

Go implementation of the BIG IoT library/SDK. BIG IoT is an attempt to create a marketplace to connect IoT-Platforms all over the web. Please see: https://market.big-iot.org/.

Implemented Features

  • Register an offering in the marketplace
  • Unregister an offering from the marketplace

Planned Features

  • Validating tokens presented by offering subscribers
  • Discovering an offering in the marketplace
  • Subscribing to an offering

Documentation

Overview

Package bigiot is an attempt at porting the BIGIot client library from Java to Go, adapting the library where appropriate to better fit Go idioms and practices. This is very much a work in progress, so currently is a long way from supporting the same range of functionality as the Java library.

Implemented functionality:

  • register an offering in the marketplace
  • delete or unregister an offering from the marketplace
  • reactivating offerings from the marketplace
  • validating tokens presented by offering subscribers

Planned functionality:

  • discovering an offering in the marketplace
  • subscribing to an offering

Here's an example of how you can create a local Provider client, and authenticate with the marketplace. This assumes that you have already created an account on the marketkplace and you have extracted from the marketplace your providerID and secret. 

provider, err := bigiot.NewProvider(providerID, providerSecret)
if err != nil {
	panic(err) // handle error properly
}

err = provider.Authenticate()
if err != nil {
	panic(err) // handle error properly
}

Then in order to register an offering a client would first create a description of the offering. 

addOfferingInput := &bigiot.OfferingDescription{
	LocalID:  "ParkingOffering",
	Name:     "Demo Parking Offering",
	Category: "urn:big-iot:ParkingSpaces"
	Inputs: []bigiot.DataField{
		{
			Name:   "longitude",
			RdfURI: "schema:longitude",
		},
		{
			Name:   "latitude",
			RdfURI: "schema:latitude",
		},
	},
	Outputs: []bigiot.DataField{
		{
			Name:   "geoCoordinates",
			RdfURI: "schema:geoCoordinates",
		}
	},
	Endpoints: []bigiot.Endpoint{
		{
			URI:                 "https://example.com/parking",
			EndpointType:        bigiot.HTTPGet,
			AccessInterfaceType: bigiot.External,
		}
	},
	License: bigiot.OpenDataLicense,
	SpatialExtent: &bigiot.SpatialExtent{
		City: "Berlin",
		BoundingBox: &bigiot.BoundingBox{
			Location1: bigiot.Location{
				Lng: 2.33,
				Lat: 54.5,
			},
			Location2: bigiot.Location{
				Lng: 2.38,
				Lat: 54.53,
			},
		},
	},
	Price: bigiot.Price{
		Money: bigiot.Money{
			Amount:   0.01,
			Currency: bigiot.EUR,
		},
		PricingModel: bigiot.PerAccess,
	},
	Activation: &bigiot.Activation{
		Status:   true,
		Duration: 15 * time.Minute,
	},
}

Then we can use the above description to register our offering on the marketplace: 

offering, err := provider.RegisterOffering(context.Background(), addOfferingInput)
if err != nil {
	panic(err) // handle error properly
}

To delete an offering we need to invoke the DeleteOffering method: 

deleteOfferingInput := &bigiot.DeleteOffering{
	ID: offering.ID,
}

err = provider.DeleteOffering(context.Background(), deleteOfferingInput)
if err != nil {
	panic(err) // handle error properly
}

To re-activate an offering (a provider will want to do this as they are expected to continously re-activate to show an offering is still alive) you can use the following method on the Provider: 

activateOfferingInput := &bigiot.ActivateOffering{
	ID: offering.ID,
	Duration: 15 * time.Minute,
}

err := provider.ActivateOffering(context.Background(), activateOfferingInput)
if err != nil {
	panic(err) // handle error properly
}

To validate incoming tokens presented by a consumer, we expose a ValidateToken method. This takes as input a token string encoded via the compact JWT serialization form, and returns either the ID of the offering being requested, or an error should the incoming token be invalid. 

offeringID, err := provider.ValidateToken(tokenStr)
if err != nil {
	panic(err) // handle error properly
}

Index

Constants

View Source 
const (
	// DefaultMarketplaceURL is the URI to the default BIG IoT marketplace
	DefaultMarketplaceURL = "https://market.big-iot.org"

	// DefaultTimeout is the default timeout in seconds to set on on requests to
	// the marketplace
	DefaultTimeout = 10

	// DefaultActivationDuration is the default duration a resource will be
	// activated for. Currently this is set for 10 minutes.
	DefaultActivationDuration = 10 * time.Minute
)
View Source 
const (
	// Version string for the library. By default this is added to the user-agent
	// string sent by the client, but users of the library can override the user
	// agent string when instantiating the client.
	Version = "v0.0.2"
)

Variables

This section is empty.

Functions

func FromEpochMs added in v0.0.3 

func FromEpochMs(v int64) time.Time

FromEpochMs takes as input an int value (as returned from ToEpochMs) and then returns this as a time.Time in UTC.

func ToEpochMs added in v0.0.3 

func ToEpochMs(t time.Time) string

ToEpochMs takes a time.Time and returns this time as a epoch milliseconds formatted as a string.

Types

type AccessInterfaceType 

type AccessInterfaceType string

AccessInterfaceType is a type used to represent the type of an access interface. This can be one of BIGIOT_LIB or EXTERNAL. 

const (
	// BIGIoTLib is the const value representing an interface type of BIGIOT_LIB
	BIGIoTLib AccessInterfaceType = "BIGIOT_LIB"

	// External is the const value representing an interface type of EXTERNAL
	External AccessInterfaceType = "EXTERNAL"
)

func (AccessInterfaceType) String 

func (a AccessInterfaceType) String() string

String is an implementation of Stringer for our AccessInterfaceType type.

type ActivateOffering added in v0.0.3 

type ActivateOffering struct {
	ID             string
	ExpirationTime time.Time
	Duration       time.Duration
}

ActivateOffering is an input type used to reactivate an existing offering.

type Activation 

type Activation struct {
	Status         bool          `json:"status"`
	ExpirationTime time.Time     `json:"-"`
	Duration       time.Duration `json:"-"`
}

Activation represents an activation of a resource. This comprises a boolean flag, and an expiration time. If the flag is set to true and the expiration time is in the future, then the offering is active; otherwise it is inactive.

func (*Activation) UnmarshalJSON 

func (a *Activation) UnmarshalJSON(b []byte) error

UnmarshalJSON is an implementation of the json Unmarshaler interface. We add a custom implementation to handle converting timestamps from epoch milliseconds into golang time.Time objects.

type BoundingBox added in v0.10.0 

type BoundingBox struct {
	Location1 Location
	Location2 Location
}

BoundingBox is used to represent a geographical bounding box within which an offering provides data. It contains two locations representing opposite corners of a geospatial box.

type Clock added in v0.0.3 

type Clock interface {
	Now() time.Time
}

Clock is an interface used to make it possible to test time related code more easily.

type Currency 

type Currency string

Currency is a type alias for string used to represent currencies 

const (
	// EUR is a currency instance representing the Euro currency
	EUR Currency = "EUR"
)

func (Currency) String 

func (c Currency) String() string

String is an implementation of Stringer for our Currency type.

type DataField 

type DataField struct {
	Name   string
	RdfURI string
}

DataField captures information about an offering's inputs or outputs. Used when creating an offering.

type DeleteOffering added in v0.0.2 

type DeleteOffering struct {
	ID string
}

DeleteOffering is an input type used to delete or unregister an offering.

type Endpoint 

type Endpoint struct {
	EndpointType        EndpointType
	URI                 string
	AccessInterfaceType AccessInterfaceType
}

Endpoint captures information about the endpoint of an offering.

type EndpointType 

type EndpointType string

EndpointType represents the type of an Endpoint accessible via the BIGIoT Marketplace. 

const (
	// HTTPGet is a const value representing an endpoint type accessible via HTTP
	// GET
	HTTPGet EndpointType = "HTTP_GET"

	// HTTPPost is a const value representing an endpoint type accessible via HTTP
	// POST
	HTTPPost EndpointType = "HTTP_POST"

	// WebSocket is a const value representing an endpoint type accessible via
	// WebSockets
	WebSocket EndpointType = "WEBSOCKET"
)

func (EndpointType) String 

func (e EndpointType) String() string

String is an implementation of the Stringer interface for EndpointType instances.

type Error 

type Error struct {
	Message string `json:"message"`
}

Error is used for unmarshalling error messages from the marketplace

type ErrorResponse added in v0.10.0 

type ErrorResponse struct {
	Errors []Error `json:"errors"`
}

ErrorResponse is used to unmarshal the response from the marketplace in the event of an error.

type License 

type License string

License is a type alias for string used to represent the license being applied to an offering. 

const (
	// CreativeCommons is a License instance representing the Creative Commons License
	CreativeCommons License = "CREATIVE_COMMONS"

	// OpenDataLicense is a License instance representing an open data license
	OpenDataLicense License = "OPEN_DATA_LICENSE"

	// NonCommercialDataLicense is a License instance representing a non-commercial
	// data license
	NonCommercialDataLicense License = "NON_COMMERCIAL_DATA_LICENSE"
)

func (License) String 

func (l License) String() string

String is an implementation of Stringer for our License type.

type Location added in v0.10.0 

type Location struct {
	Lng float64
	Lat float64
}

Location is used to represent a geographic location expressed as a decimal lng/lat pair.

type Money 

type Money struct {
	Amount   float64 // TODO: look at more precise numeric type here
	Currency Currency
}

Money is used to capture price information for the offering. Note we aren't using precise numeric types here so this is not suitable for precision calculations.

type Offering 

type Offering struct {
	ID         string     `json:"id"`
	Name       string     `json:"name"`
	Activation Activation `json:"activation"`
}

Offering is an output type used when returning information about an offering. This can happen either after creating an offering or if we get information on an offering from the marketplace.

type OfferingDescription added in v0.0.3 

type OfferingDescription struct {
	LocalID       string
	Name          string
	Category      string
	Inputs        []DataField
	Outputs       []DataField
	Endpoints     []Endpoint
	SpatialExtent *SpatialExtent
	License       License
	Price         Price
	Activation    *Activation
	// contains filtered or unexported fields
}

OfferingDescription is the type used to register an offering with the marketplace. It contains information about the offerings inputs and outputs, its endpoints, license and price. In addition this is how offerings specify that they are active.

type Option 

type Option func(*base) error

Option is a type alias for our functional configuration type. Callers can use this type when creating a new Provider or Consumer instance to configure different properties of the client.

func WithClock added in v0.0.3 

func WithClock(clock Clock) Option

WithClock allows a caller to specify a custom Clock implementaton. Typically this will only be used within tests to mock out calls to time.Now().

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient allows a caller to pass in a custom http Client allowing them to customize the behaviour of our HTTP interactions.

Example: 

provider, _ := bigiot.NewProvider(
	providerID,
	providerSecret,
	bigiot.WithHTTPClient(myClient),
)

func WithMarketplace 

func WithMarketplace(marketplaceURL string) Option

WithMarketplace is a functional configuration option allowing us to optionally set a custom marketplace URI when constructing a BIGIoT instance.

Example: 

provider, _ := bigiot.NewProvider(
	providerID,
	providerSecret,
	bigiot.WithMarketplace("https://market-dev.bigiot.org"),
)

func WithUserAgent 

func WithUserAgent(userAgent string) Option

WithUserAgent allows the caller to specify the user agent that should be sent to the marketplace.

Example: 

provider, _ := bigiot.NewProvider(
	providerID,
	providerSecret,
	bigiot.WithUserAgent("BIGIoT App"),
)

type Price 

type Price struct {
	PricingModel PricingModel
	Money        Money
}

Price captures information about the pricing of an offering.

type PricingModel 

type PricingModel string

PricingModel is a type alias for string used to represent pricing models to be applied to BIGIoT offerings. 

const (
	// Free is a const used to represent a free pricing model.
	Free PricingModel = "FREE"

	// PerMonth is a const used to represent a per month based pricing model.
	PerMonth PricingModel = "PER_MONTH"

	// PerAccess is a const used to represent a per access based pricing model.
	PerAccess PricingModel = "PER_ACCESS"

	// PerByte is a const used to represent a per byte based pricing model.
	PerByte PricingModel = "PER_BYTE"
)

func (PricingModel) String 

func (p PricingModel) String() string

String is an implementation of Stringer for our PricingModel type.

type Provider 

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

Provider is our type for interacting with the marketplace from the perspective of a data provider. We embed the base Config type which stores our runtime configuration (auth credentials, base url etc.).

func NewProvider 

func NewProvider(id, secret string, options ...Option) (*Provider, error)

NewProvider instantiates and returns a configured Provider instance. The required parameters to the function are the provider ID and secret. If you want to connect to a marketplace other than the official marketplace (i.e. connecting to a local instance for testing), you can configure this by means of the variadic third parameter, which can be used for additional configuration.

func (*Provider) ActivateOffering added in v0.0.3 

func (p *Provider) ActivateOffering(ctx context.Context, activation *ActivateOffering) (*Offering, error)

func (Provider) Authenticate added in v0.0.2 

func (b Provider) Authenticate() (err error)

Authenticate makes a call to the /accessToken endpoint on the marketplace to obtain an access token which the client will then be able to use when making requests to the graphql endpoint. We make a GET request passing over our client id and secret, and get back a token if our credentials are valid.

func (*Provider) DeleteOffering added in v0.0.2 

func (p *Provider) DeleteOffering(ctx context.Context, offering *DeleteOffering) error

DeleteOffering attempts to delete or unregister an offering on the marketplace. It is called with a context, and a DeleteOffering instance. This instance is serialized and the query executed against the GraphQL server. The function returns an error if anything goes wrong.

func (*Provider) RegisterOffering 

func (p *Provider) RegisterOffering(ctx context.Context, offering *OfferingDescription) (*Offering, error)

RegisterOffering allows calles to register an offering on the marketplace. When registering the caller will supply an activation lifetime for the Offering as part of the input AddOffering instance. The function returns a populated Offering instance or nil and an error.

func (*Provider) ValidateToken added in v0.0.3 

func (p *Provider) ValidateToken(tokenStr string) (string, error)

ValidateToken takes as input a string which should be JWT token generated by the marketplace and given to the client before it is allowed to access data from an offering. It takes as input the encoded token string, extracts its component parts and verifies the signature using the secret of the provider. It returns the ID of the offering the token is for, or an empty string and an error if unable to validate the token.

type SpatialExtent added in v0.10.0 

type SpatialExtent struct {
	City        string
	BoundingBox *BoundingBox
}

SpatialExtent is how the BIG IoT marketplace defines geographical constraints when registering an offering.

Source Files

View all Source files

Directories

Path Synopsis

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.