Merge pull request #40 from Cogmasters/dev

Fix missing documentation for gencodecs files enums and functions, update README.md

Makefile

@@ -14,18 +14,18 @@ EXAMPLES_DIR  = examples
 TEST_DIR      = test
 CCORDDOCS_DIR = concord-docs
 
-GENCODECS_HDR = $(GENCODECS_DIR)/discord-codecs.h
-GENCODECS_OBJ = $(GENCODECS_DIR)/discord-codecs.o
-
-COGUTILS_OBJS = $(OBJDIR)/$(COGUTILS_DIR)/cog-utils.o \
-                $(OBJDIR)/$(COGUTILS_DIR)/log.o       \
-                $(OBJDIR)/$(COGUTILS_DIR)/logconf.o
+GENCODECS_HDR = $(GENCODECS_DIR)/discord_codecs.h
+GENCODECS_OBJ = $(GENCODECS_DIR)/discord_codecs.o
+
+COGUTILS_OBJS = $(OBJDIR)/$(COGUTILS_DIR)/cog-utils.o  \
+                $(OBJDIR)/$(COGUTILS_DIR)/log.o        \
+                $(OBJDIR)/$(COGUTILS_DIR)/logconf.o    \
+                $(OBJDIR)/$(COGUTILS_DIR)/json-build.o \
+                $(OBJDIR)/$(COGUTILS_DIR)/jsmn-find.o
 CORE_OBJS     = $(OBJDIR)/$(CORE_DIR)/work.o       \
                 $(OBJDIR)/$(CORE_DIR)/user-agent.o \
                 $(OBJDIR)/$(CORE_DIR)/websockets.o \
-                $(OBJDIR)/$(CORE_DIR)/io_poller.o  \
-                $(OBJDIR)/$(CORE_DIR)/json-build.o \
-                $(OBJDIR)/$(CORE_DIR)/jsmn-find.o
+                $(OBJDIR)/$(CORE_DIR)/io_poller.o
 THIRDP_OBJS   = $(OBJDIR)/$(THIRDP_DIR)/sha1.o           \
                 $(OBJDIR)/$(THIRDP_DIR)/curl-websocket.o \
                 $(OBJDIR)/$(THIRDP_DIR)/threadpool.o

README.md

@@ -1,42 +1,40 @@
 <div align="center">
   <br />
   <p>
-    <a href="https://github.com/cogmasters/concord.git"><img src="https://raw.githubusercontent.com/Cogmasters/concord/bd1436a84af21384d93d92aed32b4c7828d0d793/docs/static/logo.svg" width="536" alt="Concord" /></a>
+    <a href="https://github.com/cogmasters/concord.git"><img src="https://raw.githubusercontent.com/Cogmasters/concord/bd1436a84af21384d93d92aed32b4c7828d0d793/docs/static/logo.svg" width="250" alt="Concord" /></a>
   </p>
   <br />
   <p>
     <br> <a href="https://discord.gg/Y7Xa6MA82v"><img src="https://img.shields.io/discord/928763123362578552?color=5865F2&logo=discord&logoColor=white" alt="Discord server" /></a> </br>
   </p>
 </div>
 
+## Concord
+
 ## About
 
-Concord is implemented in plain C99, its symbols are organized to be easily matched to the documentation of the API being covered.
-Concord's implementation has minimum external dependencies to make bot deployment deadly simple.
+Concord is an asynchronous C99 Discord API wrapper library. It has minimal external dependencies, and a low-level translation of the Discord official documentation to C code.
 
 ### Minimal example
 
 ```c
-#include <string.h> // strcmp()
+#include <string.h>
 #include <concord/discord.h>
 
-void on_ready(struct discord *client) 
-{
+void on_ready(struct discord *client) {
   const struct discord_user *bot = discord_get_self(client);
   log_info("Logged in as %s!", bot->username);
 }
 
-void on_message(struct discord *client, const struct discord_message *msg)
-{
+void on_message(struct discord *client, const struct discord_message *msg) {
   if (strcmp(msg->content, "ping") != 0)
-    return; // ignore messages that aren't 'ping'
+    return; /* ignore messages that aren't 'ping' */
 
   struct discord_create_message params = { .content = "pong" };
   discord_create_message(client, msg->channel_id, &params, NULL);
 }
 
-int main(void)
-{
+int main(void) {
   struct discord *client = discord_init(BOT_TOKEN);
   discord_set_on_ready(client, &on_ready);
   discord_set_on_message_create(client, &on_message);
@@ -51,42 +49,70 @@ int main(void)
 
 * Install **Cygwin**
 * **Make sure that you installed libcurl, gcc, make, and git when you ran the Cygwin installer!**
+* You will want to check the Windows tutorial [here](docs/WINDOWS.md)!
 
-### On Linux
+### On Linux, BSD, and Mac OS X
 
-The only dependency is `curl-7.4.1` or higher
+The only dependency is `curl-7.56.1` or higher. If you are compiling libcurl from source, you will need to build it with SSL support.
 
 #### Ubuntu and Debian
 
-```bash
-sudo apt install -y build-essential libcurl4-openssl-dev
+```console
+$ sudo apt install -y build-essential libcurl4-openssl-dev
 ```
 
 #### Void Linux
 
-```bash
-sudo xbps-install -S libcurl-devel
+```console
+$ sudo xbps-install -S libcurl-devel
 ```
 
 #### Alpine
 
-```bash
-sudo apk add curl-dev
+```console
+$ sudo apk add curl-dev
+```
+
+#### FreeBSD
+
+```console
+$ pkg install curl
+```
+
+#### OS X
+```console
+$ brew install curl (Homebrew)
+$ port install curl (MacPorts)
 ```
 ### Setting up your environment
 
 #### Clone Concord into your workspace
 
-```bash
+```console
 $ git clone https://github.com/cogmasters/concord.git && cd concord
 ```
 
 #### Compile Concord 
 
-```bash
+```console
 $ make
 ```
 
+#### Special notes for non-Linux systems
+You might run into trouble with the compiler and linker not finding your Curl headers. You can do something like this:
+```console
+$ CFLAGS=-I<some_path> LDFLAGS=-L<some_path> make
+```
+For instance, on a FreeBSD system:
+```console
+$ CFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib make
+```
+
+On OS X using MacPorts:
+```console
+$ CFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib make
+```
+
 ### Configuring Concord
 
 The following outlines the default fields of `config.json`
@@ -122,11 +148,11 @@ The following outlines the default fields of `config.json`
    [discord-irc](https://github.com/reactiflux/discord-irc/wiki/Creating-a-discord-bot-&-getting-a-token)
    explaining how to get your bot token and adding it to a server.
 2. Build example executables:
-   ```bash
+   ```console
    $ make examples
    ```
 3. Run Copycat-Bot:
-   ```bash
+   ```console
    $ cd examples && ./copycat
    ```
 
@@ -136,33 +162,51 @@ Type a message in any channel the bot is part of and the bot should send an exac
 
 #### Terminate Copycat-Bot
 
-With <kbd>Ctrl</kbd>+<kbd>c</kbd> or by closing the Terminal.
+With <kbd>Ctrl</kbd>+<kbd>c</kbd> or with <kbd>Control</kbd>+<kbd>|</kbd>
 
 ## Installing Concord
 
-```bash
-sudo make install
+*(note -- `#` means that you should be running as root)*
+
+```console
+# make install
 ```
 
 Included headers must be `concord/` prefixed:
 ```c
 #include <concord/discord.h>
 ```
 
+This will install the headers and libary files into $PREFIX. You can override this as such:
+```console
+# PREFIX=/opt/concord make install
+```
+
 ### Standalone executable
 
 #### GCC 
 
-```bash
+```console
 $ gcc myBot.c -o myBot -pthread -ldiscord -lcurl
 ```
 
 #### Clang
 
-```bash
+```console
 $ clang myBot.c -o myBot -pthread -ldiscord -lcurl
 ```
 
+#### UNIX C compiler
+```console
+$ cc myBot.c -o myBot -ldiscord -lcurl -lpthread
+```
+
+Note: some systems such as **Cygwin** require you to do this:
+```console
+$ gcc myBot.c -o myBot -pthread -lpthread -ldiscord -lcurl
+```
+(this links against libpthread.a in `/usr/lib`)
+
 ## Recommended debuggers
 
 First, make sure your executable is compiled with the `-g` flag to ensure human-readable debugger messages.
@@ -171,7 +215,7 @@ First, make sure your executable is compiled with the `-g` flag to ensure human-
 
 Using valgrind to check for memory leaks:
 
-```bash
+```console
 valgrind --leak-check=full ./myBot
 ```
 For a more comprehensive guide check [Valgrind's Quick Start](https://valgrind.org/docs/manual/quick-start.html).
@@ -180,15 +224,15 @@ For a more comprehensive guide check [Valgrind's Quick Start](https://valgrind.o
 
 Using GDB to check for runtime errors, such as segmentation faults:
 
-```bash
+```console
 $ gdb ./myBot
 ```
 And then execute your bot from the gdb environment:
-```bash
+```console
 (gdb) run
 ```
 If the program has crashed, get a backtrace of the function calls leading to it:
-```bash
+```console
 (gdb) bt
 ```
 

SECURITY.md

@@ -0,0 +1,19 @@
+# Concord Cybersecurity Policy
+
+## Covered Versions
+Only the latest Concord versioned release will receive security fixes. 
+No older versions fall under this requirement.
+
+## How Security Patches Are Implemented
+All security patches will be applied to the `dev` branch of the repository.
+To install these patches, simply clone the source code, `git checkout dev`, and
+compile as normal. Please note that `dev` might contain some breaking changes.
+It is advised that you do NOT attempt to manually backport fixes to older
+Concord releases, as your bot will eventually become inoperable due to old
+library age. 
+
+## Reporting A Security Issue (Vulnerability)
+If you come across a serious security issue, please file an issue request.
+Pull requests for security fixes will be examined in great detail.
+Alternatively, you can join the Discord chat as linked in the README file
+if you'd like to have one-on-one conversations with the Concord developers.

cog-utils/logconf.c

@@ -142,11 +142,11 @@ logconf_setup(struct logconf *conf, const char id[], FILE *fp)
 {
     struct {
         char level[16];
-        char filename[LOGCONF_PATH_MAX];
+        char filename[1028];
         bool quiet, use_color, overwrite;
         struct {
             bool enable;
-            char filename[LOGCONF_PATH_MAX];
+            char filename[1028];
         } http;
     } l = { 0 };
 
@@ -235,7 +235,7 @@ logconf_setup(struct logconf *conf, const char id[], FILE *fp)
 
     /* SET LOGGER CONFIGS */
     if (*l.filename) {
-        memcpy(conf->logger->fname, l.filename, LOGCONF_PATH_MAX);
+        conf->logger->fname = strdup(l.filename);
         conf->logger->f =
             fopen(conf->logger->fname, l.overwrite ? "w+" : "a+");
         ASSERT_S(NULL != conf->logger->f, "Could not create logger file");
@@ -247,7 +247,7 @@ logconf_setup(struct logconf *conf, const char id[], FILE *fp)
 
     /* SET HTTP DUMP CONFIGS */
     if (l.http.enable && *l.http.filename) {
-        memcpy(conf->http->fname, l.http.filename, LOGCONF_PATH_MAX);
+        conf->http->fname = strdup(l.http.filename);
         conf->http->f = fopen(conf->http->fname, l.overwrite ? "w+" : "a+");
         ASSERT_S(NULL != conf->http->f, "Could not create http logger file");
     }
@@ -307,10 +307,12 @@ logconf_cleanup(struct logconf *conf)
             free(conf->file.start);
         }
         if (conf->logger) {
+            if (conf->logger->fname) free(conf->logger->fname);
             if (conf->logger->f) fclose(conf->logger->f);
             free(conf->logger);
         }
         if (conf->http) {
+            if (conf->http->fname) free(conf->http->fname);
             if (conf->http->f) fclose(conf->http->f);
             free(conf->http);
         }

cog-utils/logconf.h

@@ -12,7 +12,7 @@ extern "C" {
 
 #define __ERR(fmt, ...) log_fatal(fmt "%s", __VA_ARGS__)
 
-# define ERR(...)                                                             \
+#define ERR(...)                                                              \
   do {                                                                        \
     __ERR(__VA_ARGS__, "");                                                   \
     abort();                                                                  \
@@ -159,8 +159,6 @@ extern "C" {
 
 /** Maximum length for module id */
 #define LOGCONF_ID_LEN 64 + 1
-/** Maximum length for the output file path */
-#define LOGCONF_PATH_MAX 4096
 
 /**
  * @brief A stackful and modularized wrapper over the popular 'log.c'
@@ -183,7 +181,7 @@ struct logconf {
     struct sized_buffer file;
     struct {
         /** name of logging output file */
-        char fname[LOGCONF_PATH_MAX];
+        char *fname;
         /** pointer to logging output file */
         FILE *f;
     } * logger, *http;