meteTorrent

---------------------------------------------------------------------------
ABOUT
---------------------------------------------------------------------------

meteTorrent is a native BitTorrent client for AROS x86_64.  It uses the
pure-C libtransmission 3.00 engine (the last C release of Transmission)
and comes in two flavours:

    mt_gui   MUI/Zune GUI
    mt_cli   small command-line client (handy for testing / scripting)

---------------------------------------------------------------------------
PACKAGE CONFIG
---------------------------------------------------------------------------

An "mtcfg" drawer is created automatically next to the executable the
first time you run either program.  It holds the session data:

    mtcfg/torrents/     cached .torrent files
    mtcfg/resume/       resume data (lets torrents continue after a restart)
    mtcfg/blocklists/   blocklist storage (unused for now)

The default download drawer is SYS:mt.

---------------------------------------------------------------------------
INSTALLATION
---------------------------------------------------------------------------

1. Copy the programs wherever you like, for example:

       SYS:Tools/meteTorrent
     
   mtcfg is created next to the executable.  If the program drawer is read-only,
mtcfg falls
   back to SYS:mtcfg.

2. For HTTPS (https trackers, https web seeds, https magnet "xs=" links)
   install AmiSSL 5:

       Copy amisslmaster.library  SYS:Libs/
       Copy amissl_v362.library   SYS:Libs/

   Without AmiSSL, plain http trackers and web seeds still work.

3. Start it from a Shell (or attach a project icon):

       SYS:Tools/meteTorrent/mt_gui

   You can also pass a torrent or a magnet link on the command line:

       mt_gui SYS:Downloads/example.torrent
       mt_gui "magnet:?xt=urn:btih:..."
       mt_gui SYS:Downloads/example.magnet

---------------------------------------------------------------------------
GUI QUICK START
---------------------------------------------------------------------------

1. Click "Open..." (or File -> Open Torrent...), pick a .torrent file.
   A plain text file whose first line is a magnet: link also works.

2. New torrents are added PAUSED.  Select the torrent and press
   "Download" to start it (this also resumes a paused torrent).

3. Use "Pause" to stop a torrent, "Cancel" to stop it and "Remove" to
   drop it from the list.

4. The window has:
       - a sidebar with status filters (All, Downloading, Seeding,
         Completed, Resumed, Paused, Active, Inactive, Error)
       - a torrent table: Name, Size, Done, Status, Seeds, Peers, Down, Up
       - a detail area with tabs:
             General      progress, availability, speeds, ratio, ETA
             Trackers     tracker list and status
             Peers        connected peers
             HTTP Sources web seeds (http/https)
             Content      files inside the torrent
             Pieces       piece map
       - a status bar: DHT state, total download, total upload

5. Tools -> Settings...
       Save path:     download drawer (default SYS:mt)
       Shared folder: a drawer you want to seed
       Share now:     creates <folder>.torrent and starts seeding it

   "Share now" builds a .torrent from the folder, verifies the local data
   and seeds it back to the swarm.  Share it (or its magnet) with others
   so they can download from you.  A tracker or peers must be reachable
   for others to find you; meteTorrent does not run a tracker itself.

   Note: Save path and Shared folder apply to the current session only;
   they are not written to a preferences file yet.

6. Help -> About meteTorrent... shows the animated data-world window and
   the optional PayPal donation link (needs openurl.library).

The GUI refreshes once per second while at least one torrent is active.

---------------------------------------------------------------------------
CLI USAGE
---------------------------------------------------------------------------

    mt_cli [torrent | magnet-link | .magnet-file] [seconds]

    seconds   how long to run before closing the session (default 40)

Examples:

    mt_cli SYS:Downloads/example.torrent 120
    mt_cli "magnet:?xt=urn:btih:..." 180
    mt_cli SYS:Downloads/example.magnet

Every second it prints one status line, for example:

    status=4 progress=12.5% peers=8 webseeds=1 left=45000000 
    dl=512.0 ul=0.0 rawdl=640.0 err=0

    status        4 = downloading, 6 = seeding/complete, 2 = checking
    progress      percent of verified data
    peers         connected peers
    webseeds      web seeds currently sending data
    left          bytes left to download
    dl / ul       payload speeds in KB/s
    rawdl         raw download speed (including protocol overhead)
    err           transmission error code (0 = no error)

The CLI always closes the session when the time is up.  For everyday
use the GUI is recommended.

GUI command-line options:

    --download    start added torrents immediately (default: paused)
    --pieces      open the Pieces tab at startup

---------------------------------------------------------------------------
WHAT METETORRENT SUPPORTS
---------------------------------------------------------------------------

Torrents
    - BitTorrent v1 .torrent files (single-file and multi-file)
    - Magnet links
        * "xs=" exact-source metadata fetch over http/https
        * trackers and web seeds carried in the magnet link
    - Adding a plain-text .magnet file (first line starts with "magnet:")
    - Piece hash verification and resume data
    - Seeding after the download completes

Network / transfer
    - TCP peer connections
    - Peer Exchange (PEX)
    - HTTP and HTTPS trackers
    - HTTP and HTTPS web seeds
    - IPv4 and IPv6 bind addresses
    - Plaintext peer connections (see limitations for encryption)

GUI
    - serk118 style layout
    - Status sidebar filters
    - Live torrent table (seeds, peers, speeds, progress)
    - Tabs: General, Trackers, Peers, HTTP Sources, Content, Pieces
    - Add paused, then Download/Pause/Cancel/Remove
    - Configurable download drawer for the session
    - Shared-folder seeding ("Share now")
    - About window with animation and donation link
    - 1-second auto refresh while a torrent is active

---------------------------------------------------------------------------
LIMITATIONS / NOT YET SUPPORTED
---------------------------------------------------------------------------

    - BitTorrent v2 (BEP 52) torrents are not supported (engine 3.00 is v1).
    - DHT is disabled in this build.
    - uTP is disabled; peers use TCP only.
    - No UPnP or NAT-PMP port forwarding.  If you are behind a router,
      forward your peer port manually for best connectivity.
    - No encrypted peer connections (plaintext only).  TR_CLEAR_PREFERRED
      is used to avoid the unsupported DH path.
    - UDP trackers are compiled in but not verified on AROS; use
      http/https trackers when possible.
    - The torrent list is not restored automatically when you restart the
      program.  Re-open the same .torrent/magnet and resume data is used.
    - Settings (save path, shared folder) are not persisted yet.
    - No bandwidth limits, queueing, scheduling, RSS or web interface.
    - Edit and View menus are placeholders.
    - AROS sqrt: the CLI session close path is not fully clean; the
      download itself completes.  Use the GUI for long-running sessions.

---------------------------------------------------------------------------
TROUBLESHOOTING
---------------------------------------------------------------------------

No peers / 0%:
    - Check that the tracker is reachable; https trackers need AmiSSL.
    - DHT is off, so a torrent needs a working tracker or web seed.
    - Try a torrent with an http tracker (for example a Linux distro ISO).
    - Behind NAT: forward the peer port manually.

"Metadata fetch failed" on a magnet:
    - The magnet's "xs=" URL could not be fetched.  https needs AmiSSL.
    - Try opening the matching .torrent file directly.

HTTPS fails but HTTP works:
    - Copy amisslmaster.library and amissl_v362.library to SYS:Libs/
      and restart meteTorrent.

Crash log:
    SYS:mt_crash.log (written next to SYS: by the crash logger).

H
---------------------------------------------------------------------------
CREDITS
---------------------------------------------------------------------------

Engine:  libtransmission 3.00, (c) Transmission authors, GPLv2.
         https://transmissionbt.com/
TLS:     AmiSSL 5.27 (OpenSSL 3.6.2) for AROS x86_64.
GUI:     MUI/Zune.
Icon / About animation: original artwork for meteTorrent.

meteTorrent is free software under the GNU General Public License v2.
See the libtransmission source for the full license text.

Donations (optional): PayPal serk118()gmail.com