path: root/src/mongo-sync.h

/* mongo-sync.h - libmongo-client synchronous wrapper API
 * Copyright 2011, 2012, 2013, 2014 Gergely Nagy <algernon@balabit.hu>
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/** @file src/mongo-sync.h
 * MongoDB synchronous wrapper API public header.
 */

#ifndef LIBMONGO_SYNC_H
#define LIBMONGO_SYNC_H 1

#include <mongo-client.h>

#include <glib.h>

G_BEGIN_DECLS

/** Default maximum size for a single bulk insert.
 *
 * Defaults to somewhat shy of 4Mb.
 */
#define MONGO_SYNC_DEFAULT_MAX_INSERT_SIZE 4 * 1000 * 1000

/** @defgroup mongo_sync Mongo Sync API
 *
 * These commands provide wrappers for the most often used MongoDB
 * commands. All of these will send the command, and receive any
 * results, thus saving the caller from having to do that himself.
 *
 * However, these are only of use when blocking the application is not
 * an issue. For asynchronous operation, one should still construct
 * the packets himself, and send / receive when appropriate.
 *
 * @addtogroup mongo_sync
 * @{
 */

/** Opaque synchronous connection object. */
typedef struct _mongo_sync_connection mongo_sync_connection;

/** synchronous connection recovery cache object */
typedef struct _mongo_sync_conn_recovery_cache mongo_sync_conn_recovery_cache;

/** Create a new connection recovery cache object.
 *
 * @return the newly created recovery cache object
 */
mongo_sync_conn_recovery_cache *mongo_sync_conn_recovery_cache_new (void);

/** Free a connection recovery cache object.
 *
 * @param cache is the recovery cache object
 */
void mongo_sync_conn_recovery_cache_free (mongo_sync_conn_recovery_cache *cache);

/** Discards a connection recovery cache object.
 *
 * @param cache is the recovery cache object
 */
void mongo_sync_conn_recovery_cache_discard (mongo_sync_conn_recovery_cache *cache);

/** Add a seed to a connection recovery cache object.
 *
 * The seed list will be used for reconnects, prioritized before the
 * automatically discovered host list.
 *
 * @param cache is the connection recovery cache to add a seed to.
 * @param host is the seed host to add.
 * @param port is the seed's port.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_conn_recovery_cache_seed_add (mongo_sync_conn_recovery_cache *cache,
                                                  const gchar *host, gint port);

/** Synchronously connect to a MongoDB server using an external
 *  connection recovery cache object.
 *
 * Sets up a synchronous connection to a MongoDB server.
 *
 * @param cache is the externally managed connection recovery cache object.
 * @param slaveok signals whether queries made against a slave are
 * acceptable.
 *
 * @returns A newly allocated mongo_sync_connection object, or NULL on
 * error. It is the responsibility of the caller to close and free the
 * connection when appropriate.
 */
mongo_sync_connection *mongo_sync_connect_recovery_cache (mongo_sync_conn_recovery_cache *cache,
                                                          gboolean slaveok);

/** Synchronously connect to a MongoDB server.
 *
 * Sets up a synchronous connection to a MongoDB server.
 *
 * @param address is the address of the server (IP or unix socket path).
 * @param port is the port to connect to, or #MONGO_CONN_LOCAL if
 * address is a unix socket.
 * @param slaveok signals whether queries made against a slave are
 * acceptable.
 *
 * @returns A newly allocated mongo_sync_connection object, or NULL on
 * error. It is the responsibility of the caller to close and free the
 * connection when appropriate.
 */
mongo_sync_connection *mongo_sync_connect (const gchar *address,
                                           gint port,
                                           gboolean slaveok);

/** Add a seed to an existing MongoDB connection.
 *
 * The seed list will be used for reconnects, prioritized before the
 * automatically discovered host list.
 *
 * @param conn is the connection to add a seed to.
 * @param host is the seed host to add.
 * @param port is the seed's port.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_conn_seed_add (mongo_sync_connection *conn,
                                   const gchar *host, gint port);

/** Attempt to connect to another member of a replica set.
 *
 * Given an existing connection, this function will try to connect to
 * an available node (enforcing that it's a primary, if asked to) by
 * trying all known hosts until it finds one available.
 *
 * @param conn is an existing MongoDB connection.
 * @param force_master signals whether a primary node should be found.
 *
 * @returns A mongo_sync_collection object, or NULL if the reconnect fails
 * for one reason or the other.
 *
 * @note The original connection object will be updated too!
 */
mongo_sync_connection *mongo_sync_reconnect (mongo_sync_connection *conn,
                                             gboolean force_master);

/** Close and free a synchronous MongoDB connection.
 *
 * @param conn is the connection to close.
 *
 * @note The object will be freed, and shall not be used afterwards!
 */
void mongo_sync_disconnect (mongo_sync_connection *conn);

/** Retrieve the state of the SLAVE_OK flag from a sync connection.
 *
 * @param conn is the connection to check the flag on.
 *
 * @returns The state of the SLAVE_OK flag.
 */
gboolean mongo_sync_conn_get_slaveok (const mongo_sync_connection *conn);

/** Set the SLAVE_OK flag on a sync connection.
 *
 * @param conn is the connection to set the flag on.
 * @param slaveok is the state to set.
 *
 * @returns TRUE on sucess, FALSE otherwise.
 */
gboolean mongo_sync_conn_set_slaveok (mongo_sync_connection *conn,
                                      gboolean slaveok);

/** Retrieve the state of the safe mode flag from a sync connection.
 *
 * @param conn is the connection to check the flag on.
 *
 * @returns The state of the safe mode flag.
 */
gboolean mongo_sync_conn_get_safe_mode (const mongo_sync_connection *conn);

/** Set the safe mode flag on a sync connection.
 *
 * Enabling safe mode will result in an additional getLastError() call
 * after each insert or update, and extra checks performed on other
 * commands aswell.
 *
 * The upside is more guarantees that the commands succeed, at the
 * expense of network traffic and speed.
 *
 * @param conn is the connection to set the flag on.
 * @param safe_mode is the state to set it to.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_conn_set_safe_mode (mongo_sync_connection *conn,
                                        gboolean safe_mode);

/** Get the state of the auto-reconnect flag from a sync connection.
 *
 * @param conn is the connection to check the flag on.
 *
 * @returns The state of the auto-reconnect flag.
 */
gboolean mongo_sync_conn_get_auto_reconnect (const mongo_sync_connection *conn);

/** Set the state of the auto-reconnect flag on a sync connection.
 *
 * When auto-reconnect is enabled, the library will automatically
 * attempt to reconnect to a server behind the scenes, when it detects
 * an error.
 *
 * If safe-mode is turned on aswell, then auto-reconnect will only
 * happen if the error is detected before a command is sent towards
 * the database.
 *
 * @param conn is the connection to set auto-reconnect on.
 * @param auto_reconnect is the state to set it to.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_conn_set_auto_reconnect (mongo_sync_connection *conn,
                                             gboolean auto_reconnect);

/** Get the maximum size of a bulk insert package.
 *
 * @param conn is the connection to get the maximum size from.
 *
 * @returns The maximum size, or -1 on failiure.
 */
gint32 mongo_sync_conn_get_max_insert_size (mongo_sync_connection *conn);

/** Set the maximum size of a bulk insert package.
 *
 * When inserting multiple documents at a time, the library can
 * automatically split the pack up into smaller chunks. With this
 * function, one can set the maximum size, past which, the request
 * will be split into smaller chunks.
 *
 * @param conn is the connection to set the maximum size for.
 * @param max_size is the maximum size, in bytes.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_conn_set_max_insert_size (mongo_sync_connection *conn,
                                              gint32 max_size);

/** Send an update command to MongoDB.
 *
 * Constructs and sends an update command to MongoDB.
 *
 * @param conn is the connection to work with.
 * @param ns is the namespace to work in.
 * @param flags are the flags for the update command. See
 * mongo_wire_cmd_update().
 * @param selector is the BSON document that will act as the selector.
 * @param update is the BSON document that contains the updated
 * values.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_update (mongo_sync_connection *conn,
                                const gchar *ns,
                                gint32 flags, const bson *selector,
                                const bson *update);

/** Send an insert command to MongoDB.
 *
 * Constructs and sends an insert command to MongodB.
 *
 * @param conn is the connection to work with.
 * @param ns is the namespace to work in.
 * @tparam docs are the documents to insert. One must close the list
 * with a NULL value.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_insert (mongo_sync_connection *conn,
                                const gchar *ns, ...) G_GNUC_NULL_TERMINATED;


/** Send an insert command to MongoDB.
 *
 * Constructs and sends an insert command to MongodB.
 *
 * @param conn is the connection to work with.
 * @param ns is the namespace to work in.
 * @param n is the number of documents to insert.
 * @param docs is the array the documents to insert. There must be at
 * least @a n documents in the array.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_insert_n (mongo_sync_connection *conn,
                                  const gchar *ns, gint32 n,
                                  const bson **docs);

/** Send a query command to MongoDB.
 *
 * @param conn is the connection to work with.
 * @param ns is the namespace, the database and collection name
 * concatenated, and separated with a single dot.
 * @param flags are the query options. See mongo_wire_cmd_query().
 * @param skip is the number of documents to skip.
 * @param ret is the number of documents to return.
 * @param query is the query BSON object.
 * @param sel is the (optional) selector BSON object indicating the
 * fields to return. Passing NULL will return all fields.
 *
 * @returns A newly allocated reply packet, or NULL on error. It is the
 * responsibility of the caller to free the packet once it is not used
 * anymore.
 */
mongo_packet *mongo_sync_cmd_query (mongo_sync_connection *conn,
                                    const gchar *ns, gint32 flags,
                                    gint32 skip, gint32 ret, const bson *query,
                                    const bson *sel);

/** Send a get more command to MongoDB.
 *
 * @param conn is the connection to work with.
 * @param ns is the namespace, the database and collection name
 * concatenated, and separated with a single dot.
 * @param ret is the number of documents to return.
 * @param cursor_id is the ID of the cursor to use.
 *
 * @returns A newly allocated reply packet, or NULL on error. It is
 * the responsibility of the caller to free the packet once it is not
 * used anymore.
 */
mongo_packet *mongo_sync_cmd_get_more (mongo_sync_connection *conn,
                                       const gchar *ns,
                                       gint32 ret, gint64 cursor_id);

/** Send a delete command to MongoDB.
 *
 * @param conn is the connection to work with.
 * @param ns is the namespace, the database and collection name
 * concatenated, and separated with a single dot.
 * @param flags are the delete options. See mongo_wire_cmd_delete().
 * @param sel is the BSON object to use as a selector.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_delete (mongo_sync_connection *conn, const gchar *ns,
                                gint32 flags, const bson *sel);

/** Send a kill_cursors command to MongoDB.
 *
 * @param conn is the connection to work with.
 * @param n is the number of cursors to kill.
 * @tparam cursor_ids is the list of cursor ids to kill.
 *
 * @note One must supply exaclty @a n number of cursor IDs.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_kill_cursors (mongo_sync_connection *conn,
                                      gint32 n, ...);

/** Send a custom command to MongoDB.
 *
 * Custom commands are queries run in the db.$cmd namespace. The
 * commands themselves are queries, and as such, BSON objects.
 *
 * @param conn is the connection to work with.
 * @param db is the database in which the command shall be run.
 * @param command is the BSON object representing the command.
 *
 * @returns A newly allocated reply packet, or NULL on error. It is
 * the responsibility of the caller to free the packet once it is not
 * used anymore.
 */
mongo_packet *mongo_sync_cmd_custom (mongo_sync_connection *conn,
                                     const gchar *db,
                                     const bson *command);

/** Send a count() command to MongoDB.
 *
 * The count command is an efficient way to count tha available
 * documents matching a selector.
 *
 * @param conn is the connection to work with.
 * @param db is the name of the database.
 * @param coll is the name of the collection.
 * @param query is the optional selector (NULL will count all
 * documents within the collection).
 *
 * @returns The number of matching documents, or -1 on error.
 */
gdouble mongo_sync_cmd_count (mongo_sync_connection *conn,
                              const gchar *db, const gchar *coll,
                              const bson *query);

/** Flags that can be set during collection creation. */
enum
  {
    /** Default options. */
    MONGO_COLLECTION_DEFAULTS = 0,
    /** The collection is capped. */
    MONGO_COLLECTION_CAPPED = 1 << 0,
    /** The collection is capped by element number aswell. */
    MONGO_COLLECTION_CAPPED_MAX = 1 << 1,
    /** The collection's _id should be autoindexed. */
    MONGO_COLLECTION_AUTO_INDEX_ID = 1 << 2,
    /** The collection needs to be pre-allocated. */
    MONGO_COLLECTION_SIZED = 1 << 3
  };

/** Create a new MongoDB collection.
 *
 * This command can be used to explicitly create a MongoDB collection,
 * with various parameters pre-set.
 *
 * @param conn is the connection to work with.
 * @param db is the name of the database.
 * @param coll is the name of the collection to create.
 * @param flags is a collection of flags for the collection.  Any
 * combination of MONGO_COLLECTION_DEFAULTS, MONGO_COLLECTION_CAPPED,
 * MONGO_COLLECTION_CAPPED_MAX, MONGO_COLLECTION_SIZED and
 * MONGO_COLLECTION_AUTO_INDEX_ID is acceptable.
 *
 * @tparam size @b MUST be a 64-bit integer, if
 * MONGO_COLLECTION_CAPPED or MONGO_COLLECTION_SIZED is specified, and
 * it must follow the @a flags parameter.
 * @tparam max @b MUST be a 64-bit integer, if
 * MONGO_COLLECTION_CAPPED_MAX is specified, and must follow @a size.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_create (mongo_sync_connection *conn,
                                const gchar *db, const gchar *coll,
                                gint flags, ...);

/** Check whether a collection exists in MongoDB.
 *
 * @param conn is the connection to work with.
 * @param db is the database to search for the collection.
 * @param coll is the collection to search for.
 *
 * @returns A newly allocated BSON object, with data about the
 * collection on success, NULL otherwise. It is the responsiblity of
 * the caller to free the BSON object once it is no longer needed.
 */
bson *mongo_sync_cmd_exists (mongo_sync_connection *conn,
                             const gchar *db, const gchar *coll);

/** Send a drop() command to MongoDB.
 *
 * With this command, one can easily drop a collection.
 *
 * @param conn is the connection to work with.
 * @param db is the name of the database.
 * @param coll is the name of the collection to drop.
 *
 * @returns TRUE if the collection was dropped, FALSE otherwise.
 */
gboolean mongo_sync_cmd_drop (mongo_sync_connection *conn,
                              const gchar *db, const gchar *coll);

/** Get the last error from MongoDB.
 *
 * Retrieves the last error from MongoDB.
 *
 * @param conn is the connection to work with.
 * @param db is the name of the database.
 * @param error is a pointer to a string variable that will hold the
 * error message.
 *
 * @returns TRUE if the error was succesfully retrieved, FALSE
 * otherwise. The output variable @a error is only set if the function
 * is returning TRUE.
 */
gboolean mongo_sync_cmd_get_last_error (mongo_sync_connection *conn,
                                        const gchar *db, gchar **error);

/** Get the last error from MongoDB.
 *
 * Retrieves the last error from MongoDB.
 *
 * @param conn is the connection to work with.
 * @param db is the name of the database.
 * @param error is a pointer to a BSON variable that will hold the
 * error message.
 *
 * @returns TRUE if the error was succesfully retrieved, FALSE
 * otherwise. The output variable @a error is only set if the function
 * is returning TRUE.
 */
gboolean mongo_sync_cmd_get_last_error_full (mongo_sync_connection *conn,
                                             const gchar *db, bson **error);

/** Reset the last error variable in MongoDB.
 *
 * @param conn is the connection to work with.
 * @param db is the name of the database.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_reset_error (mongo_sync_connection *conn,
                                     const gchar *db);

/** Check whether the current node is the master.
 *
 * @param conn is the connection to work with.
 *
 * @returns TRUE if it is master, FALSE otherwise and on errors.
 */
gboolean mongo_sync_cmd_is_master (mongo_sync_connection *conn);

/** Send a PING command to MongoDB.
 *
 * @param conn is the connection to work with.
 *
 * @returns TRUE if the connection is alive and kicking, FALSE
 * otherwise.
 */
gboolean mongo_sync_cmd_ping (mongo_sync_connection *conn);

/** Add a user to MongoDB.
 *
 * @param conn is the connection to work with.
 * @param db is the database to add the user to.
 * @param user is the user to add.
 * @param pw is the password.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_user_add (mongo_sync_connection *conn,
                                  const gchar *db,
                                  const gchar *user,
                                  const gchar *pw);

/** Add a user to MongoDB, with roles.
 *
 * @param conn is the connection to work with.
 * @param db is the database to add the user to.
 * @param user is the user to add.
 * @param pw is the password.
 * @param roles is a BSON array containing the roles for the user.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_user_add_with_roles (mongo_sync_connection *conn,
                                             const gchar *db,
                                             const gchar *user,
                                             const gchar *pw,
                                             const bson *roles);

/** Remove a user from MongoDB.
 *
 * @param conn is the connection to work with.
 * @param db is the database to remove the user from.
 * @param user is the username to remove.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_user_remove (mongo_sync_connection *conn,
                                     const gchar *db,
                                     const gchar *user);

/** Authenticate a user with MongoDB.
 *
 * @param conn is the connection to work with.
 * @param db is the database to authenticate against.
 * @param user is the username.
 * @param pw is the password.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_authenticate (mongo_sync_connection *conn,
                                      const gchar *db,
                                      const gchar *user,
                                      const gchar *pw);

/** Flags that can be set at index creation. */
enum
  {
    MONGO_INDEX_UNIQUE = 0x01, /**< Create a unique index. */
    MONGO_INDEX_DROP_DUPS = 0x02, /**< Drop duplicate entries when
                                     creating the indexes. */
    MONGO_INDEX_BACKGROUND = 0x04, /**< Create indexes in the
                                      background. */
    MONGO_INDEX_SPARSE = 0x08 /**< Create sparse indexes. */
  };

/** Create an index.
 *
 * @param conn is the connection to work with.
 * @param ns is the namespace to create indexes for.
 * @param key is the key pattern to base indexes on.
 * @param options are the index options.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_index_create (mongo_sync_connection *conn,
                                      const gchar *ns,
                                      const bson *key,
                                      gint options);

/** Drop an index.
 *
 * @param conn is the connection to work with.
 * @param ns is the namespace to drop the index from.
 * @param key is the index pattern to drop.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_index_drop (mongo_sync_connection *conn,
                                    const gchar *ns,
                                    const bson *key);

/** Drop all indexes from a namespace.
 *
 * @param conn is the connection to work with.
 * @param ns is the namespace whose indexes to drop.
 *
 * @returns TRUE on success, FALSE otherwise.
 */
gboolean mongo_sync_cmd_index_drop_all (mongo_sync_connection *conn,
                                        const gchar *ns);

/** Get the last error message on a connection
 *
 * @param conn is the connection
 *
 * @returns pointer to the error message, if exists, NULL otherwise
 */
const gchar *mongo_sync_conn_get_last_error (mongo_sync_connection *conn);

/** @} */

G_END_DECLS

#endif