soudan

A Rust-based comment server using SQLite and an intuitive REST API. Soudan is built with simplicity and static sites in mind.

CLI usage

See soudan --help for help information.

soudan 0.1.0
ElnuDev <elnu@elnu.com>
A Rust-based comment server using SQLite and an intuitive REST API.

USAGE:
    soudan [OPTIONS] <SITES>...

ARGS:
    <SITES>...    Set sites where comments will be posted

OPTIONS:
    -e, --email-required    Require email for comment submissions
    -h, --help              Print help information
    -n, --name-required     Require name for comment submissions
    -p, --port <PORT>       Set port where HTTP requests will be received [default: 8080]
    -t, --testing           Run in testing mode, with in-memory database(s) and permissive CORS
                            policy
    -V, --version           Print version information

The sites must be prefixed with either http:// or https://. Each site may only use one protocol, so the HTTP and HTTPS versions of each site are considered separate sites. You should redirect HTTPS to HTTP.

For example, to run Soudan on example.com and example.org on port 8081, use the following command. Each site will be stored completely separately, with its own database, example.com.db and example.org.db, respectively.

soudan -p 8081 https://example.com https://example.org

In addition, you can add the -t/--testing flag to run Soudan in testing mode. In this mode, Soudan stores all comments in a fresh in-memory database, and all comments will be lost once Soudan is closed. In addition, a permissive CORS policy is used to make testing easier.

Finally, you can also add the -n/--name-required and/or -e/--email-required flags to prevent anonymous comments. Keep in mind that the JavaScript in soudan.js assumes that these flags are not set, so you would need to manually add the required flag to the name and email <input> fields respectively.

Moderation

Soudan does not have any spam filtering or moderation built in. However, going into the database manually to browse and remove comments is very easy. If you need an SQLite database browser, I'd recommend DB Browser for SQLite.

API usage

Fetching comments

Comments can be fetched using a simple GET request to /{content_id}, where content_id is the content ID of the post set in the page's meta tags. (See Site configuration for information about how to set up your site's HTML to use Soudan.) It is important to note that the content ID is not unique across sites. The way the intended site of the request is determined is through the Origin header. Requests without a valid Origin header are rejected. Requests made through the browser will always have this header.

Here is an example API response from real-world usage of Soudan (beautified).

Each comment will have an id, text, and timestamp fields, and optionally an author (if absent, comment is anonymous) and a gravatar field (the MD5 hash of the commenter's email address. https://www.gravatar.com/avatar/{gravatar}). Root level comments will have a replies field if replies exist.

[
	{
		"id": 1,
		"author": "Elnu",
		"gravatar": "1cfb9e38feea40e5150bc0fa69faf693",
		"text": "Nice post, me!",
		"timestamp": 1658541512,
		"replies": [
			{
				"id": 2,
				"author": "Drago",
				"text": "HELLO ELNU",
				"timestamp": 1658541674
			},
			{
				"id": 3,
				"author": "Elnu",
				"gravatar": "1cfb9e38feea40e5150bc0fa69faf693",
				"text": "HELLO DRAGO",
				"timestamp": 1658541732
			},
			{
				"id": 4,
				"author": "Drago",
				"text": "You should get to drawing ( ͡° ͜ʖ ͡°)",
				"timestamp": 1658541778
			},
			{
				"id": 5,
				"author": "Elnu",
				"gravatar": "1cfb9e38feea40e5150bc0fa69faf693",
				"text": "*soon™*",
				"timestamp": 1658541863
			}
		]
	}
]

Creating comments

Comments can be likewise created using a simple POST request to / (not /{content_id}).

Here is an example API response from real-world usage of Soudan (beautified).

The request must have a url field which is the current page URL. The comment field must contain contentId, the page content ID (see Site configuration), and text. Optionally, the author, email, and parent (the parent comment ID).

{
	"url": "http://localhost:3000/a/",
	"comment": {
		"contentId": "a",
		"author": "Elnu",
		"email": "elnu@elnu.com",
		"text": "Test comment",
		"parent": null
	}
}

Site configuration

Site configuration for Soudan is very straightforward. All you need to do is add the following meta tag to the <head> of all pages you want to enable comments on, where you insert your content ID into the content attribute of the tag:

<meta name="soudan-content-id" content="{content_id}">

The content ID can be pretty much anything, provided it's URL-safe (e.g. there must be no forward slashes (/)). Spaces are okay, as they will be escaped. A good value to use for the content ID is the slug of your page, as this will be unique and will be obvious what page it is associated with in the database. However, one must make sure that if the page is renamed/moved, either this content ID remains constant or the associated comments are manually updated accordingly in the database (see Moderation).

Reference JavaScript client implementation

There is a reference JavaScript client implementation available under demo. It supports Markdown comment rendering via markdown-it (images have been disabled) and human-readable relative timestamps for comments via moment.js. The icons are from Heroicons.

To use it, first add these two dependencies to your page's <head>, here using a CDN. You may want to check if there has been a newer version released on cdnjs since the time of writing. (markdown-it, moment.js)

<script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.29.4/moment.min.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/markdown-it/13.0.1/markdown-it.min.js" integrity="sha512-SYfDUYPg5xspsG6OOpXU366G8SZsdHOhqk/icdrYJ2E/WKZxPxze7d2HD3AyXpT7U22PZ5y74xRpqZ6A2bJ+kQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>

The demo HTML pages use the Sakura CSS framework/theme in addition to a small stylesheet just for Soudan. Optionally, you can copy this stylesheet into your project. It's pretty theme-agnostic, so it should work fine regardless of your preexisting styles.

<link rel="stylesheet" href="/path/to/style.css">

Next, copy soudan.js into your project. Open it up in your favorite text editor and update the value of url here to URL of your own Soudan server.

Finally, on each page where you want comments (and where the meta tag is present), add the following container <div> and script tag where you want your comment section to be. The comment form, etc. will be automatically generated once your page loads, and will be hidden if there is a critical error (i.e. Soudan server offline). The <script> tag must be after the <div>.

<div id="soudan"></div>
<script src="/path/to/soudan.js"></script>

And... you're done!