https://github.com/thecheese42/realtime-stream
An application to share terminal output streams.
https://github.com/thecheese42/realtime-stream
rest-api sharing stream terminal
Last synced: about 2 months ago
JSON representation
An application to share terminal output streams.
- Host: GitHub
- URL: https://github.com/thecheese42/realtime-stream
- Owner: TheCheese42
- License: unlicense
- Created: 2024-08-24T13:42:47.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-02T17:13:09.000Z (almost 2 years ago)
- Last Synced: 2025-01-29T08:43:05.497Z (over 1 year ago)
- Topics: rest-api, sharing, stream, terminal
- Language: Python
- Homepage: http://rtstream.freeddns.org
- Size: 26.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Realtime Stream
An application to share terminal output streams.
## Hosting
First, clone and install the requirements.
```sh
git clone https://github.com/TheCheese42/realtime-stream
cd realtime-stream
python -m venv .venv
source .venv/bin/activate # Linux and MacOS
.venv/Scripts/activate.ps1 # Windows
pip install -r requirements.txt
```
\
Then, add a .env file to the root directory. The content should be as follows:
```toml
FLASK_APP = "rtstream/app.py"
# The following are required when using MySQL
MYSQL_HOST = ""
MYSQL_PORT = "3306" # This is the standard MySQL port
MYSQL_USERNAME = ""
MYSQL_PASSWORD = ""
MYSQL_DATABASE = ""
# The following are required when using SQLite. Do NOT add them otherwise!
RTS_USE_SQLITE = "1"
RTS_SQLITE_PATH = "rtstream.db"
# Optional keys:
# RTS_NO_SETUP_SQLITE = "1" # If a newly created SQLite DB should not be set up automatically. Usually better to leave this away.
```
## Usage
This tool is intended to be used with a terminal binary like cURL or the `rts` script to redirect terminal output to the webserver, making it accessible for everyone with the link. Streams can be seen using the `/g` endpoint or in the webview, using the `/v` endpoint (also usable through the index page).
### Databases
The application can either connect to a MySQL or an SQLite database. Both can be initialized using the `setup_db.py` script:
```sh
python setup_db.py
```
The script reads everything it needs from the `.env` file, including wether it should use MySQL or SQLite.
### The `rts` script
The `rts` script can be found at the `/script` path of the webserver. It handles sending the cURL requests to the hostname it was downloaded from. It is a **bash** script, it does **not** work on regular Windows shells.
This install instruction can also be found on the index page, with the correct url.
```sh
curl "http://doma.in/script" > ~/.local/bin/rts && chmod +x ~/.local/bin/rts
```
It can be used like this:
```sh
neofetch | rts
```
This prints the UUID of the newly created stream to the stdout. It also prints the piped output. To append to an existing stream, pass that as an argument to `rts`.
```sh
neofetch | rts ABC123
```
### The webview
Instead of fetching stream output from the terminal, it can also be viewed from the browser. The webview at `/v/` will refresh automatically. It can also be accessed by entering the UUID into the dedicated input field at the top of the index page.
### Endpoints
The application has the following REST API endpoints:
#### Create a new output stream
Endpoint: `/c`
HTTP Method: `POST`
Successful response content: The UUID of the newly created output stream.
Examples (cURL):
`curl -X POST http://doma.in/c`
`curl -X POST -d "Initial Data" http://doma.in/c`
#### Append to an output stream
Endpoint: `/a/`
HTTP Method: `PATCH`
Example (cURL):
`curl -X PATCH -d "Some new output for the stream" http://doma.in/a/ABC123`
#### Delete an output stream
Endpoint: `/d/`
HTTP Method: `DELETE`
Example (cURL):
`curl -X DELETE http://doma.in/d/ABC123`
#### Fetch a stream's full output
Endpoint: `/g/`
Successful response content: The full output as plain text.
HTTP Method: `GET`
Example (cURL):
`curl http://doma.in/g/ABC123`