455 lines
10 KiB
Markdown
455 lines
10 KiB
Markdown
# API Reference
|
||
|
||
**goget** exposes a public Go library in `pkg/api/` for programmatic downloads, uploads, queue management, and configuration.
|
||
|
||
## Installation
|
||
|
||
```go
|
||
import "codeberg.org/petrbalvin/goget/pkg/api"
|
||
```
|
||
|
||
## Types
|
||
|
||
### `Client`
|
||
|
||
The main client for downloads and uploads. Created via `NewClient()`.
|
||
|
||
```go
|
||
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.
|
||
|
||
```go
|
||
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.
|
||
|
||
```go
|
||
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:**
|
||
```go
|
||
client := api.NewClient(
|
||
api.WithTimeout(10 * time.Minute),
|
||
api.WithUserAgent("MyDownloader/1.0"),
|
||
)
|
||
defer client.Close()
|
||
```
|
||
|
||
### `Client.Download`
|
||
|
||
Downloads a file from a URL.
|
||
|
||
```go
|
||
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:**
|
||
```go
|
||
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`.
|
||
|
||
```go
|
||
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:**
|
||
```go
|
||
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.
|
||
|
||
```go
|
||
func (c *Client) Close()
|
||
```
|
||
|
||
---
|
||
|
||
## Convenience Functions
|
||
|
||
### `Download`
|
||
|
||
One-shot download. Creates a client, downloads, and closes.
|
||
|
||
```go
|
||
func Download(urlStr, output string) (*DownloadResult, error)
|
||
```
|
||
|
||
**Example:**
|
||
```go
|
||
result, err := api.Download("https://example.com/file.zip", "output.zip")
|
||
```
|
||
|
||
### `Upload`
|
||
|
||
One-shot upload. Creates a client, uploads, and closes.
|
||
|
||
```go
|
||
func Upload(urlStr, filePath, method string) (*UploadResult, error)
|
||
```
|
||
|
||
**Example:**
|
||
```go
|
||
result, err := api.Upload("https://httpbin.org/put", "./data.csv", "PUT")
|
||
```
|
||
|
||
---
|
||
|
||
## Queue API
|
||
|
||
### `QueueClient`
|
||
|
||
Manages a download queue persisted to a JSON file.
|
||
|
||
```go
|
||
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`
|
||
|
||
```go
|
||
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`
|
||
|
||
```go
|
||
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`
|
||
|
||
```go
|
||
func (qc *QueueClient) List() []*queue.QueueItem
|
||
```
|
||
|
||
Returns all items in the queue.
|
||
|
||
**Returns:** `[]*queue.QueueItem`
|
||
|
||
### `QueueClient.Stats`
|
||
|
||
```go
|
||
func (qc *QueueClient) Stats() queue.QueueStats
|
||
```
|
||
|
||
Returns queue statistics (total, pending, completed, failed counts).
|
||
|
||
### `QueueClient.Remove`
|
||
|
||
```go
|
||
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`
|
||
|
||
```go
|
||
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.
|
||
|
||
```go
|
||
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.
|
||
|
||
```go
|
||
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`
|
||
|
||
```go
|
||
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`
|
||
|
||
```go
|
||
func DefaultConfig() *config.Config
|
||
```
|
||
|
||
Returns the default configuration values.
|
||
|
||
### `ParseSpeed`
|
||
|
||
```go
|
||
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`
|
||
|
||
```go
|
||
func Version() string
|
||
```
|
||
|
||
Returns the current goget version.
|
||
|
||
---
|
||
|
||
## Full Example
|
||
|
||
```go
|
||
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())
|
||
}
|
||
```
|