Northbound Interface

Description

This merge request provides a new gRPC based interface and replaces the deprecated HTTP API. It brings candy and love to everyone. And the old API was dead from the beginning anyway.

This MR is for implementation aspects only. Discussion of the actual API definition with protobuf should happen here

Related Issue

#83 (closed)

Motivation and Context

gRPB based NBI was planned from the beginning.

How Has This Been Tested?

Not yet yolo

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

cli/grpc.go

@@ -2,6 +2,7 @@ package cli
 
 import (
 	"context"
+	"errors"
 	"time"
 
 	ppb "code.fbi.h-da.de/cocsn/api/go/gosdn/pnd"
@@ -18,6 +19,7 @@ import (
 // TODO: Delete once proper certs are set up
 var grpcWithInsecure = grpc.WithInsecure()
 
+// Init initialises the CLI client.
 func Init(addr string) error {
 	ctx := context.Background()
 	resp, err := getAllCore(ctx, addr)
@@ -37,6 +39,7 @@ func Init(addr string) error {
 	return nil
 }
 
+// GetIds requests all UUID information from the controller
 func GetIds(addr string) ([]*ppb.PrincipalNetworkDomain, error) {
 	ctx := context.Background()
 	resp, err := getAllCore(ctx, addr)
@@ -58,6 +61,8 @@ func getAllCore(ctx context.Context, addr string) (*pb.GetResponse, error) {
 	return coreClient.Get(ctx, req)
 }
 
+// AddPnd takes a name, description and SBI UUID to create a new
+// PrincipalNetworkDomain on the controller
 func AddPnd(addr, name, description, sbi string) error {
 	coreClient, err := nbi.CoreClient(addr, grpcWithInsecure)
 	if err != nil {
@@ -83,20 +88,26 @@ func AddPnd(addr, name, description, sbi string) error {
 	return nil
 }
 
+// GetPnd requests one or several PrincipalNetworkDomains from the
+// controller. To request all PrincipalNetworkDomains without providing
+// names or UUIDs use GetIds()
 func GetPnd(addr string, args ...string) (*pb.GetResponse, error) {
 	coreClient, err := nbi.CoreClient(addr, grpcWithInsecure)
 	if err != nil {
 		return nil, err
 	}
+	if len(args) <= 0 {
+		return nil, errors.New("not enough arguments")
+	}
 	ctx := context.Background()
 	req := &pb.GetRequest{
 		Timestamp: time.Now().UnixNano(),
-		All:       false,
 		Pid:       args,
 	}
 	return coreClient.Get(ctx, req)
 }
 
+// GetChanges requests all pending and unconfirmed changes from the controller
 func GetChanges(addr, pnd string) (*ppb.GetResponse, error) {
 	ctx := context.Background()
 	client, err := nbi.PndClient(addr, grpcWithInsecure)
@@ -115,6 +126,8 @@ func GetChanges(addr, pnd string) (*ppb.GetResponse, error) {
 	return client.Get(ctx, req)
 }
 
+// Commit sends a commit request for one or multiple changes to the
+// controller.
 func Commit(addr, pnd string, cuids ...string) (*ppb.SetResponse, error) {
 	changes := make([]*ppb.SetChange, len(cuids))
 	for i, arg := range cuids {
@@ -126,6 +139,8 @@ func Commit(addr, pnd string, cuids ...string) (*ppb.SetResponse, error) {
 	return commitConfirm(addr, pnd, changes)
 }
 
+// Confirm sends a confirm request for one or multiple changes to the
+// controller
 func Confirm(addr, pnd string, cuids ...string) (*ppb.SetResponse, error) {
 	changes := make([]*ppb.SetChange, len(cuids))
 	for i, arg := range cuids {
@@ -151,6 +166,8 @@ func commitConfirm(addr, pnd string, changes []*ppb.SetChange) (*ppb.SetResponse
 	return client.Set(ctx, req)
 }
 
+// AddDevice adds a new device to the controller. The device name is optional.
+// If no name is provided a name will be generated upon device creation.
 func AddDevice(addr, username, password, sbi, pnd, deviceAddress, deviceName string) error {
 	pndClient, err := nbi.PndClient(addr, grpcWithInsecure)
 	if err != nil {
@@ -184,6 +201,9 @@ func AddDevice(addr, username, password, sbi, pnd, deviceAddress, deviceName str
 	return nil
 }
 
+// GetDevice requests one or multiple devices belongin to a given
+// PrincipalNetworkDomain from the controller. If no device identifier
+// is provided, all devices are requested.
 func GetDevice(addr, pid, path string, did ...string) (*ppb.GetResponse, error) {
 	pndClient, err := nbi.PndClient(addr, grpcWithInsecure)
 	if err != nil {
@@ -209,6 +229,8 @@ func GetDevice(addr, pid, path string, did ...string) (*ppb.GetResponse, error)
 	return pndClient.Get(ctx, req)
 }
 
+// Update creates a ChangeRequest to update the given path with the given value
+// at the given OND on the controller.
 func Update(addr, did, pid, path, value string) (*ppb.SetResponse, error) {
 	req := &ppb.ChangeRequest{
 		Id:    did,
@@ -219,6 +241,8 @@ func Update(addr, did, pid, path, value string) (*ppb.SetResponse, error) {
 	return sendChangeRequest(addr, pid, req)
 }
 
+// Replace creates a ChangeRequest to replace the given path with the given value
+// at the given OND on the controller.
 func Replace(addr, did, pid, path, value string) (*ppb.SetResponse, error) {
 	req := &ppb.ChangeRequest{
 		Id:    did,
@@ -229,6 +253,8 @@ func Replace(addr, did, pid, path, value string) (*ppb.SetResponse, error) {
 	return sendChangeRequest(addr, pid, req)
 }
 
+// Delete creates a ChangeRequest to delete the given path node
+// at the given OND on the controller.
 func Delete(addr, did, pid, path string) (*ppb.SetResponse, error) {
 	req := &ppb.ChangeRequest{
 		Id:    did,