cti

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Nov 18, 2024 License: MIT Imports: 5 Imported by: 2

README

Cross-domain Typed Identifiers (CTI) management tool and library

What is Cross-domain Typed Identifiers (CTI)?

CTIs provide a structured, standardized approach for uniquely identifying data types, instances, and their relationships across multi-service, multi-vendor, multi-platform, and multi-application environments. This system enables the unique definition of resources (both data types and instances) throughout the ecosystem, embedding vendor, package, and extension information within each identifier. Using CTI, each type and instance is represented by a CTI associated with a specific entity, ensuring clear, consistent identification across diverse systems.

[!NOTE] For more details on CTI specification, see Cross-domain Typed Identifiers (CTI) version 1.0 Specification

What does this project provide?

The project provides the following:

  • An extensible library that provides interfaces for:
    • A parser for RAMLx files that are extended with CTI specification.
    • CTI package management to work with dependent packages in other Github repositories.
    • A validator for compiled CTI entities.
  • A CLI tool that is ready to use with CTI packages and implements functionality according to the interface.

How the technology is used

CTI technology is utilized by Acronis CyberApp technology that allows third-party ISVs (application vendors) to extend Acronis Cyber Protect Cloud platform (the platform) by:

  • Bringing new object types and APIs to the system.
  • Extending the platform base domain model types (like types of tenants, alerts, events, protection plans) by new inherited types.
  • Enforce granular access to objects of different types for the API clients.

With CTI, the following entities become explicitly defined and linked to corresponding entities:

  • Domain object types, i.e. object schemas like tenants, alerts, protection plans, etc.
  • Well-known object instances, like event topics, namespaces, groups.

To describe types and instances that are associated with the CTI, RAMLx is used.

Installation

Library
go get -u github.com/acronis/go-cti
CLI
go install github.com/acronis/go-cti/cmd/cti@latest

CLI Reference

[!NOTE] By default, all commands are executed in the current working directory. You can use the global --working-dir argument to specify the working directory, if necessary.

cti init

Initializes a CTI package. Writes index.json and .ramlx folder with CTI specification files for RAMLx.

Example:

cti init
cti pkg get
cti pkg get <git_remote>@<git_ref>

Fetches the package from the specified git remote and appends the package in the dependencies list of the current component.

Example:

cti pkg get github.com/acronis/sample-package@v1
cti validate

Parses and validates the package against RAMLx.

Example:

cti validate
cti pack

Packs the package into a bundle. The valid package should be in the current working directory (or directory specified by --working-dir).

Example:

> cti pack --include-source --format zip --prefix output --output=sample-package.cti

> ls output
sample-package.cti
--include-source

Includes the source files in the bundle. By default, the source files are not included. Hidden files (starting with a dot) are not included in the bundle.

--format

The format of the output bundle. Supported formats are zip and tgz. Default is tgz.

--prefix

The directory where the output bundle will be saved. Default is ..

--output

The name of the output bundle. Default is bundle.cti. Please note that the extension is not added automatically.

Documentation

Overview

Package cti contains Cross-domain Typed Identifiers (CTI) parser and related utilities.

Index

Constants

View Source 
const (
	// InheritanceSeparator is a character that separates inheritance parts in CTI expression.
	InheritanceSeparator = '~'

	// Wildcard is a character that represents wildcard in CTI expression.
	Wildcard = '*'
)

Variables

View Source 
var ErrNotExpression = errors.New("not CTI expression")

ErrNotExpression is returned when an input is not a CTI expression.

Functions

This section is empty.

Types

type AttributeName 

type AttributeName string

AttributeName is a name of the attribute that may be used in CTI query and attribute selector.

type DynamicParameterValues 

type DynamicParameterValues map[string]string

DynamicParameterValues is a container (map) of dynamic parameter values that can be interpolated into the Expression.

type EntityName 

type EntityName string

EntityName is an entity name.

func (EntityName) EndsWithWildcard 

func (en EntityName) EndsWithWildcard() bool

EndsWithWildcard returns true if the entity name contains a wildcard in the end.

type Expression 

type Expression struct {

	// Head is a head node of the expression.
	// Each node contains a complete chunk of the expression (cti.<vendor>.<package>.<entity>.v<major>.<minor>).
	Head *Node

	// QueryAttributes is a slice of query attributes.
	// For example, for the following CTI expression:
	// cti.a.p.am.alert.v1.0~a.p.activity.canceled.v1.0[category="cti.a.p.am.category.v1.0~a.p.backup.v1.0",severity="critical"]
	// QueryAttributes will contain two attributes ("category" and "severity")
	// with values ("cti.a.p.am.category.v1.0~a.p.backup.v1.0" and "critical").
	QueryAttributes QueryAttributeSlice

	// AttributeSelector is a selector of the attribute.
	// For example, for the following CTI expression:
	// cti.a.p.am.alert.v1.0~a.p.activity.canceled.v1.0@category
	// AttributeSelector will contain "category".
	AttributeSelector AttributeName

	// AnonymousEntityUUID is an anonymous entity UUID.
	// For example, for the following CTI expression:
	// cti.a.p.am.alert.v1.0~ba3c448e-55e3-4f7f-ae54-4e87eb8635f6
	// AnonymousEntityUUID will contain "ba3c448e-55e3-4f7f-ae54-4e87eb8635f6",
	// and will be marked as valid (AnonymousEntityUUID.Valid == true).
	AnonymousEntityUUID uuid.NullUUID
	// contains filtered or unexported fields
}

Expression represents a parsed CTI expression.

func MustParse 

func MustParse(input string, opts ...ParserOption) Expression

MustParse parses input string as a CTI expression and panics on error. See Parse for more details.

func Parse 

func Parse(input string, opts ...ParserOption) (Expression, error)

Parse parses input string as a CTI expression. It accepts all kinds of expressions including identifiers, queries and attribute selectors. See ParseQuery, ParseAttributeSelector, ParseIdentifier, ParseReference for more specific parsing.

func ParseAttributeSelector 

func ParseAttributeSelector(input string, opts ...ParserOption) (Expression, error)

ParseAttributeSelector parses input string as a CTI expression. For more details see ParseAttributeSelector in Parser.

func ParseIdentifier 

func ParseIdentifier(input string, opts ...ParserOption) (Expression, error)

ParseIdentifier parses input string as a CTI expression. For more details see ParseIdentifier in Parser.

func ParseQuery 

func ParseQuery(input string, opts ...ParserOption) (Expression, error)

ParseQuery parses input string as a CTI expression. For more details see ParseQuery in Parser.

func ParseReference 

func ParseReference(input string, opts ...ParserOption) (Expression, error)

ParseReference parses input string as a CTI expression. For more details see ParseReference in Parser.

func (*Expression) GetQueryAttributeValue 

func (e *Expression) GetQueryAttributeValue(name AttributeName) (QueryAttributeValue, bool)

GetQueryAttributeValue returns QueryAttributeValue of the Expression by the attribute name.

func (*Expression) HasAnonymousEntity 

func (e *Expression) HasAnonymousEntity() bool

HasAnonymousEntity returns true if the Expression contains an anonymous entity.

func (*Expression) HasDynamicParameters 

func (e *Expression) HasDynamicParameters() bool

HasDynamicParameters returns true if the Expression contains a dynamic parameter in any node or query attribute.

func (*Expression) HasQueryAttributes 

func (e *Expression) HasQueryAttributes() bool

HasQueryAttributes returns true if the Expression contains any query attributes.

func (*Expression) HasWildcard 

func (e *Expression) HasWildcard() bool

HasWildcard returns true if the Expression contains wildcard.

func (*Expression) InterpolateDynamicParameterValues 

func (e *Expression) InterpolateDynamicParameterValues(values DynamicParameterValues) (Expression, error)

InterpolateDynamicParameterValues interpolates dynamic parameter values into the Expression.

func (*Expression) Match 

func (e *Expression) Match(secondExpression Expression) (bool, error)

Match reports whether the Expression contains any match of the second expression.

func (*Expression) MatchIgnoreQuery 

func (e *Expression) MatchIgnoreQuery(secondExpression Expression) (bool, error)

MatchIgnoreQuery reports whether the Expression contains any match of the second expression (ignoring expression query).

func (*Expression) String 

func (e *Expression) String() string

String returns the string representation of the whole CTI expression.

func (*Expression) Tail 

func (e *Expression) Tail() *Node

Tail returns the last node.

type Node 

type Node struct {
	Vendor     Vendor
	Package    Package
	EntityName EntityName
	Version    Version

	DynamicParameterName string

	Child *Node
}

Node represents a parsed complete chunk of CTI expression.

func (*Node) HasDynamicParameters 

func (n *Node) HasDynamicParameters() bool

HasDynamicParameters returns true if the Node contains a dynamic parameter.

func (*Node) HasWildcard 

func (n *Node) HasWildcard() bool

HasWildcard returns true if Node contains wildcard in any section.

func (*Node) String 

func (n *Node) String() string

String returns string representation of the Node.

type NullVersion 

type NullVersion struct {
	Value uint
	Valid bool // Valid is true if Int32 is not NULL
}

NullVersion is a nullable version value.

type Package 

type Package string

Package is a package name.

func (Package) IsWildCard 

func (p Package) IsWildCard() bool

IsWildCard returns true if the package name is a wildcard.

type ParseError 

type ParseError struct {
	Err           error
	RawExpression string
}

ParseError wraps any parsing error.

func (*ParseError) Error 

func (e *ParseError) Error() string

Error implements "error" interface.

func (*ParseError) Unwrap 

func (e *ParseError) Unwrap() error

Unwrap implements Wrapper interface.

type Parser 

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

Parser is an object for parsing CTI expressions.

func NewParser 

func NewParser(opts ...ParserOption) *Parser

NewParser creates new Parser. Available options: - WithAllowAnonymousEntity(b bool) - allows parsing anonymous entity UUID in CTI expressions. - WithAllowedDynamicParameterNames(names ...string) - allows specifying dynamic parameter names that can be used in CTI expressions.

func (*Parser) MustParse 

func (p *Parser) MustParse(input string) Expression

MustParse parses input string as a CTI expression and panics on error.

func (*Parser) Parse 

func (p *Parser) Parse(input string) (Expression, error)

Parse parses input string as a CTI expression. It accepts all kinds of expressions including identifiers, references, queries and attribute selectors. See ParseQuery, ParseAttributeSelector, ParseIdentifier, ParseReference for more specific parsing.

func (*Parser) ParseAttributeSelector 

func (p *Parser) ParseAttributeSelector(input string) (Expression, error)

ParseAttributeSelector parses input string as a CTI expression. It allows only attribute selectors but not queries. In addition, wildcard is not allowed and optional minor version is allowed. It returns error if attribute selector is absent in input string.

func (*Parser) ParseIdentifier 

func (p *Parser) ParseIdentifier(input string) (Expression, error)

ParseIdentifier parses input string as a CTI expression. It allows only identifiers without queries and attribute selectors. In addition, wildcard and optional version are not allowed.

func (*Parser) ParseQuery 

func (p *Parser) ParseQuery(input string) (Expression, error)

ParseQuery parses input string as a CTI expression. It allows only query but not attribute selectors. In addition, wildcard is not allowed and optional minor version is allowed.

func (*Parser) ParseReference 

func (p *Parser) ParseReference(input string) (Expression, error)

ParseReference parses input string as a CTI expression. It allows only identifiers without queries and attribute selectors. In addition, wildcards and optional full version are allowed.

type ParserOption 

type ParserOption interface {
	// contains filtered or unexported methods
}

ParserOption is an interface for functional options that can be passed to the NewParser constructor.

func WithAllowAnonymousEntity 

func WithAllowAnonymousEntity(b bool) ParserOption

WithAllowAnonymousEntity allows specifying whether the anonymous entity is allowed to be used in the CTI.

func WithAllowedDynamicParameterNames 

func WithAllowedDynamicParameterNames(names ...string) ParserOption

WithAllowedDynamicParameterNames allows specifying dynamic parameter names that are allowed to be used in the CTI.

type ParserOpts 

type ParserOpts struct {
	AllowedDynamicParameterNames []string
}

ParserOpts represents a parsing options.

type QueryAttribute 

type QueryAttribute struct {
	Name  AttributeName
	Value QueryAttributeValue
}

QueryAttribute is an attribute that is used in CTI query.

type QueryAttributeSlice 

type QueryAttributeSlice []QueryAttribute

QueryAttributeSlice is a slice of QueryAttribute.

func (QueryAttributeSlice) Match 

func (as QueryAttributeSlice) Match(attrSlice2 QueryAttributeSlice) (bool, error)

Match reports true if QueryAttributeSlice matches with the second QueryAttributeSlice.

type QueryAttributeValue 

type QueryAttributeValue struct {
	Raw        string
	Expression Expression
}

QueryAttributeValue is value of the attribute that is used in CTI query.

func (QueryAttributeValue) IsExpression 

func (v QueryAttributeValue) IsExpression() bool

IsExpression return true if QueryAttributeValue is expression

type Vendor 

type Vendor string

Vendor is a vendor name.

func (Vendor) IsWildCard 

func (v Vendor) IsWildCard() bool

IsWildCard returns true if the vendor name is a wildcard.

type Version 

type Version struct {
	Major            NullVersion
	HasMajorWildcard bool

	Minor            NullVersion
	HasMinorWildcard bool
}

Version is a version.

func NewPartialVersion 

func NewPartialVersion(major uint) Version

NewPartialVersion constructs a new Version with only major version part.

func NewVersion 

func NewVersion(major, minor uint) Version

NewVersion constructs a new Version.

func (Version) HasWildcard 

func (v Version) HasWildcard() bool

HasWildcard returns true if either the major or minor part is a wildcard.

func (Version) String 

func (v Version) String() string

String returns string representation of the Version.

Source Files

View all Source files

Directories

Path Synopsis
cmd
cti Module
metadata module
ramlx Module
pkg
identifier Module
ramlx Module

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.