trails

package
v0.0.0-...-4dafefa Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2024 License: Apache-2.0 Imports: 27 Imported by: 0

README

Trails

Trails allow to users to change device configurations asynchronously using a step wise approach.

Trails API hence has two views with different priliges on it:

  1. Device accounts
  2. User accounts

Creating a trail.

Trails can be created as users or device on first boot.

To create a trail log in with a device acccount (see auth api documentation).

For this REAME we assume that you saved a device token in the DTOKEN environemtn variable and a user token in the UTOKEN env.

To create a trail we use the POST method on the trails api top level element using the DTOKEN:

http POST localhost:12365/trails/ Authorization:"Bearer $DTOKEN" \
	kernel:='{ "object": "prn:pantahub.com:objects:/57b6fa88c094f67942000001"}' \
	app:='{"object": "prn:pantahub.com:objects:/57b6fa88c094f67942000002"}'

HTTP/1.1 200 OK
Content-Length: 419
Content-Type: application/json; charset=utf-8
Date: Sat, 27 Aug 2016 22:04:31 GMT
X-Powered-By: go-json-rest

{
    "device": "prn:pantahub.com:auth:/device1", 
    "factory-state": {
        "app": {
            "object": "prn:pantahub.com:objects:/57b6fa88c094f67942000002"
        }, 
        "kernel": {
            "object": "prn:pantahub.com:objects:/57b6fa88c094f67942000001"
        }
    }, 
    "id": "57c20e6fc094f6729b000001", 
    "last-seen": "0001-01-01T00:00:00Z", 
    "last-step": "2016-08-28T00:04:31.386929333+02:00", 
    "last-walk": "2016-08-28T00:04:31.386929333+02:00", 
    "owner": "prn:pantahub.com:auth:/user1", 
    "tail": 0, 
    "tip": 0
}

Getting Steps (User Account)

Taking a peek at the steps as a user will by default return all steps that are not completed.

As a device by defaults only those steps get returned that are in state NEW.

All other states can be queried with query parameter q=|ALL

Lets see as a user:

http GET localhost:12365/trails/57c20e6fc094f6729b000001/steps Authorization:"Bearer $UTOKEN"
HTTP/1.1 200 OK
Content-Length: 424
Content-Type: application/json; charset=utf-8
Date: Sat, 27 Aug 2016 22:05:07 GMT
X-Powered-By: go-json-rest

[
    {
        "commit-msg": "Factory State (rev 0)", 
        "committer": "", 
        "device": "prn:pantahub.com:auth:/device1", 
        "id": "57c20e6fc094f6729b000001-0", 
        "owner": "prn:pantahub.com:auth:/user1", 
        "progress": {
            "log": "", 
            "progress": 0, 
            "status": "DONE", 
            "status-msg": ""
        }, 
        "rev": 0, 
        "state": {
            "app": {
                "object": "prn:pantahub.com:objects:/57b6fa88c094f67942000002"
            }, 
            "kernel": {
                "object": "prn:pantahub.com:objects:/57b6fa88c094f67942000001"
            }
        }, 
        "trail-id": "57c20e6fc094f6729b000001"
    }
]

Here we see the intiial factory step being added to the system.

Adding steps

Steps need to be added with appropriate incremental rev to ensure that no concurrently added steps can cause incontinuity in the sequence of steps.

Lets simulate an app update as our rev 1:

http POST  localhost:12365/trails/57c20e6fc094f6729b000001/steps Authorization:"Bearer $UTOKEN" \
	rev:=1 \
	commit-msg="Update App to new Release" \
	state:='{
	          "kernel": {"object": "prn:pantahub.com:objects:/57b6fa88c094f67942000001"},
	          "app":    {"object": "prn:pantahub.com:objects:/57b6fa88c094f67942000003"}
			}'

HTTP/1.1 200 OK
Content-Length: 411
Content-Type: application/json; charset=utf-8
Date: Sat, 27 Aug 2016 22:22:14 GMT
X-Powered-By: go-json-rest

{
    "commit-msg": "Update App to new Release", 
    "committer": "", 
    "device": "prn:pantahub.com:auth:/device1", 
    "id": "57c20e6fc094f6729b000001-1", 
    "owner": "prn:pantahub.com:auth:/user1", 
    "progress": {
        "log": "", 
        "progress": 0, 
        "status": "NEW", 
        "status-msg": ""
    }, 
    "rev": 5, 
    "state": {
        "app": {
            "object": "prn:pantahub.com:objects:/57b6fa88c094f67942000003"
        }, 
        "kernel": {
            "object": "prn:pantahub.com:objects:/57b6fa88c094f67942000001"
        }
    }, 
    "trail-id": "57c20e6fc094f6729b000001"
}

Accessing Individual Steps

To access individual steps relative to the trail you use "rev" in the path:

http GET localhost:12365/trails/57c20e6fc094f6729b000001/steps/1 Authorization:"Bearer $UTOKEN"
HTTP/1.1 200 OK
Content-Length: 422
Content-Type: application/json; charset=utf-8
Date: Sat, 27 Aug 2016 22:45:59 GMT
X-Powered-By: go-json-rest

{
    "commit-msg": "Update App to new Release", 
    "committer": "", 
    "device": "prn:pantahub.com:auth:/device1", 
    "id": "57c20e6fc094f6729b000001-0", 
    "owner": "prn:pantahub.com:auth:/user1", 
    "progress": {
        "log": "", 
        "progress": 0, 
        "status": "NEW", 
        "status-msg": ""
    }, 
    "rev": 0, 
    "state": {
        "app": {
            "object": "prn:pantahub.com:objects:/57b6fa88c094f67942000003"
        }, 
        "kernel": {
            "object": "prn:pantahub.com:objects:/57b6fa88c094f67942000001"
        }
    }, 
    "trail-id": "57c20e6fc094f6729b000001"
}

Device Progress Postings

To post progress, devices will PUT to the pseudo "progress" node under each step. In this case our device wants to confirms that it has seen the newly requested step and that it is acting on it.

http PUT localhost:12365/trails/57c20e6fc094f6729b000001/steps/1/progress Authorization:"Bearer $DTOKEN" \
	log = "" \
	progress = 0 \
	status = "QUEUE" \
	status-msg  = ""

HTTP/1.1 200 OK
Content-Length: 57
Content-Type: application/json; charset=utf-8
Date: Sat, 27 Aug 2016 22:50:29 GMT
X-Powered-By: go-json-rest

{
    "log": "", 
    "progress": 0, 
    "status": "QUEUE", 
    "status-msg": ""
}

Steps Meta info

Steps have a general purpose 'meta' field holding a map. This is useful for apps to store info and state about steps that they need for their internal processing.

As owner you can PUT meta on any step:

http PUT localhost:12365/trails/5c2cc99990cd51000906c218/steps/10/meta Authorization:" Bearer $TOK" app-meta1=value1 app-meta2:='{"object": "also possible"}'
HTTP/1.1 200 OK
Content-Length: 61
Content-Type: application/json; charset=utf-8
Date: Wed, 17 Apr 2019 09:09:51 GMT
X-Powered-By: go-json-rest
X-Runtime: 0.003029

{
    "app-meta1": "value1",
    "app-meta2": {
        "object": "also possible"
    }
}

As owner you can GET meta on any step:

http localhost:12365/trails/5c2cc99990cd51000906c218/steps/10/meta Authorization:" Bearer $TOK"
HTTP/1.1 200 OK
Content-Length: 61
Content-Type: application/json; charset=utf-8
Date: Wed, 17 Apr 2019 09:10:25 GMT
X-Powered-By: go-json-rest
X-Runtime: 0.002949

{
    "app-meta1": "value1",
    "app-meta2": {
        "object": "also possible"
    }
}

Documentation

Overview

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

Package trails offer a two party master/slave relationship enabling the master to asynchronously deploy configuration changes to its slave in a stepwise manner.

## Trail API Overview

A trail represents a RESTful device state management endpoint optimized for high latency, asynchronous configuration management as found in the problem space of management of edge compute device world. 

XXX: add proper API high level doc here (deleted outdated content)
     handler func inline doc should stay up to date though...

Detailed documentation for the various operations on the API endpoints can be at the handler functions below.

TODOs:

  • properly document trails API once finalized
  • abstract access control in a better managable manner and less mistake/oversight likely manner (probably descriptive/configuration style)
  • ensure step and progres time can be effectively read from trail meta info probably async/delayed update to ensure scalability (e.g. once every 5 minute if there has been any step touch we update last progress etc
  • ensure that devices can query steps that need enqueing efficiently
  • enusre that in-sync time and status is timely updated based on step and progress
  • find smart way to figure when device is in sync based on reported state
  • consider enforcing sequential processing of steps to have a clean tail?

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetStateObjects 

func GetStateObjects(
	pctx context.Context,
	owner string,
	state map[string]interface{},
	autoLink bool,
	a *App,
) (
	[]string,
	error,
)

GetStateObjects : Get State Objects

func IsObjectGarbage 

func IsObjectGarbage(pctx context.Context, ObjectID string, a *App) (
	bool,
	error,
)

IsObjectGarbage : to check if an object is garbage or not

func ProcessObjectsInState 

func ProcessObjectsInState(
	pctx context.Context,
	owner string,
	state map[string]interface{},
	autoLink bool,
	a *App,
) (
	objects []string,
	err error,
)

ProcessObjectsInState :

1.Get Object List from the State field 2.UnMark All Objects As Garbages if they are marked as garbage

func RestoreObjects 

func RestoreObjects(
	pctx context.Context,
	objectList []string,
	a *App,
) error

RestoreObjects : Takes the list of objects and unmarks them garbage.

func UnMarkObjectAsGarbage 

func UnMarkObjectAsGarbage(pctx context.Context, ObjectID string, a *App) error

UnMarkObjectAsGarbage : to unmark object as garbage

Types

type App 

type App struct {
	API *rest.Api
	// contains filtered or unexported fields
}

App trails rest application

func New 

func New(jwtMiddleware *jwt.JWTMiddleware, mongoClient *mongo.Client) *App

New create a new trails rest application 

finish getsteps
post walk
get walks
search attributes for advanced steps/walk searching inside trail

func (*App) IsDevicePublic 

func (a *App) IsDevicePublic(ctx context.Context, ID primitive.ObjectID) (bool, error)

IsDevicePublic checks if a device is public or not

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.