#pragma once
/*
 * Copyright (c) 2016 MariaDB Corporation Ab
 *
 * Use of this software is governed by the Business Source License included
 * in the LICENSE.TXT file and at www.mariadb.com/bsl11.
 *
 * Change Date: 2020-01-01
 *
 * On the date above, in accordance with the Business Source License, use
 * of this software will be governed by version 2 or later of the General
 * Public License.
 */

/**
 * @file include/maxscale/filter.h - The public filter interface
 */

#include <maxscale/cdefs.h>
#include <stdint.h>
#include <maxscale/buffer.h>
#include <maxscale/config.h>
#include <maxscale/dcb.h>
#include <maxscale/routing.h>
#include <maxscale/session.h>
#include <maxscale/jansson.h>

MXS_BEGIN_DECLS

/**
 * MXS_FILTER is an opaque type representing a particular filter instance.
 *
 * MaxScale itself does not do anything with it, except for receiving it
 * from the @c createInstance function of a filter module and subsequently
 * passing it back to the API functions of the filter.
 */
typedef struct mxs_filter
{
} MXS_FILTER;

/**
 * MXS_FILTER_SESSION is an opaque type representing the session related
 * data of a particular filter instance.
 *
 * MaxScale itself does not do anything with it, except for receiving it
 * from the @c newSession function of a filter module and subsequently
 * passing it back to the API functions of the filter.
 */
typedef struct mxs_filter_session
{
} MXS_FILTER_SESSION;

/**
 * @verbatim
 * The "module object" structure for a filter module. All entry points
 * marked with `(optional)` are optional entry points which can be set to NULL
 * if no implementation is required.
 *
 * The entry points are:
 *      createInstance   Called by the service to create a new instance of the filter
 *      newSession       Called to create a new user session within the filter
 *      closeSession     Called when a session is closed
 *      freeSession      Called when a session is freed
 *      setDownstream    Sets the downstream component of the filter pipline
 *      setUpstream      Sets the upstream component of the filter pipline
 *      routeQuery       Called on each query that requires routing
 *      clientReply      Called for each reply packet (optional)
 *      diagnostics      Called for diagnostic output
 *      getCapabilities  Called to obtain the capabilities of the filter (optional)
 *      destroyInstance  Called for destroying a filter instance (optional)
 *
 * @endverbatim
 *
 * @see load_module
 */
typedef struct mxs_filter_object
{

    /**
     * @brief Create a new instance of the filter
     *
     * This function is called when a new filter instance is created. The return
     * value of this function will be passed as the first parameter to the
     * other API functions.
     *
     * @param name    Name of the filter instance
     * @param options Filter options
     * @param params  Filter parameters
     *
     * @return New filter instance on NULL on error
     */
    MXS_FILTER *(*createInstance)(const char *name, char **options, MXS_CONFIG_PARAMETER *params);

    /**
     * Called to create a new user session within the filter
     *
     * This function is called when a new filter session is created for a client.
     * The return value of this function will be passed as the second parameter
     * to the @c routeQuery, @c clientReply, @c closeSession, @c freeSession,
     * @c setDownstream and @c setUpstream functions.
     *
     * @param instance Filter instance
     * @param session Client MXS_SESSION object
     *
     * @return New filter session or NULL on error
     */
    MXS_FILTER_SESSION *(*newSession)(MXS_FILTER *instance, MXS_SESSION *session);

    /**
     * @brief Called when a session is closed
     *
     * The filter should close all objects but not free any memory.
     *
     * @param instance Filter instance
     * @param fsession Filter session
     */
    void     (*closeSession)(MXS_FILTER *instance, MXS_FILTER_SESSION *fsession);

    /**
     * @brief Called when a session is freed
     *
     * The session should free all allocated memory in this function.
     *
     * @param instance Filter instance
     * @param fsession Filter session
     */
    void     (*freeSession)(MXS_FILTER *instance, MXS_FILTER_SESSION *fsession);

    /**
     * @brief Sets the downstream component of the filter pipeline
     *
     * @param instance Filter instance
     * @param fsession Filter session
     */
    void     (*setDownstream)(MXS_FILTER *instance, MXS_FILTER_SESSION *fsession, MXS_DOWNSTREAM *downstream);

    /**
     * @brief Sets the upstream component of the filter pipeline
     *
     * @param instance Filter instance
     * @param fsession Filter session
     */
    void     (*setUpstream)(MXS_FILTER *instance, MXS_FILTER_SESSION *fsession, MXS_UPSTREAM *downstream);

    /**
     * @brief Called on each query that requires routing
     *
     * TODO: Document how routeQuery should be used
     *
     * @param instance Filter instance
     * @param fsession Filter session
     * @param queue    Request from the client
     *
     * @return If successful, the function returns 1. If an error occurs
     * and the session should be closed, the function returns 0.
     */
    int32_t  (*routeQuery)(MXS_FILTER *instance, MXS_FILTER_SESSION *fsession, GWBUF *queue);

    /**
     * @brief Called for each reply packet
     *
     * TODO: Document how clientReply should be used
     *
     * @param instance Filter instance
     * @param fsession Filter session
     * @param queue    Response from the server
     *
     * @return If successful, the function returns 1. If an error occurs
     * and the session should be closed, the function returns 0.
     */
    int32_t  (*clientReply)(MXS_FILTER *instance, MXS_FILTER_SESSION *fsession, GWBUF *queue);

    /**
     * @brief Called for diagnostic output
     *
     * @param instance Filter instance
     * @param fsession Filter session, NULL if general information about the filter is queried
     * @param dcb      DCB where the diagnostic information should be written
     */
    void     (*diagnostics)(MXS_FILTER *instance, MXS_FILTER_SESSION *fsession, DCB *dcb);

    /**
     * @brief Called for diagnostic output
     *
     * @param instance Filter instance
     * @param fsession Filter session, NULL if general information about the filter is queried
     *
     * @return JSON formatted information about the filter
     *
     * @see jansson.h
     */
    json_t* (*diagnostics_json)(const MXS_FILTER *instance, const MXS_FILTER_SESSION *fsession);

    /**
     * @brief Called to obtain the capabilities of the filter
     *
     * @return Zero or more bitwise-or'd values from the mxs_routing_capability_t enum
     *
     * @see routing.h
     */
    uint64_t (*getCapabilities)(MXS_FILTER *instance);

    /**
     * @brief Called for destroying a filter instance
     *
     * @param instance Filter instance
     */
    void     (*destroyInstance)(MXS_FILTER *instance);

} MXS_FILTER_OBJECT;

/**
 * The filter API version. If the MXS_FILTER_OBJECT structure or the filter API
 * is changed these values must be updated in line with the rules in the
 * file modinfo.h.
 */
#define MXS_FILTER_VERSION  {3, 0, 0}

/**
 * MXS_FILTER_DEF represents a filter definition from the configuration file.
 * Its exact definition is private to MaxScale.
 */
struct mxs_filter_def;
typedef struct mxs_filter_def MXS_FILTER_DEF;

/**
 * Lookup a filter definition using the unique section name in
 * the configuration file.
 *
 * @param name The name of a filter.
 *
 * @return A filter definition or NULL if not found.
 */
MXS_FILTER_DEF *filter_def_find(const char *name);

/**
 * Get the name of a filter definition. This corresponds to
 * to a filter section in the configuration file.
 *
 * @param filter_def  A filter definition.
 *
 * @return The filter name.
 */
const char* filter_def_get_name(const MXS_FILTER_DEF* filter_def);

/**
 * Get module name of a filter definition.
 *
 * @param filter_def  A filter definition.
 *
 * @return The module name.
 */
const char* filter_def_get_module_name(const MXS_FILTER_DEF* filter_def);

/**
 * Get the filter instance of a particular filter definition.
 *
 * @return A filter instance.
 */
MXS_FILTER* filter_def_get_instance(const MXS_FILTER_DEF* filter_def);

/**
 * @brief Convert a filter to JSON
 *
 * @param filter Filter to convert
 * @param host Hostname of this server
 *
 * @return Filter converted to JSON format
 */
json_t* filter_to_json(const MXS_FILTER_DEF* filter, const char* host);

/**
 * @brief Convert all filters into JSON
 *
 * @param host Hostname of this server
 *
 * @return A JSON array containing all filters
 */
json_t* filter_list_to_json(const char* host);

void dprintAllFilters(DCB *);
void dprintFilter(DCB *, const MXS_FILTER_DEF *);
void dListFilters(DCB *);

/**
 * Specifies capabilities specific for filters. Common capabilities
 * are defined by @c routing_capability_t.
 *
 * @see enum routing_capability
 *
 * @note The values of the capabilities here *must* be between 0x80000000
 *       and 0x01000000, that is, bits 24 to 31.
 */

typedef enum filter_capability
{
    FCAP_TYPE_NONE = 0x0 // TODO: remove once filter capabilities are defined
} filter_capability_t;

MXS_END_DECLS
