agent

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Mar 12, 2025 License: Apache-2.0 Imports: 31 Imported by: 0

README

Agent

Agent service provides a barebones HTTP and gRPC API and Service interface implementation for the development of the agent service.

Configuration

The service is configured using the environment variables from the following table. Note that any unset variables will be replaced with their default values.

Variable Description Default
AGENT_LOG_LEVEL Log level for agent service (debug, info, warn, error) debug
AGENT_CVM_GRPC_HOST Agent service gRPC host ""
AGENT_CVM_GRPC_PORT Agent service gRPC port 7001
AGENT_CVM_GRPC_SERVER_CERT Path to gRPC server certificate in pem format ""
AGENT_CVM_GRPC_SERVER_KEY Path to gRPC server key in pem format ""
AGENT_CVM_GRPC_SERVER_CA_CERTS Path to gRPC server CA certificate ""
AGENT_CVM_GRPC_CLIENT_CA_CERTS Path to gRPC client CA certificate ""

Deployment

To start the service outside of the container, execute the following shell script:

# Download the latest version of the service
git clone git@github.com:ultravioletrs/cocos.git

cd cocos

# Compile the service
make agent

# Run the service
./build/cocos-agent

Usage

For more information about service capabilities and its usage, please check out the README documentation.

Documentation

Overview

Copyright (c) Ultraviolet SPDX-License-Identifier: Apache-2.0

Index

Constants

View Source 
const (
	AgentService_Algo_FullMethodName        = "/agent.AgentService/Algo"
	AgentService_Data_FullMethodName        = "/agent.AgentService/Data"
	AgentService_Result_FullMethodName      = "/agent.AgentService/Result"
	AgentService_Attestation_FullMethodName = "/agent.AgentService/Attestation"
)
View Source 
const DecompressKey = "decompress"

Variables

View Source 
var (
	// ErrMalformedEntity indicates malformed entity specification (e.g.
	// invalid username or password).
	ErrMalformedEntity = errors.New("malformed entity specification")
	// ErrUnauthorizedAccess indicates missing or invalid credentials provided
	// when accessing a protected resource.
	ErrUnauthorizedAccess = errors.New("missing or invalid credentials provided")
	// ErrUndeclaredAlgorithm indicates algorithm was not declared in computation manifest.
	ErrUndeclaredDataset = errors.New("dataset not declared in computation manifest")
	// ErrAllManifestItemsReceived indicates no new computation manifest items expected.
	ErrAllManifestItemsReceived = errors.New("all expected manifest Items have been received")
	// ErrUndeclaredConsumer indicates the consumer requesting results in not declared in computation manifest.
	ErrUndeclaredConsumer = errors.New("result consumer is undeclared in computation manifest")
	// ErrResultsNotReady indicates the computation results are not ready.
	ErrResultsNotReady = errors.New("computation results are not yet ready")
	// ErrStateNotReady agent received a request in the wrong state.
	ErrStateNotReady = errors.New("agent not expecting this operation in the current state")
	// ErrHashMismatch provided algorithm/dataset does not match hash in manifest.
	ErrHashMismatch = errors.New("malformed data, hash does not match manifest")
	// ErrFileNameMismatch provided dataset filename does not match filename in manifest.
	ErrFileNameMismatch = errors.New("malformed data, filename does not match manifest")
	// ErrAllResultsConsumed indicates all results have been consumed.
	ErrAllResultsConsumed = errors.New("all results have been consumed by declared consumers")
	// ErrAttestationFailed attestation failed.
	ErrAttestationFailed = errors.New("failed to get raw quote")
	// ErrAttType indicates that the attestation type that is requested does not exist or is not supported.
	ErrAttestationType = errors.New("attestation type does not exist or is not supported")
)
View Source 
var AgentService_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "agent.AgentService",
	HandlerType: (*AgentServiceServer)(nil),
	Methods:     []grpc.MethodDesc{},
	Streams: []grpc.StreamDesc{
		{
			StreamName:    "Algo",
			Handler:       _AgentService_Algo_Handler,
			ClientStreams: true,
		},
		{
			StreamName:    "Data",
			Handler:       _AgentService_Data_Handler,
			ClientStreams: true,
		},
		{
			StreamName:    "Result",
			Handler:       _AgentService_Result_Handler,
			ServerStreams: true,
		},
		{
			StreamName:    "Attestation",
			Handler:       _AgentService_Attestation_Handler,
			ServerStreams: true,
		},
	},
	Metadata: "agent/agent.proto",
}

AgentService_ServiceDesc is the grpc.ServiceDesc for AgentService service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

View Source 
var File_agent_agent_proto protoreflect.FileDescriptor

Functions

func DecompressFromContext added in v0.3.0 

func DecompressFromContext(ctx context.Context) bool

func DecompressToContext added in v0.3.0 

func DecompressToContext(ctx context.Context, decompress bool) context.Context

func IndexFromContext added in v0.2.0 

func IndexFromContext(ctx context.Context) (int, bool)

func IndexToContext added in v0.2.0 

func IndexToContext(ctx context.Context, index int) context.Context

func RegisterAgentServiceServer 

func RegisterAgentServiceServer(s grpc.ServiceRegistrar, srv AgentServiceServer)

Types

type AgentConfig added in v0.0.2 

type AgentConfig struct {
	Host         string `json:"host,omitempty"`
	Port         string `json:"port,omitempty"`
	CertFile     string `json:"cert_file,omitempty"`
	KeyFile      string `json:"server_key,omitempty"`
	ServerCAFile string `json:"server_ca_file,omitempty"`
	ClientCAFile string `json:"client_ca_file,omitempty"`
	AttestedTls  bool   `json:"attested_tls,omitempty"`
}

type AgentEvent added in v0.4.0 

type AgentEvent int
const (
	Start AgentEvent = iota
	ManifestReceived
	AlgorithmReceived
	DataReceived
	RunComplete
	ResultsConsumed
	RunFailed
)

func (AgentEvent) String added in v0.4.0 

func (i AgentEvent) String() string

type AgentServiceClient 

type AgentServiceClient interface {
	Algo(ctx context.Context, opts ...grpc.CallOption) (grpc.ClientStreamingClient[AlgoRequest, AlgoResponse], error)
	Data(ctx context.Context, opts ...grpc.CallOption) (grpc.ClientStreamingClient[DataRequest, DataResponse], error)
	Result(ctx context.Context, in *ResultRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[ResultResponse], error)
	Attestation(ctx context.Context, in *AttestationRequest, opts ...grpc.CallOption) (grpc.ServerStreamingClient[AttestationResponse], error)
}

AgentServiceClient is the client API for AgentService service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

func NewAgentServiceClient 

func NewAgentServiceClient(cc grpc.ClientConnInterface) AgentServiceClient

type AgentServiceServer 

type AgentServiceServer interface {
	Algo(grpc.ClientStreamingServer[AlgoRequest, AlgoResponse]) error
	Data(grpc.ClientStreamingServer[DataRequest, DataResponse]) error
	Result(*ResultRequest, grpc.ServerStreamingServer[ResultResponse]) error
	Attestation(*AttestationRequest, grpc.ServerStreamingServer[AttestationResponse]) error
	// contains filtered or unexported methods
}

AgentServiceServer is the server API for AgentService service. All implementations must embed UnimplementedAgentServiceServer for forward compatibility.

type AgentService_AlgoClient added in v0.2.0 

type AgentService_AlgoClient = grpc.ClientStreamingClient[AlgoRequest, AlgoResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type AgentService_AlgoServer added in v0.2.0 

type AgentService_AlgoServer = grpc.ClientStreamingServer[AlgoRequest, AlgoResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type AgentService_AttestationClient added in v0.4.0 

type AgentService_AttestationClient = grpc.ServerStreamingClient[AttestationResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type AgentService_AttestationServer added in v0.4.0 

type AgentService_AttestationServer = grpc.ServerStreamingServer[AttestationResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type AgentService_DataClient added in v0.2.0 

type AgentService_DataClient = grpc.ClientStreamingClient[DataRequest, DataResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type AgentService_DataServer added in v0.2.0 

type AgentService_DataServer = grpc.ClientStreamingServer[DataRequest, DataResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type AgentService_ResultClient added in v0.2.0 

type AgentService_ResultClient = grpc.ServerStreamingClient[ResultResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type AgentService_ResultServer added in v0.2.0 

type AgentService_ResultServer = grpc.ServerStreamingServer[ResultResponse]

This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.

type AgentState added in v0.4.0 

type AgentState int
const (
	Idle AgentState = iota
	ReceivingManifest
	ReceivingAlgorithm
	ReceivingData
	Running
	ConsumingResults
	Complete
	Failed
)

func (AgentState) String added in v0.4.0 

func (i AgentState) String() string

type AlgoRequest 

type AlgoRequest struct {
	Algorithm    []byte `protobuf:"bytes,1,opt,name=algorithm,proto3" json:"algorithm,omitempty"`
	Requirements []byte `protobuf:"bytes,2,opt,name=requirements,proto3" json:"requirements,omitempty"`
	// contains filtered or unexported fields
}

func (*AlgoRequest) Descriptor deprecated 

func (*AlgoRequest) Descriptor() ([]byte, []int)

Deprecated: Use AlgoRequest.ProtoReflect.Descriptor instead.

func (*AlgoRequest) GetAlgorithm 

func (x *AlgoRequest) GetAlgorithm() []byte

func (*AlgoRequest) GetRequirements added in v0.2.0 

func (x *AlgoRequest) GetRequirements() []byte

func (*AlgoRequest) ProtoMessage 

func (*AlgoRequest) ProtoMessage()

func (*AlgoRequest) ProtoReflect 

func (x *AlgoRequest) ProtoReflect() protoreflect.Message

func (*AlgoRequest) Reset 

func (x *AlgoRequest) Reset()

func (*AlgoRequest) String 

func (x *AlgoRequest) String() string

type AlgoResponse 

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

func (*AlgoResponse) Descriptor deprecated 

func (*AlgoResponse) Descriptor() ([]byte, []int)

Deprecated: Use AlgoResponse.ProtoReflect.Descriptor instead.

func (*AlgoResponse) ProtoMessage 

func (*AlgoResponse) ProtoMessage()

func (*AlgoResponse) ProtoReflect 

func (x *AlgoResponse) ProtoReflect() protoreflect.Message

func (*AlgoResponse) Reset 

func (x *AlgoResponse) Reset()

func (*AlgoResponse) String 

func (x *AlgoResponse) String() string

type Algorithm 

type Algorithm struct {
	Algorithm    []byte   `json:"-"`
	Hash         [32]byte `json:"hash,omitempty"`
	UserKey      []byte   `json:"user_key,omitempty"`
	Requirements []byte   `json:"-"`
}

type AttestationRequest 

type AttestationRequest struct {
	TeeNonce  []byte `protobuf:"bytes,1,opt,name=teeNonce,proto3" json:"teeNonce,omitempty"`   // Should be less or equal 64 bytes.
	VtpmNonce []byte `protobuf:"bytes,2,opt,name=vtpmNonce,proto3" json:"vtpmNonce,omitempty"` // Should be less or equal 32 bytes.
	Type      int32  `protobuf:"varint,3,opt,name=type,proto3" json:"type,omitempty"`
	// contains filtered or unexported fields
}

func (*AttestationRequest) Descriptor deprecated 

func (*AttestationRequest) Descriptor() ([]byte, []int)

Deprecated: Use AttestationRequest.ProtoReflect.Descriptor instead.

func (*AttestationRequest) GetTeeNonce added in v0.5.0 

func (x *AttestationRequest) GetTeeNonce() []byte

func (*AttestationRequest) GetType added in v0.5.0 

func (x *AttestationRequest) GetType() int32

func (*AttestationRequest) GetVtpmNonce added in v0.5.0 

func (x *AttestationRequest) GetVtpmNonce() []byte

func (*AttestationRequest) ProtoMessage 

func (*AttestationRequest) ProtoMessage()

func (*AttestationRequest) ProtoReflect 

func (x *AttestationRequest) ProtoReflect() protoreflect.Message

func (*AttestationRequest) Reset 

func (x *AttestationRequest) Reset()

func (*AttestationRequest) String 

func (x *AttestationRequest) String() string

type AttestationResponse 

type AttestationResponse struct {
	File []byte `protobuf:"bytes,1,opt,name=file,proto3" json:"file,omitempty"`
	// contains filtered or unexported fields
}

func (*AttestationResponse) Descriptor deprecated 

func (*AttestationResponse) Descriptor() ([]byte, []int)

Deprecated: Use AttestationResponse.ProtoReflect.Descriptor instead.

func (*AttestationResponse) GetFile 

func (x *AttestationResponse) GetFile() []byte

func (*AttestationResponse) ProtoMessage 

func (*AttestationResponse) ProtoMessage()

func (*AttestationResponse) ProtoReflect 

func (x *AttestationResponse) ProtoReflect() protoreflect.Message

func (*AttestationResponse) Reset 

func (x *AttestationResponse) Reset()

func (*AttestationResponse) String 

func (x *AttestationResponse) String() string

type Computation 

type Computation struct {
	ID              string           `json:"id,omitempty"`
	Name            string           `json:"name,omitempty"`
	Description     string           `json:"description,omitempty"`
	Datasets        Datasets         `json:"datasets,omitempty"`
	Algorithm       Algorithm        `json:"algorithm,omitempty"`
	ResultConsumers []ResultConsumer `json:"result_consumers,omitempty"`
}

type DataRequest 

type DataRequest struct {
	Dataset  []byte `protobuf:"bytes,1,opt,name=dataset,proto3" json:"dataset,omitempty"`
	Filename string `protobuf:"bytes,2,opt,name=filename,proto3" json:"filename,omitempty"`
	// contains filtered or unexported fields
}

func (*DataRequest) Descriptor deprecated 

func (*DataRequest) Descriptor() ([]byte, []int)

Deprecated: Use DataRequest.ProtoReflect.Descriptor instead.

func (*DataRequest) GetDataset 

func (x *DataRequest) GetDataset() []byte

func (*DataRequest) GetFilename added in v0.3.0 

func (x *DataRequest) GetFilename() string

func (*DataRequest) ProtoMessage 

func (*DataRequest) ProtoMessage()

func (*DataRequest) ProtoReflect 

func (x *DataRequest) ProtoReflect() protoreflect.Message

func (*DataRequest) Reset 

func (x *DataRequest) Reset()

func (*DataRequest) String 

func (x *DataRequest) String() string

type DataResponse 

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

func (*DataResponse) Descriptor deprecated 

func (*DataResponse) Descriptor() ([]byte, []int)

Deprecated: Use DataResponse.ProtoReflect.Descriptor instead.

func (*DataResponse) ProtoMessage 

func (*DataResponse) ProtoMessage()

func (*DataResponse) ProtoReflect 

func (x *DataResponse) ProtoReflect() protoreflect.Message

func (*DataResponse) Reset 

func (x *DataResponse) Reset()

func (*DataResponse) String 

func (x *DataResponse) String() string

type Dataset 

type Dataset struct {
	Dataset  []byte   `json:"-"`
	Hash     [32]byte `json:"hash,omitempty"`
	UserKey  []byte   `json:"user_key,omitempty"`
	Filename string   `json:"filename,omitempty"`
}

type Datasets 

type Datasets []Dataset

func (*Datasets) String 

func (d *Datasets) String() string

type ManifestIndexKey added in v0.2.0 

type ManifestIndexKey struct{}

type ResultConsumer added in v0.2.0 

type ResultConsumer struct {
	UserKey []byte `json:"user_key,omitempty"`
}

type ResultRequest 

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

func (*ResultRequest) Descriptor deprecated 

func (*ResultRequest) Descriptor() ([]byte, []int)

Deprecated: Use ResultRequest.ProtoReflect.Descriptor instead.

func (*ResultRequest) ProtoMessage 

func (*ResultRequest) ProtoMessage()

func (*ResultRequest) ProtoReflect 

func (x *ResultRequest) ProtoReflect() protoreflect.Message

func (*ResultRequest) Reset 

func (x *ResultRequest) Reset()

func (*ResultRequest) String 

func (x *ResultRequest) String() string

type ResultResponse 

type ResultResponse struct {
	File []byte `protobuf:"bytes,1,opt,name=file,proto3" json:"file,omitempty"`
	// contains filtered or unexported fields
}

func (*ResultResponse) Descriptor deprecated 

func (*ResultResponse) Descriptor() ([]byte, []int)

Deprecated: Use ResultResponse.ProtoReflect.Descriptor instead.

func (*ResultResponse) GetFile 

func (x *ResultResponse) GetFile() []byte

func (*ResultResponse) ProtoMessage 

func (*ResultResponse) ProtoMessage()

func (*ResultResponse) ProtoReflect 

func (x *ResultResponse) ProtoReflect() protoreflect.Message

func (*ResultResponse) Reset 

func (x *ResultResponse) Reset()

func (*ResultResponse) String 

func (x *ResultResponse) String() string

type Service 

type Service interface {
	InitComputation(ctx context.Context, cmp Computation) error
	StopComputation(ctx context.Context) error
	Algo(ctx context.Context, algorithm Algorithm) error
	Data(ctx context.Context, dataset Dataset) error
	Result(ctx context.Context) ([]byte, error)
	Attestation(ctx context.Context, reportData [quoteprovider.Nonce]byte, nonce [vtpm.Nonce]byte, attType config.AttestationType) ([]byte, error)
	State() string
}

Service specifies an API that must be fullfiled by the domain service implementation, and all of its decorators (e.g. logging & metrics).

func New 

func New(ctx context.Context, logger *slog.Logger, eventSvc events.Service, quoteProvider client.LeveledQuoteProvider, vmlp int) Service

New instantiates the agent service implementation.

type Status added in v0.4.0 

type Status uint8
const (
	IdleState Status = iota
	InProgress
	Ready
	Completed
	Terminated
	Warning
	Starting
)

func (Status) String added in v0.4.0 

func (i Status) String() string

type UnimplementedAgentServiceServer 

type UnimplementedAgentServiceServer struct{}

UnimplementedAgentServiceServer must be embedded to have forward compatible implementations.

NOTE: this should be embedded by value instead of pointer to avoid a nil pointer dereference when methods are called.

func (UnimplementedAgentServiceServer) Algo 

func (UnimplementedAgentServiceServer) Algo(grpc.ClientStreamingServer[AlgoRequest, AlgoResponse]) error

func (UnimplementedAgentServiceServer) Attestation 

func (UnimplementedAgentServiceServer) Attestation(*AttestationRequest, grpc.ServerStreamingServer[AttestationResponse]) error

func (UnimplementedAgentServiceServer) Data 

func (UnimplementedAgentServiceServer) Data(grpc.ClientStreamingServer[DataRequest, DataResponse]) error

func (UnimplementedAgentServiceServer) Result 

func (UnimplementedAgentServiceServer) Result(*ResultRequest, grpc.ServerStreamingServer[ResultResponse]) error

type UnsafeAgentServiceServer 

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

UnsafeAgentServiceServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to AgentServiceServer will result in compilation errors.

Source Files

View all Source files

Directories

Path Synopsis
binary
docker
logging
python
wasm
api
Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
 Package api contains API-related concerns: endpoint definitions, middlewares and all resource representations.
grpc
Package grpc contains implementation of kit service gRPC API.
 Package grpc contains implementation of kit service gRPC API.
mocks
api/grpc
api/grpc/storage
api/grpc/storage/mocks
server
server/mocks
mocks
mocks

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.