{{title}}
3 |{{summary}}
4 |404
86 |Page not found
87 |
92 |
139 |
140 |
144 |
145 |
146 |
170 |
171 |
172 |
173 |
--------------------------------------------------------------------------------
/docs/site/fonts/fontawesome-webfont.eot:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/fonts/fontawesome-webfont.eot
--------------------------------------------------------------------------------
/docs/site/fonts/fontawesome-webfont.ttf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/fonts/fontawesome-webfont.ttf
--------------------------------------------------------------------------------
/docs/site/fonts/fontawesome-webfont.woff:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/fonts/fontawesome-webfont.woff
--------------------------------------------------------------------------------
/docs/site/fonts/fontawesome-webfont.woff2:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/fonts/fontawesome-webfont.woff2
--------------------------------------------------------------------------------
/docs/site/fonts/glyphicons-halflings-regular.eot:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/fonts/glyphicons-halflings-regular.eot
--------------------------------------------------------------------------------
/docs/site/fonts/glyphicons-halflings-regular.ttf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/fonts/glyphicons-halflings-regular.ttf
--------------------------------------------------------------------------------
/docs/site/fonts/glyphicons-halflings-regular.woff:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/fonts/glyphicons-halflings-regular.woff
--------------------------------------------------------------------------------
/docs/site/fonts/glyphicons-halflings-regular.woff2:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/fonts/glyphicons-halflings-regular.woff2
--------------------------------------------------------------------------------
/docs/site/img/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/img/favicon.ico
--------------------------------------------------------------------------------
/docs/site/img/grid.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/img/grid.png
--------------------------------------------------------------------------------
/docs/site/img/screenshot.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/docs/site/img/screenshot.png
--------------------------------------------------------------------------------
/docs/site/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
97 |
98 |
99 |
138 | Handling Error Responses
100 |Errors in BBJ are separated into 6 different codes, to allow easy mapping to 101 | native exception and signaling systems available in the client's programming 102 | language. Errors are all or nothing, there are no "warnings". If a response has 103 | a non-false error field, then data will always be null. An error response from 104 | the api looks like this...
105 |{
106 | "error": {
107 | "code": // an integer from 0 to 5,
108 | "description": // a string describing the error in detail.
109 | }
110 | "data": null // ALWAYS null if error is not false
111 | "usermap": {} // ALWAYS empty if error is not false
112 | }
113 | The codes split errors into categories. Some are oriented 116 | to client developers while others should be shown directly to 117 | users.
118 |-
119 |
-
120 |
Code 0: Malformed but non-empty json input. An empty json input where it is required is handled by code 3. This is just decoding errors. The exception text is returned as description.
121 |
122 | -
123 |
Code 1: Internal server error. A short representation of the internal exception as well as the code the server logged it as is returned in the description. Your clients cannot recover from this class of error, and its probably not your fault if you encounter it. If you ever get one, file a bug report.
124 |
125 | -
126 |
Code 2: Server HTTP error: This is similar to the above but captures errors for the HTTP server rather than BBJs own codebase. The description contains the HTTP error code and server description. This notably covers 404s and thus invalid endpoint names. The HTTP error code is left intact, so you may choose to let your HTTP library or tool of choice handle these for you.
127 |
128 | -
129 |
Code 3: Parameter error: client sent erroneous input for its method. This could mean missing arguments, type errors, etc. It generalizes errors that should be fixed by the client developer and the returned descriptions are geared to them rather than end users.
130 |
131 | -
132 |
Code 4: User error: These errors regard actions that the user has taken that are invalid, but not really errors in a traditional sense. The description field should be shown to users verbatim, in a clear and noticeable fashion. They are formatted as concise English sentences and end with appropriate punctuation marks.
133 |
134 | -
135 |
Code 5: Authorization error: This code represents an erroneous User/Auth header pair. This should trigger the user to provide correct credentials or fall back to anon mode.
136 |
137 |
92 |
115 |
116 |
120 |
121 |
122 |
146 |
147 |
148 |
149 |
150 |
154 |
--------------------------------------------------------------------------------
/docs/site/js/base.js:
--------------------------------------------------------------------------------
1 | function getSearchTerm()
2 | {
3 | var sPageURL = window.location.search.substring(1);
4 | var sURLVariables = sPageURL.split('&');
5 | for (var i = 0; i < sURLVariables.length; i++)
6 | {
7 | var sParameterName = sURLVariables[i].split('=');
8 | if (sParameterName[0] == 'q')
9 | {
10 | return sParameterName[1];
11 | }
12 | }
13 | }
14 |
15 | $(document).ready(function() {
16 |
17 | var search_term = getSearchTerm(),
18 | $search_modal = $('#mkdocs_search_modal');
19 |
20 | if(search_term){
21 | $search_modal.modal();
22 | }
23 |
24 | // make sure search input gets autofocus everytime modal opens.
25 | $search_modal.on('shown.bs.modal', function () {
26 | $search_modal.find('#mkdocs-search-query').focus();
27 | });
28 |
29 | // Highlight.js
30 | hljs.initHighlightingOnLoad();
31 | $('table').addClass('table table-striped table-hover');
32 |
33 | // Improve the scrollspy behaviour when users click on a TOC item.
34 | $(".bs-sidenav a").on("click", function() {
35 | var clicked = this;
36 | setTimeout(function() {
37 | var active = $('.nav li.active a');
38 | active = active[active.length - 1];
39 | if (clicked !== active) {
40 | $(active).parent().removeClass("active");
41 | $(clicked).parent().addClass("active");
42 | }
43 | }, 50);
44 | });
45 |
46 | });
47 |
48 |
49 | $('body').scrollspy({
50 | target: '.bs-sidebar',
51 | });
52 |
53 | /* Toggle the `clicky` class on the body when clicking links to let us
54 | retrigger CSS animations. See ../css/base.css for more details. */
55 | $('a').click(function(e) {
56 | $('body').toggleClass('clicky');
57 | });
58 |
59 | /* Prevent disabled links from causing a page reload */
60 | $("li.disabled a").click(function() {
61 | event.preventDefault();
62 | });
63 |
--------------------------------------------------------------------------------
/docs/site/mkdocs/js/lunr.min.js:
--------------------------------------------------------------------------------
1 | /**
2 | * lunr - http://lunrjs.com - A bit like Solr, but much smaller and not as bright - 0.7.0
3 | * Copyright (C) 2016 Oliver Nightingale
4 | * MIT Licensed
5 | * @license
6 | */
7 | !function(){var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.7.0",t.utils={},t.utils.warn=function(t){return function(e){t.console&&console.warn&&console.warn(e)}}(this),t.utils.asString=function(t){return void 0===t||null===t?"":t.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var t=Array.prototype.slice.call(arguments),e=t.pop(),n=t;if("function"!=typeof e)throw new TypeError("last argument must be a function");n.forEach(function(t){this.hasHandler(t)||(this.events[t]=[]),this.events[t].push(e)},this)},t.EventEmitter.prototype.removeListener=function(t,e){if(this.hasHandler(t)){var n=this.events[t].indexOf(e);this.events[t].splice(n,1),this.events[t].length||delete this.events[t]}},t.EventEmitter.prototype.emit=function(t){if(this.hasHandler(t)){var e=Array.prototype.slice.call(arguments,1);this.events[t].forEach(function(t){t.apply(void 0,e)})}},t.EventEmitter.prototype.hasHandler=function(t){return t in this.events},t.tokenizer=function(e){return arguments.length&&null!=e&&void 0!=e?Array.isArray(e)?e.map(function(e){return t.utils.asString(e).toLowerCase()}):e.toString().trim().toLowerCase().split(t.tokenizer.seperator):[]},t.tokenizer.seperator=/[\s\-]+/,t.tokenizer.load=function(t){var e=this.registeredFunctions[t];if(!e)throw new Error("Cannot load un-registered function: "+t);return e},t.tokenizer.label="default",t.tokenizer.registeredFunctions={"default":t.tokenizer},t.tokenizer.registerFunction=function(e,n){n in this.registeredFunctions&&t.utils.warn("Overwriting existing tokenizer: "+n),e.label=n,this.registeredFunctions[n]=e},t.Pipeline=function(){this._stack=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in this.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[e.label]=e},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.registeredFunctions[e];if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._stack.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._stack.indexOf(e);if(-1==i)throw new Error("Cannot find existingFn");i+=1,this._stack.splice(i,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._stack.indexOf(e);if(-1==i)throw new Error("Cannot find existingFn");this._stack.splice(i,0,n)},t.Pipeline.prototype.remove=function(t){var e=this._stack.indexOf(t);-1!=e&&this._stack.splice(e,1)},t.Pipeline.prototype.run=function(t){for(var e=[],n=t.length,i=this._stack.length,r=0;n>r;r++){for(var o=t[r],s=0;i>s&&(o=this._stack[s](o,r,t),void 0!==o&&""!==o);s++);void 0!==o&&""!==o&&e.push(o)}return e},t.Pipeline.prototype.reset=function(){this._stack=[]},t.Pipeline.prototype.toJSON=function(){return this._stack.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Vector=function(){this._magnitude=null,this.list=void 0,this.length=0},t.Vector.Node=function(t,e,n){this.idx=t,this.val=e,this.next=n},t.Vector.prototype.insert=function(e,n){this._magnitude=void 0;var i=this.list;if(!i)return this.list=new t.Vector.Node(e,n,i),this.length++;if(e
98 |
99 |
100 |
114 | Bulletin Butter & Jelly
101 |A simple community textboard
102 |BBJ is a trivial collection of python scripts and database queries that miraculously shit out a fully functional client-server textboard with Python 3.4+
103 |See also: the GitHub repository.
104 |BBJ is heavily inspired by image boards like 4chan, but it offers a simple 105 | account system to allow users to identify themselves and set profile 106 | attributes like a more traditional forum. Registration is optional and there 107 | are only minimal restrictions on anonymous participation.
108 |
Being a command-line-oriented text board, BBJ has no avatars or file sharing 110 | capabilties, so its easier to administrate and can't be used to distribute illegal 111 | content like imageboards. It has very few dependancies and is easy to set up.
112 |The API is simple and doesn't use require complex authorization schemes or session management. 113 | It is fully documented on this site (though the verbage is still being revised for friendliness)
No results found
"); 64 | } 65 | 66 | if(jQuery){ 67 | /* 68 | * We currently only automatically hide bootstrap models. This 69 | * requires jQuery to work. 70 | */ 71 | jQuery('#mkdocs_search_modal a').click(function(){ 72 | jQuery('#mkdocs_search_modal').modal('hide'); 73 | }); 74 | } 75 | 76 | }; 77 | 78 | var search_input = document.getElementById('mkdocs-search-query'); 79 | 80 | var term = getSearchTerm(); 81 | if (term){ 82 | search_input.value = term; 83 | search(); 84 | } 85 | 86 | search_input.addEventListener("keyup", search); 87 | 88 | }); 89 | -------------------------------------------------------------------------------- /docs/site/mkdocs/js/text.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @license RequireJS text 2.0.12 Copyright (c) 2010-2014, The Dojo Foundation All Rights Reserved. 3 | * Available via the MIT or new BSD license. 4 | * see: http://github.com/requirejs/text for details 5 | */ 6 | /*jslint regexp: true */ 7 | /*global require, XMLHttpRequest, ActiveXObject, 8 | define, window, process, Packages, 9 | java, location, Components, FileUtils */ 10 | 11 | define(['module'], function (module) { 12 | 'use strict'; 13 | 14 | var text, fs, Cc, Ci, xpcIsWindows, 15 | progIds = ['Msxml2.XMLHTTP', 'Microsoft.XMLHTTP', 'Msxml2.XMLHTTP.4.0'], 16 | xmlRegExp = /^\s*<\?xml(\s)+version=[\'\"](\d)*.(\d)*[\'\"](\s)*\?>/im, 17 | bodyRegExp = /
92 |
181 |
182 |
186 |
187 |
188 |
212 |
213 |
214 |
215 |
--------------------------------------------------------------------------------
/gendocs.sh:
--------------------------------------------------------------------------------
1 | #!/bin/sh
2 | # Generate the documentation site.
3 | # Invoke with no arguments in the base repo directory.
4 | # Nothing magical here.
5 |
6 | python3 ./mkendpoints.py
7 | cd ./docs
8 | mkdocs build
9 | cd ..
10 |
--------------------------------------------------------------------------------
/js/datetime.js:
--------------------------------------------------------------------------------
1 | function divmod(x, y) {
2 | return [Math.floor(x / y), x % y];
3 | }
4 |
5 | function timestring(timestamp) {
6 | time_milliseconds = timestamp * 1000
7 | date = new Date(time_milliseconds);
8 | return date.toLocaleDateString() + " " + date.toLocaleTimeString()
9 | }
10 |
11 | function readable_delta(timestamp) {
12 | current_time_seconds = Date.now() / 1000
13 | delta = current_time_seconds - timestamp
14 | mod = divmod(delta, 3600)
15 | hours = mod[0]
16 | remainder = mod[1]
17 | if (hours > 48) {
18 | return timestring(timestamp)
19 | }
20 | else if (hours > 1) {
21 | return hours + " hours ago"
22 | }
23 | else if (hours == 1) {
24 | return "about an hour ago"
25 | }
26 | mod = divmod(remainder, 60)
27 | minutes = mod[0]
28 | remainder = mod[1]
29 | if (minutes > 1) {
30 | return minutes + " minutes ago"
31 | }
32 | return "less than a minute ago"
33 | }
34 |
35 | timestamps = document.getElementsByClassName("datetime")
36 | for (let i = 0; i < timestamps.length; i++) {
37 | delta = readable_delta(timestamps[i].textContent)
38 | timestamps[i].textContent = delta
39 | }
--------------------------------------------------------------------------------
/js/postboxes.js:
--------------------------------------------------------------------------------
1 | function revealPostReplyBox(post_id) {
2 | domElement = document.getElementById("replyBox" + post_id)
3 | document.getElementById("replyLink" + post_id).remove()
4 |
5 | form = document.createElement("form")
6 | form.setAttribute("method", "post")
7 | form.setAttribute("action", "/threadReply")
8 |
9 | textarea = document.createElement("textarea")
10 | textarea.setAttribute("class", "directReplyBox")
11 | textarea.setAttribute("id", "postContent")
12 | textarea.setAttribute("name", "postContent")
13 | textarea.setAttribute("rows", "10")
14 | textarea.setAttribute("cols", "50")
15 | textarea.value = ">>" + post_id + " \n"
16 |
17 | input = document.createElement("input")
18 | input.setAttribute("name", "threadId")
19 | input.value = thread_id
20 | input.style = "display:none"
21 |
22 | submit = document.createElement("input")
23 | submit.setAttribute("class", "directReplyBox")
24 | submit.setAttribute("type", "submit")
25 | submit.setAttribute("value", "Submit")
26 |
27 | form.appendChild(textarea)
28 | form.appendChild(input)
29 | form.appendChild(document.createElement("br"))
30 | form.appendChild(submit)
31 |
32 | domElement.appendChild(form)
33 |
34 | }
35 |
36 | function revealThreadCreateForm() {
37 | form = document.getElementById("threadCreateBox")
38 | if (form.style.display == "none") {
39 | form.style.display = "block"
40 | } else {
41 | form.style.display = "none"
42 | }
43 | }
44 |
45 | function revealPostReplyForm() {
46 | form = document.getElementById("postReplyBox")
47 | if (form.style.display == "none") {
48 | form.style.display = "block"
49 | } else {
50 | form.style.display = "none"
51 | }
52 | }
--------------------------------------------------------------------------------
/mkendpoints.py:
--------------------------------------------------------------------------------
1 | """
2 | This is a small script that creates the endpoint doc page. It should be
3 | evoked from the command line each time changes are made. It writes
4 | to ./docs/docs/api_overview.md
5 |
6 | The code used in this script is the absolute minimum required to
7 | get the job done; it can be considered a crude hack at best. I am
8 | more interested in writing good documentation than making sure that
9 | the script that shits it out is politcally correct ;)
10 | """
11 |
12 | from server import API
13 | import pydoc
14 |
15 | body = """
16 | # How to BBJ?
17 |
18 | ## Input
19 |
20 | BBJ is interacted with entirely through POST requests, whose bodies are
21 | json objects.
22 |
23 | The endpoints, all listed below, can be contacted at the path /api/ relative
24 | to the root of where BBJ is hosted. If bbj is hosted on a server on port 80
25 | at the root:
26 |
27 | `http://server.com/api/endpoint_here`
28 |
29 | The body of your request contains all of it's argument fields, instead of
30 | using URL parameters. As a demonstration, to call `thread_create`,
31 | it requires two arguments: `title`, and `body`. We put those argument
32 | names at the root of the json object, and their values are the info
33 | passed into the API for that spot. Your input will look like this:
34 |
35 | ```json
36 | {
37 | "title": "Hello world!!",
38 | "body": "Hi! I am exploring this cool board thing!!"
39 | }
40 | ```
41 |
42 | And you will POST this body to `http://server.com:PORT/api/thread_create`.
43 |
44 | A few endpoints do not require any arguments. These can still be POSTed to,
45 | but the body may be completely empty or an empty json object. You can even
46 | GET these if you so choose.
47 |
48 | For all endpoints, argument keys that are not consumed by the endpoint are
49 | ignored. Posting an object with a key/value pair of `"sandwich": True` will
50 | not clog up any pipes :) In the same vein, endpoints who dont take arguments
51 | don't care if you supply them anyway.
52 |
53 | ## Output
54 |
55 | BBJ returns data in a consistently formatted json object. The base object
56 | has three keys: `data`, `usermap`, and `error`. Visualizied:
57 |
58 | ```javascript
59 | {
60 | "error": false, // boolean false or error object
61 | "data": null, // null or the requested data from endpoint.
62 | "usermap": {} // potentially empty object, maps user_ids to user objects
63 | }
64 |
65 | // If "error" is true, it looks like this:
66 |
67 | {
68 | "error": {
69 | "code": // an integer from 0 to 5,
70 | "description": // a string describing the error in detail.
71 | }
72 | "data": null // ALWAYS null if error is not false
73 | "usermap": {} // ALWAYS empty if error is not false
74 | }
75 | ```
76 |
77 | ### data
78 |
79 | `data` is what the endpoint actually returns. The type of contents vary
80 | by endpoint and are documented below. If an endpoint says it returns a
81 | boolean, it will look like `"data": True`. If it says it returns an array,
82 | it will look like `"data": ["stuff", "goes", "here"]`
83 |
84 | ### usermap
85 |
86 | The usermap is a json object mapping user_ids within `data` to full user
87 | objects. BBJ handles users entirely by an ID system, meaning any references
88 | to them inside of response data will not include vital information like their
89 | username, or their profile information. Instead, we fetch those values from
90 | this usermap object. All of it's root keys are user_id's and their values
91 | are user objects. It should be noted that the anonymous user has it's own
92 | ID and profile object as well.
93 |
94 | ### error
95 |
96 | `error` is typically `false`. If it is __not__ false, then the request failed
97 | and the json object that `error` contains should be inspected. (see the above
98 | visualation) Errors follow a strict code system, making it easy for your client
99 | to map these responses to native exception types or signals in your language of
100 | choice. See [the full error page](errors.md) for details.
101 |
102 |
103 | """
104 |
105 | extra = {
106 | "Authorization": "See also [the Authorization page](authorization.md).",
107 | "Users": "",
108 | "Threads & Messages": "",
109 | "Tools": ""
110 | }
111 |
112 | endpoints = [
113 | ref for name, ref in API.__dict__.items()
114 | if hasattr(ref, "exposed")
115 | ]
116 |
117 | types = {
118 | function.doctype: list() for function in endpoints
119 | }
120 |
121 | for function in endpoints:
122 | types[function.doctype].append(function)
123 |
124 | for doctype in sorted(types.keys()):
125 | body += "
97 |
98 |
99 |
180 | Implementing good sanity checks in your client.
100 |The server has an endpoint called db_validate. What this does is take
101 | a key and a value argument, and compares value to a set of rules specified by
102 | key. This is the same function used internally by the database to check
103 | values before committing them to the database. By default it returns a
104 | descriptive object under data, but you can specify the key/value pair
105 | "error": True to get a standard error response back. A standard call
106 | to db_validate will look like this.
{
108 | "key": "title",
109 | "value": "this title\nis bad \nbecause it contains \nnewlines"
110 | }
111 | and the server will respond like this when the input should be corrected.
114 |{
115 | "data": {
116 | "bool": False,
117 | "description": "Titles cannot contain whitespace characters besides spaces."
118 | },
119 | "error": False,
120 | "usermap": {}
121 | }
122 | if everything is okay, the data object will look like this instead.
125 | "data": {
126 | "bool": True,
127 | "description": null
128 | },
129 | Alternatively, you can supply "error": True in the request.
{
133 | "error": True,
134 | "key": "title",
135 | "value": "this title\nis bad \nbecause it contains \nnewlines"
136 | }
137 | // and you get...
138 | {
139 | "data": null,
140 | "usermap": {},
141 | "error": {
142 | "code": 4,
143 | "description": "Titles cannot contain whitespace characters besides spaces."
144 | }
145 | }
146 | The following keys are currently available.
149 |-
150 |
- "user_name" 151 |
- "auth_hash" 152 |
- "quip" 153 |
- "bio" 154 |
- "title" 155 |
- "body" 156 |
- "color" 157 |
The descriptions returned are friendly, descriptive, and should be shown 159 | directly to users
160 |By using this endpoint, you will never have to validate values in your 161 | own code before sending them to the server. This means you can do things 162 | like implement an interactive prompt which will not allow the user to 163 | submit it unless the value is correct.
164 |This is used in the elisp client when registering users and for the thread 165 | title prompt which is shown before opening a composure window. The reason 166 | for rejection is displayed clearly to the user and input window is restored.
167 |(defun bbj-sane-value (prompt key)
168 | "Opens an input loop with the user, where the response is
169 | passed to the server to check it for validity before the
170 | user is allowed to continue. Will recurse until the input
171 | is valid, then it is returned."
172 | (let* ((value (read-from-minibuffer prompt))
173 | (response (bbj-request! 'db_validate 'value value 'key key)))
174 | (if (alist-get 'bool response)
175 | value ;; return the user's input back to the caller
176 | (message (alist-get 'description response))
177 | (sit-for 2)
178 | (bbj-sane-value prompt key))))
179 | \n# %s\n------\n" % doctype 126 | desc = extra[doctype] 127 | if desc: 128 | body += desc + "\n" 129 | funcs = sorted(types[doctype], key=lambda _: _.__name__) 130 | for f in funcs: 131 | body += "## %s\n\n" % f.__name__ 132 | if f.arglist[0][0]: 133 | body += "**Arguments:**\n\n" 134 | for key, value in f.arglist: 135 | body += " * __%s__: %s\n\n" % (key, value) 136 | else: 137 | body += "_requires no arguments_" 138 | 139 | body += "\n\n" + pydoc.getdoc(f) + "\n\n" 140 | body += "\n
\n" 141 | 142 | with open("docs/docs/api_overview.md", "w") as output: 143 | output.write(body) 144 | -------------------------------------------------------------------------------- /prototype/clients/network_client.py: -------------------------------------------------------------------------------- 1 | from hashlib import sha256 2 | import socket 3 | import json 4 | 5 | 6 | class BBJ: 7 | def __init__(self, host, port): 8 | self.host = host 9 | self.port = port 10 | self.username = None 11 | self.auth_hash = None 12 | 13 | 14 | def __call__(self, method, **params): 15 | return self.request(method, **params) 16 | 17 | 18 | def setuser(self, username, unhashed_password): 19 | self.auth_hash = sha256(bytes(unhashed_password, "utf8")).hexdigest() 20 | self.username = username 21 | return self.auth_hash 22 | 23 | 24 | def request(self, method, **params): 25 | params["method"] = method 26 | 27 | if not params.get("user") and self.username: 28 | params["user"] = self.username 29 | 30 | if not params.get("auth_hash") and self.auth_hash: 31 | params["auth_hash"] = self.auth_hash 32 | 33 | 34 | connection = socket.create_connection((self.host, self.port)) 35 | connection.sendall(bytes(json.dumps(params), "utf8")) 36 | connection.shutdown(socket.SHUT_WR) 37 | 38 | try: 39 | buff, length = bytes(), 1 40 | while length != 0: 41 | recv = connection.recv(2048) 42 | length = len(recv) 43 | buff += recv 44 | 45 | finally: 46 | connection.close() 47 | 48 | response = json.loads(str(buff, "utf8")) 49 | if not isinstance(response, dict): 50 | return response 51 | 52 | error = response.get("error") 53 | if not error: 54 | return response 55 | 56 | code, desc = error["code"], error["description"] 57 | 58 | # tfw no qt3.14 python case switches 59 | if error in (0, 1): 60 | raise ChildProcessError("internal server error: " + desc) 61 | elif error in (2, 3): 62 | raise ChildProcessError(desc) 63 | 64 | return response 65 | -------------------------------------------------------------------------------- /prototype/clients/urwid/main.py: -------------------------------------------------------------------------------- 1 | from src import network 2 | 3 | 4 | bbj = network.BBJ("192.168.1.137", 7066) 5 | 6 | 7 | def geterr(obj): 8 | """ 9 | Returns false if there are no errors in a network response, 10 | else a tuple of (code integer, description string) 11 | """ 12 | error = obj.get("error") 13 | if not error: 14 | return False 15 | return (error["code"], error["description"]) 16 | 17 | 18 | def register_prompt(user, initial=True): 19 | if initial: 20 | print("Register for BBJ as {}?".format(user)) 21 | reply = input("(y[es], d[ifferent name], q[uit])> ").lower() 22 | 23 | if reply.startswith("d"): 24 | register_prompt(input("(Username)> ")) 25 | elif reply.startswith("q"): 26 | exit("bye!") 27 | 28 | def getpass(ok): 29 | p1 = input( 30 | "(Choose a password)> " if ok else \ 31 | "(Those didn't match. Try again)> ") 32 | p2 = input("(Now type it one more time)> ") 33 | return p1 if p1 == p2 else getpass(False) 34 | 35 | # this method will sha256 it for us 36 | bbj.setuser(user, getpass(True)) 37 | 38 | response = bbj("user_register", quip="", bio="") 39 | error = geterr(response) 40 | if error: 41 | exit("Registration error: " + error[1]) 42 | return response 43 | 44 | 45 | def login(user, ok=True): 46 | if not bbj("is_registered", target_user=user): 47 | register_prompt(user) 48 | else: 49 | bbj.setuser(user, input( 50 | "(Password)> " if ok else \ 51 | "(Invalid password, try again)> ")) 52 | 53 | if not bbj("check_auth"): 54 | login(user, ok=False) 55 | 56 | return bbj("user_get", target_user=user) 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | # user = input("(BBJ Username)> ") 65 | # if not bbj("is_registered", target_user=user): 66 | 67 | 68 | login(input("(Username)> ")) 69 | 70 | import urwid 71 | 72 | f = urwid.Frame( 73 | urwid.ListBox( 74 | urwid.SimpleFocusListWalker( 75 | [urwid.Text(i["body"]) for i in bbj("thread_index")["threads"]] 76 | ) 77 | ) 78 | ) 79 | 80 | t = urwid.Overlay( 81 | f, urwid.SolidFill('!'), 82 | align='center', 83 | width=('relative', 80), 84 | height=('relative', 80), 85 | valign='middle' 86 | ) 87 | 88 | loop = urwid.MainLoop(t) 89 | -------------------------------------------------------------------------------- /prototype/clients/urwid/src/network.py: -------------------------------------------------------------------------------- 1 | from hashlib import sha256 2 | import socket 3 | import json 4 | 5 | 6 | class BBJ: 7 | def __init__(self, host, port): 8 | self.host = host 9 | self.port = port 10 | self.username = None 11 | self.auth_hash = None 12 | 13 | 14 | def __call__(self, method, **params): 15 | return self.request(method, **params) 16 | 17 | 18 | def setuser(self, username, unhashed_password): 19 | self.auth_hash = sha256(bytes(unhashed_password, "utf8")).hexdigest() 20 | self.username = username 21 | return self.auth_hash 22 | 23 | 24 | def request(self, method, **params): 25 | params["method"] = method 26 | 27 | if not params.get("user") and self.username: 28 | params["user"] = self.username 29 | 30 | if not params.get("auth_hash") and self.auth_hash: 31 | params["auth_hash"] = self.auth_hash 32 | 33 | 34 | connection = socket.create_connection((self.host, self.port)) 35 | connection.sendall(bytes(json.dumps(params), "utf8")) 36 | connection.shutdown(socket.SHUT_WR) 37 | 38 | try: 39 | buff, length = bytes(), 1 40 | while length != 0: 41 | recv = connection.recv(2048) 42 | length = len(recv) 43 | buff += recv 44 | 45 | finally: 46 | connection.close() 47 | 48 | response = json.loads(str(buff, "utf8")) 49 | if not isinstance(response, dict): 50 | return response 51 | 52 | error = response.get("error") 53 | if not error: 54 | return response 55 | 56 | code, desc = error["code"], error["description"] 57 | 58 | # tfw no qt3.14 python case switches 59 | if error in (0, 1): 60 | raise ChildProcessError("internal server error: " + desc) 61 | elif error in (2, 3): 62 | raise ChildProcessError(desc) 63 | 64 | return response 65 | -------------------------------------------------------------------------------- /prototype/clients/urwid/src/widgets.py: -------------------------------------------------------------------------------- 1 | import urwid 2 | 3 | class PostBox(urwid.ListBox): 4 | pass 5 | -------------------------------------------------------------------------------- /prototype/docs/protocol.org: -------------------------------------------------------------------------------- 1 | Data Standards 2 | -------------- 3 | 4 | 5 | * UTF-8 in, UTF-8 out. No exceptions. 6 | 7 | * SHA256 for auth_hash. Server will do a basic check to make sure of this. 8 | 9 | * Security is not a #1 concern. Basic authorization will be implemented 10 | to **help prevent** users from impersonating each other, but this isn't 11 | intended to be bulletproof and you shouldn't trust the system with a 12 | password you use elsewhere. All clients should inform the user of this. 13 | 14 | * Command-line, on-tilde comes first. Local clients should be possible using 15 | SSH port binding, however features like inline images, graphical elements 16 | and the like will never be implemented as part of the protocol. Local clients 17 | can definitely do things like URL image previews though. Hyperlinks with a 18 | different text then the link itself will never be implemented. 19 | 20 | 21 | Text Entities 22 | ------------- 23 | 24 | The `entities` attribute is an array of objects that represent blocks 25 | of text within a post that have special properties. Clients may safely 26 | ignore these things without losing too much meaning, but in a rich 27 | implementation like an Emacs or GUI, they can provide 28 | some highlighting and navigation perks. The array object may be 29 | empty. If its not, its populated with arrays representing the 30 | modifications to be made. 31 | 32 | Objects **always** have a minimum of 3 attributes: 33 | ``` 34 | ["quote", 5, 7] 35 | ``` 36 | object[0] is a string representing the attribute type. They are 37 | documented below. The next two items are the indices of the 38 | property in the body string. The way clients are to access these 39 | indices is beyond the scope of this document; accessing a subsequence 40 | varies a lot between programming languages. 41 | 42 | Some objects will provide further arguments beyond those 3. They will 43 | always be at the end of the array. 44 | 45 | | Name | Description | 46 | |-------------+----------------------------------------------------------| 47 | | `quote` | This is a string that refers to a previous post number. | 48 | | | These are formatted like >>5, which means it is a | 49 | | | reference to `post_id` 5. These are not processed in | 50 | | | thread OPs. >>0 may be used to refer to the OP. In | 51 | | | addition to the indices at i[1] and i[2], a fourth value | 52 | | | is provided, which is an integer of the `post_id` being | 53 | | | quoted. Note that the string indices include the >>'s. | 54 | |-------------+----------------------------------------------------------| 55 | | `linequote` | This is a line of text, denoted by a newline during | 56 | | | composure, representing text that is assumed to be | 57 | | | a quote of someone else. The indices span from the > | 58 | | | until (not including) the newline. | 59 | |-------------+----------------------------------------------------------| 60 | | `color` | This is a block of text, denoted by [[color: body]] | 61 | | | during composure. The body may span across newlines. | 62 | | | A fourth item is provided in the array: it is one of the | 63 | | | following strings representing the color. | 64 | | | `red`, `green`, `yellow`, `blue`, `magenta`, or `cyan`. | 65 | |-------------+----------------------------------------------------------| 66 | | `bold` | Like color, except that no additional attribute is | 67 | | `italic` | provided. it is denoted as [[directive: body]] during | 68 | | `underline` | composure. | 69 | 70 | 71 | Threads & Replies 72 | ----------------- 73 | 74 | Threads are represented the same when using `thread_index` and 75 | `thread_load`, except that the `replies` attribute is only 76 | present with `thread_load`. The following attributes are 77 | available on the parent object: 78 | 79 | | Name | Description | 80 | |---------------|------------------------------------------------------| 81 | | `author` | The ID string of the author. | 82 | |---------------|------------------------------------------------------| 83 | | `thread_id` | The ID string of the thread. | 84 | |---------------|------------------------------------------------------| 85 | | `title` | The title string of the thread. | 86 | |---------------|------------------------------------------------------| 87 | | `body` | The body string of the post's text. | 88 | |---------------|------------------------------------------------------| 89 | | `entities` | A (possibly empty) array of entity objects for | 90 | | | the post `body`. | 91 | |---------------|------------------------------------------------------| 92 | | `tags` | An array of strings representing tags the | 93 | | | author gave to the thread at creation. | 94 | | | When empty, it is an array with no elements. | 95 | |---------------|------------------------------------------------------| 96 | | `replies` | An array containing full reply objects in | 97 | | | the order they were posted. Your clients | 98 | | | do not need to sort these. Array can be empty. | 99 | |---------------|------------------------------------------------------| 100 | | `reply_count` | An integer representing the number of replies | 101 | | | that have been posted in this thread. | 102 | |---------------|------------------------------------------------------| 103 | | `lastmod` | Unix timestamp of when the thread was last | 104 | | | posted in, or a message was edited. | 105 | |---------------|------------------------------------------------------| 106 | | `edited` | Boolean of whether the post has been edited. | 107 | |---------------|------------------------------------------------------| 108 | | `created` | Unix timestamp of when the post was originally made. | 109 | 110 | The following attributes are available on each reply object in `replies`: 111 | 112 | 113 | | Name | Description | 114 | |------------|---------------------------------------------------------| 115 | | `post_id` | An integer of the posts ID; unlike thread and user ids, | 116 | | | this is not a uuid but instead is incremental, starting | 117 | | | from 1 as the first reply and going up by one for each | 118 | | | post. These may be referenced by `quote` entities. | 119 | |------------|---------------------------------------------------------| 120 | | `author` | Author ID string | 121 | |------------|---------------------------------------------------------| 122 | | `body` | The body string the reply's text. | 123 | |------------|---------------------------------------------------------| 124 | | `entities` | A (possibly empty) array of entity objects for | 125 | | | the reply `body`. | 126 | |------------|---------------------------------------------------------| 127 | | `lastmod` | Unix timestamp of when the post was last edited, or | 128 | | | the same as `created` if it never was. | 129 | |------------|---------------------------------------------------------| 130 | | `edited` | A boolean of whether the post was edited. | 131 | |------------|---------------------------------------------------------| 132 | | `created` | Unix timestamp of when the reply was originally posted. | 133 | 134 | 135 | Errors 136 | ------ 137 | 138 | Errors are represented in the `error` field of the response. The error 139 | field is always present, but is usually false. If its not false, it is 140 | an object with the fields `code` and `description`. `code` is an integer 141 | representing the type of failure, and `description` is a string describing 142 | the problem. `description` is intended for human consumption; in your client 143 | code, use the error codes to handle conditions. The `presentable` column 144 | indicates whether the `description` should be shown to users verbatim. 145 | 146 | | Code | Presentable | Documentation | 147 | |------+--------------+----------------------------------------------------| 148 | | 0 | Never, fix | Malformed json input. `description` is the error | 149 | | | your client | string thrown by the server-side json decoder. | 150 | |------+--------------+----------------------------------------------------| 151 | | 1 | Not a good | Internal server error. Unaltered exception text | 152 | | | idea, the | is returned as `description`. This shouldn't | 153 | | | exceptions | happen, and if it does, make a bug report. | 154 | | | are not | clients should not attempt to intelligently | 155 | | | helpful | recover from any errors of this class. | 156 | |------+--------------+----------------------------------------------------| 157 | | 2 | Nadda. | Unknown `method` was requested. | 158 | |------+--------------+----------------------------------------------------| 159 | | 3 | Fix. Your. | Missing, malformed, or otherwise incorrect | 160 | | | Client. | parameters or values for the requested `method`. | 161 | | | | This is returned, for example, when a request to | 162 | | | | `edit_post` tries to edit a post_id that does | 163 | | | | not exist. Its also used to indicate a lack of | 164 | | | | required arguments for a method. This is a generic | 165 | | | | error class that can cover programming errors | 166 | | | | but never user errors. | 167 | |------+--------------+----------------------------------------------------| 168 | | 4 | Only during | Invalid or unprovided `user`. | 169 | | | registration | | 170 | | | | During registration, this code is returned with a | 171 | | | | `description` that should be shown to the user. | 172 | | | | It could indicate an invalid name input, an | 173 | | | | occupied username, invalid/missing `auth_hash`, | 174 | | | | etc. | 175 | |------+--------------+----------------------------------------------------| 176 | | 5 | Always | `user` is not registered. | 177 | |------+--------------+----------------------------------------------------| 178 | | 6 | Always | User `auth_hash` failed or was not provided. | 179 | |------+--------------+----------------------------------------------------| 180 | | 7 | Always | Requested thread does not exist. | 181 | |------+--------------+----------------------------------------------------| 182 | | 8 | Always | Requested thread does not allow posts. | 183 | |------+--------------+----------------------------------------------------| 184 | | 9 | Always | Message edit failed; there is a 24hr limit for | 185 | | | | editing posts. | 186 | |------+--------------+----------------------------------------------------| 187 | | 10 | Always | User action requires `admin` privilege. | 188 | |------+--------------+----------------------------------------------------| 189 | | 11 | Always | Invalid formatting directives in text submission. | 190 | -------------------------------------------------------------------------------- /prototype/main.py: -------------------------------------------------------------------------------- 1 | from src import schema 2 | from src import server 3 | 4 | if __name__ == '__main__': 5 | server.run("localhost", 7066) 6 | -------------------------------------------------------------------------------- /prototype/src/db.py: -------------------------------------------------------------------------------- 1 | from src import formatting 2 | from uuid import uuid1 3 | from src import schema 4 | from time import time 5 | from os import path 6 | import json 7 | 8 | PATH = "/home/desvox/bbj/" 9 | 10 | if not path.isdir(PATH): 11 | path.os.mkdir(PATH, mode=0o744) 12 | 13 | if not path.isdir(path.join(PATH, "threads")): 14 | path.os.mkdir(path.join(PATH, "threads"), mode=0o744) 15 | 16 | try: 17 | with open(path.join(PATH, "userdb"), "r") as f: 18 | USERDB = json.loads(f.read()) 19 | 20 | except FileNotFoundError: 21 | USERDB = dict(namemap=dict()) 22 | with open(path.join(PATH, "userdb"), "w") as f: 23 | f.write(json.dumps(USERDB)) 24 | path.os.chmod(path.join(PATH, "userdb"), 0o600) 25 | 26 | 27 | ### THREAD MANAGEMENT ### 28 | 29 | def thread_index(key="lastmod", markup=True): 30 | result = list() 31 | for ID in path.os.listdir(path.join(PATH, "threads")): 32 | thread = thread_load(ID, markup) 33 | thread.pop("replies") 34 | result.append(thread) 35 | return sorted(result, key=lambda i: i[key], reverse=True) 36 | 37 | 38 | def thread_create(author, body, title, tags): 39 | ID = uuid1().hex 40 | if tags: 41 | tags = [tag.strip() for tag in tags.split(",")] 42 | else: # make sure None, False, and empty arrays are always repped consistently 43 | tags = [] 44 | scheme = schema.thread(ID, author, body, title, tags) 45 | thread_dump(ID, scheme) 46 | return scheme 47 | 48 | 49 | def thread_load(ID, markup=True): 50 | try: 51 | with open(path.join(PATH, "threads", ID), "r") as f: 52 | return json.loads(f.read()) 53 | except FileNotFoundError: 54 | return False 55 | 56 | 57 | def thread_dump(ID, obj): 58 | with open(path.join(PATH, "threads", ID), "w") as f: 59 | f.write(json.dumps(obj)) 60 | 61 | 62 | def thread_reply(ID, author, body): 63 | thread = thread_load(ID) 64 | if not thread: 65 | return schema.error(7, "Requested thread does not exist.") 66 | 67 | thread["reply_count"] += 1 68 | thread["lastmod"] = time() 69 | 70 | if thread["replies"]: 71 | lastpost = thread["replies"][-1]["post_id"] 72 | else: 73 | lastpost = 1 74 | 75 | reply = schema.reply(lastpost + 1, author, body) 76 | thread["replies"].append(reply) 77 | thread_dump(ID, thread) 78 | return reply 79 | 80 | 81 | def index_reply(reply_list, post_id): 82 | for index, reply in enumerate(reply_list): 83 | if reply["post_id"] == post_id: 84 | return index 85 | else: 86 | raise IndexError 87 | 88 | 89 | def edit_handler(json, thread=None): 90 | try: 91 | target_id = json["post_id"] 92 | if not thread: 93 | thread = thread_load(json["thread_id"]) 94 | if not thread: 95 | return False, schema.error(7, "Requested thread does not exist.") 96 | 97 | 98 | if target_id == 1: 99 | target = thread 100 | else: 101 | target = thread["replies"][ 102 | index_reply(thread["replies"], target_id)] 103 | 104 | if not user_is_admin(json["user"]): 105 | if json["user"] != target["author"]: 106 | return False, schema.error(10, 107 | "non-admin attempt to edit another user's message") 108 | 109 | elif (time() - target["created"]) > 86400: 110 | return False, schema.error(9, 111 | "message is too old to edit (24hr limit)") 112 | 113 | return True, target 114 | 115 | except IndexError: 116 | return False, schema.error(3, "post_id out of bounds for requested thread") 117 | 118 | 119 | ### USER MANAGEMENT ### 120 | 121 | def user_dbdump(dictionary): 122 | with open(path.join(PATH, "userdb"), "w") as f: 123 | f.write(json.dumps(dictionary)) 124 | 125 | 126 | def user_resolve(name_or_id): 127 | check = USERDB.get(name_or_id) 128 | try: 129 | if check: 130 | return name_or_id 131 | else: 132 | return USERDB["namemap"][name_or_id] 133 | except KeyError: 134 | return False 135 | 136 | 137 | def user_register(auth_hash, name, quip, bio): 138 | if USERDB["namemap"].get(name): 139 | return schema.error(4, "Username taken.") 140 | 141 | for ok, error in [ 142 | user_namecheck(name), 143 | user_authcheck(auth_hash), 144 | user_quipcheck(quip), 145 | user_biocheck(bio)]: 146 | 147 | if not ok: 148 | return error 149 | 150 | ID = uuid1().hex 151 | scheme = schema.user_internal(ID, auth_hash, name, quip, bio, False) 152 | USERDB.update({ID: scheme}) 153 | USERDB["namemap"].update({name: ID}) 154 | user_dbdump(USERDB) 155 | return scheme 156 | 157 | 158 | def user_get(ID): 159 | user = USERDB[ID] 160 | return schema.user_external( 161 | ID, user["name"], user["quip"], 162 | user["bio"], user["admin"]) 163 | 164 | 165 | def user_auth(ID, auth_hash): 166 | return auth_hash == USERDB[ID]["auth_hash"] 167 | 168 | 169 | def user_is_admin(ID): 170 | return USERDB[ID]["admin"] 171 | 172 | 173 | def user_update(ID, **params): 174 | USERDB[ID].update(params) 175 | return USERDB[ID] 176 | 177 | 178 | ### SANITY CHECKS ### 179 | 180 | def contains_nonspaces(string): 181 | return any([char in string for char in "\t\n\r\x0b\x0c"]) 182 | 183 | 184 | def user_namecheck(name): 185 | if not name: 186 | return False, schema.error(4, 187 | "Username may not be empty.") 188 | 189 | elif contains_nonspaces(name): 190 | return False, schema.error(4, 191 | "Username cannot contain whitespace chars besides spaces.") 192 | 193 | elif not name.strip(): 194 | return False, schema.error(4, 195 | "Username must contain at least one non-space character") 196 | 197 | 198 | elif len(name) > 24: 199 | return False, schema.error(4, 200 | "Username is too long (max 24 chars)") 201 | 202 | return True, True 203 | 204 | 205 | def user_authcheck(auth_hash): 206 | if not auth_hash: 207 | return False, schema.error(3, 208 | "auth_hash may not be empty") 209 | 210 | elif len(auth_hash) != 64: 211 | return False, schema.error(4, 212 | "Client error: invalid SHA-256 hash.") 213 | 214 | return True, True 215 | 216 | 217 | def user_quipcheck(quip): 218 | if not quip: 219 | return True, True 220 | 221 | elif contains_nonspaces(quip): 222 | return False, schema.error(4, 223 | "Quip cannot contain whitespace chars besides spaces.") 224 | 225 | elif len(quip) > 120: 226 | return False, schema.error(4, 227 | "Quip is too long (max 120 chars)") 228 | 229 | return True, True 230 | 231 | 232 | def user_biocheck(bio): 233 | if not bio: 234 | return True, True 235 | 236 | elif len(bio) > 4096: 237 | return False, schema.error(4, 238 | "Bio is too long (max 4096 chars)") 239 | 240 | return True, True 241 | -------------------------------------------------------------------------------- /prototype/src/endpoints.py: -------------------------------------------------------------------------------- 1 | from src import formatting 2 | from src import schema 3 | from time import time 4 | from src import db 5 | 6 | 7 | endpoints = { 8 | "check_auth": ["user", "auth_hash"], 9 | "is_registered": ["target_user"], 10 | "is_admin": ["target_user"], 11 | "thread_index": [], 12 | "thread_load": ["thread_id"], 13 | "thread_create": ["title", "body", "tags"], 14 | "thread_reply": ["thread_id", "body"], 15 | "edit_post": ["thread_id", "post_id", "body"], 16 | "edit_query": ["thread_id", "post_id"], 17 | "can_edit": ["thread_id", "post_id"], 18 | "user_register": ["user", "auth_hash", "quip", "bio"], 19 | "user_get": ["target_user"], 20 | "user_name_to_id": ["target_user"] 21 | } 22 | 23 | 24 | authless = [ 25 | "is_registered", 26 | "user_register" 27 | ] 28 | 29 | 30 | # this is not actually an endpoint, but produces a required 31 | # element of thread responses. 32 | def create_usermap(thread, index=False): 33 | if index: 34 | return {user: db.user_get(user) for user in 35 | {i["author"] for i in thread}} 36 | 37 | result = {reply["author"] for reply in thread["replies"]} 38 | result.add(thread["author"]) 39 | return {x: db.user_get(x) for x in result} 40 | 41 | 42 | def user_name_to_id(json): 43 | """ 44 | Returns a string of the target_user's ID when it is 45 | part of the database: a non-existent user will return 46 | a boolean false. 47 | """ 48 | return db.user_resolve(json["target_user"]) 49 | 50 | 51 | def is_registered(json): 52 | """ 53 | Returns true or false whether target_user is registered 54 | in the system. This function only takes usernames: not 55 | user IDs. 56 | """ 57 | return bool(db.USERDB["namemap"].get(json["target_user"])) 58 | 59 | 60 | def check_auth(json): 61 | "Returns true or false whether auth_hashes matches user." 62 | return bool(db.user_auth(json["user"], json["auth_hash"])) 63 | 64 | 65 | def is_admin(json): 66 | """ 67 | Returns true or false whether target_user is a system 68 | administrator. Takes a username or user ID. Nonexistent 69 | users return false. 70 | """ 71 | user = db.user_resolve(json["target_user"]) 72 | if user: 73 | return db.user_is_admin(user) 74 | return False 75 | 76 | 77 | def user_register(json): 78 | """ 79 | Registers a new user into the system. Returns the new internal user 80 | object on success, or an error response. 81 | 82 | auth_hash should be a hexadecimal SHA-256 string, produced from a 83 | UTF-8 password string. 84 | 85 | user should be a string containing no newlines and 86 | under 24 characters in length. 87 | 88 | quip is a string, up to 120 characters, provided by the user 89 | the acts as small bio, suitable for display next to posts 90 | if the client wants to. Whitespace characters besides space 91 | are not allowed. The string may be empty. 92 | 93 | bio is a string, up to 4096 chars, provided by the user that 94 | can be shown on profiles. There are no character type limits 95 | for this entry. The string may be empty. 96 | 97 | All errors for this endpoint with code 4 should show the 98 | description direcrtly to the user. 99 | 100 | """ 101 | 102 | return schema.response( 103 | db.user_register( 104 | json["auth_hash"], 105 | json["user"], 106 | json["quip"], 107 | json["bio"])) 108 | 109 | 110 | def user_get(json): 111 | """ 112 | On success, returns an external user object for target_user (ID or name). 113 | If the user isn't in the system, returns false. 114 | """ 115 | user = db.user_resolve(json["target_user"]) 116 | if not user: 117 | return False 118 | return db.user_get(user) 119 | 120 | 121 | def thread_index(json): 122 | index = db.thread_index(markup=not json.get("nomarkup")) 123 | return schema.response({"threads": index}, create_usermap(index, True)) 124 | 125 | 126 | def thread_load(json): 127 | thread = db.thread_load(json["thread_id"], not json.get("nomarkup")) 128 | if not thread: 129 | return schema.error(7, "Requested thread does not exist") 130 | return schema.response(thread, create_usermap(thread)) 131 | 132 | 133 | def thread_create(json): 134 | thread = db.thread_create( 135 | json["user"], 136 | json["body"], 137 | json["title"], 138 | json["tags"]) 139 | return schema.response(thread) 140 | 141 | 142 | def thread_reply(json): 143 | reply = db.thread_reply( 144 | json["thread_id"], 145 | json["user"], 146 | json["body"]) 147 | return schema.response(reply) 148 | 149 | 150 | def edit_query(json): 151 | return db.edit_handler(json)[1] 152 | 153 | 154 | def can_edit(json): 155 | return db.edit_handler(json)[0] 156 | 157 | 158 | def edit_post(json): 159 | thread = db.thread_load(json["thread_id"]) 160 | admin = db.user_is_admin(json["user"]) 161 | target_id = json["post_id"] 162 | ok, obj = db.edit_handler(json, thread) 163 | 164 | if ok: 165 | 166 | if json.get("reformat"): 167 | json["body"] = formatting.parse(json["body"]) 168 | 169 | obj["body"] = json["body"] 170 | obj["lastmod"] = time() 171 | obj["edited"] = True 172 | db.thread_dump(json["thread_id"], thread) 173 | 174 | return obj 175 | -------------------------------------------------------------------------------- /prototype/src/formatting.py: -------------------------------------------------------------------------------- 1 | from markdown import markdown 2 | from html import escape 3 | import re 4 | 5 | 6 | COLORS = ["red", "green", "yellow", "blue", "magenta", "cyan"] 7 | MARKUP = ["bold", "italic", "underline", "strike"] 8 | TOKENS = re.compile(r"\[({}): (.+?)]".format("|".join(COLORS + MARKUP)), flags=re.DOTALL) 9 | QUOTES = re.compile(">>([0-9]+)") 10 | LINEQUOTES = re.compile("^(>.+)$", flags=re.MULTILINE) 11 | 12 | 13 | def map_html(match): 14 | directive, body = match.group(1).lower(), match.group(2) 15 | if directive in COLORS: 16 | return '{1}'.format(directive, body) 17 | elif directive in MARKUP: 18 | return '<{0}>{1}'.format(directive[0], body) 19 | return body 20 | 21 | 22 | def parse(text, doquotes=True): 23 | text = TOKENS.sub(map_html, escape(text)) 24 | if doquotes: 25 | text = QUOTES.sub(r'\g<0>', text) 26 | return markdown( 27 | LINEQUOTES.sub(r'\1
', text) 28 | ) 29 | -------------------------------------------------------------------------------- /prototype/src/schema.py: -------------------------------------------------------------------------------- 1 | from src import formatting 2 | from time import time 3 | 4 | 5 | def base(): 6 | return { 7 | "error": False 8 | } 9 | 10 | 11 | def response(dictionary, usermap=None): 12 | result = base() 13 | result.update(dictionary) 14 | if usermap: 15 | result["usermap"] = usermap 16 | return result 17 | 18 | 19 | def error(code, description): 20 | result = base() 21 | result.update({ 22 | "error": { 23 | "description": description, # string 24 | "code": code # integer 25 | } 26 | }) 27 | return result 28 | 29 | 30 | def user_internal(ID, auth_hash, name, quip, bio, admin): 31 | if not quip: 32 | quip = "" 33 | 34 | if not bio: 35 | bio = "" 36 | 37 | return { 38 | "user_id": ID, # string 39 | "quip": quip, # (possibly empty) string 40 | "bio": bio, # (possibly empty) string 41 | "name": name, # string 42 | "admin": admin, # boolean 43 | "auth_hash": auth_hash # SHA256 string 44 | } 45 | 46 | 47 | def user_external(ID, name, quip, bio, admin): 48 | if not quip: 49 | quip = "" 50 | 51 | if not bio: 52 | bio = "" 53 | 54 | return { 55 | "user_id": ID, # string 56 | "quip": quip, # (possibly empty) string 57 | "name": name, # string 58 | "bio": bio, # string 59 | "admin": admin # boolean 60 | } 61 | 62 | 63 | def thread(ID, author, body, title, tags): 64 | if not tags: 65 | tags = list() 66 | 67 | body = formatting.parse(body, doquotes=False) 68 | now = time() 69 | 70 | return { 71 | "thread_id": ID, # string 72 | "post_id": 1, # integer 73 | "author": author, # string 74 | "body": body, # string 75 | "title": title, # string 76 | "tags": tags, # (possibly empty) list of strings 77 | "replies": list(), # (possibly empty) list of reply objects 78 | "reply_count": 0, # integer 79 | "edited": False, # boolean 80 | "lastmod": now, # floating point unix timestamp 81 | "created": now # floating point unix timestamp 82 | } 83 | 84 | 85 | def reply(ID, author, body): 86 | 87 | body = formatting.parse(body) 88 | now = time() 89 | 90 | return { 91 | "post_id": ID, # integer 92 | "author": author, # string 93 | "body": body, # string 94 | "edited": False, # boolean 95 | "lastmod": now, # floating point unix timestamp 96 | "created": now # floating point unix timestamp 97 | } 98 | -------------------------------------------------------------------------------- /prototype/src/server.py: -------------------------------------------------------------------------------- 1 | from socketserver import StreamRequestHandler, TCPServer 2 | from src import endpoints 3 | from src import schema 4 | from src import db 5 | import json 6 | 7 | 8 | class RequestHandler(StreamRequestHandler): 9 | """ 10 | Receieves and processes json input; dispatches input to the 11 | requested endpoint, or responds with error objects. 12 | """ 13 | 14 | 15 | def reply(self, obj): 16 | self.wfile.write(bytes(json.dumps(obj), "utf8")) 17 | 18 | 19 | def handle(self): 20 | try: 21 | request = json.loads(str(self.rfile.read(), "utf8")) 22 | endpoint = request.get("method") 23 | 24 | if endpoint not in endpoints.endpoints: 25 | return self.reply(schema.error(2, "Invalid endpoint")) 26 | 27 | # check to make sure all the arguments for endpoint are provided 28 | elif any([key not in request for key in endpoints.endpoints[endpoint]]): 29 | return self.reply(schema.error(3, "{} requires: {}".format( 30 | endpoint, ", ".join(endpoints.endpoints[endpoint])))) 31 | 32 | elif endpoint not in endpoints.authless: 33 | if not request.get("user"): 34 | return self.reply(schema.error(4, "No username provided.")) 35 | 36 | user = db.user_resolve(request["user"]) 37 | request["user"] = user 38 | 39 | if not user: 40 | return self.reply(schema.error(5, "User not registered")) 41 | 42 | elif endpoint != "check_auth" and not \ 43 | db.user_auth(user, request.get("auth_hash")): 44 | return self.reply(schema.error(6, "Authorization failed.")) 45 | 46 | # post_ids are always returned as integers, but for callers who 47 | # provide them as something else, try to convert them. 48 | if isinstance(request.get("post_id"), (float, str)): 49 | try: request["post_id"] = int(request["post_id"]) 50 | except Exception: 51 | return schema.error(3, "Non-numeric post_id") 52 | 53 | # exception handling is now passed to the endpoints; 54 | # anything unhandled beyond here is a code 1 55 | self.reply(eval("endpoints." + endpoint)(request)) 56 | 57 | except json.decoder.JSONDecodeError as E: 58 | return self.reply(schema.error(0, str(E))) 59 | 60 | except Exception as E: 61 | return self.reply(schema.error(1, str(E))) 62 | 63 | 64 | def run(host, port): 65 | server = TCPServer((host, port), RequestHandler) 66 | try: 67 | server.serve_forever() 68 | except KeyboardInterrupt: 69 | print("bye") 70 | server.server_close() 71 | -------------------------------------------------------------------------------- /readme.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bbj-dev/bbj/50ffb5ebc96221d947502c06a5f1fbda1a062219/readme.png -------------------------------------------------------------------------------- /schema.sql: -------------------------------------------------------------------------------- 1 | drop table if exists users; 2 | drop table if exists threads; 3 | drop table if exists messages; 4 | 5 | 6 | create table users ( 7 | user_id text, -- string (uuid1) 8 | user_name text, -- string 9 | auth_hash text, -- string (sha256 hash) 10 | quip text, -- string (possibly empty) 11 | bio text, -- string (possibly empty) 12 | color int, -- int (from 0 to 6) 13 | is_admin int, -- bool 14 | created real -- floating point unix timestamp (when this user registered) 15 | ); 16 | 17 | 18 | create table threads ( 19 | thread_id text, -- uuid string 20 | author text, -- string (uuid1, user.user_id) 21 | title text, -- string 22 | last_mod real, -- floating point unix timestamp (of last post or post edit) 23 | created real, -- floating point unix timestamp (when thread was made) 24 | reply_count int, -- integer (incremental, starting with 0) 25 | pinned int, -- boolean 26 | last_author text -- uuid string 27 | ); 28 | 29 | 30 | create table messages ( 31 | thread_id text, -- string (uuid1 of parent thread) 32 | post_id int, -- integer (incrementing from 1) 33 | author text, -- string (uuid1, user.user_id) 34 | created real, -- floating point unix timestamp (when reply was posted) 35 | edited int, -- bool 36 | body text, -- string 37 | send_raw int -- bool (1/true == never apply formatting) 38 | ); 39 | -------------------------------------------------------------------------------- /setup.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | DEPS=( 4 | cherrypy 5 | urwid 6 | jinja2 7 | ) 8 | 9 | case $1 in 10 | --help ) 11 | cat <
23 | {% if authorized_user %}
24 |
30 |
96 |
97 |
--------------------------------------------------------------------------------
/templates/threadIndex.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
31 |
38 | Change Username
32 | 37 |
39 |
48 | Change Password
40 | 47 |
49 |
69 |
70 |
71 | {% else %}
72 | Username Color
50 | 68 |
73 |
80 |
81 | {% endif %}
82 |
83 |
84 |
95 | Theme
85 | 94 |
41 |
56 | {% endif %}
57 |
58 | {% if bookmarked_threads %}
59 | Pinned Threads
42 | {% for thread in pinned_threads %} 43 |
44 | {{ thread["title"] }}
45 |
46 | by 47 |
48 | Created: {{ thread["created"] }} 49 |
50 | {{ thread["reply_count"] }} replies; active {{ thread["last_mod"] }} 51 |
52 | last active by 53 |
54 | {% endfor %}
55 | 46 | by 47 |
48 | Created: {{ thread["created"] }} 49 |
50 | {{ thread["reply_count"] }} replies; active {{ thread["last_mod"] }} 51 |
52 | last active by 53 |
60 |
76 | {% endif %}
77 |
78 | {% if threads %}
79 | Bookmarked Threads
61 | {% for thread in bookmarked_threads %} 62 |
63 | {{ thread["title"] }}
64 |
65 | by 66 |
67 | Created: {{ thread["created"] }} 68 |
69 | {{ thread["reply_count"] }} replies; active {{ thread["last_mod"] }} 70 |
71 | last active by 72 |
Unbookmark this thread. 73 |
74 | {% endfor %}
75 | 65 | by 66 |
67 | Created: {{ thread["created"] }} 68 |
69 | {{ thread["reply_count"] }} replies; active {{ thread["last_mod"] }} 70 |
71 | last active by 72 |
Unbookmark this thread. 73 |
80 |
96 | {% endif %}
97 |
98 | {% if not threads %}
99 | Threads
81 | {% for thread in threads %} 82 |
83 | {{ thread["title"] }}
84 |
85 | by 86 |
87 | Created: {{ thread["created"] }} 88 |
89 | {{ thread["reply_count"] }} replies; active {{ thread["last_mod"] }} 90 |
91 | last active by 92 |
Bookmark this thread. 93 |
94 | {% endfor %}
95 | 85 | by 86 |
87 | Created: {{ thread["created"] }} 88 |
89 | {{ thread["reply_count"] }} replies; active {{ thread["last_mod"] }} 90 |
91 | last active by 92 |
Bookmark this thread. 93 |