// ==================================================================================
// Copyright (c) 2017  Ericsson AB
// All rights reserved. This program and the accompanying materials
// are made available under the terms of the Eclipse Public License v2.0
// which accompanies this distribution, and is available at
// https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html
// ==================================================================================
// Contributors:
//  Krisztian Gulyas - initial implementation and initial documentation
//
//  File:               MongoDBProtocol.ttcn
//  Rev:                R1A
//  Prodnr:             CNL 0
// ==================================================================================
module MongoDB_Types
{
    // ==============================================================================
    //
    // mongoDB wire protocol definitions
    // reference: https://docs.mongodb.com/manual/reference/mongodb-wire-protocol/
    // version: mongoDB version 3.4
    //
    // ==============================================================================

    // ------------------------------------------------------------------------------
    // general definitions
    // ------------------------------------------------------------------------------

    // 32 bit integer (little endian encoding) and decoding function
    type integer int32 with { variant "FIELDLENGTH(32), COMP(signbit), BYTEORDER(first)" };

    // decoding int32 value from octetstring
    external function decInt32 (in octetstring stream) return int32 with { extension "prototype(convert) decode(RAW)" }

    // 64 bit integer (little endian encoding)
    type integer int64 with { variant "FIELDLENGTH(64), COMP(signbit), BYTEORDER(first)" };

    // record of int64 type
    type record of int64 roInt64;

    /// null terminaged string
    type universal charstring cstring with { variant "FIELDLENGTH(null_terminated)"};

    // different size of bit fields
    type bitstring BIT1 with  { variant "BITORDER(lsb), FIELDLENGTH(1)"  };
    type bitstring BIT24 with { variant "BITORDER(lsb), FIELDLENGTH(24)" };
    type bitstring BIT28 with { variant "BITORDER(lsb), FIELDLENGTH(28)" };
    type bitstring BIT30 with { variant "BITORDER(lsb), FIELDLENGTH(30)" };
    type bitstring BIT31 with { variant "BITORDER(lsb), FIELDLENGTH(31)" };

    // record of JSON documents
    type record of universal charstring JSONRecords;

    // ------------------------------------------------------------------------------
    // mongoDB message header definitions (common part of the message)
    // ------------------------------------------------------------------------------

    // code of the operations: 32 bit integer (little endian encoding)
    type enumerated OpCode
    {
        OP_REPLY            (1),    //	Reply to a client request. responseTo is set.
        OP_MSG	         (1000), 	// Generic msg command followed by a string.
        OP_UPDATE 	     (2001), 	// Update document.
        OP_INSERT 	     (2002), 	// Insert new document.
        OP_QUERY 	     (2004), 	// Query a collection.
        OP_GET_MORE 	 (2005), 	// Get more data from a query. See Cursors.
        OP_DELETE 	     (2006), 	// Delete documents.
        OP_KILL_CURSORS  (2007), 	// Notify database that the client has finished with the cursor.
        OP_COMMAND 	     (2010), 	// Cluster internal protocol representing a command request.
        OP_COMMANDREPLY  (2011), 	// Cluster internal protocol representing a reply to an OP_COMMAND.
        OP_UNDEFINED        (0)     // Undefined value for ttcn test cases
    } with { variant "BYTEORDER(first), FIELDLENGTH(32)" };

    // header structure
    type record MsgHeader
    {
        // The total size of the message in bytes. This total includes the 4 bytes that holds the message length.
        int32   messageLength,

        // A client or database-generated identifier that uniquely identifies this message.
        // For the case of client-generated messages (e.g. OP_QUERY and OP_GET_MORE), it will be returned in the responseTo
        // field of the OP_REPLY message. Clients can use the requestID and the responseTo fields to associate query
        //  responses with the originating query.
        int32   requestId,

        // In the case of a message from the database, this will be the requestID taken from the OP_QUERY or OP_GET_MORE
        // messages from the client. Clients can use the requestID and the responseTo fields to associate query responses
        // with the originating query.
        int32   responseTo,

        // Type of message. See Request Opcodes above
        OpCode   opCode
    } with { variant "" }

    // ==============================================================================
    //
    // mongoDB client request messages
    //
    // ==============================================================================

    // ------------------------------------------------------------------------------
    // mongoDB insert message,
    // ------------------------------------------------------------------------------

    // flags: definitions of bits
    type record InsertMsgFlagsBits {
        // If set, the database will not stop processing a bulk insert if one fails (eg due to duplicate IDs).
        // This makes bulk insert behave similarly to a series of single inserts, except lastError will be set
        // if any insert fails, not just the last one. If multiple errors occur, only the most recent will be
        // reported by getLastError. (new in 1.9.1)
        BIT1        ContinueOnError,
        // 1-31 bits are reserved. Must be set to 0
        BIT31       Reserved0
    } with { variant "" }

    // flags can be accessed via bits or value
    type union InsertMsgFlags {
        InsertMsgFlagsBits  bits,
        int32               bytes
    } with { variant "FIELDLENGTH(32), COMP(signbit), BYTEORDER(first)" };

    // message structure
    type record InsertMsg
    {
        MsgHeader       header,             // standard message header
        InsertMsgFlags  flags,              // bit vector of insert options.
        cstring         fullCollectionName, // "dbname.collectionname"
        octetstring     documents           // one or more BSON documents to insert into the collection
    } with {
        variant "TAG (header, opCode = OP_INSERT)";
        variant (header) "LENGTHTO(header, flags, fullCollectionName, documents)";
        variant (header) "LENGTHINDEX(messageLength)"
    }


    // ------------------------------------------------------------------------------
    // mongoDB update message,
    // ------------------------------------------------------------------------------

    // flags: definitions of bits
    type record UpdateMsgFlagsBits {
        // If set, the database will insert the supplied object into the collection if no matching document is found.
        BIT1        Upsert,

        // If set, the database will update all matching objects in the collection. Otherwise only updates first matching document.
        BIT1        MultiUpdate,

        // 2-31 bits are reserved. Must be set to 0
        BIT30       Reserved0
    } with { variant "" }

    // flags can be accessed via bits or value
    type union UpdateMsgFlags {
        UpdateMsgFlagsBits  bits,
        int32               bytes
    } with { variant "FIELDLENGTH(32), COMP(signbit), BYTEORDER(first)" };

    // message structure
    type record UpdateMsg
    {
        MsgHeader       header,             // standard message header
        int32           ZERO,               // 0 - reserved for future use
        cstring         fullCollectionName, // "dbname.collectionname"
        UpdateMsgFlags  flags,              // bit vector of update options.
        octetstring     selector,           // BSON document that specifies the query for selection of the document to update
        octetstring     update              // BSON document that specifies the update to be performed
    } with {
        variant "TAG (header, opCode = OP_UPDATE)";
        variant (header) "LENGTHTO(header, ZERO, fullCollectionName, flags, selector, update)";
        variant (header) "LENGTHINDEX(messageLength)"
    }

    // ------------------------------------------------------------------------------
    // mongoDB query message,
    // ------------------------------------------------------------------------------

    // flags: definitions of bits
    type record QueryMsgFlagsBits {
        // Reserved. Must be set to 0.
        BIT1        Reserved0,

        // Tailable means cursor is not closed when the last data is retrieved. Rather, the cursor marks the final
        // object’s position. You can resume using the cursor later, from where it was located, if more data were received.
        // Like any “latent cursor”, the cursor may become invalid at some point (CursorNotFound) – for example if the
        // final object it references were deleted.
        BIT1        TailableCursor,

        // Allow query of replica slave. Normally these return an error except for namespace “local”.
        BIT1        SlaveOK,

        // Internal replication use only - driver should not set.
        BIT1        OplogReplay,

        // The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use.
        // Set this option to prevent that.The server normally times out idle cursors after an inactivity period (10 minutes)
        // to prevent excess memory use. Set this option to prevent that.
        BIT1        NoCursorTimeout,

        // Use with TailableCursor. If we are at the end of the data, block for a while rather than returning no data.
        // After a timeout period, we do return as normal.
        BIT1        AwaitData,

        // Stream the data down full blast in multiple “more” packages, on the assumption that the client will fully read all
        // data queried. Faster when you are pulling a lot of data and know you want to pull it all down. Note: the client is
        // not allowed to not read all the data unless it closes the connection.Stream the data down full blast in multiple “more” packages,
        // on the assumption that the client will fully read all data queried. Faster when you are pulling a lot of data and know you want
        // to pull it all down. Note: the client is not allowed to not read all the data unless it closes the connection.
        BIT1        Exhaust,

        // Get partial results from a mongos if some shards are down (instead of throwing an error)
        BIT1        Partial,

        // 8-31 bits are reserved. Must be set to 0.
        BIT24       Reserved1
    } with { variant "" }

    // flags can be accessed via bits or value
    type union QueryMsgFlags {
        QueryMsgFlagsBits   bits,
        int32               bytes
    } with { variant "FIELDLENGTH(32), COMP(signbit), BYTEORDER(first)" };

    // message structure
    type record QueryMsg
    {
        MsgHeader       header,                         // standard message header
        QueryMsgFlags   flags,                          // bit vector of query options.
        cstring         fullCollectionName,             // "dbname.collectionname"
        int32           numberToSkip,                   // number of documents to skip
        int32           numberToReturn,                 // number of documents to return in the first OP_REPLY batch
        octetstring     query,                          // BSON document that represents the query
        octetstring     returnFieldsSelector optional   // BSON document that limits the fields in the returned documents.
    } with {
        variant "TAG (header, opCode = OP_QUERY)";
        variant (header) "LENGTHTO(header, flags, fullCollectionName, numberToSkip, numberToReturn, query, returnFieldsSelector)";
        variant (header) "LENGTHINDEX(messageLength)"
    }


    // ------------------------------------------------------------------------------
    // mongoDB get more message,
    // ------------------------------------------------------------------------------

    // message structure
    type record GetMoreMsg
    {
        MsgHeader       header,             // standard message header
        int32           ZERO,               // 0 - reserved for future use
        cstring         fullCollectionName, // "dbname.collectionname"
        int32           numberToReturn,     // number of documents to return
        int64           cursorID            // cursor id from OP_REPLY
    } with {
        variant "TAG (header, opCode = OP_GET_MORE)";
        variant (header) "LENGTHTO(header, ZERO, fullCollectionName, numberToReturn, cursorID)";
        variant (header) "LENGTHINDEX(messageLength)"
    }


    // ------------------------------------------------------------------------------
    // mongoDB delete message,
    // ------------------------------------------------------------------------------

    // flags: definitions of bits
    type record DeleteMsgFlagsBits {
        // If set, the database will remove only the first matching document in the collection.
        // Otherwise all matching documents will be removed.
        BIT1        SingleRemove,

        // 1-31 bits are reserved. Must be set to 0.
        BIT31       Reserved1
    } with { variant "" }

    // flags can be accessed via bits or value
    type union DeleteMsgFlags {
        DeleteMsgFlagsBits   bits,
        int32                bytes
    } with { variant "FIELDLENGTH(32), COMP(signbit), BYTEORDER(first)" };

    // message structure
    type record DeleteMsg
    {
        MsgHeader       header,             // standard message header
        int32           ZERO,               // 0 - reserved for future use
        cstring         fullCollectionName, // "dbname.collectionname"
        DeleteMsgFlags  flags,              // bit vector of delete options.
        octetstring     selector            // BSON document that represent the query used to select the documents to be removed
    } with {
        variant "TAG (header, opCode = OP_DELETE)";
        variant (header) "LENGTHTO(header, ZERO, fullCollectionName, flags, selector)";
        variant (header) "LENGTHINDEX(messageLength)"
    }


    // ------------------------------------------------------------------------------
    // mongoDB kill cursor message
    // ------------------------------------------------------------------------------

    // message structure
    type record KillCursorMsg
    {
        MsgHeader       header,             // standard message header
        int32           ZERO,               // 0 - reserved for future use
        int32           numberOfCursorIDs,  // number of cursorIDs in message
        roInt64         cursorIDs           // sequence of cursorIDs
    } with {
        variant "TAG (header, opCode = OP_KILL_CURSORS)";
        variant (header) "LENGTHTO(header, ZERO, numberOfCursorIDs, cursorIDs)";
        variant (header) "LENGTHINDEX(messageLength)"
    }


    // ------------------------------------------------------------------------------
    // mongoDB command message,
    // ------------------------------------------------------------------------------

    // command message structure
    type record CommandMsg
    {
       MsgHeader   header,             // standard message header
       cstring     database,
       cstring     commandName,
       octetstring metadata,
       octetstring commandArgs,
       octetstring inputDocs optional
    }
    with {
       variant "TAG (header, opCode = OP_COMMAND)";
       variant (header) "LENGTHTO(header, database, commandName, metadata, commandArgs, inputDocs)";
       variant (header) "LENGTHINDEX(messageLength)"
    }


    // ==============================================================================
    //
    // mongoDB response messages
    //
    // ==============================================================================


    // ------------------------------------------------------------------------------
    // mongoDB reply message,
    // ------------------------------------------------------------------------------

    // flags: definitions of bits
    type record ReplyMsgFlagsBits {
        // Is set when getMore is called but the cursor id is not valid at the server. Returned with zero results.
        BIT1        CursorNotFound,

        // Is set when query failed. Results consist of one document containing an “$err” field describing the failure.
        BIT1        QueryFailure,

        // Drivers should ignore this. Only mongos will ever see this set, in which case, it needs to update config from the server.
        BIT1        ShardConfigStale,

        // Is set when the server supports the AwaitData Query option. If it doesn’t, a client should sleep a little
        // between getMore’s of a Tailable cursor. Mongod version 1.6 supports AwaitData and thus always sets AwaitCapable.
        BIT1        AwaitCapable,

        // 4-31 bits are reserved. Ignore.
        BIT28       Reserved
    } with { variant "" }

    // flags can be accessed via bits or value
    type union ReplyMsgFlags {
        ReplyMsgFlagsBits   bits,
        int32               bytes
    } with { variant "FIELDLENGTH(32), COMP(signbit), BYTEORDER(first)" };

    type union ReplyMsgDocuments {
        octetstring             octets,
        JSONRecords             json
    } with { variant "" };

    // command message structure
    type record ReplyMsg
    {
        MsgHeader           header,             // standard message header
        ReplyMsgFlags       responseFlags,      // bit vector - see details below
        int64               cursorID,           // cursor id if client needs to do get more's
        int32               startingFrom,       // where in the cursor this reply is starting
        int32               numberReturned,     // number of documents in the reply
        ReplyMsgDocuments   documents           // documents
    } with {
        variant "TAG (header, opCode = OP_REPLY)";
    }

    // ------------------------------------------------------------------------------
    // mongoDB command reply message
    // ------------------------------------------------------------------------------
    type record CommandReplyMsg
    {
        MsgHeader   header,             // standard message header
        octetstring metadata,           // A BSON document containing any required metadata
        octetstring commandArgs,        // A BSON document containing the command reply
        octetstring inputDocs optional  // A variable number of BSON documents
    }
    with { variant "" }

    // ==============================================================================
    //
    // Generic mongoDB message definitions
    //
    // ==============================================================================

    // ------------------------------------------------------------------------------
    // generic mongoDB message (union of all message types)
    // ------------------------------------------------------------------------------
    type union Msg {
        InsertMsg       insert,
        UpdateMsg       update,
        QueryMsg        query,
        GetMoreMsg      getMore,
        DeleteMsg       delete,
        KillCursorMsg   killCursor,
        CommandMsg      command,
        ReplyMsg        reply_,
        CommandReplyMsg commandReply,
        octetstring     octects
    } with {
        variant (insert)        "TAG (header, opCode = OP_INSERT)";
        variant (update)        "TAG (header, opCode = OP_UPDATE)";
        variant (query)         "TAG (header, opCode = OP_QUERY)";
        variant (getMore)       "TAG (header, opCode = OP_GET_MORE)";
        variant (delete)        "TAG (header, opCode = OP_DELETE)";
        variant (killCursor)    "TAG (header, opCode = OP_KILL_CURSORS)";
        variant (command)       "TAG (header, opCode = OP_COMMAND)";
        variant (reply_)        "TAG (header, opCode = OP_REPLY)";
        variant (commandReply)  "TAG (header, opCode = OP_COMMANDREPLY)";
    }

    // ------------------------------------------------------------------------------
    // generic encode and decode function for generic message type
    // ------------------------------------------------------------------------------
    external function encMsg (in Msg msg) return octetstring
    with { extension "prototype(convert) encode(RAW)" }

    external function decMsg (in octetstring octets) return Msg
    with { extension "prototype(convert) decode(RAW)" }

} with { encode "RAW" }