#lang scribble/manual

@(require racket/base
          scribble/core
          (for-label racket/base
                     racket/file
                     setup/dirs
                     "../racket-webview-downloader.rkt"))

@title{racket-webview-downloader}
@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]

@defmodule[racket-webview/racket-webview-downloader]

Downloader support for the native @tt{racket-webview-qt} runtime.

This module provides functions for checking whether the native runtime is
already installed, whether it can be resolved and downloaded, and for
downloading and unpacking it into the user's addon directory.

@section{Overview}

The module manages one specific downloadable version of the native
@tt{racket-webview-qt} package. The version is fixed in the source code through
three constants: a major, minor, and patch number.

The download URL is derived from:

@itemlist[#:style 'compact
 @item{the configured download site}
 @item{the configured base path}
 @item{the version string}
 @item{the current operating system}
 @item{the current machine architecture}]

The downloaded archive is installed below the user's addon directory in a
subdirectory named @tt{racket-webview-qt}.

@section{Installation Layout}

The installation directory is:

@racketblock[
(build-path (find-system-path 'addon-dir) "racket-webview-qt")
]

Within that directory, the module uses:

@itemlist[#:style 'compact
 @item{@tt{version.txt} to store the installed version}
 @item{an OS/architecture-specific subdirectory for the unpacked native files}]

The OS and architecture components are derived from:

@racketblock[
(system-type 'os*)
(system-type 'arch)
]

@section{Availability and Version Checks}

@defproc[(racket-webview-qt-is-available?) boolean?]{

Returns @racket[#t] if the expected native runtime version is already installed,
and @racket[#f] otherwise.

The function checks whether @tt{version.txt} exists and can be read as a value.
It then compares the stored major, minor, and patch numbers with the version
hard-coded in this module.

If reading the version file fails, the result is @racket[#f].
}

@defproc[(racket-webview-qt-version) (or/c list? #f)]{

Returns the installed version as stored in @tt{version.txt}, or @racket[#f] if
the expected native runtime is not available.

The returned value is the value read from the version file. In the current
implementation this is a list of three numbers: major, minor, and patch.
}

@defproc[(racket-webview-qt-directory) (or/c path? #f)]{

Returns the directory containing the unpacked native runtime for the current
operating system and architecture, or @racket[#f] if the expected version is not
available.

The returned path has the form:

@racketblock[
(build-path install-path (format "~a-~a" rkt-qt-os rkt-qt-arch))
]
}

@section{Downloadability Checks}

@defproc[(racket-webview-qt-resolves?) boolean?]{

Returns @racket[#t] if the configured download host can be resolved through DNS,
and @racket[#f] otherwise.

If no nameserver can be found, or if DNS resolution fails, the result is
@racket[#f].
}

@defproc[(racket-webview-qt-is-downloadable?) boolean?]{

Returns @racket[#t] if the configured download URL can be opened, and
@racket[#f] otherwise.

The function attempts to open an HTTPS input port for the download URL. If that
succeeds, the port is closed immediately and the function returns
@racket[#t]. Any failure is caught and results in @racket[#f].
}

@section{Downloading}

@defproc[(download-racket-webview-qt) boolean?]{

Downloads and installs the configured version of @tt{racket-webview-qt}.

The function performs the following steps:

@itemlist[#:style 'compact
 @item{opens an HTTPS input port for the configured download URL}
 @item{creates the installation directory if necessary}
 @item{downloads the archive to @tt{archive.zip}}
 @item{removes any existing unpacked directory for the current OS and architecture}
 @item{unzips the archive into the installation directory}
 @item{removes the downloaded zip archive}
 @item{writes the installed version to @tt{version.txt}}]

Progress information is printed to the current output port while downloading and
installing.

If no download port can be obtained, the function raises an exception. Otherwise,
on successful completion, it returns @racket[#t].
}

@section{Notes}

The module forces HTTPS downloads by temporarily setting the current HTTPS
protocol to @racket['secure] while opening the download port.

The installed runtime is specific to the current operating system and machine
architecture. The selected archive name has the form:

@racketblock[
(format "~a-~a.zip" (system-type 'os*) (system-type 'arch))
]