Grab

https://github.com/cavaliergopher/grab
Admin
Grab is an extensible Go package designed for concurrently downloading files from the internet with...
Tokens:43,832
Snippets:290
Trust Score:6
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install grab command line downloader

Source: https://github.com/cavaliergopher/grab/blob/main/README.md

Installs the `grab` command line downloader binary to your Go bin directory. Use `@latest` to get the most recent version.

```shell
$ go install github.com/cavaliergopher/grab/v3/cmd/grab@latest
```

--------------------------------

### grab usage example with output

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/cli.md

Shows installing grab, downloading multiple files with progress output, and the exit codes for successful and failed runs. The output format is from ConsoleClient.

```console
$ go install github.com/cavaliergopher/grab/v3/cmd/grab@latest
$ grab https://example.com/archive.tar.gz https://example.com/readme.txt
Downloading 2 files...
Downloading ./archive.tar.gz 1.2MB / 8.4MB (14%) - 1.05MB/s ETA: ~7s
Downloading ./readme.txt 4KB / 4KB (100%) - 1.20MB/s ETA: <1s
Finished ./readme.txt 4KB / 4KB (100%)
...
Finished 2 successful, 0 failed, 0 incomplete.
$ echo $?
0
$ grab https://example.com/missing.bin
...
Finished 0 successful, 1 failed, 0 incomplete.
$ echo $?
1
```

--------------------------------

### Example: using grabtest options with WithTestServer

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabtest.md

Shows how to pass multiple HandlerOptions to grabtest.WithTestServer. The example sets a static status code of 418, a content length of 1024, an attachment filename, and a method whitelist for GET requests.

```go
grabtest.WithTestServer(t, func(url string) {
	req := grabtest.MustHTTPNewRequest("GET", url, nil)
	resp := grabtest.MustHTTPDoWithClose(req)
	grabtest.AssertHTTPResponseStatusCode(t, resp, 418)
},
	grabtest.StatusCodeStatic(418),
	grabtest.ContentLength(1024),
	grabtest.AttachmentFilename("file.bin"),
	grabtest.MethodWhitelist("GET"),
)
```

--------------------------------

### DoBatch example with 4 workers

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/client.md

Example of using DoBatch to download 10 files with 4 workers. It creates requests, starts the batch, and iterates over the response channel, checking each response's error and printing the downloaded file. Adapted from ExampleClient_DoBatch.

```go
import "github.com/cavaliergopher/grab/v3"

reqs := make([]*grab.Request, 0)
for i := 0; i < 10; i++ {
	url := fmt.Sprintf("http://example.com/example%d.zip", i+1)
	req, err := grab.NewRequest("/tmp", url)
	if err != nil {
		panic(err)
	}
	reqs = append(reqs, req)
}

client := grab.NewClient()
respch := client.DoBatch(4, reqs...)

for resp := range respch {
	if err := resp.Err(); err != nil {
		panic(err)
	}
	fmt.Printf("Downloaded %s to %s\n", resp.Request.URL(), resp.Filename)
}
```

--------------------------------

### Canonical grabtest usage example

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabtest.md

Shows the core test pattern using WithTestServer to start a test server and perform a grab.Get request, asserting the response status code.

```go
import "github.com/cavaliergopher/grab/v3/pkg/grabtest"

grabtest.WithTestServer(t, func(url string) {
	resp, err := grab.Get(filename, url)
	if err != nil {
		t.Fatalf("error in Get(): %v", err)
	}
	grabtest.AssertHTTPResponseStatusCode(t, resp.HTTPResponse, 200)
	// ...
}, grabtest.ContentLength(4096), grabtest.AcceptRanges(true))
```

--------------------------------

### Using NewConsoleClient with custom client

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabui.md

Example showing how to create a ConsoleClient with a custom grab.Client (e.g., to set a custom User-Agent) and process responses.

```go
client := grab.NewClient()
client.UserAgent = "my-downloader/1.0"

ui := grabui.NewConsoleClient(client)
respch := ui.Do(context.Background(), 4, reqs...)
for resp := range respch {
	if err := resp.Err(); err != nil {
		fmt.Fprintf(os.Stderr, "%v\n", err)
	}
}
```

--------------------------------

### Install Grab package with go get

Source: https://github.com/cavaliergopher/grab/blob/main/README.md

Adds the Grab package to your Go module dependencies. Run this in your project directory before using the package in your own program.

```shell
$ go get github.com/cavaliergopher/grab/v3
```

--------------------------------

### NewSMA usage example

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/bps.md

Example of using NewSMA to sample data and calculate BPS.

```go
import "github.com/cavaliergopher/grab/v3/pkg/bps"
import "time"

g := bps.NewSMA(6)

g.Sample(time.Now(), 0)
time.Sleep(time.Second)
g.Sample(time.Now(), 1024)
time.Sleep(time.Second)
g.Sample(time.Now(), 2048)

fmt.Println(g.BPS()) // ≈ 1024.0 — (2048-0) bytes over 2 seconds
```

--------------------------------

### Example: create and configure a download request

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/request.md

Shows how to create a request with grab.NewRequest, set the NoResume flag and an Authorization header, then execute it with the default client. Panics on request creation or response errors.

```go
import "github.com/cavaliergopher/grab/v3"

req, err := grab.NewRequest("/tmp", "http://example.com/example.zip")
if err != nil {
	panic(err)
}
req.NoResume = true
req.HTTPRequest.Header.Set("Authorization", "Basic YWxhZGRpbjpvcGVuc2VzYW1l")

resp := grab.DefaultClient.Do(req)
if err := resp.Err(); err != nil {
	panic(err)
}
```

--------------------------------

### NewSMA invalid configuration example

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/bps.md

Example showing that providing an invalid sample count to NewSMA results in a panic.

```go
g := bps.NewSMA(1)
// panic: sample count must be greater than 1
```

--------------------------------

### Basic download with grab.Get

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grab.md

Basic download example using grab.Get. It downloads a file to the /tmp directory and prints the final filename. Requires the grab package import.

```go
import "github.com/cavaliergopher/grab/v3"

resp, err := grab.Get("/tmp", "http://example.com/example.zip")
if err != nil {
	log.Fatal(err)
}
fmt.Println("Download saved to", resp.Filename)
```

--------------------------------

### Watch usage example

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/bps.md

Example of using Watch to monitor a stream in a separate goroutine.

```go
import "github.com/cavaliergopher/grab/v3/pkg/bps"
import "context"
import "time"

g := bps.NewSMA(6)
stream := myStream // an io.Reader, say

ctx, cancel := context.WithCancel(context.Background())

go bps.Watch(ctx, g,
	func() (n int64) {
		return stream.BytesRead()
	},
	time.Second)

// ... consume stream ...

cancel() // stop Watch; no goroutine leaks
```

--------------------------------

### grab CLI usage of grabui.GetBatch

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabui.md

Example from the grab CLI showing how to use grabui.GetBatch to download files and exit with the number of failed downloads.

```go
import "github.com/cavaliergopher/grab/v3/pkg/grabui"
import "context"
import "os"

respch, err := grabui.GetBatch(context.Background(), 0, ".", urls...)
if err != nil {
	fmt.Fprint(os.Stderr, err)
	os.Exit(1)
}

// return the number of failed downloads as exit code
failed := 0
for resp := range respch {
	if resp.Err() != nil {
		failed++
	}
}
os.Exit(failed)
```

--------------------------------

### WithTestServer

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabtest.md

Starts a test HTTP server with configurable handler options and invokes a callback with the server URL. The server is automatically cleaned up after the callback returns.

```APIDOC
## WithTestServer

### Description
Starts a test HTTP server for use in grab tests. The server is configured with the provided handler options and the callback is invoked with the server's base URL. The server is automatically stopped when the callback returns.

### Method
N/A (Go function)

### Endpoint
N/A

### Parameters
#### Function Parameters
- **t** (*testing.T) - Required - Test context
- **f** (func(url string)) - Required - Callback invoked with the server base URL
- **options** (...HandlerOption) - Optional - Handler options for configuring the test server

### Request Example
```go
import "github.com/cavaliergopher/grab/v3/pkg/grabtest"

grabtest.WithTestServer(t, func(url string) {
    resp, err := grab.Get(filename, url)
    if err != nil {
        t.Fatalf("error in Get(): %v", err)
    }
    grabtest.AssertHTTPResponseStatusCode(t, resp.HTTPResponse, 200)
    // ...
}, grabtest.ContentLength(4096), grabtest.AcceptRanges(true))
```

### Response
#### Success Response
No return value. The callback is expected to perform assertions and fail the test if necessary.

#### Response Example
N/A

### Behavior
- Builds the handler via `NewHandler(options...)`.
- Starts an `httptest` server.
- Calls `f(s.URL)` with the base URL.
- On return, stops the rate limiter ticker and closes the server (`h.close()`, `s.Close()`).
- Aborts the test with `t.Fatalf` if the handler cannot be created.

### Handler Request Serving (Behavior Reference)
`ServeHTTP` implements:
- Optional `ttfb` delay (TimeToFirstByte).
- Request method check against `methodWhitelist`, else `http.StatusMethodNotAllowed`.
- `Accept-Ranges: bytes` header when enabled.
- `Content-Disposition: attachment;filename="..."` when a filename is set.
- `Last-Modified` header (fixed value when configured, else now).
- `Range: bytes=N-` parsing when ranges are enabled; `offset >= contentLength` yields `http.StatusRequestedRangeNotSatisfiable`; malformed range yields `http.StatusBadRequest`.
- Header deletion via `headerBlacklist` before the header block is written.
- Body bytes `byte(i)` for `i` in `[offset, contentLength)` on GET (HEAD sends headers only), optionally throttled by a `time.Ticker`.
```

--------------------------------

### Do

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabui.md

Executes a batch of download requests with console progress display. Returns a channel of responses that are pumped as downloads start.

```APIDOC
## Do

### Description
Executes a batch of download requests with console progress display. Returns a channel of responses that are pumped as downloads start.

### Method
Method

### Endpoint
`func (c *ConsoleClient) Do(ctx context.Context, workers int, reqs ...*grab.Request) <-chan *grab.Response`

### Parameters
- **ctx** (context.Context) - Required - Cancellation context; breaks the UI loop when done.
- **workers** (int) - Required - Concurrency for `Client.DoBatch`.
- **reqs** (...*grab.Request) - Required - The requests to download.

### Returns
- **<-chan \*grab.Response** - Each response is pumped to the caller as soon as it starts downloading. The pump channel is closed when all downloads are complete, the context is done, or the request channel closes.

### Behavior
Runs a background goroutine that:
1. Resets counters, falls back to `grab.DefaultClient` when `client == nil`, prints `Downloading %d files...`.
2. Calls `c.client.DoBatch(workers, reqs...)` and starts a 200ms `time.Ticker`.
3. In a `select` loop: on `ctx.Done()` → stop; on each response → records it and pumps it to the caller's channel; on each tick → `c.refresh()`.
4. Refreshes once more, closes the pump channel, prints the final summary line.

The pump channel has a buffer of `len(reqs)` — enough to prevent slow receivers from causing back-pressure on the downloads.

### Example
```go
respch, err := grabui.GetBatch(context.Background(), 0, ".", urls...)
if err != nil {
    fmt.Fprint(os.Stderr, err)
    os.Exit(1)
}

failed := 0
for resp := range respch {
    if resp.Err() != nil {
        failed++
    }
}
os.Exit(failed)
```

Using a custom client:
```go
client := grab.NewClient()
client.UserAgent = "my-downloader/1.0"

ui := grabui.NewConsoleClient(client)
respch := ui.Do(context.Background(), 4, reqs...)
for resp := range respch {
    if err := resp.Err(); err != nil {
        fmt.Fprintf(os.Stderr, "%v\n", err)
    }
}
```
```

--------------------------------

### Monitoring a Download

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/response.md

Example showing how to monitor a download's progress using the Done channel and non-blocking checks.

```APIDOC
## Example — monitoring a download

### Description
Progress loop from the README / `v3/doc.go` pattern. Non-blocking checks are done on the `Done` channel; blocking methods (`Err`, `Wait`) must not be called from hook callbacks.

### Code
```go
client := grab.NewClient()
req, err := grab.NewRequest(".", "http://www.golang-book.com/public/pdf/gobook.pdf")
if err != nil {
    panic(err)
}

resp := client.Do(req)

t := time.NewTicker(500 * time.Millisecond)
defer t.Stop()

Loop:
for {
    select {
    case <-t.C:
        fmt.Printf("transferred %d / %d bytes (%.2f%%)\n",
            resp.BytesComplete(), resp.Size(), 100*resp.Progress())

    case <-resp.Done:
        break Loop
    }
}

if err := resp.Err(); err != nil {
    fmt.Fprintf(os.Stderr, "Download failed: %v\n", err)
    os.Exit(1)
}
fmt.Printf("Download saved to ./%v\n", resp.Filename)
```
```

--------------------------------

### Example: Using grabui.GetBatch to download multiple files

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabui.md

Shows how to call grabui.GetBatch with a context, worker count, destination directory, and multiple URLs. It iterates over the response channel, counting failures via resp.Err().

```go
import "github.com/cavaliergopher/grab/v3/pkg/grabui"
import "context"

respch, err := grabui.GetBatch(context.Background(), 8, "/tmp",
	"http://example.com/a.zip",
	"http://example.com/b.zip",
	"http://example.com/c.zip")
if err != nil {
	panic(err)
}

failed := 0
for resp := range respch {
	if resp.Err() != nil {
		failed++
	}
}
```

--------------------------------

### Throttle Download with Token Bucket

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/rate-limiter.md

Example of configuring a request with a token-bucket limiter from the golang.org/x/time/rate package.

```go
import "github.com/cavaliergopher/grab/v3"
import "time/rate"

req, err := grab.NewRequest("/tmp", "http://example.com/example.zip")
if err != nil {
	panic(err)
}

req.RateLimiter = &rate.Limiter{ // rate.Limiter implements grab.RateLimiter
	Capacity: 64 * 1024,
	Rate:     64 * 1024, // 64KB per second
}
req.BufferSize = 4096 // poll the limiter every 4KB

resp := grab.DefaultClient.Do(req)
if err := resp.Err(); err != nil {
	panic(err)
}
```

--------------------------------

### Progress

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/response.md

Method to get the download progress as a ratio.

```APIDOC
## Progress

### Description
Returns the ratio of total bytes downloaded (`BytesComplete() / Size()`); multiply by 100 for a percentage. Returns `0` when the size is unknown or non-positive (`size <= 0`).

### Method
Function

### Signature
`func (c *Response) Progress() float64`

### Parameters
None

### Returns
- **float64** - Progress ratio (0.0 to 1.0).
```

--------------------------------

### GetBatch

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabui.md

Starts a batch download with a console UI, returning a channel of responses and an error. It creates a console client and delegates to ConsoleClient.Do, printing progress and summary lines.

```APIDOC
## GetBatch

### Description
Starts a batch download with a console UI, returning a channel of responses and an error. It creates a console client and delegates to ConsoleClient.Do, printing progress and summary lines.

### Method
GetBatch

### Endpoint
GetBatch(ctx context.Context, workers int, dst string, urlStrs ...string) (<-chan *grab.Response, error)

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - cancelation context; when done, the UI loop and downloads stop
- **workers** (int) - Required - number of concurrent workers (passed through to Client.DoBatch)
- **dst** (string) - Required - destination directory (see NewRequest)
- **urlStrs** (...string) - Required - variadic URL strings

### Request Example
```go
import "github.com/cavaliergopher/grab/v3/pkg/grabui"
import "context"

respch, err := grabui.GetBatch(context.Background(), 8, "/tmp",
	"http://example.com/a.zip",
	"http://example.com/b.zip",
	"http://example.com/c.zip")
if err != nil {
	panic(err)
}

failed := 0
for resp := range respch {
	if resp.Err() != nil {
		failed++
	}
}
```

### Response
#### Success Response (200)
- **<-chan *grab.Response** - channel of responses; each download's response is delivered to the caller (and printed by the console client). The channel is closed when all downloads complete, the context is done, or a request could not be created.
- **error** - non-nil if any NewRequest fails (invalid URL).

#### Response Example
```go
respch, err := grabui.GetBatch(context.Background(), 8, "/tmp",
	"http://example.com/a.zip",
	"http://example.com/b.zip",
	"http://example.com/c.zip")
if err != nil {
	panic(err)
}

failed := 0
for resp := range respch {
	if resp.Err() != nil {
		failed++
	}
}
```
```

--------------------------------

### Producer/consumer with DoChannel

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/client.md

Producer/consumer example with 4 workers. The producer sends 10 requests, closes the request channel, and waits for workers to finish. Each worker processes one request at a time, and responses are sent to a buffered channel. The consumer reads responses and prints download results or errors.

```go
import "github.com/cavaliergopher/grab/v3"
import "sync"

reqch := make(chan *grab.Request)
respch := make(chan *grab.Response, 10)

client := grab.NewClient()
wg := sync.WaitGroup{}
for i := 0; i < 4; i++ {
	wg.Add(1)
	go func() {
		client.DoChannel(reqch, respch)
		wg.Done()
	}()
}

go func() {
	for i := 0; i < 10; i++ {
		url := fmt.Sprintf("http://example.com/example%d.zip", i+1)
		req, err := grab.NewRequest("/tmp", url)
		if err != nil {
			panic(err)
		}
		reqch <- req
	}
	close(reqch)
	wg.Wait()
	close(respch)
}()

for resp := range respch {
	if err := resp.Err(); err != nil {
		fmt.Fprintf(os.Stderr, "download failed: %v\n", err)
		continue
	}
	fmt.Printf("Downloaded %s to %s\n", resp.Request.URL(), resp.Filename)
}
```

--------------------------------

### Client struct

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/client.md

The download client struct with public configuration fields. All fields are plain assignments, e.g. client.HTTPClient.Transport.DisableCompression = true (example in v3/doc.go).

```go
type Client struct {
	// HTTPClient specifies the http.Client which will be used for communicating
	// with the remote server during the file transfer.
	HTTPClient HTTPClient

	// UserAgent specifies the User-Agent string which will be set in the
	// headers of all requests made by this client.
	//
	// The user agent string may be overridden in the headers of each request.
	UserAgent string

	// BufferSize specifies the size in bytes of the buffer that is used for
	// transferring all requested files. Larger buffers may result in faster
	// throughput but will use more memory and result in less frequent updates
	// to the transfer progress statistics. The BufferSize of each request can
	// be overridden on each Request object. Default: 32KB.
	BufferSize int
}
```

--------------------------------

### Cancellation and In-Memory Download

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/response.md

Examples for cancelling a download and reading a NoStore transfer from memory.

```APIDOC
## Example — cancellation and in-memory download

### Description
Cancel a hanging download with `Cancel()` and inspect the resulting error. Also demonstrates reading a `NoStore` transfer straight from memory.

### Code
```go
req, err := grab.NewRequest("", "http://example.com/example.zip")
if err != nil {
    panic(err)
}
resp := grab.DefaultClient.Do(req)

time.Sleep(200 * time.Millisecond) // let it start
err := resp.Cancel()
// err is typically context.Canceled; the transfer is finalized
if err != nil {
    fmt.Fprintln(os.Stderr, err)
}
```

### Code
```go
req, err := grab.NewRequest("", "http://example.com/example.zip")
if err != nil {
    panic(err)
}
req.NoStore = true

resp := grab.DefaultClient.Do(req)
if err := resp.Err(); err != nil { // blocks until complete
    panic(err)
}

b, err := resp.Bytes()
if err != nil {
    panic(err)
}
// b now holds the entire downloaded file; nothing was written to disk
```
```

--------------------------------

### Get

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grab.md

Blocking convenience function to download a URL to a destination file or directory.

```APIDOC
## Get

### Description
Blocking convenience function that downloads the content of a URL to a destination file path or directory. It uses the shared DefaultClient and blocks until the download completes.

### Function Signature
```go
func Get(dst, urlStr string) (*Response, error)
```

### Parameters
- **dst** (string) - Required - Destination file path or existing directory. Empty string is treated as current working directory.
- **urlStr** (string) - Required - URL string to download.

### Returns
- **\*Response** - The completed response; use `resp.Filename` for the final path.
- **error** - Non-nil if the request could not be created, client policy rejected the transfer, non-2XX status code, or any HTTP protocol/IO error occurred.

### Errors
- **StatusCodeError** - Server responded with a status outside 200-299 (post-redirect).
- **IO / HTTP protocol errors** - Network or filesystem failures during the transfer.

### Example
```go
import "github.com/cavaliergopher/grab/v3"

resp, err := grab.Get("/tmp", "http://example.com/example.zip")
if err != nil {
	log.Fatal(err)
}
fmt.Println("Download saved to", resp.Filename)
```
```

--------------------------------

### DoChannel

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/client.md

Documentation for the DoChannel method of the grab Client, including parameters, return behavior, notes, and an example.

```APIDOC
## DoChannel

### Description
Processes requests from a receive channel and sends responses to a send channel. The worker executes one request at a time until the request channel is closed by another goroutine.

### Method
DoChannel

### Signature
func (c *Client) DoChannel(reqch <-chan *Request, respch chan<- *Response)

### Parameters
- **reqch** (`<-chan *Request`) - Required - Receive channel of requests; the worker executes one request at a time until the channel is closed by another goroutine.
- **respch** (`chan<- *Response`) - Required - Send channel for responses; each response is sent as soon as it is received from the remote server.

### Returns
Void. Blocks the calling goroutine until `reqch` is closed and all transfers have completed.

### Notes
- Every response is sent through `respch`, then the worker blocks on `<-resp.Done` before processing the next request — so each download is fully completed before the next begins.
- Slow response receivers cause a worker to block and delay the transfer for an already-initiated connection, potentially causing a server timeout. The caller must use a sufficiently buffered `respch` to prevent this.
- Supports a producer/consumer model: the caller can keep sending new requests until it closes `reqch` (the comment preceding `ExampleClient_DoChannel` in `v3/example_client_test.go:24-32` calls this out as the difference from `DoBatch`).
- Per-transfer errors are available via `Response.Err`.
- As of the source revision, batch jobs cannot be canceled from the client (`// TODO: enable cancelling of batch jobs`, `v3/client.go:129`); cancel a single transfer via `Response.Cancel`.

### Example
Producer/consumer with 4 workers (adapted from `ExampleClient_DoChannel`, `v3/example_client_test.go:34-63`):

```go
import "github.com/cavaliergopher/grab/v3"
import "sync"

reqch := make(chan *grab.Request)
respch := make(chan *grab.Response, 10)

client := grab.NewClient()
wg := sync.WaitGroup{}
for i := 0; i < 4; i++ {
	wg.Add(1)
	go func() {
		client.DoChannel(reqch, respch)
		wg.Done()
	}()
}

go func() {
	for i := 0; i < 10; i++ {
		url := fmt.Sprintf("http://example.com/example%d.zip", i+1)
		req, err := grab.NewRequest("/tmp", url)
		if err != nil {
			panic(err)
		}
		reqch <- req
	}
	close(reqch)
	wg.Wait()
	close(respch)
}()

for resp := range respch {
	if err := resp.Err(); err != nil {
		fmt.Fprintf(os.Stderr, "download failed: %v\n", err)
		continue
	}
	fmt.Printf("Downloaded %s to %s\n", resp.Request.URL(), resp.Filename)
}
```
```

--------------------------------

### WithContext: Create request with 100ms timeout

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/request.md

Creates a grab request with a 100ms timeout using context.WithTimeout, then passes the context via WithContext. The example shows how to handle a cancelled request by checking resp.Err().

```go
import "github.com/cavaliergopher/grab/v3"
import "context"
import "time"

ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
defer cancel()

req, err := grab.NewRequest("", "http://example.com/example.zip")
if err != nil {
	panic(err)
}
req = req.WithContext(ctx)

resp := grab.DefaultClient.Do(req)
if err := resp.Err(); err != nil {
	fmt.Println("error: request cancelled")
}
```

--------------------------------

### DefaultClient singleton declaration

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/configuration.md

Declares the module-level DefaultClient using NewClient() with default configuration. Used by Get, GetBatch, grabui.GetBatch, and the CLI. Mutating its fields changes behavior of all convenience calls.

```go
var DefaultClient = NewClient()
```

--------------------------------

### NewHandler function signature

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabtest.md

Creates a handler with defaults: status http.StatusOK, method whitelist ["GET", "HEAD"], contentLength 1 MiB, acceptRanges true. Returns an error if any option builder fails (e.g. StatusCode(nil)).

```go
func NewHandler(options ...HandlerOption) (http.Handler, error)
```

--------------------------------

### Error handling with grab.Get

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grab.md

Error handling example for grab.Get. It checks for status code errors and other errors, printing appropriate messages and exiting. The empty destination string is treated as the current working directory.

```go
resp, err := grab.Get("", "http://example.com/example.zip")
if err != nil {
	if grab.IsStatusCodeError(err) {
		fmt.Fprintf(os.Stderr, "server rejected request: %v\n", err)
	} else {
		fmt.Fprintf(os.Stderr, "download failed: %v\n", err)
	}
	os.Exit(1)
}
fmt.Println("saved to", resp.Filename)
```

--------------------------------

### Do

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/client.md

Initiates a transfer request asynchronously. It blocks only until the transfer has started, then returns a Response that tracks progress and errors. Errors are not returned directly but are surfaced via Response.Err().

```APIDOC
## Do

### Description
Initiates a transfer request asynchronously. It blocks only until the transfer has started, then returns a Response that tracks progress and errors. Errors are not returned directly but are surfaced via Response.Err().

### Method Signature
```go
func (c *Client) Do(req *Request) *Response
```

### Parameters
#### Path Parameters
- **req** (\*Request) - Required - The transfer request to execute.

### Returns
- **\*Response** - Never nil. The transfer is initiated while the caller is blocked, but `Do` returns as soon as the transfer has started in a background goroutine, or if it failed early.

### Notes
- Errors are not returned by `Do`; they are recorded on the `Response` and surfaced by `Response.Err()`, which blocks until the transfer completes.
- `Do` cancels the request's context on all code paths.
- A `Response.BufferSize` of 0 falls back to `c.BufferSize`; if that is also `< 1`, a 32KB buffer is used.

### Examples
#### Basic Usage
```go
import "github.com/cavaliergopher/grab/v3"

client := grab.NewClient()
req, err := grab.NewRequest("/tmp", "http://example.com/example.zip")
if err != nil {
	panic(err)
}

resp := client.Do(req)
if err := resp.Err(); err != nil {
	panic(err)
}

fmt.Println("Download saved to", resp.Filename)
```

#### Error Handling with Progress Monitoring
```go
client := grab.NewClient()
req, err := grab.NewRequest("", "http://example.com/example.zip")
if err != nil {
	panic(err)
}
resp := client.Do(req)

t := time.NewTicker(time.Second)
defer t.Stop()
for {
	select {
	case <-t.C:
		fmt.Printf("%.02f%% complete\n", resp.Progress())
	case <-resp.Done:
		if err := resp.Err(); err != nil {
			fmt.Fprintf(os.Stderr, "download failed: %v\n", err)
			os.Exit(1)
		}
		return
	}
}
```
```

--------------------------------

### NewHandler

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabtest.md

Creates a new http.Handler with configurable options. The handler defaults to status OK, accepts GET and HEAD methods, serves 1 MiB of content, and supports range requests.

```APIDOC
## NewHandler

### Description
Creates a new http.Handler with configurable options. The handler defaults to status OK, accepts GET and HEAD methods, serves 1 MiB of content, and supports range requests.

### Function Signature
func NewHandler(options ...HandlerOption) (http.Handler, error)

### Parameters
- **options** (`...HandlerOption`) - Optional - Configuration closures; see handler options below.

### Returns
- **http.Handler** - A handler with defaults: status `http.StatusOK`, method whitelist `["GET", "HEAD"]`, `contentLength` = 1 MiB, `acceptRanges = true`.
- **error** - Non-nil if any option builder fails (e.g. `StatusCode(nil)`).
```

--------------------------------

### Basic download with Client.Do

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/client.md

Basic usage of Client.Do. Creates a new client and request, performs the download, and checks for errors after completion. Adapted from ExampleClient_Do in v3/example_client_test.go.

```go
import "github.com/cavaliergopher/grab/v3"

client := grab.NewClient()
req, err := grab.NewRequest("/tmp", "http://example.com/example.zip")
if err != nil {
	panic(err)
}

resp := client.Do(req)
if err := resp.Err(); err != nil {
	panic(err)
}

fmt.Println("Download saved to", resp.Filename)
```

--------------------------------

### Get function signature

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grab.md

Signature of the blocking Get function. It sends a GET request and downloads the content to the destination, blocking until completion. Returns a *Response and an error.

```go
func Get(dst, urlStr string) (*Response, error)
```

--------------------------------

### Duration

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/response.md

Method to get the elapsed duration of the transfer.

```APIDOC
## Duration

### Description
Returns the duration of the transfer. While in progress: `time.Since(c.Start)` (now minus start). Once complete: `c.End.Sub(c.Start)`.

### Method
Function

### Signature
`func (c *Response) Duration() time.Duration`

### Parameters
None

### Returns
- **time.Duration** - Duration of the transfer.
```

--------------------------------

### Simple download with grab.Get

Source: https://github.com/cavaliergopher/grab/blob/main/README.md

Downloads a file from a URL into the current working directory using the default client. Prints the saved filename or logs a fatal error on failure.

```go
resp, err := grab.Get(".", "http://www.golang-book.com/public/pdf/gobook.pdf")
if err != nil {
	log.Fatal(err)
}

fmt.Println("Download saved to", resp.Filename)
```

--------------------------------

### Progress method

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/response.md

Returns the ratio of downloaded bytes to total size (BytesComplete() / Size()). Returns 0 when size is unknown or non-positive (size <= 0). Multiply by 100 for a percentage.

```go
func (c *Response) Progress() float64
```

--------------------------------

### ETA

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/response.md

Method to get the estimated time of arrival for the transfer.

```APIDOC
## ETA

### Description
Returns the estimated completion time given the current `BytesPerSecond` (`time.Now().Add(Duration(*secs))` where `secs = (Size()-BytesComplete())/BPS`). If the transfer is complete, returns the actual `End` time. Returns a zero `time.Time{}` if the current BPS is 0.

### Method
Function

### Signature
`func (c *Response) ETA() time.Time`

### Parameters
None

### Returns
- **time.Time** - Estimated completion time.
```

--------------------------------

### BytesPerSecond

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/response.md

Method to get the transfer speed in bytes per second.

```APIDOC
## BytesPerSecond

### Description
Returns the bytes per second transferred, using a simple moving average of the last five seconds. If the download is already complete, returns the average bytes/sec for the life of the download.

### Method
Function

### Signature
`func (c *Response) BytesPerSecond() float64`

### Parameters
None

### Returns
- **float64** - Bytes per second transferred.
```

--------------------------------

### Complete download with progress and auto-resume

Source: https://github.com/cavaliergopher/grab/blob/main/README.md

A full Go program that downloads a file with a custom client, prints progress every 500ms, and auto-resumes on the second run. Exits with an error message if the download fails.

```go
package main

import (
	"fmt"
	"os"
	"time"

	"github.com/cavaliergopher/grab/v3"
)

func main() {
	// create client
	client := grab.NewClient()
	req, _ := grab.NewRequest(".", "http://www.golang-book.com/public/pdf/gobook.pdf")

	// start download
	fmt.Printf("Downloading %v...\n", req.URL())
	resp := client.Do(req)
	fmt.Printf("  %v\n", resp.HTTPResponse.Status)

	// start UI loop
	t := time.NewTicker(500 * time.Millisecond)
	defer t.Stop()

Loop:
	for {
		select {
		case <-t.C:
			fmt.Printf("  transferred %v / %v bytes (%.2f%%)\n",
				resp.BytesComplete(),
				resp.Size(),
				100*resp.Progress())

		case <-resp.Done:
			// download is complete
			break Loop
		}
	}

	// check for errors
	if err := resp.Err(); err != nil {
		fmt.Fprintf(os.Stderr, "Download failed: %v\n", err)
		os.Exit(1)
	}

	fmt.Printf("Download saved to ./%v \n", resp.Filename)

	// Output:
	// Downloading http://www.golang-book.com/public/pdf/gobook.pdf...
	//   200 OK
	//   transferred 42970 / 2893557 bytes (1.49%)
	//   transferred 1207474 / 2893557 bytes (41.73%)
	//   transferred 2758210 / 2893557 bytes (95.32%)
	// Download saved to ./gobook.pdf
}
```

--------------------------------

### Watch

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/bps.md

Starts a blocking loop that samples a gauge at a given interval until the context is canceled. It immediately samples once, then uses a ticker to sample periodically.

```APIDOC
## Watch

### Description
Starts a blocking loop that samples a gauge at a given interval until the context is canceled. It immediately samples once, then uses a ticker to sample periodically.

### Function Signature
func Watch(ctx context.Context, g Gauge, f SampleFunc, interval time.Duration)

### Parameters
- **ctx** (context.Context) - Required - cancelation context; Watch returns when ctx.Done() fires
- **g** (Gauge) - Required - the gauge to update
- **f** (SampleFunc) - Required - function returning total bytes transferred
- **interval** (time.Duration) - Required - sampling interval

### Behavior
Immediately samples once (g.Sample(time.Now(), f())), then starts a time.Ticker at interval and samples on every tick until the context is canceled. Watch is a blocking call and should typically be run in a new goroutine; to prevent goroutine leaks, cancel the given context once the stream completes or is canceled.

### Example
```go
import "github.com/cavaliergopher/grab/v3/pkg/bps"
import "context"
import "time"

g := bps.NewSMA(6)
stream := myStream // an io.Reader, say

ctx, cancel := context.WithCancel(context.Background())

go bps.Watch(ctx, g,
	func() (n int64) {
		return stream.BytesRead()
	},
	time.Second)

// ... consume stream ...

cancel() // stop Watch; no goroutine leaks
```
```

--------------------------------

### Client.Do

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/types.md

Performs a download request using the configured HTTPClient. This is the primary method for initiating downloads.

```APIDOC
## Client.Do

### Description
Performs a download request using the configured HTTPClient. This is the primary method for initiating downloads.

### Method
Do

### Signature
Do(req *http.Request) (*Response, error)

### Parameters
- **req** (*http.Request) - Required - The HTTP request to perform.

### Returns
- **resp** (*Response) - The response object.
- **err** (error) - An error if the request failed.

### Usage
This method is part of the Client struct. It uses the HTTPClient field to perform the request. The UserAgent and BufferSize fields affect the request.

### Example
```go
client := grab.NewClient()
req, _ := http.NewRequest("GET", "http://example.com/file.zip", nil)
resp := client.Do(req)
```
```

--------------------------------

### NewConsoleClient function signature

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabui.md

Constructor for ConsoleClient. Accepts a *grab.Client; passing nil causes fallback to grab.DefaultClient at Do time.

```go
func NewConsoleClient(client *grab.Client) *ConsoleClient
```

--------------------------------

### grab main function

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/cli.md

Entry point for the grab command line tool. It is the only exported symbol and is not intended for use as a library.

```go
func main()
```

--------------------------------

### Client struct with HTTPClient, UserAgent, BufferSize fields

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/types.md

Represents the main client configuration. HTTPClient defaults to &http.Client{Transport: &http.Transport{Proxy: http.ProxyFromEnvironment}} when created via NewClient. UserAgent defaults to DefaultUserAgent ("grab/3"). BufferSize defaults to 0 with a per-request fallback to 32KB. Produced by NewClient() and DefaultClient; consumed by Client.Do, Client.DoChannel, Client.DoBatch, and grabui.NewConsoleClient.

```go
type Client struct {
	HTTPClient HTTPClient
	UserAgent string
	BufferSize int
}
```

--------------------------------

### Download with progress monitoring and error handling

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/client.md

Error handling with progress monitoring. Periodically prints download progress using a ticker and waits for completion via resp.Done, checking for errors and exiting on failure. Progress loop pattern taken from v3/doc.go and README.md.

```go
client := grab.NewClient()
req, err := grab.NewRequest("", "http://example.com/example.zip")
if err != nil {
	panic(err)
}
resp := client.Do(req)

t := time.NewTicker(time.Second)
defer t.Stop()
for {
	select {
	case <-t.C:
		fmt.Printf("%.02f%% complete\n", resp.Progress())
	case <-resp.Done:
		if err := resp.Err(); err != nil {
			fmt.Fprintf(os.Stderr, "download failed: %v\n", err)
			os.Exit(1)
		}
		return
	}
}
```

--------------------------------

### SampleFunc type alias

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/bps.md

Type alias for a function that reports the current total number of bytes transferred since the stream started. Used by Watch for periodic sampling.

```go
type SampleFunc func() (n int64)
```

--------------------------------

### NewClient

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/client.md

Returns a new Client with default configuration, including a UserAgent and an HTTP transport that uses environment proxy settings.

```APIDOC
## NewClient

### Description
Returns a new `Client` with default configuration, including `UserAgent: DefaultUserAgent` and an HTTP transport that sources its proxy from the environment (`http.ProxyFromEnvironment`).

### Function Signature
```go
func NewClient() *Client
```

### Returns
- **\*Client** - A new client instance with default settings.

### Example
```go
client := grab.NewClient()
```
```

--------------------------------

### Handle GetBatch destination error

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grab.md

Error handling example showing how to detect a destination validation error (ErrNotADirectory) from the returned tuple. The error is non-nil if the destination does not exist or is not a directory.

```go
respch, err := grab.GetBatch(4, "/var/lib/does-not-exist", "http://example.com/a")
if err != nil {
	if err == grab.ErrNotADirectory {
		fmt.Fprintln(os.Stderr, "destination is not a directory")
	} else {
		fmt.Fprintln(os.Stderr, err)
	}
	os.Exit(1)
}
```

--------------------------------

### Do method signature

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabui.md

Method signature for Do, which runs a batch of downloads with console UI. Returns a channel of responses.

```go
func (c *ConsoleClient) Do(
	ctx context.Context,
	workers int,
	reqs ...*grab.Request,
) <-chan *grab.Response
```

--------------------------------

### Client.Do method signature

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/client.md

Signature for the Do method. Takes a *Request and returns a *Response that is never nil. Do blocks while the transfer is initiated, then returns once the transfer starts in a background goroutine or fails early.

```go
func (c *Client) Do(req *Request) *Response
```

--------------------------------

### Open method

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/response.md

Blocks until transfer completes, then opens the transferred file for reading. With Request.NoStore, reads from memory. Returns an error from the transfer via Err() before opening. Caller must close the returned handle.

```go
func (c *Response) Open() (io.ReadCloser, error)
```

--------------------------------

### NewConsoleClient

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabui.md

Creates a new ConsoleClient with the provided underlying grab.Client. If nil is passed, the default client is used at Do time.

```APIDOC
## NewConsoleClient

### Description
Creates a new ConsoleClient with the provided underlying grab.Client. If nil is passed, the default client is used at Do time.

### Method
Constructor

### Endpoint
`func NewConsoleClient(client *grab.Client) *ConsoleClient`

### Parameters
- **client** (*grab.Client) - Required - The underlying client; `grab.DefaultClient` is used when nil is passed (fallback happens in `Do`).

### Returns
- **\*ConsoleClient** - A new console client with zeroed counters and an empty response list.

### Example
```go
client := grab.NewClient()
ui := grabui.NewConsoleClient(client)
```
```

--------------------------------

### NewClient function signature

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/client.md

Signature for NewClient, which returns a new Client with default configuration as shown.

```go
func NewClient() *Client
```

--------------------------------

### GetBatch function signature

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/api-reference/grabui.md

Defines the GetBatch function that initiates a batch download with a console UI. It takes a context, number of workers, destination directory, and variadic URL strings, returning a channel of responses and an error.

```go
func GetBatch(
	ctx context.Context,
	workers int,
	dst string,
	urlStrs ...string,
) (<-chan *grab.Response, error)
```

--------------------------------

### Error handling with grab.Get and resp.Err()

Source: https://github.com/cavaliergopher/grab/blob/main/_autodocs/errors.md

Shows how to check errors from grab operations. The Get call returns a (response, error) pair; then resp.Err() provides per-request errors after the transfer. The switch compares against grab.ErrBadChecksum and uses grab.IsStatusCodeError for HTTP status errors.

```go
resp, err := grab.Get("/tmp", "http://example.com/example.zip")
if err != nil {
	log.Fatal(err)
}

// later, for per-request errors:
if err := resp.Err(); err != nil {
	switch {
	case err == grab.ErrBadChecksum:
		fmt.Fprintln(os.Stderr, "checksum mismatch")
	case grab.IsStatusCodeError(err):
		fmt.Fprintln(os.Stderr, "server status: " + err)
	default:
		fmt.Fprintln(os.Stderr, err)
	}
}

```
Tokens:
Raw