gridtypes

package
v0.5.5 Latest Latest
Warning

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

Go to latest
Published: Feb 24, 2022 License: Apache-2.0 Imports: 16 Imported by: 0

README

Grid Types

Those are types that are used to communicate with a zos node.

Workload

This is the main envelope that hold all reservation information

type Workload struct {
	//Version (optional) is version of reservation object
	Version int `json:"version"`
	// ID of the reservation (filled by the node)
	ID ID `json:"id"`
	// User (required) of the user requesting the reservation
	User ID `json:"user_id"`
	// Type (required) of the reservation (container, zdb, vm, etc...)
	Type WorkloadType `json:"type"`
	// Data (required) is the reservation type arguments. It's different per Type
	Data json.RawMessage `json:"data"`
	// Date of creation (filled by the node)
	Created time.Time `json:"created"`
	//ToDelete is set if the user/farmer asked the reservation to be deleted
	ToDelete bool `json:"to_delete"`
	// Metadata (optional) is custom user metadata
	Metadata string `json:"metadata"`
	//Description (optional)
	Description string `json:"description"`
	// User signature (required)
	Signature string `json:"signature"`
	// Result of reservation (filled by the node)
	Result Result `json:"result"`
}

The signature is filled up by computing a challenge message from the Workload data, then the signature is filled as

signature = hex(ed25591.sign(sk, challenge))

please check the implementation in this package how the challenge is computed from the workload data.

WorkloadType

Data

For each workload type, the Data must be filled with proper parameters for this workload types.

Zmount

check Zmount data here

ZDB

check zdb data here

Network

check network data here

IPV4

check ipv4 data here

Zmachine

check zmachine data here

Kubernetes

check k8s data here

Documentation

Index

Constants

View Source
const (
	SignatureTypeEd25519 = "ed25519"
	SignatureTypeSr25519 = "sr25519"
)

Variables

View Source
var (
	// ErrWorkloadNotFound error
	ErrWorkloadNotFound = fmt.Errorf("workload not found")
)

Functions

func IsSharable

func IsSharable(typ WorkloadType) bool

func IsValidName

func IsValidName(n Name) error

IsValidName validates workload name

func MustMarshal

func MustMarshal(data WorkloadData) json.RawMessage

MustMarshal is a utility function to quickly serialize workload data

func RegisterSharableType

func RegisterSharableType(t WorkloadType, d WorkloadData)

RegisterSharableType same as RegisterType, but also register this type as sharable, which means this type can be accessed (referenced) from other deploments. But only modifiable from the type deployment that created it.

func RegisterType

func RegisterType(t WorkloadType, d WorkloadData)

RegisterType register a new workload type. This is used by zos to "declare" the workload types it supports. please check `zos` sub package for all supported types. Note: a user never need to call this, it's done by zos libraries.

Types

type Capacity

type Capacity struct {
	CRU   uint64 `json:"cru"`
	SRU   Unit   `json:"sru"`
	HRU   Unit   `json:"hru"`
	MRU   Unit   `json:"mru"`
	IPV4U uint64 `json:"ipv4u"`
}

Capacity the expected capacity of a workload

func (*Capacity) Add

func (c *Capacity) Add(o *Capacity)

Add increments value of capacity with o

func (*Capacity) Zero

func (c *Capacity) Zero() bool

Zero returns true if capacity is zero

type Deployment

type Deployment struct {
	// Version must be set to 0 on deployment creation. And then it has to
	// be incremented with each call to update.
	Version uint32 `json:"version"`
	// TwinID is the id of the twin sendign the deployment. A twin then can only
	// `get` status about deployments he owns.
	TwinID uint32 `json:"twin_id"`
	// ContractID the contract must be "pre created" on substrate before the deployment is
	// sent to the node. The node will then validate that this deployment hash, will match the
	// hash attached to this contract.
	// the flow should go as follows:
	// - fill in ALL deployment details (metadata, and workloads)
	// - calculate the deployment hash (by calling ChallengeHash method)
	// - create the contract with the right hash
	// - set the contract id on the deployment object
	// - send deployment to node.
	ContractID uint64 `json:"contract_id"`
	// Metadata is user specific meta attached to deployment, can be used to link this
	// deployment to other external systems for automation
	Metadata string `json:"metadata"`
	// Description is human readable description of the deployment
	Description string `json:"description"`
	// Expiration [deprecated] is not used
	Expiration Timestamp `json:"expiration"`
	// SignatureRequirement specifications
	SignatureRequirement SignatureRequirement `json:"signature_requirement"`
	// Workloads is a list of workloads associated with this deployment
	Workloads []Workload `json:"workloads"`
}

Deployment structure

func (*Deployment) ByType

func (d *Deployment) ByType(typ ...WorkloadType) []*WorkloadWithID

ByType gets all workloads from this reservation by type.

func (*Deployment) Challenge

func (d *Deployment) Challenge(w io.Writer) error

Challenge computes challenge for SignatureRequest

func (*Deployment) ChallengeHash

func (d *Deployment) ChallengeHash() ([]byte, error)

ChallengeHash computes the hash of the deployment. The hash is needed for the following

  • signing the deployment (done automatically by call to "Sign")
  • contract creation, the contract need to be created by this hash exactly BEFORE sending the deployment to the node
  • node verifies the hash to make sure it matches hash of the contract

func (*Deployment) Get

func (d *Deployment) Get(name Name) (*WorkloadWithID, error)

Get a workload by name

func (*Deployment) GetShareables

func (d *Deployment) GetShareables() []*WorkloadWithID

func (*Deployment) GetType

func (d *Deployment) GetType(name Name, typ WorkloadType) (*WorkloadWithID, error)

GetType gets a reservation by name if only of the correct type.

func (*Deployment) SetError

func (d *Deployment) SetError(err error)

SetError sets an error on ALL workloads. this is mostly an error caused by validation AFTTER the deployment was initially accepted

func (*Deployment) Sign

func (d *Deployment) Sign(twin uint32, sk Signer) error

Sign adds a signature to deployment given twin id

func (*Deployment) Upgrade

func (d *Deployment) Upgrade(n *Deployment) ([]UpgradeOp, error)

Upgrade validates n as an updated version of d, and return an Upgrade description for the steps that the node needs to take to move from d to n. unchanged workloads results will be set on n as is

func (*Deployment) Valid

func (d *Deployment) Valid() error

Valid validates deployment structure

func (*Deployment) Verify

func (d *Deployment) Verify(getter KeyGetter) error

Verify verifies user signatures is mainly used by the node to verify that all attached signatures are valid.

type DeploymentID

type DeploymentID string

DeploymentID is a global unique id for a deployment

func (DeploymentID) Parts

func (i DeploymentID) Parts() (twin, deployment uint32, err error)

Parts split id into building parts

func (DeploymentID) ToPath

func (i DeploymentID) ToPath() string

ToPath drive a filepath from the ID

type Ed25519VerifyingKey

type Ed25519VerifyingKey []byte

func (Ed25519VerifyingKey) Verify

func (k Ed25519VerifyingKey) Verify(msg []byte, sig []byte) bool

type IPNet

type IPNet struct{ net.IPNet }

IPNet type

func MustParseIPNet

func MustParseIPNet(txt string) IPNet

MustParseIPNet prases iprange, panics if invalid

func NewIPNet

func NewIPNet(n net.IPNet) IPNet

NewIPNet creates a new IPNet from net.IPNet

func ParseIPNet

func ParseIPNet(txt string) (r IPNet, err error)

ParseIPNet parse iprange

func (IPNet) MarshalJSON

func (i IPNet) MarshalJSON() ([]byte, error)

MarshalJSON dumps iprange as a string

func (*IPNet) Nil

func (i *IPNet) Nil() bool

Nil returns true if IPNet is not set

func (IPNet) String

func (i IPNet) String() string

func (*IPNet) UnmarshalText

func (i *IPNet) UnmarshalText(text []byte) error

UnmarshalText loads IPRange from string

type JobOperation

type JobOperation int
const (
	OpRemove JobOperation = iota
	OpAdd
	OpUpdate
)

func (JobOperation) String

func (o JobOperation) String() string

type KeyGetter

type KeyGetter interface {
	GetKey(twin uint32) ([]byte, error)
}

KeyGetter interface to get key by twin ids

type Name

type Name string

Name is a type for reservation names

func (Name) IsEmpty

func (n Name) IsEmpty() bool

IsEmpty indicates if name is not set

func (Name) String

func (n Name) String() string

type Result

type Result struct {
	// Time when the result is sent
	Created Timestamp `json:"created"`
	// State of the deployment (ok,error)
	State ResultState `json:"state"`
	// if State is "error", then this field contains the error
	// otherwise it's nil
	Error string `json:"message"`
	// Data is the information generated by the provisioning of the workload
	// its type depend on the reservation type
	Data json.RawMessage `json:"data"`
}

Result is the struct filled by the node after a reservation object has been processed

func (*Result) Bytes

func (r *Result) Bytes() ([]byte, error)

Bytes returns a slice of bytes container all the information used to sign the Result object

func (*Result) IsNil

func (r *Result) IsNil() bool

IsNil checks if Result is the zero values

func (*Result) Unmarshal

func (r *Result) Unmarshal(v interface{}) error

Unmarshal a shortcut for json.Unmarshal

func (*Result) Valid

func (r *Result) Valid() error

type ResultState

type ResultState string

ResultState type

const (
	// StateInit is the first state of the workload on storage
	StateInit ResultState = "init"
	// StateUnChanged is a special error state it means there was an error
	// running the action, but this error did not break previous state.
	StateUnChanged ResultState = "unchanged"
	// StateError constant
	StateError ResultState = "error"
	// StateOk constant
	StateOk ResultState = "ok"
	//StateDeleted constant
	StateDeleted ResultState = "deleted"
)

func (ResultState) IsAny

func (s ResultState) IsAny(state ...ResultState) bool

type Signature

type Signature struct {
	TwinID        uint32 `json:"twin_id"`
	Signature     string `json:"signature"`
	SignatureType string `json:"signature_type"`
}

Signature struct

type SignatureRequest

type SignatureRequest struct {
	TwinID   uint32 `json:"twin_id"`
	Required bool   `json:"required"`
	Weight   uint   `json:"weight"`
}

SignatureRequest struct a signature request of a twin

func (*SignatureRequest) Challenge

func (r *SignatureRequest) Challenge(w io.Writer) error

Challenge computes challenge for SignatureRequest

type SignatureRequirement

type SignatureRequirement struct {
	Requests       []SignatureRequest `json:"requests"`
	WeightRequired uint               `json:"weight_required"`
	Signatures     []Signature        `json:"signatures"`
}

SignatureRequirement struct describes the signatures that are needed to be valid for the node to accept the deployment for example

SignatureRequirement{
	WeightRequired: 1,
	Requests: []gridtypes.SignatureRequest{
		{
			TwinID: twinID,
			Weight: 1,
		},
	},
}

basically states that a total signature weight of 1 is required for the node to accept the deployment. the list of acceptable signatures is one from twin with `twinID` and his signature weight is 1 So, in this example this twin signature is enough. You can build a more sophisticated signature request to allow multiple twins to sign for example

SignatureRequirement{
	WeightRequired: 2,
	Requests: []gridtypes.SignatureRequest{
		{
			TwinID: Twin1,
			Weight: 1,
		},
		{
			TwinID: Twin2,
			Weight: 1,
		},
		{
			TwinID: Twin3,
			Required: true,
			Weight: 1,
		},
	},
},

this means that twin3 must sign + one of either (twin1 or twin2) to have the right signature weight

func (*SignatureRequirement) Challenge

func (r *SignatureRequirement) Challenge(w io.Writer) error

Challenge computes challenge for SignatureRequest

type Signer

type Signer interface {
	Sign(msg []byte) ([]byte, error)
	Type() string
}

type Sr25519VerifyingKey

type Sr25519VerifyingKey []byte

func (Sr25519VerifyingKey) Verify

func (k Sr25519VerifyingKey) Verify(msg []byte, sig []byte) bool

type Timestamp

type Timestamp int64

Timestamp type

func Now

func Now() Timestamp

Now returns timestamp of now

func (*Timestamp) Time

func (t *Timestamp) Time() time.Time

Time gets time from timestamp

func (*Timestamp) UnmarshalJSON

func (t *Timestamp) UnmarshalJSON(data []byte) error

UnmarshalJSON supports multiple formats

type Unit

type Unit uint64

Unit defines a capacity unit in "bytes" Any "value" of type Unit must be in bytes only hence use the Unit mutliplies below to set the write value

const (
	// Kilobyte unit multiplier
	Kilobyte Unit = 1024
	// Megabyte unit multiplier
	Megabyte Unit = 1024 * Kilobyte
	// Gigabyte unit multiplier
	Gigabyte Unit = 1024 * Megabyte
	// Terabyte unit multiplier
	Terabyte Unit = 1024 * Gigabyte
)

func Max

func Max(u, v Unit) Unit

Max return max of u, and v

func Min

func Min(u, v Unit) Unit

Min return min of u, and v

type UpgradeOp

type UpgradeOp struct {
	WlID *WorkloadWithID
	Op   JobOperation
}

type Verifier

type Verifier interface {
	Verify(msg []byte, sig []byte) bool
}

type Workload

type Workload struct {
	// Version is version of reservation object. On deployment creation, version must be 0
	// then only workloads that need to be updated must match the version of the deployment object.
	// if a deployment update message is sent to a node it does the following:
	// - validate deployment version
	// - check workloads list, if a version is not matching the new deployment version, the workload is untouched
	// - if a workload version is same as deployment, the workload is "updated"
	// - if a workload is removed, the workload is deleted.
	Version uint32 `json:"version"`
	//Name is unique workload name per deployment  (required)
	Name Name `json:"name"`
	// Type of the reservation (container, zdb, vm, etc...)
	Type WorkloadType `json:"type"`
	// Data is the reservation type arguments.
	Data json.RawMessage `json:"data"`
	// Metadata is user specific meta attached to deployment, can be used to link this
	// deployment to other external systems for automation
	Metadata string `json:"metadata"`
	//Description human readale description of the workload
	Description string `json:"description"`
	// Result of reservation, set by the node
	Result Result `json:"result"`
}

Workload struct

func (*Workload) Capacity

func (w *Workload) Capacity() (Capacity, error)

Capacity returns the used capacity by this workload

func (*Workload) Challenge

func (w *Workload) Challenge(i io.Writer) error

Challenge implementation

func (*Workload) IsResult

func (w *Workload) IsResult(state ResultState) bool

IsResult returns true if workload has a valid result of the given state

func (*Workload) Valid

func (w *Workload) Valid(getter WorkloadGetter) error

Valid validate reservation

func (Workload) WithResults

func (w Workload) WithResults(result Result) Workload

func (*Workload) WorkloadData

func (w *Workload) WorkloadData() (WorkloadData, error)

WorkloadData loads data of workload into WorkloadData object

type WorkloadData

type WorkloadData interface {
	Valid(getter WorkloadGetter) error
	Challenge(io.Writer) error
	Capacity() (Capacity, error)
}

WorkloadData interface

type WorkloadGetter

type WorkloadGetter interface {
	Get(name Name) (*WorkloadWithID, error)
	ByType(typ ...WorkloadType) []*WorkloadWithID
}

WorkloadGetter is used to get a workload by name inside the deployment context. Mainly used to validate dependency

type WorkloadID

type WorkloadID string

WorkloadID is a global unique id for a workload

func NewUncheckedWorkloadID

func NewUncheckedWorkloadID(twin uint32, deployment uint64, name Name) WorkloadID

func NewWorkloadID

func NewWorkloadID(twin uint32, deployment uint64, name Name) (WorkloadID, error)

NewWorkloadID creates a new global ID from it's parts

func (WorkloadID) Parts

func (i WorkloadID) Parts() (twin uint32, deployment uint64, name Name, err error)

Parts split id into building parts

func (WorkloadID) String

func (i WorkloadID) String() string

func (WorkloadID) ToPath

func (i WorkloadID) ToPath() string

ToPath drive a filepath from the ID

type WorkloadType

type WorkloadType string

WorkloadType type

func Types

func Types() []WorkloadType

Types return a list of all registered types

func (WorkloadType) String

func (t WorkloadType) String() string

func (WorkloadType) Valid

func (t WorkloadType) Valid() error

Valid checks if this is a known reservation type

type WorkloadWithID

type WorkloadWithID struct {
	*Workload
	ID WorkloadID
}

WorkloadWithID wrapper around workload type that holds the global workload ID Note: you never need to construct this manually

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL