framework

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Aug 19, 2024 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package framework: Overall management of the benchmarking process, including Baseline, Checker and Listor

Explanation:

  • Listor:

    Used to retrieve a list of resources and their basic information from the cloud with connector.

  • Checker:

    Used to extract required properties and validate that they meet the requirements of benchmark guidelines.

    1. Checker.GetProp:

    Used to get property either by extracting it from existing data of a listor, or by retrieving it via another API from the cloud if required.

    2. Checker.Validate:

    Used to validate the property against the benchmark and return the result.

    3. NOTE:

    It is useful to separate the GetProp and Validate steps into different functions to serve them from different servers, or from local-side and remote-side, but it is also acceptable to put them in sequence in your own code.

  • Baseline:

    Used to manage checkers and listors. It is recommended that each baseline corresponds to a single benchmark recommendation.

Index

Constants

View Source 
const AZURE_NEXT_MARKER = "nextLink"
View Source 
const DEFAULT_PAGE_SIZE = 10

Variables

This section is empty.

Functions

func CalcHash added in v0.2.0 

func CalcHash(hashType crypto.Hash, obj any) ([]byte, error)

CalcHash: Calculate specific hash of any object @param: hashType: Method of hash @param: obj: Object to calculate @return: Hash value as []byte. Convert to string with `fmt.Sprintf("%x", hash)` is recommended @return: Error

func GetEntireList 

func GetEntireList(p IPaginator, conf def.ConfPaginator, opts ...GetPageOption) ([]*json.RawMessage, error)

GetEntireList: Get list of all raw data according to definition of ConfPaginator

There are several ways of pagination: Note: [i, j) means starts with index i (inclusive) and ends with index j (exclusive)

- PaginationType == PAGE_OFFSET_LIMIT: List items of [offset, offset + limit), and offset starts with 0. We defines pageIndex as offset and pageSize as limit in paginationParam of GetOnePage. NextCondition from IPaginator.GetOnePage: Total count of items in the entire list returned by cloud (negative means not given)

- PaginationType == PAGE_CURPAGE_SIZE: List items of [(curpage - 1) * pagesize, curpage * pagesize), and curpage starts with 1. We defines pageIndex as curpage and pageSize as pagesize in paginationParam of GetOnePage. NextCondition from IPaginator.GetOnePage: Total count of items in the entire list returned by cloud (negative means not given)

- PaginationType == PAGE_MARKER: List items with marker of empty string on 1st page, and use NextMarkerName as marker for the next page if value of NextMarkerName is not empty. We defines marker and pagesize in paginationParam of GetOnePage. NextCondition from IPaginator.GetOnePage: Value of next marker

@param: p: Implementation of interface IPaginator to get data of one page @param: conf: Definition of ConfPaginator @param: opts: Options to pass to IPaginator.GetOnePage @return: List of data merged from all pages @return: Error

func SetLogger 

func SetLogger(newLogger *log.Logger)

SetLogger: Set global logger @param: newLogger: New logger instance

func SetPageSize 

func SetPageSize(pageSize int)

SetPageSize: Set PageSize option @param: pageSize: New value

Types

type Baseline 

type Baseline struct {
	// contains filtered or unexported fields
}

Baseline: Used to manage checkers and listors.

Usage of Baseline consists of 3 steps: (Optional) 1. GetListorId: Get the ids of the listors used in all the Checkers of the Baseline, which may be used to prepare the raw data in advance 2. GetProp: Extract properties from the raw data provided by the IDataProvider, which can retrieve it from the cloud connector or cache. Additional data would be retrieved directly via the cloud connector on demand. 3. Validate: Validate the property against the benchmark and return the result

func NewBaseline 

func NewBaseline(conf *def.ConfBaseline, authProvider auth.IAuthProvider, dataProvider IDataProvider) *Baseline

NewBaseline: Constructor of Baseline @param: conf: Definition of Baseline @param: authProvider: IAuthProvider to provide profile of auth @param: dataProvider: IDataProvider to provide raw data

func (*Baseline) GetHash added in v0.2.0 

func (b *Baseline) GetHash(hashType crypto.Hash, listorHashList [][]*[]byte) ([]byte, error)

GetHash: Get the hash of the Baseline

The hash value is useful to ensure data is provided from the same Baseline. Before calculation, a conversion from conf struct to unmarshaled json object is required, so that the order of keys in the json object remains stable.

Note:

  1. The id of listor is replaced by the hash of each item to avoid being affected by id remapping in different servers. The function takes a list of hashes as param so that Listor.GetHash can be called on an existing instance instead of creating a temporary one.
  2. Validator of the Checker is removed, so it is easy to deploy one server in an environment with access to connect to the cloud, and deploy another server to do the validation and keep the rules secret in the server only, while the data can be shared and processed between the 2 servers.

@param: hashType: Method of hash @param: listorHashList: Prepared hash of the Listors in the Checker @return: Hash value @return: Error

func (*Baseline) GetListorId 

func (b *Baseline) GetListorId() []int

GetListorId: Get the ids of the Listors used in all the Checkers of the Baseline @return: ids of Listors

func (*Baseline) GetMetadata 

func (b *Baseline) GetMetadata() *map[string]string

GetMetadata: Get the metadata defined in Baseline.conf @return: metadata

func (*Baseline) GetProp 

func (b *Baseline) GetProp(opts ...GetPropOption) BaselinePropList

GetProp: Extract properties from the raw data

The length of the outer list is equal to the length of checkers @param: opts: Options to pass to checker.GetProp @return: List of the result of GetProp of each checker, whose' elements are the list of props extracted from raw data

func (*Baseline) SetAuthProvider 

func (b *Baseline) SetAuthProvider(authProvider auth.IAuthProvider)

SetAuthProvider: Set new authProvider for all checkers @param: authProvider: New provider

func (*Baseline) SetDataProvider 

func (b *Baseline) SetDataProvider(dataProvider IDataProvider)

SetDataProvider: Set new dataProvider for all checkers @param: dataProvider: New provider

func (*Baseline) Validate 

func (b *Baseline) Validate(data BaselinePropList) ([]*ValidateResult, error)

Validate: Validate the property against the benchmark and return the result

NOTE: The length of the list of data must be the same as the length of checkers, as each item in the list is sent to a checker in order @param: data: List of properties to be validated @return: List of validation results @return: Error

type BaselinePropList 

type BaselinePropList []CheckerPropList

BaselinePropList: Type alias of list of CheckerPropList for a Baseline

The order of the items in the list must be the same as the order of the Checkers in the Baseline

type Checker 

type Checker struct {
	// contains filtered or unexported fields
}

Checker: Used to extract properties and validate them 

Usage of Checker consists of 2 steps:

1. GetProp: Extract Id, Name (if required) and properties of the raw data from either IDataProvider or cloud connector 2. Validate: Validate properties and generate result according to the rule defined in JsonSchema

func NewChecker 

func NewChecker(conf *def.ConfChecker, authProvider auth.IAuthProvider, dataProvider IDataProvider) *Checker

NewChecker: Constructor of Checker @param: conf: Definition of Baseline @param: authProvider: IAuthProvider to provide profile of auth @param: dataProvider: IDataProvider to provide raw data

func (*Checker) GetProp 

func (c *Checker) GetProp(opts ...GetPropOption) (CheckerPropList, error)

GetProp: Extract Id, Name (if required) and properties of the raw data @param: opts: Additional options @return: List of properties extracted from raw data @return: Error

func (*Checker) SetAuthProvider 

func (c *Checker) SetAuthProvider(authProvider auth.IAuthProvider)

SetAuthProvider: Set new authProvider @param: authProvider: New provider

func (*Checker) SetDataProvider 

func (c *Checker) SetDataProvider(dataProvider IDataProvider)

SetDataProvider: Set new dataProvider @param: dataProvider: New provider

func (*Checker) Validate 

func (c *Checker) Validate(data CheckerPropList) ([]*ValidateResult, error)

Validate: Validate properties and generate result @param: data: Properties extracted from the step of GetProp @return: Result of validation @return: Error

type CheckerProp 

type CheckerProp struct {
	// Resource identifier used in cloud connector
	Id string
	// Human readable name of the resource
	Name string
	// Properties extracted
	Prop *json.RawMessage
}

CheckerProp: Properties extracted from raw data that need to be validated

type CheckerPropList 

type CheckerPropList []*CheckerProp

CheckerPropList: Type alias of list of CheckerProp

type ConstraintChecker added in v0.2.1 

type ConstraintChecker struct {
	// contains filtered or unexported fields
}

ConstraintChecker: Used to check the constraint of a cloud connector

func NewConstraintChecker added in v0.2.1 

func NewConstraintChecker(conf *def.ConfConstraint) *ConstraintChecker

NewConstraintChecker: Constructor of ConstraintChecker @param: conf: Definition of Listor

func (*ConstraintChecker) Check added in v0.2.1 

func (c *ConstraintChecker) Check(authProvider auth.IAuthProvider, cloudType string) (string, error)

Check: Check the constraint @param: authProvider: IAuthProvider to provide profile of auth @param: cloudType: Type of cloud that the constraint is associated with @return: Empty string if the constraint is satisfied, or description if not satisfied @return: Error

type GetPageOption added in v0.2.0 

type GetPageOption func(opt *getPageOpt) error

GetPageOption: Functional options used in GetOnePage in case more options are added

func SetListorAuthProvider added in v0.2.0 

func SetListorAuthProvider(val auth.IAuthProvider) GetPageOption

SetListorAuthProvider: Set getPageOpt.ap

IAuthProvider used in call of GetOnePage instead of default value @param: val: Value for IAuthProvider

type GetPropOption added in v0.2.0 

type GetPropOption func(opt *getPropOpt) error

GetPropOption: Functional options used in GetProp in case more options are added

func SetAuthProviderOpt added in v0.2.0 

func SetAuthProviderOpt(val auth.IAuthProvider) GetPropOption

SetAuthProviderOpt: Set getPropOpt.ap

IAuthProvider used in call of GetProp instead of default value @param: val: Value for IAuthProvider

func SetDataProviderOpt added in v0.2.0 

func SetDataProviderOpt(val IDataProvider) GetPropOption

SetDataProviderOpt: Set getPropOpt.dp

IDataProvider used in call of GetProp instead of default value @param: val: Value for IDataProvider

type IDataProvider 

type IDataProvider interface {
	// GetRawDataByListorId: Get raw data of given id of Listor.
	//
	// Returns (nil, nil) if there is no data of Listor in the cloud
	//
	// IMPORTANT: The function must be goroutine safe
	// @param: listorId: Id of Listor
	// @return: Raw data of Listor
	// @return: Error
	GetRawDataByListorId(listorId int) ([]*json.RawMessage, error)
	// GetCloudTypeByListorId: Get raw data of given id of Listor.
	//
	// Returns ("", nil) if there is no data of Listor in the cloud
	//
	// IMPORTANT: The function must be goroutine safe
	// @param: listorId: Id of Listor
	// @return: Cloud type of Listor
	// @return: Error
	GetCloudTypeByListorId(listorId int) (string, error)
}

IDataProvider: Interface that provides different management of Listor

type IPaginator 

type IPaginator interface {
	// See function of GetEntireList for details of paginationParam
	// @param: paginationParam: Parameter of each page
	// @param: opts: Additional options
	// @return: List of data on one page
	// @return: NextCondition, See function GetEntireList for detail
	// @return: Error
	GetOnePage(paginationParam map[string]any, opts ...GetPageOption) ([]*json.RawMessage, NextCondition, error)
}

IPaginator: Interface to get single page of data

type Listor 

type Listor struct {
	// contains filtered or unexported fields
}

Listor: Used to retrieve a list of resources from the cloud

Implements the interface of IPaginator

func NewListor 

func NewListor(conf *def.ConfListor, authProvider auth.IAuthProvider) *Listor

NewListor: Constructor of Listor @param: conf: Definition of Listor @param: authProvider: IAuthProvider to provide profile of auth

func (*Listor) GetHash added in v0.2.0 

func (l *Listor) GetHash(hashType crypto.Hash) ([]byte, error)

GetHash: Get the hash of the Listor

The hash value is useful to ensure data is provided from the same Listor. Before calculation, a conversion from conf struct to unmarshaled json object is required, so that the order of keys in the json object remains stable.

The id of listor is removed to avoid being affected by id remapping in different servers.

@param: hashType: Method of hash @return: Hash value @return: Error

func (*Listor) GetOnePage 

func (l *Listor) GetOnePage(paginationParam map[string]any, opts ...GetPageOption) ([]*json.RawMessage, NextCondition, error)

GetOnePage: Implementation of IPaginator.GetOnePage

See function of GetEntireList in pagination for details of paginationParam @param: paginationParam: Parameter of each page @param: opts: Additional options @return: List of data on one page @return: NextCondition, See function of GetEntireList in pagination for detail @return: Error

func (*Listor) ListData 

func (l *Listor) ListData(opts ...GetPageOption) ([]*json.RawMessage, error)

ListData: Get list of all raw data according to Listor.conf

Raw data from different pages are merged where necessary. Listor.GetOnePage is called to retrieve data as an implementation of IPaginator. @param: opts: Options to pass to GetEntireList, and finally Listor.GetOnePage @return: List of raw data @return: Error

func (*Listor) SetAuthProvider 

func (l *Listor) SetAuthProvider(authProvider auth.IAuthProvider)

SetAuthProvider: Set new authProvider @param: authProvider: New provider

type NextCondition 

type NextCondition struct {
	TotalCount int
	NextMarker string
}

NextCondition: Indicate if data on the next page should be retrieved

See function of GetEntireList for detail

func ResultDataParse 

func ResultDataParse(resultData *json.RawMessage, conf def.ConfPaginator, dataListJsonPath string, opts ...RDPOption) (
	[]*json.RawMessage, NextCondition, error)

ResultDataParse: Helper function to parse the pagination data from the result of cloud according to ConfPaginator @param: resultData: Result of the cloud @param: conf: Definition of ConfPaginator @param: dataListJsonPath: JsonPath of how to get the list from resultData @param: opts: Additional options @return: List of data on one page @return: NextCondition, See function GetEntireList for detail @return: Error

type RDPOption 

type RDPOption func(opt *rdpOpt) error

RDPOption: Functional options used in ResultDataParse in case more options are added

func SetConvertObjectToList 

func SetConvertObjectToList(flag bool) RDPOption

SetConvertObjectToList: Set rdpOpt.convertObjectToList

Indicate whether to put an object got by dataListJsonPath into a list and return it @param: flag: Value for convertObjectToList

type SyncMapDataProvider 

type SyncMapDataProvider struct {
	// sync.Map of data
	DataMap sync.Map
	// sync.Map of cloud_type
	CtMap sync.Map
}

SyncMapDataProvider: Simple implementation of IDataProvider using sync.Map

func (*SyncMapDataProvider) GetCloudTypeByListorId 

func (p *SyncMapDataProvider) GetCloudTypeByListorId(listorId int) (string, error)

GetCloudTypeByListorId: Implementation of IDataProvider.GetCloudTypeByListorId @param: listorId: Id of listor @return: Cloud type of listor @return: Error

func (*SyncMapDataProvider) GetRawDataByListorId 

func (p *SyncMapDataProvider) GetRawDataByListorId(listorId int) ([]*json.RawMessage, error)

GetRawDataByListorId: Implementation of IDataProvider.GetRawDataByListorId @param: listorId: Id of listor @return: Raw data of listor @return: Error

type ValidateResult 

type ValidateResult struct {
	// Name of cloud
	CloudType def.CloudType
	// Resource identifier on the cloud
	Id string
	// Human readable name of the resource
	Name string
	// Indicate if the property has failed the benchmark check
	InRisk bool
	// Actual value of the property to be displayed
	Value string
}

ValidateResult: Result of validation

Source Files

View all Source files

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.