docs: configuration options

.envrc

@@ -0,0 +1 @@
+use_nix

.readthedocs.yaml

@@ -0,0 +1,8 @@
+version: 2
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  version: 3.7
+  install:
+    - requirements: docs/requirements.txt

docs/api-v2.md

@@ -0,0 +1,234 @@
+# API
+
+Piston exposes an API for managing packages and executing user-defined code.
+
+The API is broken in to 2 main sections - packages and jobs.
+
+The API is exposed from the container, by default on port 2000, at `/api/v2/`.
+
+All inputs are validated, and if an error occurs, a 4xx or 5xx status code is returned.
+In this case, a JSON payload is sent back containing the error message as `message`
+
+## Runtimes
+
+### `GET /api/v2/runtimes`
+
+Returns a list of available languages, including the version, runtime and aliases.
+
+#### Response
+
+- `[].language`: Name of the language
+- `[].version`: Version of the runtime
+- `[].aliases`: List of alternative names that can be used for the language
+- `[].runtime` (_optional_): Name of the runtime used to run the langage, only provided if alternative runtimes exist for the language
+
+#### Example
+
+```
+GET /api/v2/runtimes
+```
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+[
+  {
+    "language": "bash",
+    "version": "5.1.0",
+    "aliases": ["sh"]
+  },
+  {
+    "language": "javascript",
+    "version": "15.10.0",
+    "aliases": ["node-javascript", "node-js", "javascript", "js"],
+    "runtime": "node"
+  }
+]
+```
+
+## Execute
+
+### `POST /api/v2/execute`
+
+Runs the given code, using the given runtime and arguments, returning the result.
+
+#### Request
+
+- `language`: Name or alias of a language listed in [runtimes](#runtimes)
+- `version`: SemVer version selector of a language listed in [runtimes](#runtimes)
+- `files`: An array of files which should be uploaded into the job context
+- `files[].name` (_optional_): Name of file to be written, if none a random name is picked
+- `files[].content`: Content of file to be written
+- `stdin` (_optional_): Text to pass into stdin of the program. Defaults to blank string.
+- `args` (_optional_): Arguments to pass to the program. Defaults to none
+- `run_timeout` (_optional_): The maximum allowed time in milliseconds for the compile stage to finish before bailing out. Must be a number, less than or equal to the configured maximum timeout.
+- `compile_timeout` (_optional_): The maximum allowed time in milliseconds for the run stage to finish before bailing out. Must be a number, less than or equal to the configured maximum timeout. Defaults to maximum.
+- `compile_memory_limit` (_optional_): The maximum amount of memory the compile stage is allowed to use in bytes. Must be a number, less than or equal to the configured maximum. Defaults to maximum, or `-1` (no limit) if none is configured.
+- `run_memory_limit` (_optional_): The maximum amount of memory the run stage is allowed to use in bytes. Must be a number, less than or equal to the configured maximum. Defaults to maximum, or `-1` (no limit) if none is configured.
+
+#### Response
+
+- `language`: Name (not alias) of the runtime used
+- `version`: Version of the used runtime
+- `run`: Results from the run stage
+- `run.stdout`: stdout from run stage process
+- `run.stderr`: stderr from run stage process
+- `run.output`: stdout and stderr combined in order of data from run stage process
+- `run.code`: Exit code from run process, or null if signal is not null
+- `run.signal`: Signal from run process, or null if code is not null
+- `compile` (_optional_): Results from the compile stage, only provided if the runtime has a compile stage
+- `compile.stdout`: stdout from compile stage process
+- `compile.stderr`: stderr from compile stage process
+- `compile.output`: stdout and stderr combined in order of data from compile stage process
+- `compile.code`: Exit code from compile process, or null if signal is not null
+- `compile.signal`: Signal from compile process, or null if code is not null
+
+#### Example
+
+```json
+POST /api/v2/execute
+Content-Type: application/json
+
+{
+  "language": "js",
+  "version": "15.10.0",
+  "files": [
+    {
+      "name": "my_cool_code.js",
+      "content": "console.log(process.argv)"
+    }
+  ],
+  "stdin": "",
+  "args": ["1", "2", "3"],
+  "compile_timeout": 10000,
+  "run_timeout": 3000,
+  "compile_memory_limit": -1,
+  "run_memory_limit": -1
+}
+```
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "run": {
+    "stdout": "[\n  '/piston/packages/node/15.10.0/bin/node',\n  '/piston/jobs/e87afa0d-6c2a-40b8-a824-ffb9c5c6cb64/my_cool_code.js',\n  '1',\n  '2',\n  '3'\n]\n",
+    "stderr": "",
+    "code": 0,
+    "signal": null,
+    "output": "[\n  '/piston/packages/node/15.10.0/bin/node',\n  '/piston/jobs/e87afa0d-6c2a-40b8-a824-ffb9c5c6cb64/my_cool_code.js',\n  '1',\n  '2',\n  '3'\n]\n"
+  },
+  "language": "javascript",
+  "version": "15.10.0"
+}
+```
+
+## Packages
+
+### `GET /api/v2/packages`
+
+Returns a list of all possible packages, and whether their installation status.
+
+#### Response
+
+- `[].language`: Name of the contained runtime
+- `[].language_version`: Version of the contained runtime
+- `[].installed`: Status on the package being installed
+
+#### Example
+
+```
+GET /api/v2/packages
+```
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+[
+  {
+    "language": "node",
+    "language_version": "15.10.0",
+    "installed": true
+  },
+  {
+    "language": "bash",
+    "language_version": "5.1.0",
+    "installed": true
+  }
+]
+```
+
+### `POST /api/v2/packages`
+
+Install the given package.
+
+#### Request
+
+- `language`: Name of package from [package list](#get-apiv2packages)
+- `version`: SemVer version selector for package from [package list](#get-apiv2packages)
+
+#### Response
+
+- `language`: Name of package installed
+- `version`: Version of package installed
+
+#### Example
+
+```json
+POST /api/v2/packages
+Content-Type: application/json
+
+{
+  "language": "bash",
+  "version": "5.x"
+}
+```
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "language": "bash",
+  "version": "5.1.0"
+}
+```
+
+### `DELETE /api/v2/packages`
+
+Uninstall the given package.
+
+#### Request
+
+- `language`: Name of package from [package list](#get-apiv2packages)
+- `version`: SemVer version selector for package from [package list](#get-apiv2packages)
+
+#### Response
+
+- `language`: Name of package uninstalled
+- `version`: Version of package uninstalled
+
+#### Example
+
+```json
+DELETE /api/v2/packages
+Content-Type: application/json
+
+{
+  "language": "bash",
+  "version": "5.x"
+}
+```
+
+```json
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "language": "bash",
+  "version": "5.1.0"
+}
+```

docs/configuration.md

@@ -0,0 +1,147 @@
+# Configuration
+
+Piston provides many different configuration options to tweak Piston to meet your needs.
+
+Configuration is specified through environment variables, prefixed with `PISTON_`.
+
+## Log Level
+
+```yaml
+key: PISTON_LOG_LEVEL
+default: INFO
+```
+
+Level of log output to provide.
+
+One of `DEBUG`, `INFO`, `WARN`, `ERROR` or `NONE`
+
+## Bind Address
+
+```yaml
+key: PISTON_BIND_ADDRESS
+default: 0.0.0.0:2000
+```
+
+Port and IP address to bind the Piston API to.
+
+<!-- prettier-ignore -->
+!!! warning
+    Changing this value is not recommended.
+
+    This changes the bind address inside the container, and thus serves no purpose when running in a container
+
+## Data Directory
+
+```yaml
+key: PISTON_DATA_DIRECTORY
+default: /piston
+```
+
+Absolute path to piston related data, including packages and job contexts.
+
+<!-- prettier-ignore -->
+!!! warning
+    Changing this value is not recommended.
+
+    Some packages require absolute paths on disk at build time.
+    Due to this, some packages may break when changing this parameter.
+
+## Runner GID/UID range
+
+```yaml
+key:
+  - PISTON_RUNNER_UID_MIN
+  - PISTON_RUNNER_UID_MAX
+  - PISTON_RUNNER_GID_MIN
+  - PISTON_RUNNER_GID_MAX
+default:
+  - 1001
+  - 1500
+  - 1001
+  - 1500
+```
+
+UID and GID ranges to use when executing jobs.
+
+<!-- prettier-ignore -->
+!!! warning
+    Changing this value is not recommended.
+
+    The piston container creates 500 users and groups by default, and reserves user/group 1000 for running the API.
+    Any processes run by these users will be killed when cleaning up a job.
+
+## Disable Networking
+
+```yaml
+key: PISTON_DISABLE_NETWORKING
+default: true
+```
+
+Disallows access to `socket` syscalls, effectively disabling networking for jobs run by piston.
+
+## Max Process Count
+
+```yaml
+key: PISTON_MAX_PROCESS_COUNT
+default: 64
+```
+
+Maximum number of processess allowed to to have open for a job.
+
+Resists against exhausting the process table, causing a full system lockup.
+
+## Output Max Side
+
+```yaml
+key: PISTON_OUTPUT_MAX_SIZE
+default: 1024
+```
+
+Maximum size of stdio buffers for each job.
+
+Resist against run-away output which could lead to memory exhaustion.
+
+## Max Open Files
+
+```yaml
+key: PISTON_MAX_OPEN_FILES
+default: 64
+```
+
+Maximum number of open files at a given time by a job.
+
+Resists against writing many smaller files to exhaust inodes.
+
+## Max File Size
+
+```yaml
+key: PISTON_MAX_FILE_SIZE
+default: 10000000 #10MB
+```
+
+Maximum size for a singular file written to disk.
+
+Resists against large file writes to exhaust disk space.
+
+## Compile/Run memory limits
+
+```yaml
+key:
+  - PISTON_COMPILE_MEMORY_LIMIT
+  - PISTON_RUN_MEMORY_LIMIT
+default: -1
+```
+
+Maximum memory allowed by a stage in bytes.
+Use -1 for unlimited memory usage.
+
+Useful for running memory-limited contests.
+
+## Repository URL
+
+```yaml
+key: PISTON_REPO_URL
+default: https://github.com/engineer-man/piston/releases/download/pkgs/index
+```
+
+URL for repository index, where packages will be downloaded from.

docs/index.md

@@ -0,0 +1,3 @@
+# Piston
+
+These docs are a WIP

docs/requirements.txt

@@ -0,0 +1 @@
+mkdocs==1.1.2

mkdocs.yml

@@ -0,0 +1,15 @@
+site_name: Piston
+nav:
+  - Home: index.md
+  - Configuration: configuration.md
+  - API: api-v2.md
+
+theme:
+  name: readthedocs
+  highlightjs: true
+  hljs_languages:
+    - yaml
+    - json
+
+markdown_extensions:
+  - admonition

readme.md

@@ -33,7 +33,8 @@
   <a href="#Supported-Languages">Supported Languages</a> •
   <a href="#Principle-of-Operation">Principles</a> •
   <a href="#Security">Security</a> •
-  <a href="#License">License</a>
+  <a href="#License">License</a> •
+  <a href="https://piston.readthedocs.io">Documentation</a>
 </h4>
 
 ---
@@ -69,7 +70,6 @@ The following are approved and endorsed extensions/utilities to the core Piston
 - [Piston4J](https://github.com/the-codeboy/Piston4J), a Java wrapper for accessing the Piston API.
 - [Pyston](https://github.com/ffaanngg/pyston), a Python wrapper for accessing the Piston API.
 
-        
 <br>
 
 # Public API

shell.nix

@@ -1,5 +1,5 @@
 { pkgs ? import <nixpkgs> {} }:
   pkgs.mkShell {
     # nativeBuildInputs is usually what you want -- tools you need to run
-    nativeBuildInputs = with pkgs; [ nodejs-15_x jq ];
+    nativeBuildInputs = with pkgs; [ nodejs-15_x jq mkdocs ];
 }