Core Types

Core types and abstractions used throughout updater.zig.

GitProvider

The provider-agnostic abstraction for Git hosting platforms.

pub const GitProvider = struct {
    /// Human-readable name of the provider
    name: []const u8,

    /// Build the URL used to fetch the latest release or tag
    buildLatestUrl: *const fn (
        allocator: std.mem.Allocator,
        owner: []const u8,
        repo: []const u8,
    ) std.mem.Allocator.Error![]const u8,

    /// Parse the API response body and extract release information
    parseLatest: *const fn (
        allocator: std.mem.Allocator,
        body: []const u8,
    ) ParseError!ReleaseInfo,

    /// Optional request headers (User-Agent, Accept, Auth)
    headers: []const HttpHeader = &.{},

    /// Base URL for self-hosted instances
    base_url: ?[]const u8 = null,

    /// Whether to include prereleases
    include_prereleases: bool = false,

    pub const ParseError = error{
        InvalidJson,
        MissingField,
        InvalidFormat,
        OutOfMemory,
    };
};

Creating a Custom Provider

const myProvider = GitProvider{
    .name = "my-git-server",
    .buildLatestUrl = myBuildUrl,
    .parseLatest = myParseResponse,
    .headers = &myHeaders,
};

ReleaseInfo

Information about a release or tag from a Git provider.

pub const ReleaseInfo = struct {
    /// The version tag (e.g., "v1.2.3", "1.2.3")
    tag: []const u8,

    /// URL to the release page
    url: []const u8,

    /// Release name/title (optional)
    name: ?[]const u8 = null,

    /// Release body/description (optional)
    body: ?[]const u8 = null,

    /// Publication timestamp (optional)
    published_at: ?[]const u8 = null,

    /// Whether this is a prerelease
    prerelease: bool = false,

    /// Whether this is a draft
    draft: bool = false,

    /// Free allocated memory
    pub fn deinit(self: *ReleaseInfo, allocator: std.mem.Allocator) void;
};

HttpHeader

HTTP header key-value pair for provider requests.

pub const HttpHeader = struct {
    name: []const u8,
    value: []const u8,
};

Example

const headers = [_]HttpHeader{
    .{ .name = "Accept", .value = "application/json" },
    .{ .name = "User-Agent", .value = "myapp/1.0" },
    .{ .name = "Authorization", .value = "Bearer TOKEN" },
};

UpdateConfig

Configuration for update checking.

pub const UpdateConfig = struct {
    /// Whether update checking is enabled
    enabled: bool = true,

    /// Whether to run checks in background
    background: bool = false,

    /// Check interval in seconds (for background mode)
    interval_seconds: u64 = 86400,

    /// HTTP request timeout in milliseconds
    timeout_ms: u64 = 10000,

    /// Git provider to use
    provider: GitProvider,

    /// Repository owner/organization
    owner: []const u8,

    /// Repository name
    repo: []const u8,

    /// Current version of the application
    current_version: []const u8,

    /// Version comparator to use
    comparator: ?VersionComparator = null,

    /// Callback when an update is found
    on_update: ?*const fn (UpdateResult) void = null,

    /// Whether to include prereleases
    include_prereleases: bool = false,

    /// Custom user agent string
    user_agent: ?[]const u8 = null,
};

UpdateResult

Result of an update check operation.

pub const UpdateResult = struct {
    /// Whether a newer version is available
    has_update: bool,

    /// Whether the check was skipped
    skipped: bool = false,

    /// Reason for skipping (if skipped)
    skip_reason: SkipReason = .none,

    /// Current version string
    current_version: []const u8,

    /// Latest available version (null if check failed/skipped)
    latest_version: ?[]const u8,

    /// URL to the latest release (null if check failed/skipped)
    release_url: ?[]const u8,

    /// Full release info (optional)
    release_info: ?ReleaseInfo = null,

    /// Error message if the check failed
    error_message: ?[]const u8 = null,
};

SkipReason

Reason why an update check was skipped.

pub const SkipReason = enum {
    none,              // Not skipped
    globally_disabled, // ZIG_UPDATE_CHECK_DISABLE is set
    config_disabled,   // enabled = false in config
    ci_environment,    // Running in CI
    network_error,     // Network request failed
    rate_limited,      // API rate limit exceeded
    provider_error,    // Provider returned an error
};

UpdateError

Errors that can occur during update checking.

pub const UpdateError = error{
    GloballyDisabled,
    BackgroundCheckingDisabled,
    NetworkError,
    Timeout,
    ProviderError,
    ParseError,
    RateLimited,
    InvalidConfig,
    OutOfMemory,
    TlsError,
    ConnectionRefused,
    DnsError,
};