Documentation and code style for syslog logger references XRPLF#386

Peter Thorson · Peter Thorson · commit cbe887524e46 · 2014-12-05T10:10:44.000-05:00
diff --git a/changelog.md b/changelog.md
@@ -5,13 +5,15 @@ HEAD
 - Security: Disabled SSLv3 in example servers.
 - Feature: Adds basic support for accessing HTTP request bodies in the http
   handler. #181
-- Feature: Adds the ability to register a shutdown handler when using the 
-  iostream transport. This provides a clean interface for triggering the shut 
+- Feature: Adds the ability to register a shutdown handler when using the
+  iostream transport. This provides a clean interface for triggering the shut
   down of external sockets and other cleanup without hooking in to higher level
   WebSocket handlers.
 - Feature: Adds the ability to register a write handler when using the iostream
   transport. This handler can be used to handle transport output in place of
   registering an ostream to write to.
+- Feature: Adds a new logging policy that outputs to syslog. #386 Thank you Tom
+  Hughes for submitting the initial version of this policy.
 - Improvement: Message payload logging now prints text for text messages rather
   than binary.
 - Documentation: Add Sending & Receiving Messages step to chapter one of the
diff --git a/examples/debug_server/debug_server.cpp b/examples/debug_server/debug_server.cpp
@@ -31,11 +31,55 @@
 
 #include <websocketpp/config/debug_asio_no_tls.hpp>
 
+// Custom logger
+#include <websocketpp/logger/syslog.hpp>
+
 #include <websocketpp/server.hpp>
 
 #include <iostream>
 
-typedef websocketpp::server<websocketpp::config::debug_asio> server;
+////////////////////////////////////////////////////////////////////////////////
+///////////////// Custom Config for debugging custom policies //////////////////
+////////////////////////////////////////////////////////////////////////////////
+
+struct debug_custom : public websocketpp::config::debug_asio {
+    typedef debug_custom type;
+    typedef debug_asio base;
+
+    typedef base::concurrency_type concurrency_type;
+
+    typedef base::request_type request_type;
+    typedef base::response_type response_type;
+
+    typedef base::message_type message_type;
+    typedef base::con_msg_manager_type con_msg_manager_type;
+    typedef base::endpoint_msg_manager_type endpoint_msg_manager_type;
+
+    /// Custom Logging policies
+    typedef websocketpp::log::syslog<concurrency_type,
+        websocketpp::log::elevel> elog_type;
+    typedef websocketpp::log::syslog<concurrency_type,
+        websocketpp::log::alevel> alog_type;
+
+    typedef base::rng_type rng_type;
+
+    struct transport_config : public base::transport_config {
+        typedef type::concurrency_type concurrency_type;
+        typedef type::alog_type alog_type;
+        typedef type::elog_type elog_type;
+        typedef type::request_type request_type;
+        typedef type::response_type response_type;
+        typedef websocketpp::transport::asio::basic_socket::endpoint
+            socket_type;
+    };
+
+    typedef websocketpp::transport::asio::endpoint<transport_config>
+        transport_type;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+typedef websocketpp::server<debug_custom> server;
 
 using websocketpp::lib::placeholders::_1;
 using websocketpp::lib::placeholders::_2;
@@ -93,7 +137,7 @@ int main() {
 
         // Register our message handler
         echo_server.set_message_handler(bind(&on_message,&echo_server,::_1,::_2));
-        
+
         echo_server.set_http_handler(bind(&on_http,&echo_server,::_1));
         echo_server.set_fail_handler(&on_fail);
         echo_server.set_close_handler(&on_close);
diff --git a/websocketpp/logger/stub.hpp b/websocketpp/logger/stub.hpp
@@ -45,7 +45,7 @@ class stub {
      * @param hint A channel type specific hint for how to construct the logger
      */
     explicit stub(channel_type_hint::value) {}
-    
+
     /// Construct the logger
     /**
      * @param default_channels A set of channels to statically enable
@@ -56,16 +56,16 @@ class stub {
 
     /// Dynamically enable the given list of channels
     /**
-     * All operations on the stub logger are no-ops and all arguments are 
+     * All operations on the stub logger are no-ops and all arguments are
      * ignored
      *
      * @param channels The package of channels to enable
      */
     void set_channels(level) {}
-    
+
     /// Dynamically disable the given list of channels
     /**
-     * All operations on the stub logger are no-ops and all arguments are 
+     * All operations on the stub logger are no-ops and all arguments are
      * ignored
      *
      * @param channels The package of channels to disable
@@ -76,34 +76,34 @@ class stub {
     /**
      * Writing on the stub logger is a no-op and all arguments are ignored
      *
-     * @param channel The package of channels to write to
+     * @param channel The channel to write to
      * @param msg The message to write
      */
     void write(level, std::string const &) {}
-    
+
     /// Write a cstring message to the given channel
     /**
      * Writing on the stub logger is a no-op and all arguments are ignored
      *
-     * @param channel The package of channels to write to
+     * @param channel The channel to write to
      * @param msg The message to write
      */
     void write(level, char const *) {}
 
     /// Test whether a channel is statically enabled
     /**
-     * The stub logger has no channels so all arguments are ignored and 
+     * The stub logger has no channels so all arguments are ignored and
      * `static_test` always returns false.
      *
      * @param channel The package of channels to test
      */
     _WEBSOCKETPP_CONSTEXPR_TOKEN_ bool static_test(level) const {
         return false;
     }
-    
+
     /// Test whether a channel is dynamically enabled
     /**
-     * The stub logger has no channels so all arguments are ignored and 
+     * The stub logger has no channels so all arguments are ignored and
      * `dynamic_test` always returns false.
      *
      * @param channel The package of channels to test
diff --git a/websocketpp/logger/syslog.hpp b/websocketpp/logger/syslog.hpp
@@ -1,3 +1,33 @@
+/*
+ * Copyright (c) 2014, Peter Thorson. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *     * Redistributions of source code must retain the above copyright
+ *       notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ *     * Neither the name of the WebSocket++ Project nor the
+ *       names of its contributors may be used to endorse or promote products
+ *       derived from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL PETER THORSON BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ *
+ * The initial version of this logging policy was contributed to the WebSocket++
+ * project by Tom Hughes.
+ */
+
 #ifndef WEBSOCKETPP_LOGGER_SYSLOG_HPP
 #define WEBSOCKETPP_LOGGER_SYSLOG_HPP
 
@@ -15,37 +45,71 @@ namespace log {
 template <typename concurrency, typename names>
 class syslog : public basic<concurrency, names> {
 public:
-    syslog<concurrency,names>(channel_type_hint::value h =
+    typedef basic<concurrency, names> base;
+
+    /// Construct the logger
+    /**
+     * @param hint A channel type specific hint for how to construct the logger
+     */
+    syslog<concurrency,names>(channel_type_hint::value hint =
         channel_type_hint::access)
-      : basic<concurrency,names>(h), channel_type_hint_(h) {}
+      : basic<concurrency,names>(hint), m_channel_type_hint(hint) {}
 
-    syslog<concurrency,names>(level c, channel_type_hint::value h =
+    /// Construct the logger
+    /**
+     * @param channels A set of channels to statically enable
+     * @param hint A channel type specific hint for how to construct the logger
+     */
+    syslog<concurrency,names>(level channels, channel_type_hint::value hint =
         channel_type_hint::access)
-      : basic<concurrency,names>(c, h), channel_type_hint_(h) {}
+      : basic<concurrency,names>(channels, hint), m_channel_type_hint(hint) {}
 
+    /// Write a string message to the given channel
+    /**
+     * @param channel The channel to write to
+     * @param msg The message to write
+     */
     void write(level channel, std::string const & msg) {
         write(channel, msg.c_str());
     }
 
+    /// Write a cstring message to the given channel
+    /**
+     * @param channel The channel to write to
+     * @param msg The message to write
+     */
     void write(level channel, char const * msg) {
-        scoped_lock_type lock(basic<concurrency,names>::m_lock);
+        scoped_lock_type lock(base::m_lock);
         if (!this->dynamic_test(channel)) { return; }
-        ::syslog(syslog_priority(channel), "[%s] %s", names::channel_name(channel), msg);
+        ::syslog(syslog_priority(channel), "[%s] %s",
+            names::channel_name(channel), msg);
     }
-
 private:
-    typedef typename basic<concurrency,names>::scoped_lock_type scoped_lock_type;
-    const int kDefaultSyslogLevel = LOG_INFO;
+    typedef typename base::scoped_lock_type scoped_lock_type;
+
+    /// The default level is used for all access logs and any error logs that
+    /// don't trivially map to one of the standard syslog levels.
+    static int const default_level = LOG_INFO;
 
-    const int syslog_priority(level channel) const {
-        if (channel_type_hint_ == channel_type_hint::access) {
+    /// retrieve the syslog priority code given a WebSocket++ channel
+    /**
+     * @param channel The level to look up
+     * @return The syslog level associated with `channel`
+     */
+    int syslog_priority(level channel) const {
+        if (m_channel_type_hint == channel_type_hint::access) {
             return syslog_priority_access(channel);
         } else {
             return syslog_priority_error(channel);
         }
     }
 
-    const int syslog_priority_error(level channel) const {
+    /// retrieve the syslog priority code given a WebSocket++ error channel
+    /**
+     * @param channel The level to look up
+     * @return The syslog level associated with `channel`
+     */
+    int syslog_priority_error(level channel) const {
         switch (channel) {
             case elevel::devel:
                 return LOG_DEBUG;
@@ -60,15 +124,20 @@ class syslog : public basic<concurrency, names> {
             case elevel::fatal:
                 return LOG_CRIT;
             default:
-                return kDefaultSyslogLevel;
+                return default_level;
         }
     }
 
-    _WEBSOCKETPP_CONSTEXPR_TOKEN_ int syslog_priority_access(level channel) const {
-        return kDefaultSyslogLevel;
+    /// retrieve the syslog priority code given a WebSocket++ access channel
+    /**
+     * @param channel The level to look up
+     * @return The syslog level associated with `channel`
+     */
+    _WEBSOCKETPP_CONSTEXPR_TOKEN_ int syslog_priority_access(level) const {
+        return default_level;
     }
 
-    channel_type_hint::value channel_type_hint_;
+    channel_type_hint::value m_channel_type_hint;
 };
 
 } // log
