sovonegr/TorrServerJellyfin
1
0
Fork 0
mirror of https://github.com/Ernous/TorrServerJellyfin.git synced 2025-12-19 13:36:09 +05:00
Code Issues Packages Projects Releases Wiki Activity

Add openapi API documentation (#294)

Browse Source 
* Initial version

- Add OpenAPI documentation generator
- Update README.md to remove endpoint documentations

* Adds new endpoints

- Fixes build with swag
- Adds new endpoints

* Adds more endpoints documentation

- Also removes swag from Dockerfile and build script

* Finally adds all endpoints documentation

* Initial version

- Add OpenAPI documentation generator
- Update README.md to remove endpoint documentations

* Adds new endpoints

- Fixes build with swag
- Adds new endpoints

* Adds more endpoints documentation

- Also removes swag from Dockerfile and build script

* Finally adds all endpoints documentation

* Update README (#1)

* Update README

I completely redid the `README.md`. Now it's much easier to read and understand.

---------

Co-authored-by: cocool97 <34218602+cocool97@users.noreply.github.com>

* Improves documentation

* Delete server/config.db

* Update README.md

* Update README.md

* fix download in api docs

* add api docs to web

---------

Co-authored-by: Shadeov <144587546+shadeov@users.noreply.github.com>
Co-authored-by: nikk gitanes <tsynik@gmail.com>
This commit is contained in:
cocool97
2023-11-13 07:59:23 +01:00
committed by GitHub
parent aa061fd24c
commit b72c66d433
32 changed files with 5375 additions and 2024 deletions
Download Patch File Download Diff File Expand all files Collapse all files

473
README.md
View File

@@ -1,24 +1,165 @@
## TorrServer
TorrServer, stream torrent to http
<p align="center" style="text-align: center">
<img src="https://github.com/YouROK/TorrServer/assets/144587546/53f7175a-cda4-4a06-86b6-2ac07582dcf1" width="33%"><br/>
</p>
<p align="center">
Simple and powerful tool for streaming torrents.
<br/>
<br/>
<a href="https://github.com/YouROK/TorrServer/blob/master/LICENSE">
<img alt="GitHub" src="https://img.shields.io/github/license/YouROK/TorrServer"/>
</a>
<a href="https://goreportcard.com/report/github.com/YouROK/TorrServer">
<img src="https://goreportcard.com/badge/github.com/YouROK/TorrServer" />
</a>
<a href="https://pkg.go.dev/github.com/YouROK/TorrServer">
<img src="https://pkg.go.dev/badge/github.com/YouROK/TorrServer.svg" alt="Go Reference"/>
</a>
<a href="https://github.com/YouROK/TorrServer/issues">
<img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat" alt="CodeFactor" />
</a>
<a href="https://github.com/YouROK/TorrServer/actions/workflows/github-actions-docker.yml" rel="nofollow">
<img src="https://img.shields.io/github/actions/workflow/status/YouROK/TorrServer/github-actions-docker.yml?logo=Github" alt="Build" />
</a>
<a href="https://github.com/YouROK/TorrServer/tags" rel="nofollow">
<img alt="GitHub tag (latest SemVer pre-release)" src="https://img.shields.io/github/v/tag/YouROK/TorrServer?include_prereleases&label=version"/>
</a>
</p>
## Introduction
TorrServer is a program that allows users to view torrents online without the need for preliminary file downloading.
The core functionality of TorrServer includes caching torrents and subsequent data transfer via the HTTP protocol,
allowing the cache size to be adjusted according to the system parameters and the user's internet connection speed.
## Features
- Caching
- Streaming
- Local and Remote Server
- Viewing torrents on various devices
- Selecting a player for video playback
- Integration with other apps
## Getting Started
### Installation
Just download server from releases and exec file\
https://github.com/YouROK/TorrServer/releases \
Then open the browser link http://127.0.0.1:8090 or https://127.0.0.1:8091 if the server was started with --ssl option \
On linux systems you may need to set the environment variable before run \
***export GODEBUG=madvdontneed=1***
#### macOS install / configure / uninstall script
Just run in Terminal: `curl -s https://raw.githubusercontent.com/YouROK/TorrServer/master/installTorrServerMac.sh -o installTorrserverMac.sh && chmod 755 installTorrServerMac.sh && sudo ./installTorrServerMac.sh`
Alternative install script for Intel Macs: https://github.com/dancheskus/TorrServerMacInstaller
Download the application for the required platform in the [releases](https://github.com/YouROK/TorrServer/releases) page. After installation, open the link <http://127.0.0.1:8090> in the browser.'
#### Linux on VPS install / configure / uninstall script
Just run in console: `curl -s https://raw.githubusercontent.com/YouROK/TorrServer/master/installTorrServerLinux.sh | sudo bash`
#### Windows
#### Unofficial TorrServer iocage plugin
On FreeBSD (TrueNAS/FreeNAS) you can use this plugin
Run `TorrServer-windows-amd64.exe`.
https://github.com/filka96/iocage-plugin-TorrServer
#### Linux
Run in console
```bash
curl -s https://raw.githubusercontent.com/YouROK/TorrServer/master/installTorrServerLinux.sh | sudo bash
```
#### macOS
Run in console
```bash
curl -s https://raw.githubusercontent.com/YouROK/TorrServer/master/installTorrServerMac.sh -o installTorrserverMac.sh && chmod 755 installTorrServerMac.sh && sudo ./installTorrServerMac.sh
```
Alternative install script for Intel Macs: <https://github.com/dancheskus/TorrServerMacInstaller>
#### IOCage Plugin (Unofficial)
On FreeBSD (TrueNAS/FreeNAS) you can use this plugin: <https://github.com/filka96/iocage-plugin-TorrServer>
#### For NAS Systems (Unofficial)
- Several releases are available through this link: <https://github.com/vladlenas>
- **Synology NAS** packages repo source: <https://grigi.lt>
### Server args
- `--port PORT`, `-p PORT` - web server port, default 8090
- `--ssl` - enables https for web server
- `--sslport PORT` - web server https port, default 8091. If not set, will be taken from db (if stored previously) or use default.
- `--sslcert PATH` - path to ssl cert file. If not set, will be taken from db (if stored previously) or default self-signed certificate/key will be generated.
- `--sslkey PATH` - path to ssl key file. If not set, will be taken from db (if stored previously) or default self-signed certificate/key will be generated.
- `--path PATH`, `-d PATH` - database dir path
- `--logpath LOGPATH`, `-l LOGPATH` - server log file path
- `--weblogpath WEBLOGPATH`, `-w WEBLOGPATH` - web access log file path
- `--rdb`, `-r` - start in read-only DB mode
- `--httpauth`, `-a` - enable http auth on all requests
- `--dontkill`, `-k` - don't kill server on signal
- `--ui`, `-u` - open torrserver page in browser
- `--torrentsdir TORRENTSDIR`, `-t TORRENTSDIR` - autoload torrents from dir
- `--torrentaddr TORRENTADDR` - Torrent client address (format [IP]:PORT, ex. :32000, 127.0.0.1:32768 etc)
- `--pubipv4 PUBIPV4`, `-4 PUBIPV4` - set public IPv4 addr
- `--pubipv6 PUBIPV6`, `-6 PUBIPV6` - set public IPv6 addr
- `--searchwa`, `-s` - allow search without authentication
- `--help`, `-h` - display this help and exit
- `--version` - display version and exit
Example:
```bash
TorrServer-darwin-arm64 [--port PORT] [--path PATH] [--logpath LOGPATH] [--weblogpath WEBLOGPATH] [--rdb] [--httpauth] [--dontkill] [--ui] [--torrentsdir TORRENTSDIR] [--torrentaddr TORRENTADDR] [--pubipv4 PUBIPV4] [--pubipv6 PUBIPV6] [--searchwa]
```
### Running in Docker & Docker Compose
Run in console
```bash
docker run --rm -d --name torrserver -p 8090:8090 ghcr.io/yourok/torrserver:latest
```
For running in persistence mode, just mount volume to container by adding `-v ~/ts:/opt/ts`, where `~/ts` folder path is just example, but you could use it anyway... Result example command:
```bash
docker run --rm -d --name torrserver -v ~/ts:/opt/ts -p 8090:8090 ghcr.io/yourok/torrserver:latest
```
#### Environments
- `TS_HTTPAUTH` - 1, and place auth file into `~/ts/config` folder for enabling basic auth
- `TS_RDB` - if 1, then the enabling `--rdb` flag
- `TS_DONTKILL` - if 1, then the enabling `--dontkill` flag
- `TS_PORT` - for changind default port to **5555** (example), also u need to change `-p 8090:8090` to `-p 5555:5555` (example)
- `TS_CONF_PATH` - for overriding torrserver config path inside container. Example `/opt/tsss`
- `TS_TORR_DIR` - for overriding torrents directory. Example `/opt/torr_files`
- `TS_LOG_PATH` - for overriding log path. Example `/opt/torrserver.log`
Example with full overrided command (on default values):
```bash
docker run --rm -d -e TS_PORT=5665 -e TS_DONTKILL=1 -e TS_HTTPAUTH=1 -e TS_RDB=1 -e TS_CONF_PATH=/opt/ts/config -e TS_LOG_PATH=/opt/ts/log -e TS_TORR_DIR=/opt/ts/torrents --name torrserver -v ~/ts:/opt/ts -p 5665:5665 ghcr.io/yourok/torrserver:latest
```
#### Docker Compose
```yml
# docker-compose.yml
version: '3.3'
services:
torrserver:
image: ghcr.io/yourok/torrserver
container_name: torrserver
environment:
- TS_PORT=5665
- TS_DONTKILL=1
- TS_HTTPAUTH=0
- TS_CONF_PATH=/opt/ts/config
- TS_TORR_DIR=/opt/ts/torrents
volumes:
- './CACHE:/opt/ts/torrents'
- './CONFIG:/opt/ts/config'
ports:
- '5665:5665'
restart: unless-stopped
```
#### NAS releases
https://github.com/vladlenas
@@ -26,264 +167,98 @@ https://github.com/vladlenas
Synology NAS packages repo source: https://grigi.lt
### Build
Install golang 1.16+ by instruction: https://golang.org/doc/install \
Goto dir to source\
Run build script under linux build-all.sh\
For build web page need install npm and yarn\
For instal yarn: _npm i -g yarn_ after install npm\
For build android server need android toolchain\
Download android ndk and change NDK_TOOLCHAIN in build.sh to\
path/to/Android/sdk/ndk/ver/toolchains/llvm/prebuilt/platform
#
### Server args:
#### Usage
TorrServer-darwin-arm64 [--port PORT] [--ssl] [--sslport PORT] [--sslcert PATH] [--sslkey PATH] [--path PATH] [--logpath LOGPATH] [--weblogpath WEBLOGPATH] [--rdb] [--httpauth] [--dontkill] [--ui] [--torrentsdir TORRENTSDIR] [--torrentaddr TORRENTADDR] [--pubipv4 PUBIPV4] [--pubipv6 PUBIPV6] [--searchwa]
#### Server
#### Options
* --port PORT, -p PORT
* web server port, default 8090
* --ssl
* enables https
* --sslport PORT
* web server ssl port, If not set, will be set to default 8091 or taken from db(if stored previously). Accepted if --ssl enabled.
* --sslcert PATH
* path to ssl cert file. If not set, will be taken from db(if stored previously) or default self-signed certificate/key will be generated. Accepted if --ssl enabled.
* --sslkey PATH
* path to ssl key file. If not set, will be taken from db(if stored previously) or default self-signed certificate/key will be generated. Accepted if --ssl enabled.
* --path PATH, -d PATH
* database dir path
* --logpath LOGPATH, -l LOGPATH
* server log file path
* --weblogpath WEBLOGPATH, -w WEBLOGPATH
* web access log file path
* --rdb, -r
* start in read-only DB mode
* --httpauth, -a
* enable http auth on all requests
* --dontkill, -k
* don't kill server on signal
* --ui, -u
* open torrserver page in browser
* --torrentsdir TORRENTSDIR, -t TORRENTSDIR
* autoload torrents from dir
* --torrentaddr TORRENTADDR
* Torrent client address (format [IP]:PORT, ex. :32000, 127.0.0.1:32768 etc)
* --pubipv4 PUBIPV4, -4 PUBIPV4
* set public IPv4 addr
* --pubipv6 PUBIPV6, -6 PUBIPV6
* set public IPv6 addr
* --searchwa, -s
* search without auth
* --help, -h
* display this help and exit
* --version
* display version and exit
- Install [Golang](https://golang.org/doc/install) 1.18+
- Go to the TorrServer source directory
- Run build script under linux or macOS `build-all.sh`
#### Web
#
### Http Api of TorrServer:
#### GET
- Install **npm** and **yarn**
- Go to the web directory
- Run `NODE_OPTIONS=--openssl-legacy-provider yarn build`
###### /echo
*Return version of server*
#### Android
###### /shutdown
*Shutdown server*
To build an Android server you will need the Android Toolchain.
###### /stream...
#### args:
* link - magnet/hash/link to torrent
* index - index of file
* preload - preload torrent
* stat - return stat of torrent
* save - save to db
* m3u - return m3u
* fromlast - return m3u from last play
* play - start stream torrent
* title - set title of torrent
* poster - set poster link of torrent
#### Swagger
##### Examples:
>**get stat**
>
>http://127.0.0.1:8090/stream/fname?link=...&stat
>
>**get m3u**
>
>http://127.0.0.1:8090/stream/fname?link=...&index=1&m3u
>http://127.0.0.1:8090/stream/fname?link=...&index=1&m3u&fromlast
>
>**stream torrent**
>
>http://127.0.0.1:8090/stream/fname?link=...&index=1&play
>http://127.0.0.1:8090/stream/fname?link=...&index=1&play&save
>http://127.0.0.1:8090/stream/fname?link=...&index=1&play&save&title=...&poster=...
>
>**only save**
>
>http://127.0.0.1:8090/stream/fname?link=...&save&title=...&poster=...
`swag` must be installed on the system to [re]build Swagger documentation.
###### /play/:hash/:id
#### params:
* hash - hash of torrent
* index - index of file
###### /playlistall/all.m3u
*Get all http links of all torrents in m3u list*
###### /playlist
*Get http link of torrent in m3u list*
#### args:
* hash - hash of torrent
* fromlast - from last play file
#
#### POST
###### /torrents
##### Send json:
{\
"action": "add/get/set/rem/list/drop",\
"link": "hash/magnet/link to torrent",\
"hash": "hash of torrent",\
"title": "title of torrent",\
"poster": "link to poster of torrent",\
"data": "custom data of torrent, may be json",\
"save_to_db": true/false\
}
##### Return json of torrent(s)
###### /torrent/upload
##### Send multipart/form data
Only one file support
#### args:
* title - set title of torrent
* poster - set poster link of torrent
* data - set custom data of torrent, may be json
* save - save to db
###### /cache
##### Send json:
{\
"action": "get"\
"hash" : ""hash": "hash of torrent",\
}
##### Return cache stat
https://github.com/YouROK/TorrServer/blob/d36d0c28f805ceab39adb4aac2869cd7a272085b/server/torr/storage/state/state.go
###### /settings
##### Send json:
{\
"action": "get/set/def",\
_fields of BTSets_\
}
##### Return json of BTSets
https://github.com/YouROK/TorrServer/blob/d36d0c28f805ceab39adb4aac2869cd7a272085b/server/settings/btsets.go
###### /viewed
##### Send json:
{\
"action": "set/rem/list",\
"hash": "hash of torrent",\
"file_index": int, id of file,\
}
##### Return
if hash is empty, return all viewed files\
if hash is not empty, return viewed file of torrent
##### Json struct see in
https://github.com/YouROK/TorrServer/blob/d36d0c28f805ceab39adb4aac2869cd7a272085b/server/settings/viewed.go
#
### Authorization
The user data file should be located near to the settings.\
Basic auth, read more in wiki \
https://en.wikipedia.org/wiki/Basic_access_authentication
File name: *accs.db*\
File format:
{\
"User1": "Pass1",\
"User2": "Pass2"\
}
#
### Whitelist/Blacklist ip
The lists file should be located near to the settings.
whitelist file name: wip.txt\
blacklist file name: bip.txt
whitelist has prior
Example:\
local:127.0.0.0-127.0.0.255\
127.0.0.0-127.0.0.255\
local:127.0.0.1\
127.0.0.1\
\# at the beginning of the line, comment
#
### MSX Install:
Open msx and goto: Settings -> Start Parameter -> Setup \
Enter current ip address and port of server e.g. _127.0.0.1:8090_
#
### Running in docker
Just run: `docker run --rm -d --name torrserver -p 8090:8090 ghcr.io/yourok/torrserver:latest` \
For running in persistence mode, just mount volume to container by adding `-v ~/ts:/opt/ts`, where `~/ts` folder path is just example, but you could use it anyway... Result example command: `docker run --rm -d --name torrserver -v ~/ts:/opt/ts -p 8090:8090 ghcr.io/yourok/torrserver:latest` \
Other options:
- add `-e TS_HTTPAUTH=1` and place [auth file](#authorization) into `~/ts/config` forlder for enabling basic auth
- add `-e TS_RDB=1` for enabling `--rdb` flag
- add `-e TS_DONTKILL=1` for enabling `--dontkill` flag
- add `-e TS_PORT=5555` for changind default port to 5555(example), also u need to change `-p 8090:8090` to `-p 5555:5555` (example)
- add `-e TS_CONF_PATH=/opt/tsss` for overriding torrserver config path inside container
- add `-e TS_TORR_DIR=/opt/torr_files` for overriding torrents directory
- add `-e TS_LOG_PATH=/opt/torrserver.log` for overriding log path
Example with full overrided command(on default values):
```
docker run --rm -d -e TS_PORT=5665 -e TS_DONTKILL=1 -e TS_HTTPAUTH=1 -e TS_RDB=1 -e TS_CONF_PATH=/opt/ts/config -e TS_LOG_PATH=/opt/ts/log -e TS_TORR_DIR=/opt/ts/torrents --name torrserver -v ~/ts:/opt/ts -p 5665:5665 ghcr.io/yourok/torrserver:latest
```bash
go install github.com/swaggo/swag/cmd/swag@latest
cd server; swag init -g web/server.go
# Documentation can be linted using
swag fmt
```
### MSX Install
#
### Donate:
[QIWI](https://qiwi.com/n/YOUROK85) \
[YooMoney](https://yoomoney.ru/to/410013733697114/200) \
[PayPal](https://www.paypal.me/yourok)
Open msx and goto: Settings -> Start Parameter -> Setup
SberBank card: **5484 4000 2285 7839**
Enter current ip address and port of server _e.g. 127.0.0.1:8090_
YooMoney card: **4048 4150 1812 8179**
## API
### API Docs
#
### Thanks to everyone who tested and helped
API documentation is hosted as Swagger format available at path `/swagger/index.html`.
###### @nacrolix **Matt Joiner** [github.com/anacrolix](https://github.com/anacrolix/)
### API Authentication
###### @tsynik [github.com/tsynik](https://github.com/tsynik)
The user data file should be located near to the settings. Basic auth, read more in wiki <https://en.wikipedia.org/wiki/Basic_access_authentication>.
###### @dancheskus [github.com/dancheskus](https://github.com/dancheskus)
`accs.db` in JSON format:
###### @kolsys [github.com/kolsys](https://github.com/kolsys)
```json
{
"User1": "Pass1",
"User2": "Pass2"
}
```
###### @vladlenas [github.com/vladlenas](https://github.com/vladlenas)
## Whitelist/Blacklist IP
###### @Nemiroff aka **Tw1cker** [github.com/Nemiroff](https://github.com/Nemiroff)
The lists file should be located in the same directory with config.db.
###### @spawnlmg **SpAwN_LMG** [github.com/spawnlmg](https://github.com/spawnlmg)
- Whitelist file name: `wip.txt`
- Blacklist file name: `bip.txt`
###### @TopperBG **Dimitar Maznekov** [github.com/TopperBG](https://github.com/TopperBG)
Whitelist has priority over everything else.
###### @FaintGhost **Zhang Yaowei** [github.com/FaintGhost](https://github.com/FaintGhost)
Example:
###### @Anton111111 **Anton Potekhin** [github.com/Anton111111](https://github.com/Anton111111)
```text
local:127.0.0.0-127.0.0.255
127.0.0.0-127.0.0.255
local:127.0.0.1
127.0.0.1
# at the beginning of the line, comment
```
## Donate
- [QIWI](https://qiwi.com/n/YOUROK85)
- [YooMoney](https://yoomoney.ru/to/410013733697114/200)
- [PayPal](https://www.paypal.me/yourok)
- SberBank Card: **5484 4000 2285 7839**
- YooMoney Card: **4048 4150 1812 8179**
## Thanks to everyone who tested and helped
- [anacrolix (Matt Joiner)](https://github.com/anacrolix)
- [tsynik](https://github.com/tsynik)
- [dancheskus](https://github.com/dancheskus)
- [kolsys](https://github.com/kolsys)
- [vladlenas](https://github.com/vladlenas)
- [Nemiroff (Tw1cker)](https://github.com/Nemiroff)
- [spawnlmg (SpAwN_LMG)](https://github.com/spawnlmg)
- [TopperBG (Dimitar Maznekov)](https://github.com/TopperBG)
- [FaintGhost (Zhang Yaowei)](https://github.com/FaintGhost)
- [Anton111111 (Anton Potekhin)](https://github.com/Anton111111)
- [lieranderl (Evgeni)](https://github.com/lieranderl)
- [cocool97](https://github.com/cocool97)