README
¶
directory - Things Directory Module
This directory module provides the means to store and retrieve TD (Thing Description) documents.
The primary objective is to let consumers discover what Things are available and obtain the information on how to access them.
This module follows the WoT discovery specification https://w3c.github.io/wot-discovery/#exploration-directory and a subset of the TM described at https://w3c.github.io/wot-discovery/#directory-api-spec.
This module is not a full blow stand-alone application but simply offers the directory capabilities to applications or services that want to include a directory. It must be linked to a server transport module to receive the requests.
Status
This module is in alpha. It is functional but breaking changes might still happen.
There are two notable issues for which there is no standardization: 1: For security reasons, a device TD should only be updatable by the owning agent of a device. How to determine who this agent is? 2: How to prevent thingID collisions? There is no mechanism to guarantee uniquenes between devices. One option is to use UUIDs. Another is to use namespaces in the ID.
Current solution: HiveOT uses the convention that thingIDs contain the agentID prefix separated by a colon. The format for thingID is: "{agentID}:{deviceID}", where {deviceID} is the ID of the device unique within the scope of the agent publishing the TD.
If the TD is to be published in an internet based directory, the agentID must be globally unique and the forms must be updated to externally reachable addresses. In HiveOT this is not a concern of devices. Instead a gateway module must handle external exposure and security.
Summary
The WoT discovery specification defines the directory service API for storing and retrieving TD information. This module exports a TM that matches the description provided in the specification.
The directory package contains these modules: the directory service, its http API server, a messaging client, and an HTTP client. These can be used as any other module, and operate client side or server side. Typically, the directory server is linked to a transport server to receive requests and publish notifications. Similarly the directory client module can be used by applications to query the TDs of the available Things.
The directory should be updated by IoT devices or their agent. In HiveOT, the convention is that Thing agents update the directory with one or more TD's of the Things it manages.
Alternatively, an administrator can update the directory manually with a JSON document using the provided CLI. The CLI is a simple example commandline interface that uses the directory client to read and write the directory.
To write their TD to the directory storage, IoT devices need to discover the location of the directory and invoke the createThing or updateThing action, providing the TD JSON document as the payload.
Backends
This module internally uses a Key-Value bucket store for persisting TD documents. When read, TDs are cached in memory for fast access by consumers.
TBD: maybe use a filesystem based backend where TDs are stored? It would make importing TDs out-of-band easier.
Usage
Creating a Directory
Examples of creating an instance of the directory.
-
Use the HiveKit module factory. This factory provides the application environment and automatically creates instances of the neccesary modules.
-
Manually without the HTTP API: [server]->[directory]
-
Create an instance of the module using directorypkg.NewDirectoryService() and provide it with the storage location of the embedded database.
-
Call Start on the service. This will initialize and create the store.
-
Link it as a sink of a server module chain. Any directory requests will be handled by the module. Modules can be chained and it doesn't matter where in the chain the directory module reside.
-
Before shutdown call Stop() to ensure the datastore is properly closed.
-
-
Manually with the HTTP API: [server]->[http-api]->[directory]
-
Create an instance of the directory http API server using directorypkg.NewDirectoryHttpHandler()
-
Set the HTTP API module as the sink of the server module chain.
-
Create an instance of the directory service using directorypkg.NewDirectoryService() and provide it with the storage location of the embedded database, and the http api. The http api is used to set the base URL, security and forms of the directory TD.
-
Set the service module as the sink of the http api module. Request received via the directory http API is now handled by the server.
-
Call Start on both the http api and the service(). This will initialize or create the store and register the HTTP endpoints with the HTTP server module.
-
Before shutdown call Stop() to ensure the datastore is properly closed.
-
Updating the directory
There are several use-cases for updating the directory with TD from Things. At this moment it isn't clear if there is a preferred way. HiveOT is leaning towards option 3 and 4 as HiveOT devices do not run servers.
- Stand-alone devices can use discovery to publish their TD or TDD in case there are multiple. Someone need to get the TD and add it to the directory. Who?
- A stand-alone device discovers a directory and write its TD to it.
- Devices with reverse connection to a hub or gateway can write the TDs they manage to the its directory.
- An administrator can manually upload TDs to the directory import location. This is not yet supported (but seems like a good idea)
Documentation
¶
Index ¶
Constants ¶
const ( PropThings = "things" EventThingUpdated = "thingUpdated" EventThingDeleted = "thingDeleted" ActionCreateThing = "createThing" ActionDeleteThing = "deleteThing" ActionRetrieveTDD = "retrieveTDD" ActionRetrieveThing = "retrieveThing" ActionRetrieveAllThings = "retrieveAllThings" ActionUpdateThing = "updateThing" )
Property, Event and Action affordance names as used in the TM and messaging API
const DefaultDirectoryThingID = "thingDirectory"
The thingID this directory identifies as for messaging. Must match the TD ID.
const DefaultLimit = 300
Default limit in retrieving things
const DirectoryHttpModuleType = "directory-http"
DirectoryHttpModuleType identifies the http API module for the directory service Place this module before any middleware so that requests are logged and authorized.
const DirectoryModuleType = "directory"
DirectoryModuleType identifies the directory module implementation
const WellKnownWoTPath = "/.well-known/wot"
The http path that provides the TD of the service in case of the directory this provide the directory TD path
Variables ¶
var DirectoryTMJson []byte
Embed the directory TM
Functions ¶
This section is empty.
Types ¶
type AgentInfo ¶
type AgentInfo struct {
// The agent whose info this contains
AgentID string
// ThingIDs of the devices it has registered
ThingIDs []string
}
Information of an agent that has registered Things
type DeleteTDHook ¶
The handler of deleting TD requests This returns an error if deleting the TD is not allowed.
type IDirectoryHttpServer ¶
type IDirectoryHttpServer interface {
transport.ITransportServer
}
Directory http server as per https://w3c.github.io/wot-discovery/#exploration-directory-api This acts as a simple http transport server and should be placed ahead of the DirectoryService module chain.
type IDirectoryService ¶
type IDirectoryService interface {
modules.IHiveModule
// CreateThing creates or updates the TD in the directory.
// If the thing doesn't exist in the directory it is added.
//
// Only agents can create a TD. If the administrator acts as the agent then it
// is also responsible for updating it if that is ever needed.
CreateThing(agentID string, tdJson string) error
// DeleteThing removes a Thing TD document from the directory
DeleteThing(agentID string, thingID string) error
// Return an instance of a TD from the store.
// These TD's are cached so successive requests do not parse the json each time.
GetTD(thingID string) *td.TD
// Retrieve the directory TD
RetrieveTDD() string
// RetrieveThing returns a JSON encoded TD document
RetrieveThing(thingID string) (tdJSON string, err error)
// RetrieveAllThings returns a batch of TD documents
// This returns a list of JSON encoded digital twin TD documents
RetrieveAllThings(offset int, limit int) (tdList []string, err error)
// Install a hook that is called when a Thing is writing its TD to the directory.
// This hook returns the TD that is actually written.
// Intended for updating forms and for supporting the digital twin concept.
//
// thingID is the ID whose thing is written.
// tdi is the TD instance, or nil if the thing TD is deleted.
SetTDHooks(writeTDHandler WriteTDHook, deleteTDHandler DeleteTDHook)
// UpdateThing replaces the TD in the store.
// If the thing doesn't exist in the store it is added.
//
// Only agents can update a TD.
UpdateThing(agentID string, tdJson string) error
}
IDirectoryService defines the interface to the directory service module
type RetrieveAllThingsArgs ¶
type RetrieveAllThingsArgs struct {
// Limit with Limit
//
// Maximum number of documents to return
Limit int `json:"limit,omitempty"`
// Offset with Offset
//
// Start index in the list of TD documents
Offset int `json:"offset,omitempty"`
}
RetrieveAllThingsArgs defines the arguments of the retrieveAllThings action Read all TDs - Read a batch of TD documents
type RetrieveAllThingsOutput ¶
type RetrieveAllThingsOutput []string
RetrieveAllThingsOutput output of the retrieveAllThings action
Source Files
Directories