Documentation
¶
Overview ¶
Package progress provides terminal-based progress display utilities for HTTP transfers.
This package offers ready-to-use progress callback functions that display real-time transfer progress in the terminal. These callbacks are designed to work with the options.OnUploadProgress and options.OnDownloadProgress fields in the HTTP client.
Architecture Overview ¶
The HTTP client's progress tracking system works as follows:
- User sets opt.OnUploadProgress or opt.OnDownloadProgress to a callback function
- Internally, the library wraps the reader/writer with NewProgressReader/NewProgressWriter
- As bytes flow through, the callback is invoked with (currentBytes, totalBytes)
- The callback (created by this package) renders progress to the terminal
Why Separate Upload and Download Functions? ¶
We provide CreateUploadProgressFunc and CreateDownloadProgressFunc as distinct functions rather than a single generic function for several reasons:
- Clarity: Users explicitly choose the appropriate function for their use case, making code self-documenting and reducing confusion about which callback to use
- Correct messaging: Each function displays contextually appropriate messages ("Upload complete!" vs "Download complete!", "Uploaded X bytes" vs "Downloaded X bytes")
- No runtime overhead: The operation type is determined at creation time, not checked on every progress update
- Type safety: Prevents accidentally using an upload progress callback for downloads
Usage Example ¶
// For uploads
opts := &options.Options{
OnUploadProgress: progress.CreateUploadProgressFunc(),
}
client.Post(url, body, opts)
// For downloads
opts := &options.Options{
OnDownloadProgress: progress.CreateDownloadProgressFunc(),
}
client.Get(url, opts)
Terminal Output Format ¶
When total size is known:
[==================== ] 40.00% | Speed: 1.25 MB/s | ETA: 3.2s [==================================================] 100.00% | Upload complete!
When total size is unknown (e.g., chunked transfer):
Uploaded 1048576 bytes | Speed: 1.25 MB/s
Thread Safety ¶
Each progress function returned by CreateUploadProgressFunc or CreateDownloadProgressFunc maintains its own internal state (last update time, last byte count). These functions are NOT safe for concurrent use - each goroutine should create its own progress function if needed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreateDownloadProgressFunc ¶ added in v2.2.0
CreateDownloadProgressFunc returns a progress callback function for tracking download operations.
The returned callback displays real-time download progress in the terminal, including:
- Visual progress bar showing percentage complete
- Current transfer speed (auto-scaled to B/s, KB/s, MB/s, or GB/s)
- Estimated time remaining (ETA)
- Completion message when finished
Why Use This Instead of CreateUploadProgressFunc? ¶
This function displays download-specific messages:
- Completion: "Download complete!" (not "Upload complete!")
- Unknown size: "Downloaded 1234 bytes" (not "Uploaded 1234 bytes")
Using the correct function ensures users see contextually appropriate feedback that matches the operation being performed.
Callback Signature ¶
The returned function has the signature: func(currentBytes, totalBytes int64)
- currentBytes: Number of bytes downloaded so far
- totalBytes: Total size of the download, or -1 if unknown (common with compressed responses or chunked transfer encoding)
Usage ¶
opts := &options.Options{
OnDownloadProgress: progress.CreateDownloadProgressFunc(),
}
resp, err := client.Get("https://example.com/largefile.zip", opts)
Important Notes ¶
- The returned callback writes directly to stdout using carriage return (\r) for in-place updates. Ensure no other output is written during the transfer.
- Updates are rate-limited to 100ms intervals to prevent terminal flickering.
- Each call to CreateDownloadProgressFunc returns a new callback with fresh state. Do not reuse callbacks across multiple transfers without creating a new one.
- The callback is NOT thread-safe. For concurrent downloads, create separate callbacks for each goroutine.
- For compressed responses, the server may not send Content-Length, resulting in totalBytes being -1. In this case, only byte count is displayed without percentage or ETA.
func CreateUploadProgressFunc ¶ added in v2.2.0
CreateUploadProgressFunc returns a progress callback function for tracking upload operations.
The returned callback displays real-time upload progress in the terminal, including:
- Visual progress bar showing percentage complete
- Current transfer speed (auto-scaled to B/s, KB/s, MB/s, or GB/s)
- Estimated time remaining (ETA)
- Completion message when finished
Why Use This Instead of CreateDownloadProgressFunc? ¶
This function displays upload-specific messages:
- Completion: "Upload complete!" (not "Download complete!")
- Unknown size: "Uploaded 1234 bytes" (not "Downloaded 1234 bytes")
Using the correct function ensures users see contextually appropriate feedback that matches the operation being performed.
Callback Signature ¶
The returned function has the signature: func(currentBytes, totalBytes int64)
- currentBytes: Number of bytes uploaded so far
- totalBytes: Total size of the upload, or -1 if unknown
Usage ¶
opts := &options.Options{
OnUploadProgress: progress.CreateUploadProgressFunc(),
}
resp, err := client.Post("https://example.com/upload", fileReader, opts)
Important Notes ¶
- The returned callback writes directly to stdout using carriage return (\r) for in-place updates. Ensure no other output is written during the transfer.
- Updates are rate-limited to 100ms intervals to prevent terminal flickering.
- Each call to CreateUploadProgressFunc returns a new callback with fresh state. Do not reuse callbacks across multiple transfers without creating a new one.
- The callback is NOT thread-safe. For concurrent uploads, create separate callbacks for each goroutine.
Types ¶
This section is empty.
Source Files