mt-libcouchbase 1.4.0

data/ext/libcouchbase/src/bucketconfig/clconfig.h

@@ -0,0 +1,700 @@
+/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2013 Couchbase, Inc.
+ *
+ *   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.
+ */
+
+#ifndef LCB_CLCONFIG_H
+#define LCB_CLCONFIG_H
+
+#include "hostlist.h"
+#include <list>
+#include <lcbio/timer-ng.h>
+#include <lcbio/timer-cxx.h>
+
+/** @file */
+
+/**
+ * @defgroup lcb-confmon Cluster Configuration Management
+ *
+ * @brief Monitors the retrieval and application of new cluster topology maps
+ * (vBucket Configurations)
+ *
+ * @details
+ * This module attempts to implement the 'Configuration Provider' interface
+ * described at https://docs.google.com/document/d/1bSMt0Sj1uQtm0OYolQaJDJg4sASfoCEwU6_gjm1he8s/edit
+ *
+ * The model is fairly complex though significantly more maintainable and
+ * testable than the previous model. The basic idea is as follows:
+ *
+ *
+ * <ol>
+ *
+ * <li>
+ * There is a _Configuration Monitor_ object (Confmon) which acts
+ * as the configuration supervisor. It is responsible for returning
+ * configuration objects to those entities which request it.
+ * </li>
+ *
+ * <li>
+ * There are multiple _Configuration Provider_ (Provider) objects.
+ * These providers aggregate configurations from multiple sources and
+ * implement a common interface to:
+ *
+ *  <ol>
+ *  <li>Return a _quick_ configuration without fetching from network or disk
+ *  (see Provider::get_cached())</i>
+
+ *  <li>Schedule a refresh to retrieve the latest configuration from the
+ *  network (see Provider::refresh())</li>
+ *
+ *  <li>Notify the monitor that it has received a new configuration. The
+ *  monitor itself will determine whether or not to accept the new
+ *  configuration by examining the configuration and determining if it is more
+ *  recent than the one currently in used. See lcb_confmon_set_next()</li>
+ *  </ol></li>
+ *
+ * <li>
+ * _Configuration Info_ objects. These objects are refcounted wrappers
+ * around vbucket configuration handles. They have a refcount and also an
+ * integer which can be used to compare with other objects for 'freshness'.
+ * See ConfigInfo
+ * </li>
+ *
+ * <li>
+ * _Configuration Listeners_. These are registered with the global supervisor
+ * and are invoked whenever a new valid configuration is detected. This is
+ * really only ever used during bootstrap or testing where we are explicitly
+ * waiting for a configuration without having any actual commands to schedule.
+ * See Listener
+ * </li>
+ * </ol>
+ */
+
+/**
+ *@addtogroup lcb-confmon
+ *@{
+ */
+
+namespace lcb {
+namespace clconfig {
+
+/**
+ * @brief Enumeration of the various config providers available.
+ * The type of methods available. These are enumerated in order of preference
+ */
+enum Method {
+    /** File-based "configcache" provider. Implemented in bc_file.c */
+    CLCONFIG_FILE,
+    /** New-style config-over-memcached provider. Implemented in bc_cccp.c */
+    CLCONFIG_CCCP,
+    /** Old-style streaming HTTP provider. Implemented in bc_http.c */
+    CLCONFIG_HTTP,
+    /** Raw memcached provided */
+    CLCONFIG_MCRAW,
+    /** Cluster administration provider. Static config with services */
+    CLCONFIG_CLADMIN,
+
+    CLCONFIG_MAX,
+
+    /** Ephemeral source, used for tests */
+    CLCONFIG_PHONY
+};
+
+
+/** Event types propagated to listeners */
+enum EventType {
+    /** Called when a new configuration is being set in confmon */
+    CLCONFIG_EVENT_GOT_NEW_CONFIG,
+
+    /** Called when _any_ configuration is received via set_enxt */
+    CLCONFIG_EVENT_GOT_ANY_CONFIG,
+
+    /** Called when all providers have been tried */
+    CLCONFIG_EVENT_PROVIDERS_CYCLED,
+
+    /** The monitor has stopped */
+    CLCONFIG_EVENT_MONITOR_STOPPED
+};
+
+
+/** @brief Possible confmon states */
+enum State {
+    /** The monitor is idle and not requesting a new configuration */
+    CONFMON_S_INACTIVE = 0,
+
+    /** The monitor is actively requesting a configuration */
+    CONFMON_S_ACTIVE = 1 << 0,
+
+    /** The monitor is fetching a configuration, but is in a throttle state */
+    CONFMON_S_ITERGRACE = 1 << 1
+};
+
+
+struct Provider;
+struct Listener;
+class ConfigInfo;
+
+/**
+ * This object contains the information needed for libcouchbase to deal with
+ * when retrieving new configs.
+ */
+struct Confmon {
+    /**
+     * @brief Create a new configuration monitor.
+     * This function creates a new `confmon` object which can be used to manage
+     * configurations and their providers.
+     *
+     * @param settings pointer to LCB settings
+     * @param iot pointer socket IO routines
+     * @param instance LCB handle
+     *
+     * Once the confmon object has been created you may enable or disable various
+     * providers (see lcb_confmon_set_provider_active()). Once no more providers
+     * remain to be activated you should call lcb_confmon_prepare() once. Then
+     * call the rest of the functions.
+     */
+    Confmon(lcb_settings* settings, lcbio_pTABLE iot, lcb_t instance);
+    void destroy() { delete this; }
+    ~Confmon();
+
+    /**
+     * Get the provider following the current provider, or NULL if this is
+     * the last provider in the list.
+     * @param cur The current provider.
+     * @return The next provider, or NULL if no more providers remain.
+     */
+    Provider *next_active(Provider *cur);
+
+    /**
+     * Gets the first active provider.
+     * @return the first provider, or NULL if no providers exist.
+     */
+    Provider *first_active();
+
+    /**
+     * Prepares the configuration monitor object for operations. This will insert
+     * all the enabled providers into a list. Call this function each time a
+     * provider has been enabled.
+     */
+    void prepare();
+
+    /**
+     * Set a given provider as being 'active'. This will activate the
+     * provider as well as call #prepare() to update the list.
+     * @param type The ID of the provider to activate
+     * @param enabled true for activate, false for deactivate
+     */
+    void set_active(Method type, bool enabled);
+
+    /**
+     * @brief Request a configuration refresh
+     *
+     * Start traversing the list of current providers, requesting a new
+     * configuration for each. This function will asynchronously loop through all
+     * providers until one provides a new configuration.
+     *
+     * You may call #stop() to asynchronously break out of the loop.
+     * If the confmon is already in a refreshing state
+     * (i.e. #is_refreshing()) returns true then this function does
+     * nothing.
+     *
+     * This function is reentrant safe and may be called at any time.
+     *
+     * @see lcb_confmon_add_listener()
+     * @see #stop()
+     * @see #is_refreshing()
+     */
+    void start();
+
+    /**
+     * @brief Cancel a pending configuration refresh.
+     *
+     * Stops the monitor. This will call Provider::pause() for each active
+     * provider. Typically called before destruction or when a new configuration
+     * has been found.
+     *
+     * This function is safe to call anywhere. If the monitor is already stopped
+     * then this function does nothing.
+     *
+     * @see #start()
+     * @see #is_refreshing()
+     */
+    void stop();
+
+    /**
+     * @brief Check if the monitor is waiting for a new config from a provider
+     * @return true if refreshing, false if idle
+     */
+    bool is_refreshing() const {
+        return (state & CONFMON_S_ACTIVE) != 0;
+    }
+
+    /**
+     * Get the current configuration
+     * @return The configuration
+     */
+    ConfigInfo* get_config() const {
+        return config;
+    }
+
+    /**
+     * Get the last error which occurred on this object
+     * @return The last error
+     */
+    lcb_error_t get_last_error() const {
+        return last_error;
+    }
+
+    /**
+     * @brief Get the current monitor state
+     * @return a set of flags consisting of @ref State values.
+     */
+    int get_state() const {
+        return state;
+    }
+
+    void stop_real();
+    void do_next_provider();
+    int do_set_next(ConfigInfo*, bool notify_miss);
+    void invoke_listeners(EventType, ConfigInfo*);
+
+    /**
+     * @brief Indicate that a provider has failed and advance the monitor
+     *
+     * Indicate that the current provider has failed to obtain a new configuration.
+     * This is always called by a provider and should be invoked when the provider
+     * has encountered an internal error which caused it to be unable to fetch
+     * the configuration.
+     *
+     * Note that this function is safe to call from any provider at any time. If
+     * the provider is not the current provider then it is treated as an async
+     * push notification failure and ignored. This function is _not_ safe to call
+     * from consumers of providers
+     *
+     * Once this is called, the confmon instance will either roll over to the next
+     * provider or enter the inactive state depending on the configuration and
+     * whether the current provider is the last provider in the list.
+     *
+     * @param which reference to provider, which has been failed
+     * @param why error code
+     */
+    void provider_failed(Provider *which, lcb_error_t why);
+
+    /**
+     * @brief Indicate that a provider has successfuly retrieved a configuration.
+     *
+     * Indicates that the provider has fetched a new configuration from the network
+     * and that confmon should attempt to propagate it. It has similar semantics
+     * to lcb_confmon_provider_failed() except that the second argument is a config
+     * object rather than an error code. The second argument must not be `NULL`
+     *
+     * The monitor will compare the new config against the current config.
+     * If the new config does not feature any changes from the current config then
+     * it is ignored and the confmon instance will proceed to the next provider.
+     * This is done through a direct call to provider_failed(provider, LCB_SUCCESS).
+     *
+     * This function should _not_ be called outside of an asynchronous provider's
+     * handler.
+     *
+     * @param which the provider which yielded the new configuration
+     * @param config the new configuration
+     */
+    void provider_got_config(Provider *which, ConfigInfo* config);
+
+    /**
+     * Dump information about the monitor
+     * @param fp the file to which information should be written
+     */
+    void dump(FILE *fp);
+
+    Provider* get_provider(Method m) const {
+        return all_providers[m];
+    }
+
+    /**
+     * @brief Register a listener to be invoked on state changes and events
+     *
+     * Adds a 'listener' object to be called at each configuration update. The
+     * listener may co-exist with other listeners (though it should never be added
+     * twice). When a new configuration is received and accept, the listener's
+     * Listener::callback field will be invoked with it.
+     *
+     * The callback will continue to be invoked for each new configuration received
+     * until remove_listener is called. Note that the listener is not allocated
+     * by the confmon and its responsibility is the user's
+     *
+     * @param lsn the listener. The listener's contents are not copied into
+     * confmon and should thus remain valid until it is removed
+     */
+    void add_listener(Listener* lsn);
+
+    /**
+     * @brief Unregister (and remove) a listener added via lcb_confmon_add_listener()
+     * @param lsn the listener
+     */
+    void remove_listener(Listener *lsn);
+
+    /**Current provider. This provider may either fail or succeed.
+     * In either case unless the provider can provide us with a specific
+     * config which is newer than the one we have, it will roll over to the
+     * next provider. */
+    Provider *cur_provider;
+
+    /** All providers we know about. Currently this means the 'builtin' providers */
+    Provider* all_providers[CLCONFIG_MAX];
+
+    /** The current configuration pointer. This contains the most recent accepted
+     * configuration */
+    ConfigInfo * config;
+
+    typedef std::list<Listener*> ListenerList;
+    /**  List of listeners for events */
+    ListenerList listeners;
+
+    lcb_settings *settings;
+    lcb_error_t last_error;
+    lcbio_pTABLE iot;
+
+    /** This is the async handle for a reentrant start */
+    lcb::io::Timer<Confmon, &Confmon::do_next_provider> as_start;
+
+    /** Async handle for a reentrant stop */
+    lcb::io::Timer<Confmon, &Confmon::stop_real> as_stop;
+
+    /* CONFMON_S_* values. Used internally */
+    int state;
+
+    /** Last time the provider was stopped. As a microsecond timestamp */
+    lcb_uint64_t last_stop_us;
+
+    typedef std::list<Provider*> ProviderList;
+    ProviderList active_providers;
+
+    lcb_t instance;
+};
+
+/**
+ * The base structure of a provider. This structure is intended to be
+ * 'subclassed' by implementors.
+ */
+struct Provider {
+    Provider(Confmon*, Method type_);
+
+    /** Destroy the resources created by this provider. */
+    virtual ~Provider();
+
+    /**
+     * Get the current map known to this provider. This should not perform
+     * any blocking operations. Providers which use a push model may use
+     * this method as an asynchronous return value for a previously-received
+     * configuration.
+     */
+    virtual ConfigInfo* get_cached() = 0;
+
+
+    /**
+     * Request a new configuration. This will be called by the manager when
+     * the cached configuration (i.e. 'get_cached') is deemed invalid. Thus
+     * this function should unconditionally try to schedule getting the
+     * newest configuration it can. When the configuration has been received,
+     * the provider may call provider_success or provider_failed.
+     *
+     * @note
+     * The PROVIDER is responsible for terminating its own
+     * process. In other words there is no safeguard within confmon itself
+     * against a provider taking an excessively long time; therefore a provider
+     * should implement a timeout mechanism of its choice to promptly deliver
+     * a success or failure.
+     */
+    virtual lcb_error_t refresh() = 0;
+
+    /**
+     * Callback invoked to the provider to indicate that it should cease
+     * performing any "Active" configuration changes. Note that this is only
+     * a hint and a provider may perform its own hooking based on this. In any
+     * event receiving this callback is indicating that the provider will not
+     * be needed again in quite some time. How long this "time" is can range
+     * between 0 seconds and several minutes depending on how a user has
+     * configured the client.
+     *
+     * @return true if actually paused
+     */
+    virtual bool pause() {
+        return false;
+    }
+
+    /**
+     * Called when a new configuration has been received.
+     *
+     * @param config the current configuration.
+     * Note that this should only update the server list and do nothing
+     * else.
+     */
+    virtual void config_updated(lcbvb_CONFIG* config) {
+        (void)config;
+    }
+
+    /**
+     * Retrieve the list of nodes from this provider, if applicable
+     *
+     * @return A list of nodes, or NULL if the provider does not have a list
+     */
+    virtual const lcb::Hostlist* get_nodes() const {
+        return NULL;
+    }
+
+    /**
+     * Call to change the configured nodes of this provider.
+     *
+     * @param l The list of nodes to apply
+     */
+    virtual void configure_nodes(const lcb::Hostlist& l) {
+        (void)l;
+    }
+
+    /**
+     * Dump state information. This callback is optional
+     *
+     * @param f the file to write to
+     */
+    virtual void dump(FILE *f) const {
+        (void)f;
+    }
+
+    void enable() {
+        enabled = 1;
+    }
+
+    virtual void enable(void *) {
+        assert("Must be implemented in subclass if used" && 0);
+    }
+
+    /** The type of provider */
+    const Method type;
+
+    /** Whether this provider has been disabled/enabled explicitly by a user */
+    bool enabled;
+
+    /** The parent manager object */
+    Confmon *parent;
+
+    lcb_settings& settings() const {
+        return *parent->settings;
+    }
+};
+
+Provider *new_cccp_provider(Confmon*);
+Provider *new_file_provider(Confmon*);
+Provider *new_http_provider(Confmon*);
+Provider *new_mcraw_provider(Confmon*);
+Provider *new_cladmin_provider(Confmon*);
+
+
+/** @brief refcounted object encapsulating a vbucket config */
+class ConfigInfo {
+public:
+    /**
+     * Creates a new configuration wrapper object containing the vbucket config
+     * pointed to by 'config'. Its initial refcount will be set to 1.
+     *
+     * @param vbc a newly parsed configuration
+     * @param origin the type of provider from which the config originated.
+     * @return a new ConfigInfo object. This should be incref()'d/decref()'d
+     * as needed.
+     */
+    static ConfigInfo* create(lcbvb_CONFIG *vbc, Method origin) {
+        return new ConfigInfo(vbc, origin);
+    }
+    /**
+     * @brief Compares two info structures and determine which one is newer
+     *
+     * This function returns an integer less than
+     * zero, zero or greater than zero if the first argument is considered older
+     * than, equal to, or later than the second argument.
+     *
+     * @param config anoother config
+     * @see lcbvb_get_revision
+     * @see ConfigInfo::cmpclock
+     */
+    int compare(const ConfigInfo& config);
+
+    /**
+     * @brief Increment the refcount on a config object
+     */
+    void incref() { refcount++; }
+
+    /**
+     * @brief Decrement the refcount on a config object.
+     * Decrement the refcount. If the internal refcount reaches 0 then the internal
+     * members (including the vbucket config handle itself) will be freed.
+     */
+    void decref() {
+        if (!--refcount) {
+            delete this;
+        }
+    }
+
+    operator lcbvb_CONFIG*() const {
+        return vbc;
+    }
+
+    Method get_origin() const {
+        return origin;
+    }
+
+    /** Actual configuration */
+    lcbvb_CONFIG* vbc;
+
+private:
+    ConfigInfo(lcbvb_CONFIG *vbc, Method origin);
+
+    ~ConfigInfo();
+
+    /** Comparative clock with which to compare */
+    uint64_t cmpclock;
+
+    /** Reference counter */
+    unsigned int refcount;
+
+    /** Origin provider type which produced this config */
+    Method origin;
+};
+
+/**
+ * @brief Listener for events
+ * One or more listeners may be installed into the confmon which will have
+ * a callback invoked on significant vbucket events. See clconfig_event_t
+ * for a variety of events the listener can know.
+ */
+struct Listener {
+    virtual ~Listener() {
+    }
+
+    /** Linked list node */
+    lcb_list_t ll;
+
+    /**
+     * Callback invoked for significant events
+     *
+     * @param event the event which took place
+     * @param config the configuration associated with the event. Note that
+     * `config` may also be NULL
+     */
+    virtual void clconfig_lsn(EventType event, ConfigInfo *config) = 0;
+};
+
+/* Method-specific setup methods.. */
+
+/**
+ * @name File Provider-specific APIs
+ * @{
+ */
+
+/**
+ * Sets the input/output filename for the file provider. This also enables
+ * the file provider.
+ * @param p the provider
+ * @param f the filename (if NULL, a temporary filename will be created)
+ * @param ro whether the client will never modify the file
+ * @return true on success, false on failure.
+ */
+bool file_set_filename(Provider *p, const char *f, bool ro);
+
+/**
+ * Retrieve the filename for the provider
+ * @param p The provider of type CLCONFIG_FILE
+ * @return the current filename being used.
+ */
+const char* file_get_filename(Provider *p);
+void file_set_readonly(Provider *p, bool val);
+/**@}*/
+
+/**
+ * @name HTTP Provider-specific APIs
+ * @{
+ */
+
+/**
+ * Get the socket representing the current REST connection to the cluster
+ * (if applicable)
+ * @param p The provider of type CLCONFIG_HTTP
+ * @return
+ */
+const lcbio_SOCKET* http_get_conn(const Provider *p);
+
+static inline const lcbio_SOCKET* http_get_conn(Confmon *c) {
+    return http_get_conn(c->get_provider(CLCONFIG_HTTP));
+}
+
+/**
+ * Get the hostname for the current REST connection to the cluster
+ * @param p The provider of type CLCONFIG_HTTP
+ * @return
+ */
+const lcb_host_t * http_get_host(const Provider *p);
+static inline const lcb_host_t* http_get_host(Confmon *c) {
+    return http_get_host(c->get_provider(CLCONFIG_HTTP));
+}
+/**@}*/
+
+/**
+ * @name CCCP Provider-specific APIs
+ * @{
+ */
+
+/**
+ * Note, to initialize the CCCP provider, you should use
+ * cccp->enable(instance);
+ */
+
+/**
+ * @brief Notify the CCCP provider about a new configuration from a
+ * `NOT_MY_VBUCKET` response
+ *
+ * This should be called by the packet handler when a configuration has been
+ * received as a payload to a response with the error of `NOT_MY_VBUCKET`.
+ *
+ * @param provider The CCCP provider
+ * @param host The hostname (without the port) on which the packet was received
+ * @param data The configuration JSON blob
+ * @return LCB_SUCCESS, or an error code if the configuration could not be
+ * set
+ */
+lcb_error_t
+cccp_update(Provider *provider, const char *host, const char *data);
+
+/**
+ * @brief Notify the CCCP provider about a configuration received from a
+ * `CMD_GET_CLUSTER_CONFIG` response.
+ *
+ * @param cookie The cookie object attached to the packet
+ * @param err The error code for the reply
+ * @param bytes The payload pointer
+ * @param nbytes Size of payload
+ * @param origin Host object from which the packet was received
+ */
+void cccp_update(const void *cookie, lcb_error_t err,
+    const void *bytes, size_t nbytes, const lcb_host_t *origin);
+
+/**@}*/
+
+/**@name Raw Memcached (MCRAW) Provider-specific APIs
+ * @{*/
+/**@}*/
+/**@}*/
+
+} // clconfig
+} // lcb
+#endif /* LCB_CLCONFIG_H */