qft/README.md

82 lines
3.5 KiB
Markdown
Raw Normal View History

2022-08-13 12:29:47 +02:00
# qft
QFT is a small command line application for Quick Peer-To-Peer UDP file transfer.
## Usage:
- Find a public QFT helper (for example tudbut.de:4277)
- On the sender PC, enter `qft sender <helper> <shared-phrase> <filename>`.
- On the receiver PC, enter `qft receiver <helper> <shared-phrase> <filename>`.
- Both PCs should start transferring after a short while. If they don't, try again.
2022-08-15 15:17:31 +02:00
### Arguments:
```
qft helper <bind-port>
qft sender <helper-address>:<helper-port> <phrase> <filename> [bitrate] [skip]
qft receiver <helper-address>:<helper-port> <phrase> <filename> [bitrate] [skip]
```
## What helpers do
2022-08-15 18:50:11 +02:00
Helpers are NOT relays for data, they are only used to ESTABLISH the connection.
Helpers are there to help with holepunching.
- P1 connects\* to helper
- P1 sends the phrase to the helper
- P1 waits for a response
- Some time passes
- P2 connects\* to the same helper
- P2 sends the phrase to the helper
- P2 gets P1's public IP and port
- P1 gets P2's public IP and port
- P1 and P2 disconnect\* from the helper
2022-08-15 21:21:01 +02:00
- P1 and P2 start a loop (slightly simplified):
- fire a packet at eachother multiple times
- try to receive as many packets from the other one
- if none are received, loop again
- if one is received, exit the loop
- Connection between P1 and P2 is established.
\*UDP is a connection-less protocol, there are no handshakes. The word "connection" is used here as
2022-08-15 18:48:14 +02:00
an indicator that data will be exchanged between the "connected" parties. The word "disconnect" is used
here as an indicator that no more data will be exchanged between the "previously connected" parties.
2022-08-15 15:17:31 +02:00
2022-08-13 12:29:47 +02:00
## Tips 'n Tricks
- You can add a number to the end of both of your commands (after the filename) to
boost transfer speeds (higher = faster), but a too large number might cause unreliability
2022-08-15 18:55:25 +02:00
due to local network conditions or VPNs. The maximum possible is 65533 (65535 - 2).
2022-08-15 18:58:52 +02:00
- Helpers don't **have to** be run on a public server, they work in LAN too, but that way, only
computers in the same LAN will be able to use them.
2022-08-15 14:41:46 +02:00
- To use qfts and qftr aliases on linux or mac, run (replacing `(shell)` with your shell name,
usually bash or zsh):
2022-08-14 20:28:03 +02:00
```sh
2022-08-15 12:26:07 +02:00
echo 'alias qftr="qft receiver tudbut.de:4277"' >> ~/.(shell)rc
echo 'alias qfts="qft sender tudbut.de:4277"' >> ~/.(shell)rc
2022-08-15 14:41:46 +02:00
source ~/.(shell)rc
2022-08-14 20:28:03 +02:00
```
2022-08-13 12:29:47 +02:00
2022-08-15 13:10:59 +02:00
## Cool stuff
- Files are transferred over UDP, but qft has additional reliability measures in place to avoid
broken files.
- Unreliable internet connection? No problem! QFT will simply pause transmission until the
connection is back! Doesn't work? Check out the "Resume a fully stopped transfer" section!
- Did you know you can hibernate or suspend your computer while it's transferring and it'll continue
where it left of, even when only one side is suspended (unless your router blocked the port, read
2022-08-15 13:12:47 +02:00
the "Resume a fully stopped transfer" section in that case)?
2022-08-15 18:31:27 +02:00
- It's written in *100% pure Rust*.
2022-08-15 13:10:59 +02:00
## Resume a fully stopped transfer
You most likely won't need this unless the transfer completely died due to a VERY long pause or a
computer restart, but if you do:
Stop qft on both ends and start it again with the [skip] parameter in place (if you didn't specify a
bitrate before, the default is 256). It will skip those bytes and continue where you specified.
2022-08-13 12:29:47 +02:00
## Troubleshooting
2022-08-15 21:21:01 +02:00
### It says `Connecting...` but doesn't connect
2022-08-13 12:29:47 +02:00
One of your ends didn't correctly connect to the helper. Stop the transfer on both ends
2022-08-15 21:21:01 +02:00
and try again.
2022-08-15 18:26:21 +02:00
## [Relevant XKCD](https://xkcd.com/949)
2022-08-15 18:28:17 +02:00
![Relevant XKCD Image](https://imgs.xkcd.com/comics/file_transfer.png)