goget/docs/api.md

API Reference

goget exposes a public Go library in pkg/api/ for programmatic downloads, uploads, queue management, and configuration.

Installation

import "codeberg.org/petrbalvin/goget/pkg/api"

Types

Client

The main client for downloads and uploads. Created via NewClient().

type Client struct { /* unexported */ }

func NewClient(opts ...ClientOption) *Client
func (c *Client) Download(req *DownloadRequest) (*DownloadResult, error)
func (c *Client) Upload(req *UploadRequest) (*UploadResult, error)
func (c *Client) Close()

ClientOption

Functional options for client configuration.

func WithTimeout(d time.Duration) ClientOption
func WithUserAgent(ua string) ClientOption
func WithVerbose(v bool) ClientOption

DownloadRequest

Field	Type	Description
URL	string	URL to download (required)
Output	string	Output file path (empty = auto-detect)
Resume	bool	Resume interrupted download
Verbose	bool	Enable verbose logging

DownloadResult

Field	Type	Description
BytesDownloaded	int64	Total bytes transferred
TotalSize	int64	Total file size (-1 if unknown)
Speed	float64	Average speed in bytes/second
Duration	time.Duration	Total transfer time
OutputPath	string	Path to saved file
Protocol	string	Protocol used (e.g., "http")
IPVersion	int	4 or 6
Resumed	bool	True if download was resumed
Parallel	bool	True if parallel chunks were used
ChunksCount	int	Number of parallel chunks

UploadRequest

Field	Type	Description
URL	string	Destination URL (required)
FilePath	string	Path to file to upload (required)
Method	string	HTTP method: "PUT" or "POST"
Verbose	bool	Enable verbose logging

UploadResult

Field	Type	Description
BytesUploaded	int64	Total bytes uploaded
Duration	time.Duration	Total upload time
Protocol	string	Protocol used
ResultURL	string	Result URL (may differ from input after redirects)

---

Client

NewClient

Creates a new goget client. Registers HTTP and FTP protocol handlers automatically.

func NewClient(opts ...ClientOption) *Client

Options:

Option	Effect
WithTimeout(5 * time.Minute)	Set request timeout (default: 30 minutes)
WithUserAgent("MyApp/1.0")	Custom User-Agent header
WithVerbose(true)	Enable verbose logging

Example:

client := api.NewClient(
    api.WithTimeout(10 * time.Minute),
    api.WithUserAgent("MyDownloader/1.0"),
)
defer client.Close()

Client.Download

Downloads a file from a URL.

func (c *Client) Download(req *DownloadRequest) (*DownloadResult, error)

Parameters:

Parameter	Type	Description
req.URL	string	URL to download — supports http, https, ftp, sftp, file, data, gopher, gemini
req.Output	string	Output path. Empty string uses the filename derived from the URL.
req.Resume	bool	Resume an interrupted download if resume metadata exists

Returns: *DownloadResult — bytes transferred, speed, duration, protocol info.

Throws:

• error — if URL is empty or invalid
• error — if protocol is unsupported
• *core.GogetError — typed errors for network, protocol, timeout, auth, checksum failures

Example:

result, err := client.Download(&api.DownloadRequest{
    URL:    "https://example.com/file.zip",
    Output: "downloads/file.zip",
    Resume: true,
})
if err != nil {
    log.Printf("Download failed: %v", err)
    return
}
log.Printf("Downloaded %d bytes at %.1f KB/s", result.BytesDownloaded, result.Speed/1024)

Client.Upload

Uploads a file to a URL. The protocol handler must implement core.Uploader.

func (c *Client) Upload(req *UploadRequest) (*UploadResult, error)

Parameters:

Parameter	Type	Description
req.URL	string	Destination URL (required)
req.FilePath	string	Path to local file (required)
req.Method	string	"PUT" or "POST" (default: "PUT")
req.Verbose	bool	Enable verbose logging

Returns: *UploadResult — bytes uploaded, duration, protocol, result URL.

Throws:

• error — if URL or file path is empty
• error — if protocol does not support upload

Example:

result, err := client.Upload(&api.UploadRequest{
    URL:      "https://httpbin.org/put",
    FilePath: "./data.csv",
    Method:   "PUT",
})
if err != nil {
    log.Printf("Upload failed: %v", err)
    return
}
log.Printf("Uploaded %d bytes", result.BytesUploaded)

Client.Close

Releases resources and cancels any pending operations.

func (c *Client) Close()

---

Convenience Functions

Download

One-shot download. Creates a client, downloads, and closes.

func Download(urlStr, output string) (*DownloadResult, error)

Example:

result, err := api.Download("https://example.com/file.zip", "output.zip")

Upload

One-shot upload. Creates a client, uploads, and closes.

func Upload(urlStr, filePath, method string) (*UploadResult, error)

Example:

result, err := api.Upload("https://httpbin.org/put", "./data.csv", "PUT")

---

Queue API

QueueClient

Manages a download queue persisted to a JSON file.

type QueueClient struct { /* unexported */ }

func NewQueueClient(queueFile string) (*QueueClient, error)
func (qc *QueueClient) Add(urlStr, output string, priority int) string
func (qc *QueueClient) List() []*queue.QueueItem
func (qc *QueueClient) Stats() queue.QueueStats
func (qc *QueueClient) Remove(id string) bool
func (qc *QueueClient) ClearCompleted() int

NewQueueClient

func NewQueueClient(queueFile string) (*QueueClient, error)

Creates a queue client backed by a JSON file.

Parameters:

Parameter	Type	Description
queueFile	string	Path to the queue JSON file

Returns: *QueueClient, error — error if the file cannot be read or created.

QueueClient.Add

func (qc *QueueClient) Add(urlStr, output string, priority int) string

Adds a URL to the queue.

Parameters:

Parameter	Type	Description
urlStr	string	URL to download
output	string	Output file path
priority	int	Priority (1–10, higher = processed first)

Returns: string — unique ID for the queued item.

QueueClient.List

func (qc *QueueClient) List() []*queue.QueueItem

Returns all items in the queue.

Returns: []*queue.QueueItem

QueueClient.Stats

func (qc *QueueClient) Stats() queue.QueueStats

Returns queue statistics (total, pending, completed, failed counts).

QueueClient.Remove

func (qc *QueueClient) Remove(id string) bool

Removes an item from the queue by ID.

Returns: bool — true if the item was found and removed.

QueueClient.ClearCompleted

func (qc *QueueClient) ClearCompleted() int

Removes all completed items from the queue.

Returns: int — number of removed items.

---

Metalink API

ParseMetalink

Parses a local Metalink file.

func ParseMetalink(path string) (*metalink.Metalink, error)

Parameters:

Parameter	Type	Description
path	string	Path to a local .meta4 or .metalink file

Returns: *metalink.Metalink — parsed metalink with sources, checksums, and metadata.

FetchMetalink

Downloads and parses a Metalink from a URL.

func FetchMetalink(urlStr string) (*metalink.Metalink, error)

Parameters:

Parameter	Type	Description
urlStr	string	URL pointing to a .meta4 or .metalink file

Returns: *metalink.Metalink — parsed metalink with sources, checksums, and metadata.

---

Config API

LoadConfig

func LoadConfig(path string) (*config.Config, error)

Loads the TOML configuration file. Returns default config if the file does not exist.

Parameters:

Parameter	Type	Description
path	string	Path to config file (empty = default location)

Returns: *config.Config, error

DefaultConfig

func DefaultConfig() *config.Config

Returns the default configuration values.

ParseSpeed

func ParseSpeed(s string) int64

Parses a speed string like "10MB/s" into bytes per second.

Input	Output
"1MB/s"	1000000
"500KB/s"	500000
"1GB/s"	1000000000

---

Version

Version

func Version() string

Returns the current goget version.

---

Full Example

package main

import (
    "fmt"
    "log"
    "time"

    "codeberg.org/petrbalvin/goget/pkg/api"
)

func main() {
    // Create client with custom timeout
    client := api.NewClient(
        api.WithTimeout(5 * time.Minute),
        api.WithVerbose(true),
    )
    defer client.Close()

    // Download
    result, err := client.Download(&api.DownloadRequest{
        URL:    "https://example.com/large-file.iso",
        Output: "./downloads/large-file.iso",
        Resume: true,
    })
    if err != nil {
        log.Fatalf("download failed: %v", err)
    }

    fmt.Printf("Downloaded %d bytes in %v\n", result.BytesDownloaded, result.Duration)
    fmt.Printf("Average speed: %.1f MB/s\n", result.Speed/1024/1024)
    fmt.Printf("Protocol: %s (IPv%d)\n", result.Protocol, result.IPVersion)

    if result.Resumed {
        fmt.Println("Download was resumed from previous state")
    }
    if result.Parallel {
        fmt.Printf("Used %d parallel chunks\n", result.ChunksCount)
    }

    // Queue a download
    qc, err := api.NewQueueClient("./queue.json")
    if err != nil {
        log.Fatalf("queue init failed: %v", err)
    }

    id := qc.Add("https://example.com/another.zip", "./downloads/", 5)
    fmt.Printf("Queued item ID: %s\n", id)
    fmt.Printf("Queue stats: %+v\n", qc.Stats())
}