datastore

Documentation

Overview

Package datastore provides an interface for connecting to the DataStore

Index

• Constants
• func AssignRealms(query *datastore.Query, realms []string) []*datastore.Query
• func BatchDelete(ctx context.Context, es []proto.Message, nf NewFunc) error
• func BatchDeleteACL(ctx context.Context, es []proto.Message, nf NewRealmEntityFunc, ...) error
• func BatchGet(ctx context.Context, es []proto.Message, nf NewFunc, getID GetIDFunc) ([]proto.Message, error)
• func BatchGetACL(ctx context.Context, es []proto.Message, nf NewRealmEntityFunc, ...) ([]proto.Message, error)
• func Delete(ctx context.Context, pm proto.Message, nf NewFunc) error
• func Exists(ctx context.Context, entities []FleetEntity) ([]bool, error)
• func ExistsACL(ctx context.Context, entities []RealmEntity, neededPerm realms.Permission) ([]bool, error)
• func Get(ctx context.Context, pm proto.Message, nf NewFunc) (proto.Message, error)
• func GetACL(ctx context.Context, pm proto.Message, nf NewRealmEntityFunc, ...) (proto.Message, error)
• func GetOSIndex(osversion string) []string
• func GetServoID(servoHostname string, servoPort int32) string
• func ListQuery(ctx context.Context, entityKind string, pageSize int32, pageToken string, ...) (q *datastore.Query, err error)
• func ListQueryIdPrefixSearch(ctx context.Context, entityKind string, pageSize int32, pageToken string, ...) (q *datastore.Query, err error)
• func Put(ctx context.Context, pm proto.Message, nf NewFunc, update bool) (proto.Message, error)
• func PutAll(ctx context.Context, pms []proto.Message, nf NewFunc, update bool) ([]proto.Message, error)
• func PutSingle(ctx context.Context, pm proto.Message, nf NewFunc) (proto.Message, error)
• type FleetEntity
• type GetIDFunc
• type NewFunc
• type NewRealmEntityFunc
• type OpResult
  • func (op *OpResult) LogError(e error)
• type OpResults
  • func DeleteAll(ctx context.Context, es []proto.Message, nf NewFunc) *OpResults
  • func GetAll(ctx context.Context, qf QueryAllFunc) (*OpResults, error)
  • func Insert(ctx context.Context, es []proto.Message, nf NewFunc, update, upsert bool) (*OpResults, error)
  • func (rs OpResults) Failed() OpResults
  • func (rs OpResults) Passed() OpResults
• type QueryAllFunc
• type RealmEntity

Constants

const (
	InvalidPageToken string = "Invalid Page Token."
	AlreadyExists    string = "Entity already exists."
	NotFound         string = "Entity not found"
	InternalError    string = "Internal Server Error."
	CannotDelete     string = "cannot be deleted"
	InvalidArgument  string = "Invalid argument"
	PermissionDenied string = "PermissionDenied"
)

Error messages for datastore operations

Functions

func AssignRealms

func AssignRealms(query *datastore.Query, realms []string) []*datastore.Query

AssignRealms assigns the realms to the query, and returns a list of queries such that each query has an equality condition for one realm

func BatchDelete

func BatchDelete(ctx context.Context, es []proto.Message, nf NewFunc) error

BatchDelete removes the entities from the datastore

This is a non-atomic operation Returns error even if partial delete succeeds. Must be used within a Transaction so that partial deletes are rolled back. Using it in a Transaction will rollback the partial deletes and propagate correct error message.

func BatchDeleteACL

func BatchDeleteACL(ctx context.Context, es []proto.Message, nf NewRealmEntityFunc, neededPerm realms.Permission) error

BatchDeleteACL removes the entities from the datastore after ensuring the user can access them

This is a non-atomic operation, returns error even if partial delete succeeds. Must be used within a Transaction so that partial deletes are rolled back. If any entity is not accessible to the user, this will return no data and an error.

func BatchGet

func BatchGet(ctx context.Context, es []proto.Message, nf NewFunc, getID GetIDFunc) ([]proto.Message, error)

BatchGet returns all entities in table for given IDs.

func BatchGetACL

func BatchGetACL(ctx context.Context, es []proto.Message, nf NewRealmEntityFunc, getID GetIDFunc, neededPerm realms.Permission) ([]proto.Message, error)

BatchGetACL returns all entities in table for given IDs after ensuring the user can access them. If any entity is not accessible to the user, this will return no data and an error.

func Delete

func Delete(ctx context.Context, pm proto.Message, nf NewFunc) error

Delete deletes the entity from the datastore.

func Exists

func Exists(ctx context.Context, entities []FleetEntity) ([]bool, error)

Exists checks if a list of fleet entities exist in datastore.

func ExistsACL

func ExistsACL(ctx context.Context, entities []RealmEntity, neededPerm realms.Permission) ([]bool, error)

ExistsACL checks if a list of fleet entities exist in datastore and is visible to the user with their current permissions.

func Get

func Get(ctx context.Context, pm proto.Message, nf NewFunc) (proto.Message, error)

Get retrieves entity from the datastore.

func GetACL

func GetACL(ctx context.Context, pm proto.Message, nf NewRealmEntityFunc, neededPerm realms.Permission) (proto.Message, error)

GetACL retrieves entity from the datastore and applies a realm check before returning the entity to a user.

func GetOSIndex

func GetOSIndex(osversion string) []string

GetOSIndex returns a slics of strings for a given string

func GetServoID

func GetServoID(servoHostname string, servoPort int32) string

GetServoID returns the servo_id for searching

func ListQuery

func ListQuery(ctx context.Context, entityKind string, pageSize int32, pageToken string, filterMap map[string][]interface{}, keysOnly bool) (q *datastore.Query, err error)

ListQuery constructs a query to list entities with pagination

func ListQueryIdPrefixSearch

func ListQueryIdPrefixSearch(ctx context.Context, entityKind string, pageSize int32, pageToken string, prefix string, keysOnly bool) (q *datastore.Query, err error)

ListQueryIdPrefixSearch constructs a query by searching for the name/id prefix to list entities with pagination

func Put

func Put(ctx context.Context, pm proto.Message, nf NewFunc, update bool) (proto.Message, error)

Put either creates or updates an entity in the datastore

func PutAll

func PutAll(ctx context.Context, pms []proto.Message, nf NewFunc, update bool) ([]proto.Message, error)

PutAll Upserts entities in the datastore. This is a non-atomic operation and doesnt check if the object already exists before insert/update. Returns error even if partial insert/updates succeeds. Must be used within a Transaction where objects are checked for existence before update/insert. Using it in a Transaction will rollback the partial insert/updates and propagate correct error message.

func PutSingle

func PutSingle(ctx context.Context, pm proto.Message, nf NewFunc) (proto.Message, error)

PutSingle upserts a single entity in the datastore.

If you have a clean intention to create or update an entity, please use Put(). This function doesn't need to be called in a transaction.

Types

type FleetEntity

type FleetEntity interface {
	GetProto() (proto.Message, error)

	// Validate performs a shallow check to make sure that the record can
	// be written to datastore.
	//
	// We don't validate when information is read, but we do validate when
	// it's written.
	//
	// This function is the last line of defense preventing us from writing
	// bad data to UFS. It should ONLY be used for enforcing constraints
	// that can be defined using only this record.
	//
	// For example, hostname not being an empty string is a valid
	// condition, but hostname being unique is not because the latter
	// forces us to consider what other entities exist, which is too much
	// complexity for this layer.  (Cross-entity consistency should be part
	// of request validation here)
	//
	// Validate should be a pure function. It should not modify the record.
	Validate() error
}

FleetEntity represents the interface of entity in datastore.

type GetIDFunc

type GetIDFunc func(pm proto.Message) string

GetIDFunc gets the id of a fleet entity

type NewFunc

type NewFunc func(context.Context, proto.Message) (FleetEntity, error)

NewFunc creates a new fleet entity.

type NewRealmEntityFunc

type NewRealmEntityFunc func(context.Context, proto.Message) (RealmEntity, error)

NewRealmEntityFunc creates a new realmed fleet entity

type OpResult

type OpResult struct {
	// Operations:
	// Get: record the retrieved proto object.
	// Add: record the proto object to be added.
	// Delete: record the proto object to be deleted.
	// Update: record the proto object to be updated.
	Data proto.Message
	Err  error
}

OpResult records the result of datastore operations

func (*OpResult) LogError

func (op *OpResult) LogError(e error)

LogError logs the error for an operation.

type OpResults

type OpResults []*OpResult

OpResults is a list of OpResult.

func DeleteAll

func DeleteAll(ctx context.Context, es []proto.Message, nf NewFunc) *OpResults

DeleteAll removes the entities from the datastore

func GetAll

func GetAll(ctx context.Context, qf QueryAllFunc) (*OpResults, error)

GetAll returns all entities in table.

func Insert

func Insert(ctx context.Context, es []proto.Message, nf NewFunc, update, upsert bool) (*OpResults, error)

Insert inserts the fleet objects.

func (OpResults) Failed

func (rs OpResults) Failed() OpResults

Failed generates the list of entities failed the operation.

func (OpResults) Passed

func (rs OpResults) Passed() OpResults

Passed generates the list of entities passed the operation.

type QueryAllFunc

type QueryAllFunc func(context.Context) ([]FleetEntity, error)

QueryAllFunc queries all entities for a given table.

type RealmEntity

type RealmEntity interface {
	FleetEntity
	GetRealm() string
}

RealmEntity represents the interface of an entity with a way to associate with LUCI realms.