From 72f57ef1ce38413e1d6839a8a4da586d192edd09 Mon Sep 17 00:00:00 2001 From: Thomas Hobson Date: Sun, 21 Feb 2021 13:37:21 +1300 Subject: [PATCH] docs: readme --- README.MD | 238 ++++++++++++++++++++++++++++++++++++ docs/images/icon_circle.svg | 32 +++++ 2 files changed, 270 insertions(+) create mode 100644 README.MD create mode 100644 docs/images/icon_circle.svg diff --git a/README.MD b/README.MD new file mode 100644 index 0000000..44f9298 --- /dev/null +++ b/README.MD @@ -0,0 +1,238 @@ +

+ engineer-man piston + Piston +

+ +

A high performance general purpose code execution engine.

+
+ +

+ + GitHub last commit + + GitHub issues + + GitHub pull requests +

+ +--- + +

+ About • + Public API • + Getting Started • + Usage • + Supported Languages • + Principles • + Security • + License +

+ +--- +
+ +# About + +

+Piston is a high performance general purpose code execution engine. It excels at running untrusted and +possibly malicious code without fear from any harmful effects. +

+
+ +It's used in numerous places including: +* [EMKC Challenges](https://emkc.org/challenges), +* [EMKC Weekly Contests](https://emkc.org/contests), +* [Engineer Man Discord Server](https://discord.gg/engineerman), +* [I Run Code (Discord Bot)](https://github.com/engineer-man/piston-bot) bot as well as 1300+ other servers +and 100+ direct integrations. + +To get it in your own server, go here: https://emkc.org/run. + +
+ +# Public API + +- Requires no installation and you can use it immediately. +- Reference the Versions/Execute sections below to learn about the request and response formats. + +
+ +When using the public Piston API, use the base URL: + +``` +https://emkc.org/api/v1/piston +``` + +#### GET +``` +https://emkc.org/api/v1/piston/versions +``` +#### POST +``` +https://emkc.org/api/v1/piston/execute +``` + +> Important Note: The Piston API is rate limited to 5 requests per second. If you have a need for more requests than that +and it's for a good cause, please reach out to me (EngineerMan#0001) on [Discord](https://discord.gg/engineerman) +so we can discuss potentially getting you an unlimited key. + +
+ +# Getting Started + +### Host System Package Dependencies + +- Docker +- Docker Compose +- Node JS + +#### After system dependencies are installed, clone this repository: + +```sh +# clone and enter repo +git clone https://github.com/engineer-man/piston +``` + +#### Installation + +- docker-compose up + +#### CLI Usage +- `cli/execute [language] [file path] [args]` +
+ +# Usage + +### CLI + +```sh +lxc/execute [language] [file path] [args] +``` + +### API +To use the API, it must first be started. Please note that if root is required to access +LXC then the API must also be running as root. To start the API, run the following: + +``` +cd api +./start +``` + +For your own local installation, the API is available at: + +``` +http://127.0.0.1:2000 +``` + +#### Versions Endpoint +`GET /versions` +This endpoint will return the supported languages along with the current version and aliases. To execute +code for a particular language using the `/execute` endpoint, either the name or one of the aliases must +be provided. +```json +HTTP/1.1 200 OK +Content-Type: application/json + +[ + { + "name": "awk", + "aliases": ["awk"], + "version": "1.3.3" + }, + { + "name": "bash", + "aliases": ["bash"], + "version": "4.4.20" + }, + { + "name": "c", + "aliases": ["c"], + "version": "7.5.0" + } +] +``` + +#### Execute Endpoint +`POST /execute` +This endpoint requests execution of some arbitrary code. +- `language` (**required**) The language to use for execution, must be a string and supported by Piston (see list below). +- `source` (**required**) The source code to execute, must be a string. +- `stdin` (*optional*) The text to pass as stdin to the program. Must be a string or left out of the request. +- `args` (*optional*) The arguments to pass to the program. Must be an array or left out of the request. +```json +{ + "language": "js", + "source": "console.log(process.argv)", + "stdin": "", + "args": [ + "1", + "2", + "3" + ] +} +``` +A typical response upon successful execution will contain the `language`, `version`, `output` which +is a combination of both `stdout` and `stderr` but in chronological order according to program output, +as well as separate `stdout` and `stderr`. +```json +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "ran": true, + "language": "js", + "version": "12.13.0", + "output": "[ '/usr/bin/node',\n '/tmp/code.code',\n '1',\n '2',\n '3' ]", + "stdout": "[ '/usr/bin/node',\n '/tmp/code.code',\n '1',\n '2',\n '3' ]", + "stderr": "" +} +``` +If a problem exists with the request, a `400` status code is returned and the reason in the `message` key. +```json +HTTP/1.1 400 Bad Request +Content-Type: application/json + +{ + "message": "Supplied language is not supported by Piston" +} +``` + +
+ +# Supported Languages + +`python`, + + +
+ +
+ + +# License +Piston is licensed under the MIT license. \ No newline at end of file diff --git a/docs/images/icon_circle.svg b/docs/images/icon_circle.svg new file mode 100644 index 0000000..7acfd39 --- /dev/null +++ b/docs/images/icon_circle.svg @@ -0,0 +1,32 @@ + + +