database

package
v0.4.30 Latest Latest
Warning

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

 Go to latest Published: Aug 9, 2024 License: Apache-2.0 Imports: 17 Imported by: 1

Documentation

Overview

Package database provides the database interface for the Yorkie backend.

Index

Constants

View Source 
const (
	ClientDeactivated = "deactivated"
	ClientActivated   = "activated"
)

Below are statuses of the client.

View Source 
const (
	DocumentAttached = "attached"
	DocumentDetached = "detached"
	DocumentRemoved  = "removed"
)

Below are statuses of the document.

Variables

View Source 
var (
	ErrClientNotActivated      = errors.New("client not activated")
	ErrDocumentNotAttached     = errors.New("document not attached")
	ErrDocumentNeverAttached   = errors.New("client has never attached the document")
	ErrDocumentAlreadyAttached = errors.New("document already attached")
	ErrDocumentAlreadyDetached = errors.New("document already detached")
	ErrAttachedDocumentExists  = errors.New("attached document exits when deactivated")
)

Below are the errors may occur depending on the document and client status.

View Source 
var (
	// ErrProjectAlreadyExists is returned when the project already exists.
	ErrProjectAlreadyExists = errors.New("project already exists")

	// ErrUserNotFound is returned when the user is not found.
	ErrUserNotFound = errors.New("user not found")

	// ErrProjectNotFound is returned when the project is not found.
	ErrProjectNotFound = errors.New("project not found")

	// ErrUserAlreadyExists is returned when the user already exists.
	ErrUserAlreadyExists = errors.New("user already exists")

	// ErrClientNotFound is returned when the client could not be found.
	ErrClientNotFound = errors.New("client not found")

	// ErrDocumentNotFound is returned when the document could not be found.
	ErrDocumentNotFound = errors.New("document not found")

	// ErrSnapshotNotFound is returned when the snapshot could not be found.
	ErrSnapshotNotFound = errors.New("snapshot not found")

	// ErrConflictOnUpdate is returned when a conflict occurs during update.
	ErrConflictOnUpdate = errors.New("conflict on update")

	// ErrProjectNameAlreadyExists is returned when the project name already exists.
	ErrProjectNameAlreadyExists = errors.New("project name already exists")
)
View Source 
var DefaultProjectID = types.ID("000000000000000000000000")

DefaultProjectID is the default project ID.

View Source 
var DefaultProjectName = "default"

DefaultProjectName is the default project name.

View Source 
var ErrDecodeOperationFailed = errors.New("decode operations failed")

ErrDecodeOperationFailed is returned when decoding operations failed.

View Source 
var ErrEncodeOperationFailed = errors.New("encode operations failed")

ErrEncodeOperationFailed is returned when encoding operations failed.

View Source 
var ErrInvalidTimeDurationString = errors.New("invalid time duration string format")

ErrInvalidTimeDurationString is returned when the given time duration string is not in valid format.

View Source 
var (
	// ErrMismatchedPassword is returned when the password is mismatched.
	ErrMismatchedPassword = fmt.Errorf("mismatched password")
)

Functions

func CompareHashAndPassword added in v0.2.14 

func CompareHashAndPassword(hashed, password string) error

CompareHashAndPassword compares the hashed password and the password.

func EncodeOperations 

func EncodeOperations(operations []operations.Operation) ([][]byte, error)

EncodeOperations encodes the given operations into bytes array.

func EncodePresenceChange added in v0.4.5 

func EncodePresenceChange(p *innerpresence.PresenceChange) (string, error)

EncodePresenceChange encodes the given presence change into string.

func HashedPassword added in v0.2.14 

func HashedPassword(password string) (string, error)

HashedPassword hashes the given password.

Types

type ChangeInfo 

type ChangeInfo struct {
	ID             types.ID `bson:"_id"`
	ProjectID      types.ID `bson:"project_id"`
	DocID          types.ID `bson:"doc_id"`
	ServerSeq      int64    `bson:"server_seq"`
	ClientSeq      uint32   `bson:"client_seq"`
	Lamport        int64    `bson:"lamport"`
	ActorID        types.ID `bson:"actor_id"`
	Message        string   `bson:"message"`
	Operations     [][]byte `bson:"operations"`
	PresenceChange string   `bson:"presence_change"`
}

ChangeInfo is a structure representing information of a change.

func (*ChangeInfo) DeepCopy added in v0.3.4 

func (i *ChangeInfo) DeepCopy() *ChangeInfo

DeepCopy returns a deep copy of this ChangeInfo.

func (*ChangeInfo) ToChange 

func (i *ChangeInfo) ToChange() (*change.Change, error)

ToChange creates Change model from this ChangeInfo.

type ClientDocInfo 

type ClientDocInfo struct {
	Status    string `bson:"status"`
	ServerSeq int64  `bson:"server_seq"`
	ClientSeq uint32 `bson:"client_seq"`
}

ClientDocInfo is a structure representing information of the document attached to the client.

type ClientDocInfoMap added in v0.4.14 

type ClientDocInfoMap map[types.ID]*ClientDocInfo

ClientDocInfoMap is a map that associates DocRefKey with ClientDocInfo instances.

type ClientInfo 

type ClientInfo struct {
	// ID is the unique ID of the client.
	ID types.ID `bson:"_id"`

	// ProjectID is the ID of the project the client belongs to.
	ProjectID types.ID `bson:"project_id"`

	// Key is the key of the client. It is used to identify the client by users.
	Key string `bson:"key"`

	// Status is the status of the client.
	Status string `bson:"status"`

	// Documents is a map of document which is attached to the client.
	Documents ClientDocInfoMap `bson:"documents"`

	// CreatedAt is the time when the client was created.
	CreatedAt time.Time `bson:"created_at"`

	// UpdatedAt is the last time the client was accessed.
	// NOTE(hackerwins): The field name is "updated_at" but it is used as
	// "accessed_at".
	UpdatedAt time.Time `bson:"updated_at"`
}

ClientInfo is a structure representing information of a client.

func (*ClientInfo) AttachDocument 

func (i *ClientInfo) AttachDocument(docID types.ID, alreadyAttached bool) error

AttachDocument attaches the given document to this client.

func (*ClientInfo) CheckIfInProject 

func (i *ClientInfo) CheckIfInProject(projectID types.ID) error

CheckIfInProject checks if the client is in the project.

func (*ClientInfo) Checkpoint 

func (i *ClientInfo) Checkpoint(docID types.ID) change.Checkpoint

Checkpoint returns the checkpoint of the given document.

func (*ClientInfo) Deactivate 

func (i *ClientInfo) Deactivate()

Deactivate sets the status of this client to be deactivated.

func (*ClientInfo) DeepCopy 

func (i *ClientInfo) DeepCopy() *ClientInfo

DeepCopy returns a deep copy of this client info.

func (*ClientInfo) DetachDocument 

func (i *ClientInfo) DetachDocument(docID types.ID) error

DetachDocument detaches the given document from this client.

func (*ClientInfo) EnsureActivated added in v0.4.21 

func (i *ClientInfo) EnsureActivated() error

EnsureActivated ensures the client is activated.

func (*ClientInfo) EnsureDocumentAttached 

func (i *ClientInfo) EnsureDocumentAttached(docID types.ID) error

EnsureDocumentAttached ensures the given document is attached.

func (*ClientInfo) EnsureDocumentsNotAttachedWhenDeactivated added in v0.4.25 

func (i *ClientInfo) EnsureDocumentsNotAttachedWhenDeactivated() error

EnsureDocumentsNotAttachedWhenDeactivated ensures that no documents are attached when the client is deactivated.

func (*ClientInfo) IsAttached 

func (i *ClientInfo) IsAttached(docID types.ID) (bool, error)

IsAttached returns whether the given document is attached to this client.

func (*ClientInfo) RefKey added in v0.4.14 

func (i *ClientInfo) RefKey() types.ClientRefKey

RefKey returns the refKey of the client.

func (*ClientInfo) RemoveDocument added in v0.3.3 

func (i *ClientInfo) RemoveDocument(docID types.ID) error

RemoveDocument removes the given document from this client.

func (*ClientInfo) UpdateCheckpoint 

func (i *ClientInfo) UpdateCheckpoint(
	docID types.ID,
	cp change.Checkpoint,
) error

UpdateCheckpoint updates the checkpoint of the given document.

type Database 

type Database interface {
	// Close all resources of this database.
	Close() error

	// FindProjectInfoByPublicKey returns a project by public key.
	FindProjectInfoByPublicKey(
		ctx context.Context,
		publicKey string,
	) (*ProjectInfo, error)

	// FindProjectInfoBySecretKey returns a project by secret key.
	FindProjectInfoBySecretKey(
		ctx context.Context,
		secretKey string,
	) (*ProjectInfo, error)

	// FindProjectInfoByName returns a project by the given name.
	FindProjectInfoByName(
		ctx context.Context,
		owner types.ID,
		name string,
	) (*ProjectInfo, error)

	// FindProjectInfoByID returns a project by the given id. It should not be
	// used directly by clients because it is not checked if the project is
	// permitted to be accessed by the admin client.
	FindProjectInfoByID(ctx context.Context, id types.ID) (*ProjectInfo, error)

	// EnsureDefaultUserAndProject ensures that the default user and project
	// exists.
	EnsureDefaultUserAndProject(
		ctx context.Context,
		username,
		password string,
		clientDeactivateThreshold string,
	) (*UserInfo, *ProjectInfo, error)

	// CreateProjectInfo creates a new project.
	CreateProjectInfo(
		ctx context.Context,
		name string,
		owner types.ID,
		clientDeactivateThreshold string,
	) (*ProjectInfo, error)

	// ListProjectInfos returns all project infos owned by owner.
	ListProjectInfos(ctx context.Context, owner types.ID) ([]*ProjectInfo, error)

	// UpdateProjectInfo updates the project.
	UpdateProjectInfo(
		ctx context.Context,
		owner types.ID,
		id types.ID,
		fields *types.UpdatableProjectFields,
	) (*ProjectInfo, error)

	// CreateUserInfo creates a new user.
	CreateUserInfo(
		ctx context.Context,
		username string,
		hashedPassword string,
	) (*UserInfo, error)

	// DeleteUserInfoByName deletes a user by name.
	DeleteUserInfoByName(ctx context.Context, username string) error

	// ChangeUserPassword changes to new password for user.
	ChangeUserPassword(ctx context.Context, username, hashedNewPassword string) error

	// FindUserInfoByID returns a user by the given ID.
	FindUserInfoByID(ctx context.Context, id types.ID) (*UserInfo, error)

	// FindUserInfoByName returns a user by the given username.
	FindUserInfoByName(ctx context.Context, username string) (*UserInfo, error)

	// ListUserInfos returns all users.
	ListUserInfos(ctx context.Context) ([]*UserInfo, error)

	// ActivateClient activates the client of the given key.
	ActivateClient(ctx context.Context, projectID types.ID, key string) (*ClientInfo, error)

	// DeactivateClient deactivates the client of the given refKey.
	DeactivateClient(ctx context.Context, refKey types.ClientRefKey) (*ClientInfo, error)

	// FindClientInfoByRefKey finds the client of the given refKey.
	FindClientInfoByRefKey(ctx context.Context, refKey types.ClientRefKey) (*ClientInfo, error)

	// UpdateClientInfoAfterPushPull updates the client from the given clientInfo
	// after handling PushPull.
	UpdateClientInfoAfterPushPull(ctx context.Context, clientInfo *ClientInfo, docInfo *DocInfo) error

	// FindNextNCyclingProjectInfos finds the next N cycling projects from the given projectID.
	FindNextNCyclingProjectInfos(
		ctx context.Context,
		pageSize int,
		lastProjectID types.ID,
	) ([]*ProjectInfo, error)

	// FindDeactivateCandidatesPerProject finds the clients that need housekeeping per project.
	FindDeactivateCandidatesPerProject(
		ctx context.Context,
		project *ProjectInfo,
		candidatesLimit int,
	) ([]*ClientInfo, error)

	// FindDocInfoByKey finds the document of the given key.
	FindDocInfoByKey(
		ctx context.Context,
		projectID types.ID,
		docKey key.Key,
	) (*DocInfo, error)

	// FindDocInfosByKeys finds the documents of the given keys.
	FindDocInfosByKeys(
		ctx context.Context,
		projectID types.ID,
		docKeys []key.Key,
	) ([]*DocInfo, error)

	// FindDocInfoByKeyAndOwner finds the document of the given key. If the
	// createDocIfNotExist condition is true, create the document if it does not
	// exist.
	FindDocInfoByKeyAndOwner(
		ctx context.Context,
		clientRefKey types.ClientRefKey,
		docKey key.Key,
		createDocIfNotExist bool,
	) (*DocInfo, error)

	// FindDocInfoByRefKey finds the document of the given refKey.
	FindDocInfoByRefKey(
		ctx context.Context,
		refKey types.DocRefKey,
	) (*DocInfo, error)

	// UpdateDocInfoStatusToRemoved updates the document status to removed.
	UpdateDocInfoStatusToRemoved(
		ctx context.Context,
		refKey types.DocRefKey,
	) error

	// CreateChangeInfos stores the given changes then updates the given docInfo.
	CreateChangeInfos(
		ctx context.Context,
		projectID types.ID,
		docInfo *DocInfo,
		initialServerSeq int64,
		changes []*change.Change,
		isRemoved bool,
	) error

	// PurgeStaleChanges delete changes before the smallest in `syncedseqs` to
	// save storage.
	PurgeStaleChanges(
		ctx context.Context,
		docRefKey types.DocRefKey,
	) error

	// FindChangesBetweenServerSeqs returns the changes between two server sequences.
	FindChangesBetweenServerSeqs(
		ctx context.Context,
		docRefKey types.DocRefKey,
		from int64,
		to int64,
	) ([]*change.Change, error)

	// FindChangeInfosBetweenServerSeqs returns the changeInfos between two server sequences.
	FindChangeInfosBetweenServerSeqs(
		ctx context.Context,
		docRefKey types.DocRefKey,
		from int64,
		to int64,
	) ([]*ChangeInfo, error)

	// CreateSnapshotInfo stores the snapshot of the given document.
	CreateSnapshotInfo(
		ctx context.Context,
		docRefKey types.DocRefKey,
		doc *document.InternalDocument,
	) error

	// FindSnapshotInfoByRefKey returns the snapshot by the given refKey.
	FindSnapshotInfoByRefKey(
		ctx context.Context,
		refKey types.SnapshotRefKey,
	) (*SnapshotInfo, error)

	// FindClosestSnapshotInfo finds the closest snapshot info in a given serverSeq.
	FindClosestSnapshotInfo(
		ctx context.Context,
		docRefKey types.DocRefKey,
		serverSeq int64,
		includeSnapshot bool,
	) (*SnapshotInfo, error)

	// FindMinSyncedSeqInfo finds the minimum synced sequence info.
	FindMinSyncedSeqInfo(
		ctx context.Context,
		docRefKey types.DocRefKey,
	) (*SyncedSeqInfo, error)

	// UpdateAndFindMinSyncedTicket updates the given serverSeq of the given client
	// and returns the min synced ticket.
	UpdateAndFindMinSyncedTicket(
		ctx context.Context,
		clientInfo *ClientInfo,
		docRefKey types.DocRefKey,
		serverSeq int64,
	) (*time.Ticket, error)

	// UpdateSyncedSeq updates the syncedSeq of the given client.
	UpdateSyncedSeq(
		ctx context.Context,
		clientInfo *ClientInfo,
		docRefKey types.DocRefKey,
		serverSeq int64,
	) error

	// FindDocInfosByPaging returns the documentInfos of the given paging.
	FindDocInfosByPaging(
		ctx context.Context,
		projectID types.ID,
		paging types.Paging[types.ID],
	) ([]*DocInfo, error)

	// FindDocInfosByQuery returns the documentInfos which match the given query.
	FindDocInfosByQuery(
		ctx context.Context,
		projectID types.ID,
		query string,
		pageSize int,
	) (*types.SearchResult[*DocInfo], error)

	// IsDocumentAttached returns true if the document is attached to clients.
	IsDocumentAttached(
		ctx context.Context,
		docRefKey types.DocRefKey,
		excludeClientID types.ID,
	) (bool, error)
}

Database represents database which reads or saves Yorkie data.

type DocInfo 

type DocInfo struct {
	// ID is the unique ID of the document.
	ID types.ID `bson:"_id"`

	// ProjectID is the ID of the project that the document belongs to.
	ProjectID types.ID `bson:"project_id"`

	// Key is the key of the document.
	Key key.Key `bson:"key"`

	// ServerSeq is the sequence number of the last change of the document on the server.
	ServerSeq int64 `bson:"server_seq"`

	// Owner is the owner(ID of the client) of the document.
	Owner types.ID `bson:"owner"`

	// CreatedAt is the time when the document is created.
	CreatedAt time.Time `bson:"created_at"`

	// AccessedAt is the time when the document is accessed.
	AccessedAt time.Time `bson:"accessed_at"`

	// UpdatedAt is the time when the document is updated.
	UpdatedAt time.Time `bson:"updated_at"`

	// RemovedAt is the time when the document is removed.
	RemovedAt time.Time `bson:"removed_at"`
}

DocInfo is a structure representing information of the document.

func (*DocInfo) DeepCopy 

func (info *DocInfo) DeepCopy() *DocInfo

DeepCopy creates a deep copy of this DocInfo.

func (*DocInfo) IncreaseServerSeq 

func (info *DocInfo) IncreaseServerSeq() int64

IncreaseServerSeq increases server sequence of the document.

func (*DocInfo) IsRemoved added in v0.3.3 

func (info *DocInfo) IsRemoved() bool

IsRemoved returns true if the document is removed

func (*DocInfo) RefKey added in v0.4.14 

func (info *DocInfo) RefKey() types.DocRefKey

RefKey returns the refKey of the document.

type ProjectInfo 

type ProjectInfo struct {
	// ID is the unique ID of the project.
	ID types.ID `bson:"_id"`

	// Name is the name of this project.
	Name string `bson:"name"`

	// Owner is the owner of this project.
	Owner types.ID `bson:"owner"`

	// PublicKey is the API key of this project.
	PublicKey string `bson:"public_key"`

	// SecretKey is the secret key of this project.
	SecretKey string `bson:"secret_key"`

	// AuthWebhookURL is the url of the authorization webhook.
	AuthWebhookURL string `bson:"auth_webhook_url"`

	// AuthWebhookMethods is the methods that run the authorization webhook.
	AuthWebhookMethods []string `bson:"auth_webhook_methods"`

	// ClientDeactivateThreshold is the time after which clients in
	// specific project are considered deactivate for housekeeping.
	ClientDeactivateThreshold string `bson:"client_deactivate_threshold"`

	// CreatedAt is the time when the project was created.
	CreatedAt time.Time `bson:"created_at"`

	// UpdatedAt is the time when the project was updated.
	UpdatedAt time.Time `bson:"updated_at"`
}

ProjectInfo is a struct for project information.

func NewProjectInfo 

func NewProjectInfo(name string, owner types.ID, clientDeactivateThreshold string) *ProjectInfo

NewProjectInfo creates a new ProjectInfo of the given name.

func (*ProjectInfo) ClientDeactivateThresholdAsTimeDuration added in v0.3.1 

func (i *ProjectInfo) ClientDeactivateThresholdAsTimeDuration() (time.Duration, error)

ClientDeactivateThresholdAsTimeDuration converts ClientDeactivateThreshold string to time.Duration.

func (*ProjectInfo) DeepCopy 

func (i *ProjectInfo) DeepCopy() *ProjectInfo

DeepCopy returns a deep copy of the ProjectInfo.

func (*ProjectInfo) ToProject 

func (i *ProjectInfo) ToProject() *types.Project

ToProject converts the ProjectInfo to the Project.

func (*ProjectInfo) UpdateFields added in v0.2.8 

func (i *ProjectInfo) UpdateFields(fields *types.UpdatableProjectFields)

UpdateFields updates the fields.

type SnapshotInfo 

type SnapshotInfo struct {
	// ID is the unique ID of the snapshot.
	ID types.ID `bson:"_id"`

	// ProjectID is the ID of the project which the snapshot belongs to.
	ProjectID types.ID `bson:"project_id"`

	// DocID is the ID of the document which the snapshot belongs to.
	DocID types.ID `bson:"doc_id"`

	// ServerSeq is the sequence number of the server which the snapshot belongs to.
	ServerSeq int64 `bson:"server_seq"`

	// Lamport is the Lamport timestamp of the snapshot.
	Lamport int64 `bson:"lamport"`

	// Snapshot is the snapshot data.
	Snapshot []byte `bson:"snapshot"`

	// CreatedAt is the time when the snapshot is created.
	CreatedAt time.Time `bson:"created_at"`
}

SnapshotInfo is a structure representing information of the snapshot.

func (*SnapshotInfo) DeepCopy added in v0.4.6 

func (i *SnapshotInfo) DeepCopy() *SnapshotInfo

DeepCopy returns a deep copy of the SnapshotInfo.

func (*SnapshotInfo) RefKey added in v0.4.14 

func (i *SnapshotInfo) RefKey() types.SnapshotRefKey

RefKey returns the refKey of the snapshot.

type SyncedSeqInfo 

type SyncedSeqInfo struct {
	ID        types.ID `bson:"_id"`
	ProjectID types.ID `bson:"project_id"`
	DocID     types.ID `bson:"doc_id"`
	ClientID  types.ID `bson:"client_id"`
	Lamport   int64    `bson:"lamport"`
	ActorID   types.ID `bson:"actor_id"`
	ServerSeq int64    `bson:"server_seq"`
}

SyncedSeqInfo is a structure representing information about the synchronized sequence for each client.

type UserInfo added in v0.2.14 

type UserInfo struct {
	ID             types.ID  `bson:"_id"`
	Username       string    `bson:"username"`
	HashedPassword string    `bson:"hashed_password"`
	CreatedAt      time.Time `bson:"created_at"`
}

UserInfo is a structure representing information of a user.

func NewUserInfo added in v0.2.14 

func NewUserInfo(username, hashedPassword string) *UserInfo

NewUserInfo creates a new UserInfo of the given username.

func (*UserInfo) DeepCopy added in v0.2.14 

func (i *UserInfo) DeepCopy() *UserInfo

DeepCopy returns a deep copy of the UserInfo

func (*UserInfo) ToUser added in v0.2.14 

func (i *UserInfo) ToUser() *types.User

ToUser converts the UserInfo to a User.

Source Files

View all Source files

Directories

Path Synopsis
Package memory implements the database interface using in-memory database.
 Package memory implements the database interface using in-memory database.
Package mongo implements database interfaces using MongoDB.
 Package mongo implements database interfaces using MongoDB.
Package testcases contains testcases for database.
 Package testcases contains testcases for database.

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.