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
- Variables
- func IsSharable(typ WorkloadType) bool
- func IsValidName(n Name) error
- func MustMarshal(data WorkloadData) json.RawMessage
- func RegisterSharableType(t WorkloadType, d WorkloadData)
- func RegisterType(t WorkloadType, d WorkloadData)
- type Capacity
- type Deployment
- func (d *Deployment) ByType(typ ...WorkloadType) []*WorkloadWithID
- func (d *Deployment) Challenge(w io.Writer) error
- func (d *Deployment) ChallengeHash() ([]byte, error)
- func (d *Deployment) Get(name Name) (*WorkloadWithID, error)
- func (d *Deployment) GetShareables() []*WorkloadWithID
- func (d *Deployment) GetType(name Name, typ WorkloadType) (*WorkloadWithID, error)
- func (d *Deployment) SetError(err error)
- func (d *Deployment) Sign(twin uint32, sk Signer) error
- func (d *Deployment) Upgrade(n *Deployment) ([]UpgradeOp, error)
- func (d *Deployment) Valid() error
- func (d *Deployment) Verify(getter KeyGetter) error
- type DeploymentID
- type Ed25519VerifyingKey
- type IPNet
- type JobOperation
- type KeyGetter
- type Name
- type Result
- type ResultState
- type Signature
- type SignatureRequest
- type SignatureRequirement
- type Signer
- type Sr25519VerifyingKey
- type Timestamp
- type Unit
- type UpgradeOp
- type Verifier
- type Workload
- func (w *Workload) Capacity() (Capacity, error)
- func (w *Workload) Challenge(i io.Writer) error
- func (w *Workload) IsResult(state ResultState) bool
- func (w *Workload) Valid(getter WorkloadGetter) error
- func (w Workload) WithResults(result Result) Workload
- func (w *Workload) WorkloadData() (WorkloadData, error)
- type WorkloadData
- type WorkloadGetter
- type WorkloadID
- type WorkloadType
- type WorkloadWithID
Constants ¶
const ( SignatureTypeEd25519 = "ed25519" SignatureTypeSr25519 = "sr25519" )
Variables ¶
var ( // ErrWorkloadNotFound error ErrWorkloadNotFound = fmt.Errorf("workload not found") )
Functions ¶
func IsSharable ¶
func IsSharable(typ WorkloadType) bool
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
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) 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
type IPNet ¶
IPNet type
func MustParseIPNet ¶
MustParseIPNet prases iprange, panics if invalid
func (IPNet) MarshalJSON ¶
MarshalJSON dumps iprange as a string
func (*IPNet) UnmarshalText ¶
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 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 ¶
Bytes returns a slice of bytes container all the information used to sign the Result object
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
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
type Sr25519VerifyingKey ¶
type Sr25519VerifyingKey []byte
type Timestamp ¶
type Timestamp int64
Timestamp type
func (*Timestamp) UnmarshalJSON ¶
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
type UpgradeOp ¶
type UpgradeOp struct { WlID *WorkloadWithID Op JobOperation }
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) 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 (*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
type WorkloadType ¶
type WorkloadType string
WorkloadType type
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