docs: added standardized docs

stiller-backend/.gitignore

@@ -32,4 +32,5 @@ go.work.sum
 static/
 tmp/
 build/
+book/
 

stiller-backend/db/create.sql

@@ -1,18 +1,3 @@
-create table tier (
-    id integer unique primary key not null,
-    name text unique not null
-);
-
-create table user (
-    id integer unique primary key autoincrement not null,
-    avatar integer references file (id),
-    tier integer not null references tier (id),
-    displayname text not null,
-    username text unique not null,
-    mail text not null,
-    bpasswd text not null
-);
-
 create table filetype (
     code integer unique primary key not null,
     name text unique not null
@@ -32,6 +17,25 @@ create table file (
     deleted integer not null
 );
 
+create table tier (
+    id integer unique primary key not null,
+    name text unique not null
+);
+
+create table user (
+    id integer unique primary key autoincrement not null,
+    tier integer not null references tier (id),
+    displayname text not null,
+    username text unique not null,
+    mail text not null,
+    bpasswd text not null
+);
+
+create table avatar (
+    user integer not null references user (id),
+    file integer not null references file (id)
+);
+
 create table gallery (
     id integer unique primary key autoincrement not null,
     owner integer not null references user (id),
@@ -72,5 +76,5 @@ insert into tier values
     (1, 'van gogh'),
     (2, 'picasso');
 
-insert into user VALUES (0, null, 0, 'admin', 'admin', '', '');
+insert into user VALUES (0, 0, 'admin', 'admin', '', '');
 

stiller-backend/docs/book.toml

@@ -0,0 +1,5 @@
+[book]
+title = "Stiller's docs"
+
+
+

stiller-backend/docs/src/SUMMARY.md

@@ -0,0 +1,13 @@
+# Summary
+
+[Introduction](readme.md)
+
+- [Server configuration](configuration.md)
+- [FS-based handlers](files.md)
+    - [`/file/upload`](file/upload.md)
+    - [`/file/update`](file/update.md)
+    - [`/file/retrieveall`](file/retrieveall.md)
+- [Auth Handlers](auth.md)
+    - [`/auth/checkuser/:username`](auth/checkuser.md)
+    - [`/auth/login`](auth/login.md)
+

stiller-backend/docs/src/auth.md

@@ -0,0 +1,6 @@
+# Auth-based handlers
+
+These handlers are used to fulfill most of the usual authentication-related
+operations. Authentication is done using bcrypt and json web tokens encrypted
+asymetrically.
+

stiller-backend/docs/src/auth/checkuser.md

@@ -0,0 +1,20 @@
+# Check username
+
+## Path
+
+<div align="center">
+
+`POST /auth/checkuser/:username`
+
+</div>
+
+## Request body
+
+None
+
+## Response body
+
+If succesful, the server will respond with an
+[`OK`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) status
+code.
+

stiller-backend/docs/src/auth/login.md

@@ -0,0 +1,27 @@
+# Login
+
+## Path
+
+<div align="center">
+
+`POST /auth/login`
+
+</div>
+
+## Request body
+
+A json object of the type:
+
+```go
+type ReqPayload struct {
+    Username string `json:"username"`
+    Pwd      string `json:"pwd"`
+}
+```
+
+## Response body
+
+If succesful, the server will respond with a single unformatted token string,
+it's the caller's responsibility to store this token as it is needed for most
+operations.
+

stiller-backend/docs/src/configuration.md

@@ -0,0 +1,27 @@
+# Server configuration
+
+The server configuration is done via a single globally available variable which
+type is structured as follows:
+
+```go
+type ConfigType struct {
+    Port       string /* local port where the service will be deployed at */
+    FilesPath  string /* local directory where to retrieve/store data from/to */
+    DBPath     string /* local static path of the sqlite database file */
+    Secret     []byte /* secret to be used by token generation functions and
+                         other encrypted necesities */
+    BCryptCost int    /* bcrypt password encryption cost */
+}
+```
+
+It's build upon a `.env` file which is schemed just the same way as the type.
+For example:
+
+```sh
+Port=":6969"
+FilesPath="static/"
+DBPath="db/metagallery.db"
+Secret="whatever secret"
+BCryptCost=99
+```
+

stiller-backend/docs/src/file/retrieveall.md

@@ -0,0 +1,18 @@
+# Retrieving all fileblocks
+
+## Path
+
+<div align="center">
+
+<img src="jwt_logo.png" height="10px"/> `POST /file/retrieveall`
+
+</div>
+
+## Request body
+
+None
+
+## Response body
+
+If succesful, the server will respond with an array of [`StillerFile`](/files.md)s.
+

stiller-backend/docs/src/file/update.md

@@ -0,0 +1,28 @@
+# Updating some file metadata
+
+## Path
+
+<div align="center">
+
+<img src="jwt_logo.png" height="10px"/> `POST /file/update`
+
+</div>
+
+## Request body
+
+The request body must be a json object of the schema:
+
+```go
+type ReqPayload struct {
+    Id          int    `json:"id"`
+    Title       string `json:"title"`
+    Description string `json:"description"`
+}
+```
+
+## Response body
+
+If succesful, the server will respond with a
+[OK](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200) statuscode
+and no body at all.
+

stiller-backend/docs/src/file/upload.md

@@ -0,0 +1,74 @@
+# Uploading Files
+
+## Path
+
+<div align="center">
+
+<img src="jwt_logo.png" height="10px"/> `POST /file/upload`
+
+</div>
+
+## Request body
+
+Now, the payload itself is not a "StillerFile" object but a multipart form body
+in the shape of:
+
+|   Form field name     |   form field type     |
+|-----------------------|-----------------------|
+|   stiller-name        |       `?string`       |
+|   stiller-type        |       `u8`            |
+|   stiller-file        |       `Binary File`   |
+|   stiller-hashed      |       `?u2`           |
+
+### stiller-name
+
+This is the name that the file will use when stored both in the server local
+filesytem and in the database metadata.
+
+*Values*:
+- `allowed`: Any string
+- `default`: If no string is given, or if a 0-length string is given, the system
+  will use the filename from the multipart form metadata itself. If, for some
+  reason, the form metadata also return a 0-length string then the request
+  will fail.
+
+### stiller-type
+
+*warning: this is not related to the file's MIME-type*
+
+This is the in-database type of the file metadata entry
+
+*Values*:
+- `allowed`: One of the allowed [`filetype`](/files.md) identifiers
+- `default`: Non optional field
+
+### stiller-file
+
+This is a raw binary file capped at 100mb size.
+
+*Values*:
+- `allowed`: A raw binary file
+- `default`: Non optional field
+
+### stiller-hashed
+
+This is a binary number (`0 | 1`) that gets interpret as a boolean which also
+gets used to decide if the system must or must not produce a hash of the file
+(may secure files but may slow down file retrieval too).
+
+*Values*:
+- `allowed`: `0 | 1`
+- `default`: by default, `0` is assigned
+
+## Response body
+
+If succesful, the server will respond with the following schema, where the `id`
+is that of the newly created file:
+
+```go
+type ResPayload struct {
+    Id int `json:"id"`
+}
+```
+
+

stiller-backend/docs/src/files.md

@@ -0,0 +1,35 @@
+# FS-based handlers
+
+These endpoints are stubs used to modify any kind of file, where each file is
+stored internally as follows:
+
+```go
+type StillerFileType uint8
+const (
+    Image StillerFileType = iota    // 0
+    Video                           // 1
+    Object3D                        // 3
+
+    /* control value (not actually used inside the db) */
+    Unreachable
+)
+
+type StillerFile struct {
+    Id          int             `json:"id"`
+    OwnerId     int             `json:"ownerid"`
+    Typeof      StillerFileType `json:"typeof"`
+    Path        string          `json:"path"`
+    Filename    string          `json:"filename"`
+    Title       string          `json:"title"`
+    Description string          `json:"description"`
+    Ext         string          `json:"ext"`
+    Hashed      bool            `json:"hashed"`
+    Size        int             `json:"size"`
+    Deleted     bool            `json:"deleted"`
+}
+```
+
+So each file entrance inside the database is actually a metadata block of an
+actual file that lies in the server in a path defined by [the
+configuration file](configuration.md##FilesPath).
+

stiller-backend/docs/src/readme.md

@@ -0,0 +1,23 @@
+<div align="center">
+
+<video src="iamlarry.mp4" controls></video>
+
+# Stiller
+
+---
+
+</div>
+
+## What is Stiller
+
+Stiller is both a **single-node** content distribution "network" and
+multi-purposed server created as part of the MetaGallery project. It is built as
+a totally self-contained, sqlite-based web service deployed through air and
+actions.
+
+## Components
+
+Stiller is built almost totally upon the stdlib http serving packages except for
+the router (where
+[julienschmidt/httprouter](https://github.com/julienschmidt/httprouter) shines).
+

stiller-backend/internal/dbutils/types.go

@@ -9,17 +9,17 @@ const (
 )
 
 type StillerFile struct {
-    Id          int            `json:"id"`
-    OwnerId     int            `json:"ownerid"`
+    Id          int             `json:"id"`
+    OwnerId     int             `json:"ownerid"`
     Typeof      StillerFileType `json:"typeof"`
-    Path        string         `json:"path"`
-    Filename    string         `json:"filename"`
-    Title       string         `json:"title"`
-    Description string         `json:"description"`
-    Ext         string         `json:"ext"`
-    Hashed      bool           `json:"hashed"`
-    Size        int            `json:"size"`
-    Deleted     bool           `json:"deleted"`
+    Path        string          `json:"path"`
+    Filename    string          `json:"filename"`
+    Title       string          `json:"title"`
+    Description string          `json:"description"`
+    Ext         string          `json:"ext"`
+    Hashed      bool            `json:"hashed"`
+    Size        int             `json:"size"`
+    Deleted     bool            `json:"deleted"`
 }
 
 type StillerUser struct {