magical
/
bbj
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
bbj/docs/protocol.org

190 lines
11 KiB
Org Mode
Raw Normal View History

added data standards
2017-03-01 22:57:00 +00:00
Data Standards
--------------
* UTF-8 in, UTF-8 out. No exceptions.
* SHA256 for auth_hash. Server will do a basic check to make sure of this.
* Security is not a #1 concern. Basic authorization will be implemented
to **help prevent** users from impersonating each other, but this isn't
intended to be bulletproof and you shouldn't trust the system with a
password you use elsewhere. All clients should inform the user of this.
* Command-line, on-tilde comes first. Local clients should be possible using
SSH port binding, however features like inline images, graphical elements
and the like will never be implemented as part of the protocol. Local clients
can definitely do things like URL image previews though. Hyperlinks with a
different text then the link itself will never be implemented.
hi
2017-03-01 16:59:33 +00:00
Text Entities
-------------
The `entities` attribute is an array of objects that represent blocks
of text within a post that have special properties. Clients may safely
ignore these things without losing too much meaning, but in a rich
too many things and I suck at git
2017-03-01 21:54:56 +00:00
implementation like an Emacs or GUI, they can provide
hi
2017-03-01 16:59:33 +00:00
some highlighting and navigation perks. The array object may be
empty. If its not, its populated with arrays representing the
modifications to be made.
Objects **always** have a minimum of 3 attributes:
```
["quote", 5, 7]
```
object[0] is a string representing the attribute type. They are
documented below. The next two items are the indices of the
property in the body string. The way clients are to access these
indices is beyond the scope of this document; accessing a subsequence
varies a lot between programming languages.
too many things and I suck at git
2017-03-01 21:54:56 +00:00
Some objects will provide further arguments beyond those 3. They will
always be at the end of the array.
| Name | Description |
yeah nevermind on markdown tables
2017-03-01 23:16:01 +00:00
|-------------+----------------------------------------------------------|
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| `quote` | This is a string that refers to a previous post number. |
| | These are formatted like >>5, which means it is a |
| | reference to `post_id` 5. These are not processed in |
| | thread OPs. >>0 may be used to refer to the OP. In |
| | addition to the indices at i[1] and i[2], a fourth value |
| | is provided, which is an integer of the `post_id` being |
| | quoted. Note that the string indices include the >>'s. |
yeah nevermind on markdown tables
2017-03-01 23:16:01 +00:00
|-------------+----------------------------------------------------------|
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| `linequote` | This is a line of text, denoted by a newline during |
| | composure, representing text that is assumed to be |
| | a quote of someone else. The indices span from the > |
| | until (not including) the newline. |
yeah nevermind on markdown tables
2017-03-01 23:16:01 +00:00
|-------------+----------------------------------------------------------|
| `color` | This is a block of text, denoted by [[color: body]] |
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| | during composure. The body may span across newlines. |
| | A fourth item is provided in the array: it is one of the |
| | following strings representing the color. |
| | `red`, `green`, `yellow`, `blue`, `magenta`, or `cyan`. |
yeah nevermind on markdown tables
2017-03-01 23:16:01 +00:00
|-------------+----------------------------------------------------------|
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| `bold` | Like color, except that no additional attribute is |
yeah nevermind on markdown tables
2017-03-01 23:16:01 +00:00
| `italic` | provided. it is denoted as [[directive: body]] during |
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| `underline` | composure. |
hi
2017-03-01 16:59:33 +00:00
Threads & Replies
-----------------
Threads are represented the same when using `thread_index` and
`thread_load`, except that the `replies` attribute is only
present with `thread_load`. The following attributes are
available on the parent object:
| Name | Description |
|---------------|------------------------------------------------------|
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| `author` | The ID string of the author. |
hi
2017-03-01 16:59:33 +00:00
|---------------|------------------------------------------------------|
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| `thread_id` | The ID string of the thread. |
hi
2017-03-01 16:59:33 +00:00
|---------------|------------------------------------------------------|
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| `title` | The title string of the thread. |
hi
2017-03-01 16:59:33 +00:00
|---------------|------------------------------------------------------|
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| `body` | The body string of the post's text. |
hi
2017-03-01 16:59:33 +00:00
|---------------|------------------------------------------------------|
| `entities` | A (possibly empty) array of entity objects for |
| | the post `body`. |
|---------------|------------------------------------------------------|
| `tags` | An array of strings representing tags the |
| | author gave to the thread at creation. |
| | When empty, it is an array with no elements. |
|---------------|------------------------------------------------------|
| `replies` | An array containing full reply objects in |
| | the order they were posted. Your clients |
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| | do not need to sort these. Array can be empty. |
hi
2017-03-01 16:59:33 +00:00
|---------------|------------------------------------------------------|
| `reply_count` | An integer representing the number of replies |
| | that have been posted in this thread. |
|---------------|------------------------------------------------------|
| `lastmod` | Unix timestamp of when the thread was last |
| | posted in, or a message was edited. |
|---------------|------------------------------------------------------|
markdown spam
2017-03-01 23:12:15 +00:00
| `edited` | Boolean of whether the post has been edited. |
hi
2017-03-01 16:59:33 +00:00
|---------------|------------------------------------------------------|
| `created` | Unix timestamp of when the post was originally made. |
The following attributes are available on each reply object in `replies`:
| Name | Description |
|------------|---------------------------------------------------------|
| `post_id` | An integer of the posts ID; unlike thread and user ids, |
| | this is not a uuid but instead is incremental, starting |
| | from 1 as the first reply and going up by one for each |
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| | post. These may be referenced by `quote` entities. |
hi
2017-03-01 16:59:33 +00:00
|------------|---------------------------------------------------------|
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| `author` | Author ID string |
hi
2017-03-01 16:59:33 +00:00
|------------|---------------------------------------------------------|
too many things and I suck at git
2017-03-01 21:54:56 +00:00
| `body` | The body string the reply's text. |
hi
2017-03-01 16:59:33 +00:00
|------------|---------------------------------------------------------|
| `entities` | A (possibly empty) array of entity objects for |
| | the reply `body`. |
|------------|---------------------------------------------------------|
| `lastmod` | Unix timestamp of when the post was last edited, or |
| | the same as `created` if it never was. |
|------------|---------------------------------------------------------|
| `edited` | A boolean of whether the post was edited. |
|------------|---------------------------------------------------------|
| `created` | Unix timestamp of when the reply was originally posted. |
Errors
------
Errors are represented in the `error` field of the response. The error
field is always present, but is usually false. If its not false, it is
an object with the fields `code` and `description`. `code` is an integer
representing the type of failure, and `description` is a string describing
the problem. `description` is intended for human consumption; in your client
code, use the error codes to handle conditions. The `presentable` column
indicates whether the `description` should be shown to users verbatim.
primitive message editing support; new sanity checks
2017-03-03 22:26:59 +00:00
| Code | Presentable | Documentation |
|------+--------------+----------------------------------------------------|
| 0 | Never, fix | Malformed json input. `description` is the error |
| | your client | string thrown by the server-side json decoder. |
|------+--------------+----------------------------------------------------|
| 1 | Not a good | Internal server error. Unaltered exception text |
| | idea, the | is returned as `description`. This shouldn't |
| | exceptions | happen, and if it does, make a bug report. |
| | are not | clients should not attempt to intelligently |
| | helpful | recover from any errors of this class. |
|------+--------------+----------------------------------------------------|
| 2 | Nadda. | Unknown `method` was requested. |
|------+--------------+----------------------------------------------------|
| 3 | Fix. Your. | Missing, malformed, or otherwise incorrect |
| | Client. | parameters or values for the requested `method`. |
| | | This is returned, for example, when a request to |
| | | `edit_post` tries to edit a post_id that does |
| | | not exist. Its also used to indicate a lack of |
| | | required arguments for a method. This is a generic |
| | | error class that can cover programming errors |
| | | but never user errors. |
|------+--------------+----------------------------------------------------|
| 4 | Only during | Invalid or unprovided `user`. |
| | registration | |
| | | During registration, this code is returned with a |
| | | `description` that should be shown to the user. |
| | | It could indicate an invalid name input, an |
| | | occupied username, invalid/missing `auth_hash`, |
| | | etc. |
|------+--------------+----------------------------------------------------|
| 5 | Always | `user` is not registered. |
|------+--------------+----------------------------------------------------|
| 6 | Always | User `auth_hash` failed or was not provided. |
|------+--------------+----------------------------------------------------|
| 7 | Always | Requested thread does not exist. |
|------+--------------+----------------------------------------------------|
| 8 | Always | Requested thread does not allow posts. |
|------+--------------+----------------------------------------------------|
| 9 | Always | Message edit failed; there is a 24hr limit for |
| | | editing posts. |
|------+--------------+----------------------------------------------------|
| 10 | Always | User action requires `admin` privilege. |
|------+--------------+----------------------------------------------------|
| 11 | Always | Invalid formatting directives in text submission. |