aaaaaaaaa markdown and orgtables AAAAAA

1 files changed, 183 insertions, 0 deletions

diff --git a/docs/protocol.md b/docs/protocol.md
new file mode 100644
index 0000000..36b1702
--- /dev/null
+++ b/docs/protocol.md
@@ -0,0 +1,183 @@
+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.
+
+
+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
+implementation like an Emacs or GUI, they can provide
+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.
+
+Some objects will provide further arguments beyond those 3. They will
+always be at the end of the array.
+
+| Name        | Description                                              |
+|-------------+----------------------------------------------------------|
+| `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.   |
+|-------------+----------------------------------------------------------|
+| `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.                       |
+|-------------+----------------------------------------------------------|
+| `color`     | This is a block of text, denoted by [[color: body]]          |
+|             | 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`.  |
+|-------------+----------------------------------------------------------|
+| `bold`      | Like color, except that no additional attribute is       |
+| `italic`    | provided. it is denoted as [[directive: body]] during        |
+| `underline` | composure.                                               |
+
+
+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                                          |
+|---------------|------------------------------------------------------|
+| `author`      | The ID string of the author.                         |
+|---------------|------------------------------------------------------|
+| `thread_id`   | The ID string of the thread.                         |
+|---------------|------------------------------------------------------|
+| `title`       | The title string of the thread.                      |
+|---------------|------------------------------------------------------|
+| `body`        | The body string of the post's text.                  |
+|---------------|------------------------------------------------------|
+| `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             |
+|               | do not need to sort these. Array can be empty.       |
+|---------------|------------------------------------------------------|
+| `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.                  |
+|---------------|------------------------------------------------------|
+| `edited`      | Boolean of whether the post has been edited.     |
+|---------------|------------------------------------------------------|
+| `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  |
+|            | post. These may be referenced by `quote` entities.      |
+|------------|---------------------------------------------------------|
+| `author`   | Author ID string                                        |
+|------------|---------------------------------------------------------|
+| `body`     | The body string the reply's text.                       |
+|------------|---------------------------------------------------------|
+| `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.
+
+| 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 or malformed parameter values for the     |
+|      | Client.      | requested `method`.                               |
+|------|--------------|---------------------------------------------------|
+|    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. |