Add basic structures of the boruta

Change-Id: I56ba1e2898e7b90029cbdefdd2b29f4d73b40372
Signed-off-by: Aleksander Mistewicz <a.mistewicz@samsung.com>
Reviewed-on: https://mcdsrvbld02.digital.local/review/48999
Reviewed-by: Pawel Wieczorek <p.wieczorek2@samsung.com>
Reviewed-by: Lukasz Wojciechowski <l.wojciechow@partner.samsung.com>
Reviewed-by: Maciej Wereski <m.wereski@partner.samsung.com>
Tested-by: Maciej Wereski <m.wereski@partner.samsung.com>

1 files changed, 168 insertions, 0 deletions

diff --git a/boruta.go b/boruta.go
new file mode 100644
index 0000000..e396d49
--- /dev/null
+++ b/boruta.go
@@ -0,0 +1,168 @@
+// Package boruta contains definitions of all interfaces and structs used
+// between the main modules of the Boruta system.
+// Server - service managing Users, Workers, Requests and Jobs.
+// User - a system or a person creating the Requests.
+// Worker - MuxPi with a target device, which executes the Jobs from the Server.
+package boruta
+
+import (
+	"time"
+)
+
+// ReqState denotes state of the Request.
+type ReqState byte
+
+const (
+	// WAIT - Request is in the Queue waiting for processing.
+	WAIT ReqState = iota
+	// INPROGRESS - Request has Job with Worker assigned.
+	INPROGRESS
+	// CANCEL - Request has been cancelled by the User.
+	CANCEL
+	// TIMEOUT - Deadline is past due.
+	TIMEOUT
+	// INVALID - Request can no longer be satisfied.
+	INVALID
+	// DONE - Request has finished execution.
+	DONE
+	// FAILED - Worker has failed or has been put into MAINTENANCE state by the Admin.
+	FAILED
+)
+
+// WorkerState denotes state of the Worker.
+type WorkerState byte
+
+const (
+	// MAINTENANCE - Worker will not be assigned any Jobs.
+	MAINTENANCE WorkerState = iota
+	// IDLE - Worker is waiting for the Job.
+	IDLE
+	// RUN - Job is currently being executed on the Worker.
+	RUN
+	// FAIL - An error occured, reported by the Worker itself or the Server.
+	FAIL
+)
+
+// Capabilities describe the features provided by the Worker and required by the Request.
+// They are also known as caps.
+type Capabilities map[string]string
+
+// ReqID refers to the Request created by the User.
+type ReqID uint
+
+// Priority is the importance of the Request. Lower - more important.
+type Priority uint
+
+// UserInfo is a definition of the User or the Admin.
+type UserInfo struct{}
+
+// ReqInfo describes the Request.
+type ReqInfo struct {
+	ID       ReqID
+	Priority Priority
+	// Owner is the User who created the Request.
+	Owner UserInfo
+	// Deadline is a time after which a Request's State will be set to TIMEOUT
+	// if it had not been fulfilled.
+	Deadline time.Time
+	// ValidAfter is a time before which a Request will not be executed.
+	ValidAfter time.Time
+	State      ReqState
+	Job        *JobInfo
+	// Caps are the Worker capabilities required by the Request.
+	Caps Capabilities
+}
+
+// WorkerUUID refers the Worker on which a Job will execute.
+type WorkerUUID string
+
+// JobInfo describes the Job.
+type JobInfo struct {
+	WorkerUUID WorkerUUID
+	// Timeout after which this Job will be terminated.
+	Timeout time.Time
+}
+
+// Group is a set of Workers.
+type Group string
+
+// Groups is a superset of all instances of Group.
+type Groups []Group
+
+// AccessInfo contains necessary information to access the Worker.
+type AccessInfo struct{}
+
+// WorkerInfo describes the Worker.
+type WorkerInfo struct {
+	WorkerUUID WorkerUUID
+	State      WorkerState
+	Groups     Groups
+	Caps       Capabilities
+	AccessInfo AccessInfo
+}
+
+// ListFilter is used to filter Requests in the Queue.
+type ListFilter struct{}
+
+// User defines an interaction of the User with the Queue.
+type User interface {
+	// NewRequest creates a Request with given features and adds it to the Queue.
+	// It returns ID of the created Request.
+	NewRequest(caps Capabilities, priority Priority, validAfter time.Time, deadline time.Time) (ReqID, error)
+	// CloseRequest sets the Request's State to CANCEL (removes from the Queue)
+	// or DONE (finishes the Job).
+	CloseRequest(reqID ReqID) error
+	// SetRequestPriority sets the Request's Priority after it has been created.
+	SetRequestPriority(reqID ReqID, priority Priority) error
+	// SetRequestValidAfter sets the Request's ValidAfter after it has been created.
+	SetRequestValidAfter(reqID ReqID, validAfter time.Time) error
+	// SetRequestDeadline sets the Request's Deadline after it has been created.
+	SetRequestDeadline(reqID ReqID, deadline time.Time) error
+	// GetRequestInfo returns ReqInfo associated with ReqID.
+	GetRequestInfo(reqID ReqID) (ReqInfo, error)
+	// ListRequests returns ReqInfo matching the filter
+	// or all Requests if empty filter is given.
+	ListRequests(filter ListFilter) ([]ReqInfo, error)
+	// AcquireWorker returns information necessary to access the Worker reserved by the Request
+	// and prolongs access to it. If the Request is in the WAIT state, call to this function
+	// will block until the state changes.
+	// Users should use ProlongAccess() in order to avoid side-effects.
+	AcquireWorker(reqID ReqID) (AccessInfo, error)
+	// ProlongAccess sets the Job's Deadline to a predefined time.Duration from the time.Now().
+	// It can be called multiple times, but is limited.
+	ProlongAccess(reqID ReqID) error
+	// ListWorkers returns a list of all Workers matching Groups and Capabilities
+	// or all registered Workers if both arguments are empty.
+	ListWorkers(groups Groups, caps Capabilities) ([]WorkerInfo, error)
+	// GetWorkerInfo returns WorkerInfo of specified worker.
+	GetWorkerInfo(uuid WorkerUUID) (WorkerInfo, error)
+}
+
+// Worker defines actions that can be done by Worker only.
+type Worker interface {
+	// Register adds a new Worker to the system in the MAINTENANCE state.
+	// Capabilities are set on the Worker and can be changed by subsequent Register calls.
+	Register(caps Capabilities) error
+	// SetFail notifies the Server about the Failure of the Worker.
+	// It can additionally contain non-empty reason of the failure.
+	SetFail(uuid WorkerUUID, reason string) error
+}
+
+// Admin is responsible for management of the Workers.
+type Admin interface {
+	// SetState sets the Worker's state to either MAINTENANCE or IDLE.
+	SetState(uuid WorkerUUID, state WorkerState) error
+	// SetGroups updates the groups parameter of the Worker.
+	SetGroups(uuid WorkerUUID, groups Groups) error
+	// Deregister removes the Worker from the system.
+	// It can only succeed if the Worker is in the MAINTENANCE mode.
+	Deregister(uuid WorkerUUID) error
+}
+
+// Server combines all interfaces for regular Users, Admins and Workers
+// It can also implement HTTP API.
+type Server interface {
+	User
+	Worker
+	Admin
+}