# GrabFlow (CLI prototype)

GrabFlow is a working prototype of the download-engine core of the
"GrabFlow" smart download manager concept. It performs segmented,
parallel HTTP downloading using Range requests, can resume an
interrupted download from where it left off, and verifies the finished
file against a SHA-256 checksum if you give it one. Every download is
written to a `<outfile>.part` file and only renamed to the final
`<outfile>` once it is fully written and (if requested) checksum-
verified, so a failed or interrupted download never leaves a file at
the final name that looks complete but isn't. The full GrabFlow concept
also includes browser-capture integration (catching downloads a browser
initiates) and auto-unpack/file-rules (automatically extracting
archives and routing files by type) -- both of those need a browser
extension component and are on the roadmap rather than in this CLI
prototype. See ../plan.md for the full product plan.

## Build from source

Requires Go 1.24+, no external dependencies.

    go build -o grabflow .

Cross-compile for another platform:

    GOOS=windows GOARCH=amd64 go build -o grabflow.exe .
    GOOS=darwin  GOARCH=arm64 go build -o grabflow .

## Usage

    grabflow get <url> -o <outfile> [--segments N] [--sha256 EXPECTED_HASH] [--resume] [--timeout 30s]

Flags:

  -o FILE             Output file path (required).
  --segments N        Number of parallel range-based segments to download
                      with (default 1, i.e. a plain sequential download).
                      Only used when the server confirms it supports byte
                      ranges and reports a content length; otherwise
                      GrabFlow automatically falls back to a single-stream
                      download and says so.
  --sha256 HASH       Expected SHA-256 hex digest. After the download
                      completes, GrabFlow hashes the downloaded bytes and
                      compares. On mismatch it prints the expected and
                      actual hashes, leaves the `.part` file in place
                      (does NOT rename it to <outfile>), and exits non-zero.
  --resume            If `<outfile>.part` already exists, resume from its
                      current size instead of starting over -- but only if
                      the server supports byte ranges. If it doesn't,
                      GrabFlow says so and restarts the download from
                      scratch rather than silently corrupting the file.
  --timeout DURATION  Per-HTTP-request timeout, e.g. 30s, 2m (default 30s).

### The `.part` convention

Every download is written to `<outfile>.part`. GrabFlow only renames it
to `<outfile>` after the file is fully written, its size matches the
server-reported content length (when known), and it passes checksum
verification (when `--sha256` was given). If anything goes wrong, the
`.part` file is left behind and no file appears at the final `<outfile>`
name -- so the presence of `<outfile>` is itself a reliable signal that
the download succeeded.

### How resume and segments interact

Segmented downloading and resume are not combined in this prototype.
If `--resume` finds an existing `.part` file (and the server supports
ranges), GrabFlow always falls back to a single-stream resume starting
at the partial file's current size, even if `--segments` was also
given. If there is no existing `.part` file to resume, `--segments`
behaves normally. This is called out explicitly as a stretch-goal
simplification, not an oversight: real segmented+resume (tracking each
segment's own progress) is a reasonable future enhancement.

### How range support is detected

GrabFlow does not trust the `Accept-Ranges` response header alone,
since some servers omit it while still honoring `Range` requests. It
sends an actual `Range: bytes=0-0` GET request and checks for an HTTP
`206 Partial Content` response; only then does it treat the server as
range-capable and enable segmented downloading or resume. If the
server responds `200 OK` to a ranged request (ignoring the Range
header), GrabFlow detects this and downloads the whole file as a single
stream instead.

### Example

    grabflow get https://example.com/big-file.iso -o big-file.iso --segments 8
    grabflow get https://example.com/big-file.iso -o big-file.iso --resume
    grabflow get https://example.com/big-file.iso -o big-file.iso \
        --sha256 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

## Prebuilt binaries

See ../downloads/ for prebuilt binaries (Windows/macOS/Linux) and
CHECKSUMS.txt for their SHA-256 hashes. These are unsigned indie builds --
Windows SmartScreen and macOS Gatekeeper will warn on first run, which is
expected until a code-signing certificate is in place.