Start working on documentation

This commit is contained in:
Robin Malley 2022-12-23 19:30:52 +00:00
parent 1930ade3f7
commit 39c7f2f638
4 changed files with 80 additions and 0 deletions

8
doc/appendix.md Normal file
View File

@ -0,0 +1,8 @@
## falsey
In Lua, the values `false` and `nil` are considered falsey.
All other values are considered truethy.
In addition, tables may have a metatable that has a `__toboolean` function
to implement their own truethyness or falseyness. `false` should be used in
places where a boolean is expected, and `nil` should be used otherwise.

44
doc/hacking.md Normal file
View File

@ -0,0 +1,44 @@
# A gentle introduction to SMR
SMR is a small Pastebin clone, with a few extra features. One of it's goals is
to be simple and easy to modify. This document will explain how:
## Downloading
The canonical location for the SMR source repository is
`https://git.fuwafuwa.moe/rmalley/smr`
In the case of downtime, a mirror is available at
`https://dev.sum7.eu/Robin.Malley/smr`
## Dependencies
SMR requires the following things to be install on the host system.
* kore - Web server framework for C https://kore.io
* luarocks - package manager for the Lua programming language. Will require a
working Lua environment. The maintainer recommends `luajit`, SMR is written
against Lua 5.1, but should still work on 5.2. Lua 5.3 introduced breaking
changes and may require additional modification.
* spp - A simple preprocessor used to preprocess some files.
## Installing
After doing `git clone`, `make` and `make install`, SMR will install itself
under `/var/lib/smr/`, in this folder, there will be 2 more folders, each
corresponding to a chroot environment:
* `kore_worker` - The chroot where business logic runs. All application code
lives under `/var/smr/`. This chroot also holds the database for
at `/var/smr/data/posts.db` (so the full path from the host to the database
is `/var/lib/smr/kore_worker/var/smr/data/posts.db`). After the kore worker
starts and chroots, it runs the file `/var/smr/init.lua`. In addition, SMR
will install lua rocks under `/usr/lib/luarocks` under the chroot.
* `kore_keymgr` - The chroot where https keys are stored.
The entire point of the keymgr process is to separate the processes
that runs business logic from the process that holds encryption keys.
In theory, even in the event of an arbitrary code execution vulnerability in the
SMR code, the encryption keys used for the site should still be safe.

14
doc/hooks.md Normal file
View File

@ -0,0 +1,14 @@
# Hooks
Various functions that are exposed to the lua environment. These functions may be detoured to effect their behavior.
```
connect(req :: http_request) :: boolean
```
Called before smr business logic is run, may run additional validation on the request. Return @{falsey} by default, and continues onto the business logic of smr, return `true` if this function has handled the request, and no further processing is nessessary.
```
create_user(details :: table) :: boolean
```
Called when a user creates a user account on the site.

View File

@ -105,6 +105,20 @@ do_lua(struct http_request *req, const char *name){
return KORE_RESULT_OK; return KORE_RESULT_OK;
} }
/***
Called at the endpoint <domain>/_paste.
This method doesn't need any parameters for GET requests,
and expects the following parametrs when POSTing:
* title :: string
* text :: string
* markup :: string - a valid markup type
In addition to the normal assets, this page includes
suggest_tags.js, which suggests tags that have been
submitted to the site before.
@function _G.paste
@custom http_method GET POST
@param http_request req The request to service
***/
int int
post_story(struct http_request *req){ post_story(struct http_request *req){
return do_lua(req,"paste"); return do_lua(req,"paste");