Nu-SCPTheme/ftml-json-archived

JSONRPC server for ftml

ftml-json

THIS CRATE IS ARCHIVED

Use the ftml-rpc crate instead. This code is no longer maintained.

---

See the ftml repo for information on "Foundation Text Markup Language".

This is a Rust application which enables parsing and rendering Wikidot sources into HTML, receiving requests via JSON and making client calls as needed to fetch remote information.

Available under the terms of the GNU Affero General Public License. See LICENSE.md.

Compilation

This library targets the latest stable Rust. At time of writing, that is 1.40.0

$ cargo build --release

This will create the final ftml-json binary, which can be executed using the following:

$ cargo run --release -- <config-file>

An example configuration file is available at misc/config.toml.

Testing

$ cargo test

Add -- --nocapture to the end if you want to see test output.

Requests

Utilizes the JSONRPC 2.0 protocol. The methods currently supported are:

protocol, protocolVersion: Gets the API version of ftml-json. Currently 0.

ping: Returns pong!. For testing that the server is up.

error: Returns an optional message as an error. For testing error handling.

time: Returns the current system time.

prefilter: Transforms the given input text according to ftml's preprocessing rules. Performs no parsing or rendering.

Example:

{
    "jsonrpc": "2.0",
    "method": "prefilter",
    "id": (request ID),
    "params": ["<< TEST >>"]
}

yields

{
    "jsonrpc": "2.0",
    "id": (request ID),
    "result": "« TEST »"
}

parse: Transforms the given input text to a JSON parse tree. The prefilter is not performed.

Example:

{
    "jsonrpc": "2.0",
    "method": "parse",
    "id": (request ID),
    "params": ["**test** word"]
}

yields

{
    "jsonrpc": "2.0",
    "id": (request ID),
    "result": {
        "paragraphs": [
            {
                "Words": {
                    "centered": false,
                    "words": [
                        {
                            "Bold": {
                                "words": [
                                    "Text": { "contents": "test" }
                                ]
                            }
                        },
                        {
                            "Text": { "contents": " word" }
                        }
                    ]
                }
            }
        ]
    }
}

render, transform: Performs prefilter, parsing, and HTML rendering.

Input parameters are [page_info, input], where input is a string with the source, and page_info is an object with the following schema:

{
    "title": "SCP-1000",
    "alt_title": "Bigfoot",
    "header": null,
    "subheader": null,
    "rating": 500,
    "tags": ["scp", "keter", "species", ...]
}

(header and subheader affect the "SCP Foundation" and "Secure, Contain, Protect" text above the page. If null they remain unchanged)

And returns an html object with the following schema:

{
    "html": " ... generated HTML body here ...",
    "style": " ... all custom CSS here ...",
    "meta": [
        {
            "tag_type": "name",
            "name": "generator",
            "value": "ftml"
        }
        {
            ... other tags...
        }
    ]
}