common

package
v1.21.0 Latest Latest
Warning

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

 Go to latest Published: Mar 20, 2024 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package common contains code used to be shared by different handlers.

It should eventually be moved to the parent package or split into multiple smaller packages.

Index

Constants

View Source 
const (
	// MinWireVersion is the minimal supported wire protocol version.
	MinWireVersion = int32(0) // needed for some apps and drivers

	// MaxWireVersion is the maximal supported wire protocol version.
	MaxWireVersion = int32(21)
)

Variables

This section is empty.

Functions

func AddFieldsIterator 

func AddFieldsIterator(iter types.DocumentsIterator, closer *iterator.MultiCloser, newField *types.Document) types.DocumentsIterator

AddFieldsIterator returns an iterator that adds a new field to the underlying iterator. It will be added to the given closer.

Next method returns the next document after adding the new field to the document.

Close method closes the underlying iterator.

func AssertType 

func AssertType[T types.Type](value any) (T, error)

AssertType asserts value's type, returning protocol error for unexpected types.

If a custom error is needed, use a normal Go type assertion instead: 

d, ok := value.(*types.Document)
if !ok {
  return handlererrors.NewCommandErrorMsg(handlererrors.ErrBadValue, "expected document")
}

func CheckClientMetadata 

func CheckClientMetadata(ctx context.Context, doc *types.Document) error

CheckClientMetadata checks if the message does not contain client metadata after it was received already.

func CountIterator deprecated 

func CountIterator(iter types.DocumentsIterator, closer *iterator.MultiCloser, field string) types.DocumentsIterator

CountIterator returns an iterator that returns a single document containing the number of input documents (as int32) in the specified field: {field: count}. It will be added to the given closer.

Next method returns that document, subsequent calls return ErrIteratorDone. If input iterator contains no document, it returns ErrIteratorDone.

Close method closes the underlying iterator.

Deprecated: remove this function, use iterator.ConsumeCount instead.

func FilterDistinctValues 

func FilterDistinctValues(iter types.DocumentsIterator, key string) (*types.Array, error)

FilterDistinctValues returns distinct values from the given slice of documents with the given key.

If the key is not found in the document, the document is ignored.

If the key is found in the document, and the value is an array, each element of the array is added to the result. Otherwise, the value itself is added to the result.

func FilterDocument 

func FilterDocument(doc, filter *types.Document) (bool, error)

FilterDocument returns true if given document satisfies given filter expression.

Passed arguments must not be modified.

func FilterIterator 

func FilterIterator(iter types.DocumentsIterator, closer *iterator.MultiCloser, filter *types.Document) types.DocumentsIterator

FilterIterator returns an iterator that filters out documents that don't match the filter. It will be added to the given closer.

Next method returns the next document that matches the filter.

Close method closes the underlying iterator.

func GetLimitParam 

func GetLimitParam(doc *types.Document) (int64, error)

GetLimitParam returns limit value from provided query document.

func GetLimitStageParam 

func GetLimitStageParam(value any) (int64, error)

GetLimitStageParam returns $limit stage argument from the provided value. It returns the proper error if value doesn't meet requirements.

func GetOptionalNullParam 

func GetOptionalNullParam[T types.Type](doc *types.Document, key string, defaultValue T) (T, error)

GetOptionalNullParam returns doc's value for key, default value for missing parameter or null, or protocol error for other invalid type.

func GetOptionalParam 

func GetOptionalParam[T types.Type](doc *types.Document, key string, defaultValue T) (T, error)

GetOptionalParam returns doc's value for key, default value for missing parameter, or protocol error for invalid type.

func GetRequiredParam 

func GetRequiredParam[T types.Type](doc *types.Document, key string) (T, error)

GetRequiredParam returns doc's value for key or protocol error for missing key or invalid type.

func GetSkipStageParam 

func GetSkipStageParam(value any) (int64, error)

GetSkipStageParam returns $skip stage argument from the provided value. It returns the proper error if value doesn't meet requirements.

func GetSortType 

func GetSortType(key string, value any) (types.SortType, error)

GetSortType determines SortType from input sort value.

func HasSupportedUpdateModifiers 

func HasSupportedUpdateModifiers(command string, update *types.Document) (bool, error)

HasSupportedUpdateModifiers checks if the update document contains supported update operators.

Returns false when no update operators are found. Returns an error when the document contains unsupported operators or when there is a mix of operators and non-$-prefixed fields.

func Ignored 

func Ignored(doc *types.Document, l *zap.Logger, fields ...string)

Ignored logs a message if doc has any of the given fields.

func IsMaster 

func IsMaster(ctx context.Context, query *types.Document, tcpHost, name string) (*wire.OpReply, error)

IsMaster is a common implementation of the isMaster command used by deprecated OP_QUERY message.

func IsMasterDocument added in v1.19.0 

func IsMasterDocument(tcpHost, name string) *types.Document

IsMasterDocument returns isMaster's Documents field (identical for both OP_MSG and OP_QUERY).

func LimitDocuments 

func LimitDocuments(docs []*types.Document, limit int64) ([]*types.Document, error)

LimitDocuments returns a subslice of given documents according to the given limit value.

func LimitIterator 

func LimitIterator(iter types.DocumentsIterator, closer *iterator.MultiCloser, limit int64) types.DocumentsIterator

LimitIterator returns an iterator that limits a number of documents returned by the underlying iterator. It will be added to the given closer.

Next method returns the next document until the limit is reached, then it returns iterator.ErrIteratorDone.

Close method closes the underlying iterator.

func NewUpdateError added in v1.21.0 

func NewUpdateError(code handlererrors.ErrorCode, msg, command string) error

NewUpdateError returns CommandError for findAndModify command, WriteError for other commands.

func ProjectDocument 

func ProjectDocument(doc, projection, filter *types.Document, inclusion bool) (*types.Document, error)

ProjectDocument applies projection to the copy of the document. It returns proper CommandError that can be returned by $project aggregation stage.

Command error codes: - ErrEmptySubProject when operator value is empty. - ErrFieldPathInvalidName when FieldPath is invalid. - ErrNotImplemented when the operator is not implemented yet. - ErrOperatorWrongLenOfArgs when the operator has an invalid number of arguments. - ErrInvalidPipelineOperator when an the operator does not exist.

func ProjectionIterator 

func ProjectionIterator(iter types.DocumentsIterator, closer *iterator.MultiCloser, projection, filter *types.Document) (types.DocumentsIterator, error)

ProjectionIterator returns an iterator that projects documents returned by the underlying iterator. It will be added to the given closer.

Next method returns the next projected document.

Close method closes the underlying iterator.

func SkipDocuments 

func SkipDocuments(docs []*types.Document, skip int64) ([]*types.Document, error)

SkipDocuments returns a subslice of given documents according to the given skip value.

func SkipIterator 

func SkipIterator(iter types.DocumentsIterator, closer *iterator.MultiCloser, skip int64) types.DocumentsIterator

SkipIterator returns an iterator that skips a number of documents returned by the underlying iterator. It will be added to the given closer.

Next method returns the next document after skipping a number of documents.

Close method closes the underlying iterator.

func SortArray 

func SortArray(arr *types.Array, sortType types.SortType)

SortArray sorts the values of given array.

func SortDocuments 

func SortDocuments(docs []*types.Document, sortDoc *types.Document) error

SortDocuments sorts given documents in place according to the given sorting conditions.

If sort path is invalid, it returns a possibly wrapped types.PathError.

func SortIterator 

func SortIterator(iter types.DocumentsIterator, closer *iterator.MultiCloser, sort *types.Document) (types.DocumentsIterator, error)

SortIterator returns an iterator of sorted documents. It will be added to the given closer.

Since sorting iterator is impossible, this function fully consumes and closes the underlying iterator, sorts documents in memory and returns a new iterator over the sorted slice.

func Unimplemented 

func Unimplemented(doc *types.Document, fields ...string) error

Unimplemented returns handlererrors.ErrNotImplemented if doc has any of the given fields.

func UnimplementedNonDefault 

func UnimplementedNonDefault(doc *types.Document, field string, isDefault func(v any) bool) error

UnimplementedNonDefault returns handlererrors.ErrNotImplemented if doc has given field, and isDefault, called with the actual value, returns false.

func ValidateProjection 

func ValidateProjection(projection *types.Document) (*types.Document, bool, error)

ValidateProjection check projection document. Document fields could be either included or excluded but not both. Exception is for the _id field that could be included or excluded. ValidateProjection returns errProjectionEmpty for empty projection and CommandError for invalid projection fields.

Command error codes:

  • `ErrProjectionExIn` when there is exclusion in inclusion projection;
  • `ErrProjectionInEx` when there is inclusion in exclusion projection;
  • `ErrEmptyFieldPath` when projection path is empty;
  • `ErrInvalidFieldPath` when positional projection path contains empty key;
  • `ErrPathContainsEmptyElement` when projection path contains empty key;
  • `ErrFieldPathInvalidName` when `$` is at the prefix of a key in the path;
  • `ErrWrongPositionalOperatorLocation` when there are multiple `$`;
  • `ErrExclusionPositionalProjection` when positional projection is used for exclusion;
  • `ErrBadPositionalProjection` when array or filter at positional projection path is empty;
  • `ErrBadPositionalProjection` when there is no filter field key for positional projection path;
  • `ErrElementMismatchPositionalProjection` when unexpected array was found on positional projection path;
  • `ErrNotImplemented` when there is unimplemented projection operators and expressions.

func ValidateSortDocument 

func ValidateSortDocument(sortDoc *types.Document) (*types.Document, error)

ValidateSortDocument validates sort documents, and return proper error if it's invalid.

func ValidateUpdateOperators 

func ValidateUpdateOperators(command string, update *types.Document) error

ValidateUpdateOperators validates update statement. ValidateUpdateOperators returns CommandError for findAndModify case-insensitive command name, WriteError for other commands.

Types

type CountParams 

type CountParams struct {
	Filter     *types.Document `ferretdb:"query,opt"`
	DB         string          `ferretdb:"$db"`
	Collection string          `ferretdb:"count,collection"`

	Skip  int64 `ferretdb:"skip,opt,positiveNumber"`
	Limit int64 `ferretdb:"limit,opt,positiveNumber"`

	Collation *types.Document `ferretdb:"collation,unimplemented"`

	Fields any `ferretdb:"fields,ignored"` // legacy MongoDB shell adds it, but it is never actually used

	MaxTimeMS      int64           `ferretdb:"maxTimeMS,ignored"`
	Hint           any             `ferretdb:"hint,ignored"`
	ReadConcern    *types.Document `ferretdb:"readConcern,ignored"`
	Comment        string          `ferretdb:"comment,ignored"`
	LSID           any             `ferretdb:"lsid,ignored"`
	ClusterTime    any             `ferretdb:"$clusterTime,ignored"`
	ReadPreference *types.Document `ferretdb:"$readPreference,ignored"`
}

CountParams represents parameters for the count command.

func GetCountParams 

func GetCountParams(document *types.Document, l *zap.Logger) (*CountParams, error)

GetCountParams returns the parameters for the count command.

type Delete 

type Delete struct {
	Filter  *types.Document `ferretdb:"q"`
	Limited bool            `ferretdb:"limit,zeroOrOneAsBool"`

	Collation *types.Document `ferretdb:"collation,unimplemented"`

	Hint string `ferretdb:"hint,ignored"`
}

Delete represents single delete operation parameters.

type DeleteParams 

type DeleteParams struct {
	DB         string `ferretdb:"$db"`
	Collection string `ferretdb:"delete,collection"`

	Deletes []Delete `ferretdb:"deletes,opt"`
	Comment string   `ferretdb:"comment,opt"`
	Ordered bool     `ferretdb:"ordered,opt"`

	Let *types.Document `ferretdb:"let,unimplemented"`

	MaxTimeMS      int64           `ferretdb:"maxTimeMS,ignored"`
	WriteConcern   *types.Document `ferretdb:"writeConcern,ignored"`
	LSID           any             `ferretdb:"lsid,ignored"`
	TxnNumber      int64           `ferretdb:"txnNumber,ignored"`
	ClusterTime    any             `ferretdb:"$clusterTime,ignored"`
	ReadPreference *types.Document `ferretdb:"$readPreference,ignored"`
}

DeleteParams represents parameters for the delete command.

func GetDeleteParams 

func GetDeleteParams(document *types.Document, l *zap.Logger) (*DeleteParams, error)

GetDeleteParams returns parameters for delete operation.

type DistinctParams 

type DistinctParams struct {
	DB         string          `ferretdb:"$db"`
	Collection string          `ferretdb:"distinct,collection"`
	Key        string          `ferretdb:"key"`
	Filter     *types.Document `ferretdb:"-"`
	Comment    string          `ferretdb:"comment,opt"`

	Query any `ferretdb:"query,opt"`

	Collation *types.Document `ferretdb:"collation,unimplemented"`

	ReadConcern    *types.Document `ferretdb:"readConcern,ignored"`
	LSID           any             `ferretdb:"lsid,ignored"`
	ClusterTime    any             `ferretdb:"$clusterTime,ignored"`
	ReadPreference *types.Document `ferretdb:"$readPreference,ignored"`
}

DistinctParams contains `distinct` command parameters supported by at least one handler.

func GetDistinctParams 

func GetDistinctParams(document *types.Document, l *zap.Logger) (*DistinctParams, error)

GetDistinctParams returns `distinct` command parameters.

type ExplainParams 

type ExplainParams struct {
	DB         string `ferretdb:"$db"`
	Collection string `ferretdb:"collection"`

	Explain *types.Document `ferretdb:"explain"`

	Filter *types.Document `ferretdb:"filter,opt"`
	Sort   *types.Document `ferretdb:"sort,opt"`
	Skip   int64           `ferretdb:"skip,opt"`
	Limit  int64           `ferretdb:"limit,opt"`

	StagesDocs []any           `ferretdb:"-"`
	Aggregate  bool            `ferretdb:"-"`
	Command    *types.Document `ferretdb:"-"`

	Verbosity string `ferretdb:"verbosity,ignored"`
}

ExplainParams represents the parameters for the explain command.

func GetExplainParams 

func GetExplainParams(document *types.Document, l *zap.Logger) (*ExplainParams, error)

GetExplainParams returns the parameters for the explain command.

type FindAndModifyParams 

type FindAndModifyParams struct {
	DB                string          `ferretdb:"$db"`
	Collection        string          `ferretdb:"findAndModify,collection"`
	Comment           string          `ferretdb:"comment,opt"`
	Query             *types.Document `ferretdb:"query,opt"`
	Sort              *types.Document `ferretdb:"sort,opt"`
	UpdateValue       any             `ferretdb:"update,opt"`
	Remove            bool            `ferretdb:"remove,opt"`
	Upsert            bool            `ferretdb:"upsert,opt"`
	ReturnNewDocument bool            `ferretdb:"new,opt,numericBool"`
	MaxTimeMS         int64           `ferretdb:"maxTimeMS,opt,wholePositiveNumber"`

	Update      *types.Document `ferretdb:"-"`
	Aggregation *types.Array    `ferretdb:"-"`

	HasUpdateOperators bool `ferretdb:"-"`

	Let          *types.Document `ferretdb:"let,unimplemented"`
	Collation    *types.Document `ferretdb:"collation,unimplemented"`
	Fields       *types.Document `ferretdb:"fields,unimplemented"`
	ArrayFilters *types.Array    `ferretdb:"arrayFilters,unimplemented"`

	Hint                     string          `ferretdb:"hint,ignored"`
	WriteConcern             *types.Document `ferretdb:"writeConcern,ignored"`
	BypassDocumentValidation bool            `ferretdb:"bypassDocumentValidation,ignored"`
	LSID                     any             `ferretdb:"lsid,ignored"`
	TxnNumber                int64           `ferretdb:"txnNumber,ignored"`
	ClusterTime              any             `ferretdb:"$clusterTime,ignored"`
	ReadPreference           *types.Document `ferretdb:"$readPreference,ignored"`
}

FindAndModifyParams represent parameters for the findAndModify command.

func GetFindAndModifyParams 

func GetFindAndModifyParams(doc *types.Document, l *zap.Logger) (*FindAndModifyParams, error)

GetFindAndModifyParams returns `findAndModifyParams` command parameters.

type FindParams 

type FindParams struct {
	DB           string          `ferretdb:"$db"`
	Collection   string          `ferretdb:"find,collection"`
	Filter       *types.Document `ferretdb:"filter,opt"`
	Sort         *types.Document `ferretdb:"sort,opt"`
	Projection   *types.Document `ferretdb:"projection,opt"`
	Skip         int64           `ferretdb:"skip,opt,positiveNumber"`
	Limit        int64           `ferretdb:"limit,opt,positiveNumber"`
	BatchSize    int64           `ferretdb:"batchSize,opt,positiveNumber"`
	SingleBatch  bool            `ferretdb:"singleBatch,opt"`
	Comment      string          `ferretdb:"comment,opt"`
	MaxTimeMS    int64           `ferretdb:"maxTimeMS,opt,wholePositiveNumber"`
	ShowRecordId bool            `ferretdb:"showRecordId,opt"`
	Tailable     bool            `ferretdb:"tailable,opt"`
	AwaitData    bool            `ferretdb:"awaitData,opt"`

	Collation *types.Document `ferretdb:"collation,unimplemented"`
	Let       *types.Document `ferretdb:"let,unimplemented"`

	AllowDiskUse     bool            `ferretdb:"allowDiskUse,ignored"`
	ReadConcern      *types.Document `ferretdb:"readConcern,ignored"`
	Max              *types.Document `ferretdb:"max,ignored"`
	Min              *types.Document `ferretdb:"min,ignored"`
	Hint             any             `ferretdb:"hint,ignored"`
	LSID             any             `ferretdb:"lsid,ignored"`
	TxnNumber        int64           `ferretdb:"txnNumber,ignored"`
	StartTransaction bool            `ferretdb:"startTransaction,ignored"`
	Autocommit       bool            `ferretdb:"autocommit,ignored"`
	ClusterTime      any             `ferretdb:"$clusterTime,ignored"`
	ReadPreference   *types.Document `ferretdb:"$readPreference,ignored"`

	ReturnKey           bool `ferretdb:"returnKey,unimplemented-non-default"`
	OplogReplay         bool `ferretdb:"oplogReplay,ignored"`
	AllowPartialResults bool `ferretdb:"allowPartialResults,unimplemented-non-default"`

	// TODO https://github.com/FerretDB/FerretDB/issues/4035
	NoCursorTimeout bool `ferretdb:"noCursorTimeout,unimplemented-non-default"`
}

FindParams represents parameters for the find command.

func GetFindParams 

func GetFindParams(doc *types.Document, l *zap.Logger) (*FindParams, error)

GetFindParams returns `find` command parameters.

type InsertParams 

type InsertParams struct {
	Docs       *types.Array `ferretdb:"documents,opt"`
	DB         string       `ferretdb:"$db"`
	Collection string       `ferretdb:"insert,collection"`
	Ordered    bool         `ferretdb:"ordered,opt"`

	MaxTimeMS                int64  `ferretdb:"maxTimeMS,ignored"`
	WriteConcern             any    `ferretdb:"writeConcern,ignored"`
	BypassDocumentValidation bool   `ferretdb:"bypassDocumentValidation,ignored"`
	Comment                  string `ferretdb:"comment,ignored"`
	LSID                     any    `ferretdb:"lsid,ignored"`
	TxnNumber                int64  `ferretdb:"txnNumber,ignored"`
	ClusterTime              any    `ferretdb:"$clusterTime,ignored"`
}

InsertParams represents the parameters for an insert command.

func GetInsertParams 

func GetInsertParams(document *types.Document, l *zap.Logger) (*InsertParams, error)

GetInsertParams returns the parameters for an insert command.

type Update 

type Update struct {
	Filter *types.Document `ferretdb:"q,opt"`
	Update *types.Document `ferretdb:"u,opt"` // TODO https://github.com/FerretDB/FerretDB/issues/2742
	Multi  bool            `ferretdb:"multi,opt"`
	Upsert bool            `ferretdb:"upsert,opt,numericBool"`

	HasUpdateOperators bool `ferretdb:"-"`

	C            *types.Document `ferretdb:"c,unimplemented"`
	Collation    *types.Document `ferretdb:"collation,unimplemented"`
	ArrayFilters *types.Array    `ferretdb:"arrayFilters,unimplemented"`

	Hint string `ferretdb:"hint,ignored"`
}

Update represents a single update operation parameters.

type UpdateParams 

type UpdateParams struct {
	DB         string `ferretdb:"$db"`
	Collection string `ferretdb:"update,collection"`

	Updates []Update `ferretdb:"updates"`

	Comment   string `ferretdb:"comment,opt"`
	MaxTimeMS int64  `ferretdb:"maxTimeMS,ignored"`

	Let *types.Document `ferretdb:"let,unimplemented"`

	Ordered                  bool            `ferretdb:"ordered,ignored"`
	BypassDocumentValidation bool            `ferretdb:"bypassDocumentValidation,ignored"`
	WriteConcern             *types.Document `ferretdb:"writeConcern,ignored"`
	LSID                     any             `ferretdb:"lsid,ignored"`
	TxnNumber                int64           `ferretdb:"txnNumber,ignored"`
	Autocommit               bool            `ferretdb:"autocommit,ignored"`
	ClusterTime              any             `ferretdb:"$clusterTime,ignored"`
	ReadPreference           *types.Document `ferretdb:"$readPreference,ignored"`
}

UpdateParams represents parameters for the update command.

func GetUpdateParams 

func GetUpdateParams(document *types.Document, l *zap.Logger) (*UpdateParams, error)

GetUpdateParams returns parameters for update command.

type UpdateResult added in v1.21.0 

type UpdateResult struct {
	Upserted struct {
		Doc *types.Document
	}

	Matched struct {
		Doc   *types.Document
		Count int32
	}

	Modified struct {
		Doc   *types.Document
		Count int32
	}
}

UpdateResult is the result type returned from common.UpdateDocument. It represents the number of documents matched, modified and upserted. In case of findAndModify, it also contains pointers to the documents.

func UpdateDocument 

func UpdateDocument(ctx context.Context, c backends.Collection, cmd string, iter types.DocumentsIterator, param *Update) (*UpdateResult, error)

UpdateDocument iterates through documents from iter and processes them sequentially based on param. Returns UpdateResult if all operations (update/upsert) are successful.

In case of updating multiple documents, UpdateDocument returns an error immediately after one of the operation fails. The rest of the documents are not processed. TODO https://github.com/FerretDB/FerretDB/issues/2612

Source Files

View all Source files

Directories

Path Synopsis
Package aggregations provides aggregation pipelines.
 Package aggregations provides aggregation pipelines.
operators
Package operators provides aggregation operators.
 Package operators provides aggregation operators.
operators/accumulators
Package accumulators provides aggregation accumulator operators.
 Package accumulators provides aggregation accumulator operators.
stages
Package stages provides aggregation stages.
 Package stages provides aggregation stages.
stages/projection
Package projection provides projection for aggregations.
 Package projection provides projection for aggregations.

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.