# Copyright(C) 2021 - 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.
#

# This IDL file describes the BSON format for cursor response object.

global:
  cpp_namespace: "mongo"
  cpp_includes:
    - "mongo/db/namespace_string.h"
    - "mongo/idl/basic_types.h"
    - "mongo/db/query/cursor_idl_validator.h"

imports:
    - "mongo/idl/basic_types.idl"

enums:
    CursorType:
        description: "The type of a single cursor if a response has multiple cursors"
        type: string
        values:
            SearchMetaResult: "meta"
            DocumentResult: "results"

structs:
    ResponseCursorBase:
        description: "Common fields of initial and subsequent cursor responses."
        fields:
            id:
                cpp_name: "cursorId"
                description: "The cursor id of the cursor."
                type: long
                unstable: false
            ns:
                description: "The namespace of the cursor."
                type: namespacestring
                unstable: false
            postBatchResumeToken:
                description: "An optional resume token object."
                type: object
                optional: true
                unstable: false
            atClusterTime:
                description: "The time stamp at which the response is being returned."
                type: timestamp
                optional: true
                unstable: false
            partialResultsReturned:
                description: "Boolean represents whether partial results are being returned."
                type: optionalBool
                unstable: false
            invalidated:
                description: "Boolean represents if the cursor has been invalidated."
                type: optionalBool
                unstable: false

    InitialResponseCursor:
        description: "A struct representing an initial response cursor."
        inline_chained_structs: true
        chained_structs:
            ResponseCursorBase: ResponseCursorBase
        fields:
            firstBatch:
                description: "The first batch of the cursor."
                type: array<object>
                unstable: false

    MultiResponseInitialResponseCursor: 
        description: "A struct representing an initial response cursor if multiple cursors are returned."
        inline_chained_structs: true
        chained_structs:
            ResponseCursorBase: ResponseCursorBase
        fields:
            firstBatch:
                description: "The first batch of the cursor."
                type: array<object>
                unstable: false
            type:
                description: "Optional disambiguation string of a cursor."
                type: CursorType
                cpp_name: cursorType
                unstable: true
                optional: true
 
    MultiResponseCursor:
        description: "A struct representing a cursor object inside an array of cursors"
        fields:
            cursor:
                description: "The actual cursor object."
                type: MultiResponseInitialResponseCursor 
                unstable: true
            ok:
                type: bool
                unstable: true

    CursorInitialReply:
        description: "A struct representing a initial cursor reply."
        cpp_validator_func: "validateIDLParsedCursorResponse"
        fields:
            cursor:
                description: "A response cursor object."
                type: InitialResponseCursor
                unstable: false
                optional: true
            cursors:
                description: "An array of cursor objects."
                type: array<MultiResponseCursor>
                unstable: true
                optional: true
            vars:
                description: "An optional field containing additional response information for the query."
                type: object
                optional: true
                unstable: true 
            type:
                description: "An optional field containing disambiguation information if a reply contains multiple cursors."
                type: CursorType 
                cpp_name: cursorType
                optional: true
                unstable: true

    GetMoreResponseCursor:
        description: "A struct representing a subsequent response cursor."
        inline_chained_structs: true
        chained_structs:
            ResponseCursorBase: ResponseCursorBase
        fields:
            nextBatch:
                description: "The subsequent batch of the cursor."
                type: array<object>
                unstable: false

    CursorGetMoreReply:
        description: "A struct representing a getMore cursor reply."
        fields:
            cursor:
                description: "A response cursor object."
                type: GetMoreResponseCursor
                unstable: false