path: root/README.adoc

flipdot-gschichtler
===================
sterni
November 2020

`flipdot-gschichtler` allows to display text on the OpenLab's
flipdot panel in an user- and machine-friendly way without
fear of interfering with others and without requiring direct
connectivity to the panel.

Components
----------

`flipdot-gschichtler` consists of the following three components:

- `warteraum` manages a queue of text snippets which is accessible and
  manipulable via a public REST API. Users will directly or indirectly
  use it to send text to the flipdot panel.
- `anzeigetafel` is a daemon which runs on a machine with direct
  connectivity to the flipdot panel. It monitors the queue of
  `warteraum` and displays new incoming text on the panel and
  deletes it from the queue afterwards.
- `bahnhofshalle` is a web fronted which allows users to view and
  manipulate the queue of `warteraum` from their browser.

API Documentation
-----------------

Caveats
~~~~~~~

* The `v2` API may support `application/json` request bodies in
  the future. This is not yet the case.
* Any endpoint may also return different status codes than the
  ones listed here in unusual cases. These would typically
  be codes like 500 or 502.
* ids are not guaranteed to never be reassigned. However,
  ids only start to get reassigned after the queue has been
  fully emptied.

API `v2`
~~~~~~~~

GET `/api/v2/queue`
^^^^^^^^^^^^^^^^^^^

|=============================================
| Request Content-Type  | none
| Response Content-Type | `application/json`
| Authentication        | no
|=============================================

This endpoint returns the current queue in the
following JSON format. `length` corresponds with
the length of the queue array. `queue` is ordered
by time of each item's addition, i. e. the first
item is next up to be displayed. The supplied `id`
may be used to delete the entries.

-------------------------
{
  "queue": [
    {
      "id": 0,
      "text": "hello"
    },
    {
      "id": 1,
      "text": "world"
    }
  ],
  "length": 2
}
-------------------------

|====================================
| HTTP Status  | Meaning
| 200          | Success
|====================================

POST `/api/v2/queue/add`
^^^^^^^^^^^^^^^^^^^^^^^^

|=============================================
| Request Content-Type  | `application/x-www-form-urlencoded`
| Response Content-Type | `application/json`
| Authentication        | no
|=============================================

This endpoints allows you to add text to the queue,
it requires no authentication as it is a feature
available to the public. There is also no rate
limiting as of yet, but it may be implemented should
it become necessary (hopefully not).

The endpointed expects an urlencoded form as request
body with the following field.

|=============================================
| `text` | text to be added to the queue
|=============================================

The response contains the queue entry consisting
of its `text` and `id`:

----------------------
{
  "id": 3,
  "text": "hello"
}
----------------------

|=============================================
| HTTP Status  | Meaning
| 200          | Success, text added
| 400          | Illegal method or malformed request
| 415          | Request body too big or text field longer allowed (usually 512 bytes)
| 503          | The queue is full, i. e. the max id has been reached
|=============================================

DELETE `/api/v2/queue/<id>`
^^^^^^^^^^^^^^^^^^^^^^^^^^^

|=============================================
| Request Content-Type  | `application/x-www-form-urlencoded`
| Response Content-Type | none
| Authentication        | yes (see below)
|=============================================

This endpoint can be used to delete queue entries, e. g. after
they have been displayed on the panel. The request should send
a form with the following fields as request body in order to
authenticate itself:

|=============================================
| `token` | API token of the application
|=============================================

|=============================================
| HTTP Status  | Meaning
| 204          | Success, queue entry deleted
| 400          | Illegal method or malformed request
| 401          | Unauthorized API token
| 404          | No queue entry with given `id`
| 415          | Request body too big
|=============================================

GET `/api/v2/announcement`
^^^^^^^^^^^^^^^^^^^^^^^^^^

|=============================================
| Request Content-Type  | none
| Response Content-Type | `application/json`
| Authentication        | no
|=============================================

The endpoint can be used to query the current announcement
text. If one exists, the following response format is used:

---------------------------
{
  "announcement": "some announcement text"
}
---------------------------

If however no announcement text has been set (or it has been
deleted), the response looks like this and is returned with
a response status of 404:

---------------------------
{
  "announcement": null
}
---------------------------

|=============================================
| HTTP Status  | Meaning
| 200          | Success
| 404          | No announcement text is set
|=============================================

PUT `/api/v2/announcement`
^^^^^^^^^^^^^^^^^^^^^^^^^^

|=============================================
| Request Content-Type  | `application/x-www-form-urlencoded`
| Response Content-Type | `application/json`
| Authentication        | yes (see below)
|=============================================

This endpoint allows you to set the announcement
text which will be displayed on the panel (if
enabled) during times when the queue is empty.

Since the API call overwrites previous content,
it requires authentication additionally. Any
call to this endpoint must send a form with
the following fields:

|=============================================
| `text`  | text to be added to the queue
| `token` | API token of the application
|=============================================

The response contains the announcement in the
same format as the `GET` variant of this endpoint,
except it's guaranteed to never be `null`:

----------------------
{
  "announcement": "new announcement"
}
----------------------

|=============================================
| HTTP Status  | Meaning
| 200          | Success, announcement set
| 400          | Illegal method or malformed request
| 415          | Request body too big or text field longer allowed (usually 512 bytes)
|=============================================

DELETE `/api/v2/announcement`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

|=============================================
| Request Content-Type  | `application/x-www-form-urlencoded`
| Response Content-Type | none
| Authentication        | yes (see below)
|=============================================

This endpoint can be used to delete the announcement text.
The request should send a form with the following fields
as request body in order to authenticate itself:

|=============================================
| `token` | API token of the application
|=============================================

|=============================================
| HTTP Status  | Meaning
| 204          | Success, queue entry deleted
| 400          | Illegal method or malformed request
| 401          | Unauthorized API token
| 415          | Request body too big
|=============================================

API `v1`
~~~~~~~

GET `/api/v1/queue`
^^^^^^^^^^^^^^^^^^^

Same as `/api/v2/queue`, since v2 didn't introduce any changes.

POST `/api/v1/queue/add`
^^^^^^^^^^^^^^^^^^^^^^^^

|=============================================
| Request Content-Type  | `application/x-www-form-urlencoded`
| Response Content-Type | `text/html`
| Authentication        | no
|=============================================

This is the legacy endpoint to add text to the queue. It enabled
interacting with it via a `<form>` in the old web app. The form
sent as part of the request should have the following fields:

|=============================================
| `text` | text to be added to the queue
|=============================================

The response format has been changed since the previous implementation.
I sincerly hope that nobody scraped the resulting page.

|=============================================
| HTTP Status  | Meaning
| 200          | Success, text added
| 400          | Illegal method or malformed request
| 415          | Request body too big or text field longer allowed (usually 512 bytes)
|=============================================

DELETE `/api/v1/queue/del/<id>`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Same as `/api/v2/queue/<id>`, `v2` only changed the endpoint URL.

Bug Bounty
----------

🤭

Contributing
------------

Help is welcome! Some things that remain to be done:

* More “funny” bits for the web frontend
  (hint: see `const subjects` in `main.es6`)
* Important: Documentation. Annoying sterni into doing it is also helping.
* Make `warteraum` accept `application/json` request bodies for the `v2`
  API using http://www.catb.org/~esr/microjson/[microjson] (?).
* Polish the web frontend, test across browsers
* Refresh queue regularly in the web frontend
* Write more tests
* Full Unicode support by using Unifont on the flipdots
* A completely new feature you thought of

Building
--------

warteraum
~~~~~~~~~

Requirements:

* a C99 compiler
* `redo` (https://github.com/leahneukirchen/redo-c[redo-c] and
  http://news.dieweltistgarnichtso.net/bin/redo-sh.html[redo-sh]
  are known to work)
* https://www.tarsnap.com/scrypt.html[`libscrypt-kdf`]

------------------------
cd warteraum
redo all
------------------------

Build settings can be tweaked in `warteraum/build_config`.

bahnhofshalle
~~~~~~~~~~~~~

We need `parcel` and `babel`. It is probably easiest to
either use the `bahnhofshalle` attribute of `default.nix` or `npm`
or `yarn` to install the dependencies of `package.json` like this:

------------------------
cd bahnhofshalle
yarn install
yarn run build    # result in ./dist
------------------------

Note that all requests are sent using a `same-origin` policy,
so you need to configure a reverse proxy to serve the web
frontend and API simuntaneously for testing. You may take
inspiration from the `nginx` configuration in
`nixos/flipdot-gschichtler.nix`.

A note on vendoring
~~~~~~~~~~~~~~~~~~~

To ease the submodule hassle, dependencies that are inconvenient to
handle via a package manager are vendored or added as a
https://www.atlassian.com/git/tutorials/git-subtree[git subtree].
To avoid confusion these are located under `third_party` exclusively.

Also be aware that different licensing terms may apply to code under
this directory.

Nix packages
~~~~~~~~~~~~

`default.nix` provides the following nix derivations which are
ready to be installed:

* `warteraum`: standard clang/glibc build of warteraum
* `warteraum-static`: statically linked build of warteraum
  using gcc and musl (used for the systemd service so we
  can restrict file system access)
* `bahnhofshalle`
* `anzeigetafel`

The warteraum attributes can be overriden to set the following
values:

* `apiTokens`: A list of api tokens to allow to authenticate with
* `scryptSalt`: A string of hexadecimal digits which make up the
  salt to use when hashing api tokens.

`nixos/flipdot-gschichtler.nix` provides a NixOS module which
defines `services.flipdot-gschichtler` to conveniently set up
the server side with `warteraum` and `bahnhofshalle` behind
a nginx reverse proxy. A minimal `configuration.nix` utilizing
it could look like this:

---------------
{ pkgs, ... }:

let
  flipdot-gschichtler = import /path/to/flipdot-gschichtler {
    inherit pkgs;
  };

in {
  imports = [
    /path/to/flipdot-gschichtler/nixos/flipdot-gschichtler.nix
  ];

  _module.args = { inherit flipdot-gschichtler; };

  services.flipdot-gschichtler = {
    enable = true;
    virtualHost = "flipdot.openlab-augsburg.de";
    apiTokens = [ ... ];
    salt = "...";
  };

  services.nginx.enable = true;
  security.acme = {
    ....
  };
}
---------------

Changelog
---------

2.0.0
~~~~~

https://github.com/openlab-aux/flipdot-gschichtler/tree/2.0.0[Browse code]

* Replace `admin` and `web` frontends with pure EcmaScript
  frontend `bahnhofshalle`
* Replace `web` API implementation with `warteraum`
* Rename `flipper` to `anzeigetafel`, port to Python 3
* API:
** Move endpoints from `/` to `/api/v1/`
** `/api/v1/queue/add` HTML response changes, since no longer
   used by the frontend (except when no JavaScript is available)
** Add cleaned up version of the API as `/api/v2`. This one is used
   by `bahnhofshalle` and `anzeigetafel` and should be utilized by
   clients going forward.
* Deployment:
** Implement API/Frontend deployment as a NixOS service

1.0.0
~~~~~

https://github.com/openlab-aux/flipdot-gschichtler/tree/1.0.0[Browse code]

Initial Version: Flask and Python 2.7 based web interface.