path: root/src/mongo/db/basic_types.idl

# Copyright (C) 2018-present MongoDB, Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the Server Side Public License, version 1,
# as published by MongoDB, Inc.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# Server Side Public License for more details.
#
# You should have received a copy of the Server Side Public License
# along with this program. If not, see
# <http://www.mongodb.com/licensing/server-side-public-license>.
#
# As a special exception, the copyright holders give permission to link the
# code of portions of this program with the OpenSSL library under certain
# conditions as described in each individual source file and distribute
# linked combinations including the program with the OpenSSL library. You
# must comply with the Server Side Public License in all respects for
# all of the code used other than as permitted herein. If you modify file(s)
# with this exception, you may extend this exception to your version of the
# file(s), but you are not obligated to do so. If you do not wish to do so,
# delete this exception statement from your version. If you delete this
# exception statement from all source files in the program, then also delete
# it in the license file.
#

# IDL Basic Types
global:
    cpp_namespace: "mongo"
    cpp_includes:
        - "mongo/db/basic_types.h"
        - "mongo/db/logical_time.h"
        - "mongo/db/namespace_string.h"
        - "mongo/db/tenant_id.h"
        - "mongo/util/database_name_util.h"
        - "mongo/util/namespace_string_util.h"
        - "mongo/bson/bson_duration.h"
        - "mongo/bson/bson_time_support.h"
        - "mongo/util/uuid.h"

types:
    string:
        bson_serialization_type: string
        description: "A BSON UTF-8 string"
        cpp_type: "std::string"
        deserializer: "mongo::BSONElement::str"

    int:
        bson_serialization_type: int
        description: "A BSON 32-bit integer"
        cpp_type: "std::int32_t"
        deserializer: "mongo::BSONElement::_numberInt"

    safeInt:
        bson_serialization_type:
                                - long
                                - int
                                - decimal
                                - double
        description: "Accepts any numerical type within integer range"
        cpp_type: "std::int32_t"
        deserializer: "mongo::BSONElement::safeNumberInt"

    safeInt64:
        bson_serialization_type:
                                - long
                                - int
                                - decimal
                                - double
        description: "Accepts any numerical type within int64 range"
        cpp_type: std::int64_t
        deserializer: "mongo::BSONElement::safeNumberLong"

    exactInt64:
        bson_serialization_type:
                                - long
                                - int
                                - decimal
                                - double
        description: "Accepts any number that can be exactly converted to an int64"
        cpp_type: std::int64_t
        deserializer: "mongo::BSONElement::exactNumberLong"

    safeDouble:
        bson_serialization_type:
                                - long
                                - int
                                - decimal
                                - double
        description: "Accepts any numerical type within double range"
        cpp_type: double
        deserializer: "mongo::BSONElement::safeNumberDouble"

    long:
        bson_serialization_type: long
        description: "A BSON 64-bit integer"
        cpp_type: "std::int64_t"
        deserializer: "mongo::BSONElement::_numberLong"

    double:
        bson_serialization_type: double
        description: "A BSON 64-bit floating point number"
        cpp_type: "double"
        deserializer: "mongo::BSONElement::_numberDouble"

    bool:
        bson_serialization_type: bool
        description: "A BSON bool"
        cpp_type: "bool"
        deserializer: "mongo::BSONElement::boolean"

    safeBool:
        bson_serialization_type:
                                - bool
                                - long
                                - int
                                - decimal
                                - double
        description: "Accepts any numerical type (including bool) which can be interpreted as a
                      true/false value"
        cpp_type: bool
        deserializer: "mongo::BSONElement::trueValue"

    optionalBool:
        bson_serialization_type: any
        description: "An optional bool type that does not serialize unless explicitly set. Can be
                      used in place of boost::optional<bool> to provide more intuitive semantics,
                      since the standard optional will coerce to true if populated regardless of
                      its internal value."
        cpp_type: "mongo::OptionalBool"
        default: "mongo::OptionalBool()"
        deserializer: "mongo::OptionalBool::parseFromBSON"
        serializer: "mongo::OptionalBool::serializeToBSON"

    bindata_generic:
        bson_serialization_type: bindata
        bindata_subtype: generic
        description: "A BSON bindata of generic sub type"
        cpp_type: "std::vector<std::uint8_t>"
        deserializer: "mongo::BSONElement::_binDataVector"

    bindata_function:
        bson_serialization_type: bindata
        bindata_subtype: function
        description: "A BSON bindata of function sub type"
        cpp_type: "std::vector<std::uint8_t>"
        deserializer: "mongo::BSONElement::_binDataVector"

    bindata_uuid:
        bson_serialization_type: bindata
        bindata_subtype: uuid
        description: "A BSON bindata of uuid sub type"
        cpp_type: "std::array<std::uint8_t, 16>"
        deserializer: "mongo::BSONElement::uuid"

    bindata_encrypt:
        bson_serialization_type: bindata
        bindata_subtype: encrypt
        description: "A BSON bindata of encrypt sub type"
        cpp_type: "std::vector<std::uint8_t>"
        deserializer: "mongo::BSONElement::_binDataVector"

    uuid:
        bson_serialization_type: bindata
        bindata_subtype: uuid
        description: "A UUID"
        cpp_type: "mongo::UUID"
        deserializer: "UUID"
        serializer: "mongo::UUID::toCDR"

    bindata_md5:
        bson_serialization_type: bindata
        bindata_subtype: md5
        description: "A BSON bindata of uuid sub type"
        cpp_type: "std::array<std::uint8_t, 16>"
        deserializer: "mongo::BSONElement::md5"

    objectid:
        bson_serialization_type: objectid
        description: "A BSON ObjectID"
        cpp_type: "mongo::OID"
        deserializer: "mongo::BSONElement::OID"

    object:
        bson_serialization_type: object
        description: "An unowned BSONObj without custom deserialization or serialization"
        cpp_type: "mongo::BSONObj"

    object_owned:
        bson_serialization_type: object
        description: "An owned BSONObj"
        cpp_type: "mongo::BSONObj"
        deserializer: "BSONObj::getOwned"

    array:
        bson_serialization_type: array
        description: "An unowned BSONArray without custom deserialization or seialization"
        cpp_type: "mongo::BSONArray"

    array_owned:
        bson_serialization_type: array
        description: "An owned BSONArray"
        cpp_type: "mongo::BSONArray"
        deserializer: "BSONObj::getOwned"

    date:
        bson_serialization_type: date
        description: "A BSON UTC DateTime"
        cpp_type: "mongo::Date_t"
        deserializer: "mongo::BSONElement::date"

    millisEpoch:
        bson_serialization_type: any
        description: "Milliseconds since the epoch, such as used by ecmascript"
        cpp_type: "mongo::Date_t"
        deserializer: "mongo::parseDateFromDurationSinceEpoch<Milliseconds>"
        serializer: "::mongo::serializeDateToDurationSinceEpoch<Milliseconds>"

    unixEpoch:
        bson_serialization_type: any
        description: "A unix epoch datetime (Seconds since the Epoch)"
        cpp_type: "mongo::Date_t"
        deserializer: "mongo::parseDateFromDurationSinceEpoch<Seconds>"
        serializer: "::mongo::serializeDateToDurationSinceEpoch<Seconds>"

    milliseconds:
        bson_serialization_type: any
        description: "A period of time measured in seconds"
        cpp_type: "mongo::Milliseconds"
        deserializer: "mongo::parseDurationFromCount<Milliseconds>"
        serializer: "::mongo::serializeDurationToCount<Milliseconds>"

    seconds:
        bson_serialization_type: any
        description: "A period of time measured in seconds"
        cpp_type: "mongo::Seconds"
        deserializer: "mongo::parseDurationFromCount<Seconds>"
        serializer: "::mongo::serializeDurationToCount<Seconds>"

    logicalTime:
        bson_serialization_type: any
        description: "A MongoDB LogicalTime."
        cpp_type: LogicalTime
        serializer: LogicalTime::serializeToBSON
        deserializer: LogicalTime::parseFromBSON

    timestamp:
        bson_serialization_type: timestamp
        description: "A BSON TimeStamp"
        cpp_type: "mongo::Timestamp"
        deserializer: "mongo::BSONElement::timestamp"

    namespacestring:
        bson_serialization_type: string
        description: "A MongoDB NamespaceString"
        cpp_type: "mongo::NamespaceString"
        serializer: ::mongo::NamespaceStringUtil::serialize
        deserializer: mongo::NamespaceStringUtil::deserialize
        deserialize_with_tenant: true

    base64string:
        bson_serialization_type: string
        description: "A binary-safe base64 encoded string"
        cpp_type: "std::string"
        serializer: "::mongo::base64::encode"
        deserializer: "mongo::base64::decode"

    base64urlstring:
        bson_serialization_type: string
        description: "A binary-safe base64url encoded string"
        cpp_type: "std::string"
        serializer: "::mongo::base64url::encode"
        deserializer: "mongo::base64url::decode"

    connection_string:
        bson_serialization_type: string
        description: "A MongoDB ConnectionString"
        cpp_type: "mongo::ConnectionString"
        serializer: mongo::ConnectionString::toString
        deserializer: mongo::ConnectionString::deserialize

    fcv_string:
        bson_serialization_type: string
        description: >-
            Ensures that the version strings in featureCompatibilityVersion documents
            serialize/deserialize to a fixed set of string values
        cpp_type: "multiversion::FeatureCompatibilityVersion"
        serializer: "::mongo::FeatureCompatibilityVersionParser::serializeVersion"
        deserializer: "mongo::FeatureCompatibilityVersionParser::parseVersion"

    IDLAnyType:
        bson_serialization_type: any
        description: "Holds a BSONElement of any type."
        cpp_type: "mongo::IDLAnyType"
        serializer: mongo::IDLAnyType::serializeToBSON
        deserializer: mongo::IDLAnyType::parseFromBSON

    IDLAnyTypeOwned:
        bson_serialization_type: any
        description: "Holds a BSONElement of any type. Does not require the backing BSON to stay
                      alive."
        cpp_type: "mongo::IDLAnyTypeOwned"
        serializer: mongo::IDLAnyTypeOwned::serializeToBSON
        deserializer: mongo::IDLAnyTypeOwned::parseFromBSON

    tenant_id:
        bson_serialization_type: any
        description: "A struct representing a tenant id"
        cpp_type: "TenantId"
        deserializer: "mongo::TenantId::parseFromBSON"
        serializer: "mongo::TenantId::serializeToBSON"

    database_name:
        bson_serialization_type: string
        description: "A MongoDB DatabaseName"
        cpp_type: "mongo::DatabaseName"
        serializer: "::mongo::DatabaseNameUtil::serialize"
        deserializer: "::mongo::DatabaseNameUtil::deserialize"
        deserialize_with_tenant: true

    # internal_only is used here because this type is not part of the input or output (ie. not to
    # be serialized/deserialized), and is only used internally by the class structures
    serialization_context:
        bson_serialization_type: any
        description: "modifies serializer/deserializer behavior based on caller context"
        cpp_type: "SerializationContext"
        internal_only: true

enums:
    CollationCaseFirst:
        description: Sort order of case differences.
        type: string
        values:
            kUpper: upper
            kLower: lower
            kOff: off

    CollationStrength:
        description: Controls the set of characteristics used to compare strings.
        type: int
        values:
            kPrimary: 1
            kSecondary: 2
            kTertiary: 3
            kQuaternary: 4
            kIdentical: 5

    CollationAlternate:
        description: Whether collation should consider whitespace and punctuation as base characters for purposes of comparison.
        type: string
        values:
            kNonIgnorable: non-ignorable
            kShifted: shifted

    CollationMaxVariable:
        description: Up to which characters are considered ignorable when alternate is "shifted".
        type: string
        values:
            kPunct: punct
            kSpace: space

structs:
    OkReply:
        description: "Shared by commands that reply with just {ok: 1} and no additional information"
        strict: true
        is_command_reply: true

    ErrorReply:
        description: "Error Reply structure shared by all commands"
        strict: false
        is_command_reply: true
        fields:
            ok:
                type: safeDouble
                validator: { gte: 0.0, lte: 0.0 }
                stability: stable
            code:
                type: int
                stability: stable
            codeName:
                type: string
                stability: stable
            errmsg:
                type: string
                stability: stable
            errorLabels:
                type: array<string>
                optional: true
                stability: stable

    SimpleCursorOptions:
        description: "Parser for cursor options, for commands with minimal cursor support"
        strict: true
        fields:
            batchSize:
                type: safeInt64
                optional: true
                validator: { gte: 0 }
                stability: stable

    Collation:
        description: "Specifies the default collation for the collection or the view."
        strict: true
        generate_comparison_operators: true
        fields:
            locale:
                type: string
                stability: stable
            # Turns case sensitivity on at strength 1 or 2.
            caseLevel:
                type: bool
                default: false
                stability: stable
            caseFirst:
                type: CollationCaseFirst
                default: kOff
                stability: stable
            # For backwards-compatibility, we must accept longs, ints, and doubles, so we cannot
            # use the int-typed CollationStrength enum directly.
            strength:
                type: safeInt
                default: static_cast<int>(CollationStrength::kTertiary)
                validator: { gte: 0, lte: 5 }
                stability: stable
            # Order numbers based on numerical order and not lexicographic order.
            numericOrdering:
                type: bool
                default: false
                stability: stable
            alternate:
                type: CollationAlternate
                default: kNonIgnorable
                stability: stable
            maxVariable:
                type: CollationMaxVariable
                default: kPunct
                stability: stable
            # Any language that uses multiple combining characters such as Arabic, ancient Greek,
            # Hebrew, Hindi, Thai or Vietnamese either requires Normalization Checking to be on, or
            # the text to go through a normalization process before collation.
            normalization:
                type: bool
                default: false
                stability: stable
            # Causes accent differences to be considered in reverse order, as it is done in the
            # French language. Note: the optionalBool parser rejects null/undefined inputs, which
            # preserves an invariant in updateCollationSpecFromICUCollator.
            backwards:
                type: optionalBool
                stability: stable
            # Indicates the version of the collator. It is used to ensure that we do not mix
            # versions by, for example, constructing an index with one version of ICU and then
            # attempting to use this index with a server that is built against a newer ICU version.
            version:
                type: string
                optional: true
                stability: unstable