HTsync

Publish and download complete folder structures via HTTP(S).

Intention

Quick transfer of complete folder structures in situations where SCP, rsync, SFTP, or SMB shares are not an option because of firewall restrictions, platform incompatibility or installation complexity.

Requirements

• NodeJS ≥ 10
• A (potentially NAT forwared) port at the server side must be reachable form the client via HTTP(S) protocol.

Warning

HTsync server has no authentication feature (yet). Using it on a public port in an unsafe network environment can disclose data to an unwanted audience.

Installation

npm i -g htsync

Usage

You can show help for the command line arguments with htsync --help.

The htsync command knows three sub-commands: list, serve, and pull.

• list [target] (aliases: l, ls)
  Print all relative file paths to the console, that would be published by the serve sub-command. Use it to test your include/exclude patterns before starting the HTsync server.
  The target is optional and defaults to the current working directory.
• serve [-b <ip>] [-p <port>] [target] (aliases: s, svr)
  Start the HTsync server.
  The bound ip defaults to 0.0.0.0 (all network interfaces) and the port to 8080.
• pull <url> [target] (aliases: p, u, update)
  Download files from the server, reachable by the url.
  The target is optional and defaults to the current working directory.

You can show specific help for a sub-command with htsync <command> --help.

You can set command line options via environment variables.

E. g. to prepare the server URL on the client side for multiple htsync pull executions, you can set HTSYNC_URL="http://your-server:12345".

Server side

1. Navigate to the folder, you want to transfer
2. Check which files get published with htsync list
3. Run htsync serve -p 12345 to start the server
   Replace 12345 with a port, that is reachable by the client, possibly by port-forwarding in the firewall in front of your server.

Client side

1. Navigate to the folder, in which you want to download the files from the server
2. Run htsync pull http://your-server:12345
   Replace your-server by the IP of your server or a domain name resolving to the same, and 12345 by the port you specified on the server side.

Filtering

You can filter the files and directories at both sides of the transfer. You can limit the files transfered by specifying one or multiple include patterns with --include <pattern>* or -i <pattern>*. And you can block specific files by specifying one or multiple exclude patterns with --exclude <pattern>* or -x <pattern>*.

The patterns match case insensitive by default. Case-sensitive patterns can be specified with --cinclude/--ci and --cexclude/--cx.

Pattern Syntax

The pattern is searched in the relative path below the target directory of the server. The path is normalized on Windows by replacing back-slashes with forward-slashes.

By default, patterns are searched in the whole string. (image would match the relative path home/images/vacation)

To anchor the pattern at the beginning use a leading / in the pattern. (/image would match images/vacation but not home/images/vacation)

To anchor the pattern at the end use a trailing $ in the pattern. (.htm$ would match www/index.htm but not www/index.html)

You can use the wildcards ?, *, and ** in a pattern. The ? matches one arbitrary character. The * matches any number of characters, but not /. The ** matches any number of characters, including /.

Examples

Hint: To run the examples in the Windows CMD prompt, replace single quotes ' with double quotes ".

Publish only ISO files on the server side

htsync serve --include '**/*.iso$'

Publish only folders containing 2020 and 2021

htsync server --include '2020*/' '2021*/'

Download all sub-folders of work files/2020 and exclude Windows thumbnails

htsync pull --include `/work files/2020/*/` --exclude `**/Thumbs.db$`

License

The project is published under the MIT license.
Copyright (c) 2020 Tobias Kiertscher [email protected].

Some parts of the server code is borrowed from serve by Leo Lamprecht - Vercel. Thanks a lot!