Home

Awesome

Basilica

You can see a live demo running at https://basilica.horse, which currently hosts both the API and the official Om client.

A basilica is like a forum, but for a few ill-defined differences. For more detail please consult the table below, adapted from a crude sketch I made while drunk.

ForumBasilica
PHPHaskell
90s2010s
trollsfriends
"rich formatting"markdown
paginglazy tree
threads ↑ comments ↓uniform hierarchy
<form>HTTP API
inline CSSbots, webhooks, extensions
F5websockets

Status

Basilica is usable. It is not a comprehensive, beautiful piece of software, but it works and the canonical instance of it has been live and running since 2014.

Further development is not very likely, since it works well enough for my purposes.

API

Resources

Basilica defines a few resources, which are always communicated in JSON.

Sometimes the API will send resolved data, which means that it will turn:

"idResource": 123

Into:

"resource": { "id": 123, ... }

When it does so will be documented in the route response.

Unless otherwise specified, no value will be null.

Post

{ "id": 49
, "idParent": 14
, "idUser": 43
, "at": "2014-08-17T01:19:15.139Z"
, "count": 0
, "content": "any string"
, "children": []
}

User

{ "id": 32
, "email": "name@example.com"
, "name": "ian"
, "face": {}
}

Code

Codes are never communicated via JSON, so it doesn't make sense to show their format. Publicly, they can be considered strings. They happen to currently be hexadecimal strings, but that's an implementation detail that may change.

Token

{ "id": 91
, "token": "a long string"
, "idUser": 32
}

Authentication

There's a goofy hand-rolled auth scheme.

There are no passwords. Authentication is done purely through email. The process looks this:

I'm gonna repeat that last thing because it's important: you need to set an X-Token header to make an authenticated request. No cookies, query parameters, nothing like that. That header is the only thing that counts.

This is similar to the "forgot my password" flow found in most apps, except that you don't have to pretend to remember anything.

Routes

Postal Routes

POST /posts/:idParent

$ curl -i                             # show response headers (otherwise a 401 is very confusing)
       -X POST                        # set the HTTP verb
       --data "content=hello%20world" # escape your string!
       -H "X-Token: asdf"             # requires authentication
       "http://localhost:3000/posts"  # the actual route

GET /posts/:id

GET /posts

User Routes

POST /users

Auth Routes

POST /codes

DELETE /codes/:code

POST /tokens

GET /tokens

DELETE /tokens/:id

Websockets

There is currently one websocket route, a single firehose stream of all new posts created, in JSON, with idUser resolved. The route is just /, with the ws or wss protocol.

When connected, Basilica will periodically send ping frames. If the client doesn't respond in a timely manner, that client will be closed with either a friendly or slightly hostile message.

Currently this is set to ping every 20 seconds and to disconnect clients if more than 40 seconds passes without receiving a pong. Don't rely on those values, though. Just pong the pings as quickly as you can. All websocket libraries should do this for you automatically.

Client Implementation Notes

Basiliclients

Development

Basilica uses SQLite. You need to create the database.

$ sqlite3 basilica.db ".read schema.sql"

Basilica is developed using stack:

$ stack build

After that you can modify the conf file. Here's a list of all keys and their meanings:

port = 3000
dbpath = "basilica.db"
client-origin = "http://localhost:3333"
client-url = "http://localhost:3333/client/"
mailgun-key = "asdf"

Then you can run it.

$ stack exec basilica

Now you're ready to basilicate.

Contributors