config

Documentation

Index

• Constants
• func AppName() string
• func EnsureAPIKey(cfg *Config) (generated bool, err error)
• type AdminConfig
• type AuthConfig
• type CleanupConfig
• type Config
  • func Load(cfgFile string) (*Config, error)
• type DatabaseConfig
• type LogConfig
• type PulseConfig
• type Secret
  • func (s Secret) GoString() string
  • func (s Secret) IsEmpty() bool
  • func (s Secret) LogValue() slog.Value
  • func (s Secret) MarshalJSON() ([]byte, error)
  • func (s Secret) MarshalText() ([]byte, error)
  • func (s Secret) String() string
  • func (s Secret) Value() string
• type ServerConfig
• type SpeedScheduleConfig
• type TorrentConfig
• type WebhookConfig

Constants

const (
	DefaultHost = "0.0.0.0"
	DefaultPort = 8484
	DefaultDB   = "postgres"
	DefaultLog  = "info"
	DefaultFmt  = "json"
)

Functions

func AppName

func AppName() string

AppName returns the application name constant for use in config paths.

func EnsureAPIKey

func EnsureAPIKey(cfg *Config) (generated bool, err error)

EnsureAPIKey generates a random API key if none is configured.

Types

type AdminConfig

type AdminConfig struct {
	DiagnosticsEnabled bool `mapstructure:"diagnostics_enabled"`
}

AdminConfig gates the admin-only diagnostic & cleanup endpoints. Default off — most operators never need them. Flip to true via HAUL_ADMIN_DIAGNOSTICS_ENABLED to expose Settings → System → Diagnostics.

type AuthConfig

type AuthConfig struct {
	APIKey Secret `mapstructure:"api_key"`
}

AuthConfig holds the API key used to authenticate requests.

type CleanupConfig

type CleanupConfig struct {
	RetentionDays int `mapstructure:"retention_days"`
}

CleanupConfig controls the soft-delete retention shim used by the admin diagnostics tab. Soft-deleted rows live in the cleanup_history table for RetentionDays days, then a daily sweep hard-deletes them.

type Config

type Config struct {
	Server   ServerConfig        `mapstructure:"server"`
	Database DatabaseConfig      `mapstructure:"database"`
	Log      LogConfig           `mapstructure:"log"`
	Auth     AuthConfig          `mapstructure:"auth"`
	Torrent  TorrentConfig       `mapstructure:"torrent"`
	Schedule SpeedScheduleConfig `mapstructure:"schedule"`
	Webhooks []WebhookConfig     `mapstructure:"webhooks"`
	Pulse    PulseConfig         `mapstructure:"pulse"`
	Admin    AdminConfig         `mapstructure:"admin"`
	Cleanup  CleanupConfig       `mapstructure:"cleanup"`

	// ConfigFile is the path of the config file that was loaded, if any.
	ConfigFile string `mapstructure:"-"`
}

Config holds all application configuration. Values are loaded from config.yaml and can be overridden by HAUL_* environment variables (e.g. HAUL_SERVER_PORT=8484).

func Load

func Load(cfgFile string) (*Config, error)

Load reads configuration from a YAML file and environment variables. If cfgFile is empty, the following paths are searched in order:

/config/config.yaml              (Docker volume mount)
$HOME/.config/haul/config.yaml
/etc/haul/config.yaml
./config.yaml

type DatabaseConfig

type DatabaseConfig struct {
	Driver string `mapstructure:"driver"`
	Path   string `mapstructure:"path"`
	DSN    Secret `mapstructure:"dsn"`
	// PasswordFile is a path to a file containing the Postgres password,
	// typically a Docker secret mounted at /run/secrets/*. When non-empty,
	// its contents replace the password component of DSN at load time.
	PasswordFile string `mapstructure:"password_file"`
}

DatabaseConfig selects and configures the database driver.

type LogConfig

type LogConfig struct {
	Level  string `mapstructure:"level"`
	Format string `mapstructure:"format"`
}

LogConfig controls log output format and verbosity.

type PulseConfig

type PulseConfig struct {
	URL    string `mapstructure:"url"`
	APIKey Secret `mapstructure:"api_key"`
	// APIKeyFile points at a file (typically /run/secrets/*) containing
	// Pulse's API key. When non-empty, its contents replace APIKey at
	// load time.
	APIKeyFile string `mapstructure:"api_key_file"`
}

PulseConfig holds optional Pulse integration settings.

type Secret

type Secret string

Secret is a string type that never reveals its contents when logged, printed, or serialized. Use it for API keys, passwords, and tokens.

Call .Value() when you actually need the underlying string (e.g. to make an authenticated HTTP request).

func (Secret) GoString

func (s Secret) GoString() string

GoString implements fmt.GoStringer. Always returns "***".

func (Secret) IsEmpty

func (s Secret) IsEmpty() bool

IsEmpty reports whether the secret has no value.

func (Secret) LogValue

func (s Secret) LogValue() slog.Value

LogValue implements slog.LogValuer. Always returns "***".

func (Secret) MarshalJSON

func (s Secret) MarshalJSON() ([]byte, error)

MarshalJSON always serializes as the string "***".

func (Secret) MarshalText

func (s Secret) MarshalText() ([]byte, error)

MarshalText always encodes as "***".

func (Secret) String

func (s Secret) String() string

String implements fmt.Stringer. Always returns "***".

func (Secret) Value

func (s Secret) Value() string

Value returns the underlying secret string.

type ServerConfig

type ServerConfig struct {
	Host string `mapstructure:"host"`
	Port int    `mapstructure:"port"`
}

ServerConfig controls the HTTP server.

type SpeedScheduleConfig

type SpeedScheduleConfig struct {
	Enabled  bool   `mapstructure:"enabled"`
	FromHour int    `mapstructure:"from_hour"`
	FromMin  int    `mapstructure:"from_min"`
	ToHour   int    `mapstructure:"to_hour"`
	ToMin    int    `mapstructure:"to_min"`
	Days     string `mapstructure:"days"` // "all", "weekday", "weekend"
}

SpeedScheduleConfig holds alt-speed scheduling settings.

type TorrentConfig

type TorrentConfig struct {
	// ListenPort is the port for incoming peer connections. 0 = random.
	ListenPort int `mapstructure:"listen_port"`
	// DownloadDir is the default save path for new torrents.
	DownloadDir string `mapstructure:"download_dir"`
	// DataDir is the persistent directory used for engine-internal state
	// (piece-completion DB, etc). Must survive container restarts — if it
	// doesn't, torrents will restart from 0% on every startup because
	// anacrolix's in-memory completion map will be empty even though the
	// downloaded bytes are still on disk. Defaults to "/config".
	DataDir string `mapstructure:"data_dir"`
	// WatchDir is a path that haul monitors for `.torrent` files. Files
	// dropped here are auto-added; the source file is deleted on success
	// or renamed to <name>.invalid on parse failure. Empty disables
	// auto-add entirely. Mirrors qBit's "Automatically download
	// .torrents from this directory" behavior option.
	WatchDir string `mapstructure:"watch_dir"`
	// MaxActiveDownloads is the max concurrent downloading torrents. 0 = unlimited.
	MaxActiveDownloads int `mapstructure:"max_active_downloads"`
	// MaxActiveUploads is the max concurrent seeding torrents. 0 = unlimited.
	MaxActiveUploads int `mapstructure:"max_active_uploads"`
	// MaxActiveTorrents is the combined max concurrent active torrents. 0 = unlimited.
	MaxActiveTorrents int `mapstructure:"max_active_torrents"`
	// GlobalDownloadLimit is the global download speed limit in bytes/s. 0 = unlimited.
	GlobalDownloadLimit int `mapstructure:"global_download_limit"`
	// GlobalUploadLimit is the global upload speed limit in bytes/s. 0 = unlimited.
	GlobalUploadLimit int `mapstructure:"global_upload_limit"`
	// AltDownloadLimit is the alternative (scheduled) download speed limit. 0 = unlimited.
	AltDownloadLimit int `mapstructure:"alt_download_limit"`
	// AltUploadLimit is the alternative (scheduled) upload speed limit. 0 = unlimited.
	AltUploadLimit int `mapstructure:"alt_upload_limit"`
	// DefaultSeedRatio is the default seed ratio limit. 0 = unlimited.
	DefaultSeedRatio float64 `mapstructure:"default_seed_ratio"`
	// DefaultSeedTime is the default seed time limit in seconds. 0 = unlimited.
	DefaultSeedTime int `mapstructure:"default_seed_time"`
	// SeedLimitAction is what to do when seed limit is reached: "pause", "remove", "remove_with_data".
	SeedLimitAction string `mapstructure:"seed_limit_action"`
	// EnableDHT enables the DHT peer discovery network.
	EnableDHT bool `mapstructure:"enable_dht"`
	// EnablePEX enables Peer Exchange.
	EnablePEX bool `mapstructure:"enable_pex"`
	// EnableUTP enables uTP transport.
	EnableUTP bool `mapstructure:"enable_utp"`
	// EnableLSD enables Local Service Discovery for LAN peers.
	EnableLSD bool `mapstructure:"enable_lsd"`
	// Encryption controls protocol encryption. "prefer", "require", or "disable".
	Encryption string `mapstructure:"encryption"`
	// MaxConnections is the global maximum number of peer connections. 0 = unlimited.
	MaxConnections int `mapstructure:"max_connections"`
	// MaxConnectionsPerTorrent is the per-torrent max connections. 0 = unlimited.
	MaxConnectionsPerTorrent int `mapstructure:"max_connections_per_torrent"`
	// NetworkInterface binds peer connections to a specific interface (e.g. "tun0", "wg0").
	NetworkInterface string `mapstructure:"network_interface"`
	// IncompleteFileExtension appends this extension to incomplete files (e.g. ".haul").
	IncompleteFileExtension string `mapstructure:"incomplete_file_ext"`
	// ContentLayout controls file organization: "original", "subfolder", "no_subfolder".
	ContentLayout string `mapstructure:"content_layout"`
	// SlowTorrentThreshold is the download rate (bytes/s) below which a torrent is "slow". Default 2048.
	SlowTorrentThreshold int `mapstructure:"slow_torrent_threshold"`
	// IgnoreSlowTorrents doesn't count slow torrents toward queue limits.
	IgnoreSlowTorrents bool `mapstructure:"ignore_slow_torrents"`
	// StallTimeout is the seconds of no data before a torrent is considered stalled. Default 120.
	StallTimeout int `mapstructure:"stall_timeout"`
	// PauseOnComplete immediately pauses torrents when download finishes. No seeding.
	PauseOnComplete bool `mapstructure:"pause_on_complete"`
	// PreAllocate pre-allocates disk space for new torrents.
	PreAllocate bool `mapstructure:"pre_allocate"`
	// OnAddCommand runs this shell command when a torrent is added.
	// Supports %h (hash), %n (name), %c (category).
	OnAddCommand string `mapstructure:"on_add_command"`
	// OnCompleteCommand runs this shell command when a torrent completes.
	// Supports %h (hash), %n (name), %p (path), %c (category).
	OnCompleteCommand string `mapstructure:"on_complete_command"`
	// AsyncIOThreads is the number of threads for async disk I/O. Default: 10.
	AsyncIOThreads int `mapstructure:"async_io_threads"`
	// FilePoolSize is the max number of simultaneously open files. Default: 100.
	FilePoolSize int `mapstructure:"file_pool_size"`
	// AnnounceToAllTrackers announces to all trackers, not just the first working one. Default: false.
	AnnounceToAllTrackers bool `mapstructure:"announce_to_all_trackers"`
	// RenameOnComplete renames files on download completion when media metadata is available.
	RenameOnComplete bool `mapstructure:"rename_on_complete"`
	// EpisodeFormat is the filename template for TV episodes.
	EpisodeFormat string `mapstructure:"episode_format"`
	// SeriesFolderFormat is the series root folder template.
	SeriesFolderFormat string `mapstructure:"series_folder_format"`
	// SeasonFolderFormat is the season sub-folder template.
	SeasonFolderFormat string `mapstructure:"season_folder_format"`
	// MovieFormat is the filename template for movies.
	MovieFormat string `mapstructure:"movie_format"`
	// MovieFolderFormat is the movie root folder template.
	MovieFolderFormat string `mapstructure:"movie_folder_format"`
	// ColonReplacement controls how colons in titles are handled: "delete", "dash", "space-dash".
	ColonReplacement string `mapstructure:"colon_replacement"`
}

TorrentConfig holds torrent engine settings.

type WebhookConfig

type WebhookConfig struct {
	URL    string   `mapstructure:"url"`
	Events []string `mapstructure:"events"`
}

WebhookConfig defines an outbound webhook target.