Documentation
¶
Overview ¶
Package webui installs, selects and serves the compiled DataTug web app (the public archives of github.com/datatug/web-ui) from the CLI's own HTTP server.
Spec: datatug/backstage spec/features/local-frontend-distribution (decision 0006). An archive is a gzip tar of manifest.json plus the static app under browser/; it is verified file by file against the manifest before it becomes visible under the installed-versions directory, and the CLI activates it only when both sides of the compatibility contract hold (see Compatible).
Index ¶
- Constants
- Variables
- func CompareVersions(a, b string) int
- func Compatible(m Manifest) error
- func IsPrerelease(v string) bool
- func ParseDigest(s string) (string, error)
- func SidecarDigest(archive string) (digest string, ok bool, err error)
- func ValidVersion(v string) bool
- type BuildInfo
- type Candidate
- type DigestSource
- type Entry
- type Handler
- type HandlerOptions
- type InstallOptions
- type Installed
- type Manifest
- type ManifestFileEntry
- type ReleaseSource
- type Requirements
- type RuntimeConfig
- type State
- type Store
- func (s Store) InstallArchive(archivePath string, opts InstallOptions) (Installed, error)
- func (s Store) List() ([]Entry, error)
- func (s Store) LoadState() (State, error)
- func (s Store) MarkActive(version string) error
- func (s Store) Remove(version string) error
- func (s Store) Rollback() (State, error)
- func (s Store) Select(requested string) (Entry, error)
- func (s Store) Unpin() (State, error)
- func (s Store) Use(version string) (State, error)
Constants ¶
const ( ManifestFile = "manifest.json" SignatureFile = "manifest.json.sig" BrowserDir = "browser" IndexFile = BrowserDir + "/index.html" )
ManifestFile and IndexFile are the two paths every archive must hold.
const AgentPathPrefix = "/datatug/"
AgentPathPrefix is where the agent API lives; the handler never answers under it.
const DefaultReleaseRepo = "datatug/web-ui"
DefaultReleaseRepo is the public repository of compiled frontend releases.
const DirEnv = "DATATUG_WEB_UI_DIR"
DirEnv overrides where installed web UIs live.
const LocalAPIVersion = "1.0"
LocalAPIVersion is the version of the agent's local HTTP API contract that this CLI serves (major.minor). Bump the minor for additive changes, the major when a route is removed or changes meaning: every frontend that declares "<major" is then refused cleanly instead of half-working.
const ManifestName = "datatug-web-ui"
ManifestName is the name every DataTug web UI archive declares.
const ManifestSchema = "datatug-web-ui/1"
ManifestSchema is the only manifest schema this CLI reads.
const MinFrontendVersion = "0.1.0"
MinFrontendVersion is the oldest frontend this CLI will serve. It is a security/bug floor, bumped only when an older frontend must never run against this CLI again; ordinary compatibility is the frontend's own requires.localApi range.
Variables ¶
var ErrIncompatible = errors.New("web UI is not compatible with this DataTug CLI")
ErrIncompatible marks a frontend that is installed but cannot be served by this CLI.
var ErrNotInstalled = errors.New("no DataTug web UI is installed")
ErrNotInstalled is returned when no web UI is installed.
Functions ¶
func CompareVersions ¶
CompareVersions compares two valid versions like semver.Compare.
func Compatible ¶
Compatible checks both sides of the compatibility contract.
func IsPrerelease ¶
IsPrerelease reports whether v carries a pre-release part.
func ParseDigest ¶
ParseDigest reads a digest in any of the forms people paste: bare hex, "sha256:<hex>", or a sha256sum line "<hex> <file>".
func SidecarDigest ¶
SidecarDigest reads <archive>.sha256 when it exists. ok is false when there is none.
func ValidVersion ¶
ValidVersion reports whether v is a SemVer 2.0 version without a leading "v".
Types ¶
type BuildInfo ¶
type BuildInfo struct {
Commit string `json:"commit,omitempty"`
Date string `json:"date,omitempty"`
Source string `json:"source,omitempty"`
}
BuildInfo says where an archive was built from. It is informational.
type DigestSource ¶
type DigestSource string
DigestSource says where the expected archive digest came from: the honest answer to "who vouches for this archive" until releases are signed.
const ( DigestFromFlag DigestSource = "--sha256 flag" DigestFromSidecar DigestSource = "sidecar .sha256 file" DigestFromRelease DigestSource = "GitHub release over HTTPS" DigestNone DigestSource = "none — integrity of contents only" )
type Entry ¶
type Entry struct {
Version string
Dir string
Manifest Manifest
// Incompatible is why this CLI will not serve it; nil when it can.
Incompatible error
}
Entry is one installed version.
type Handler ¶
type Handler struct {
// InlineHandlers counts inline event-handler attributes the CSP blocks.
InlineHandlers int
// contains filtered or unexported fields
}
Handler serves one installed web UI.
func NewHandler ¶
func NewHandler(opts HandlerOptions) (*Handler, error)
NewHandler reads the version's index.html, injects the runtime config and builds the CSP.
type HandlerOptions ¶
type HandlerOptions struct {
// Dir is an installed version's directory (holding browser/).
Dir string
Runtime RuntimeConfig
// ConnectSrc are extra origins the page may reach (CSP connect-src), from --ui-connect-src.
ConnectSrc []string
}
HandlerOptions configure the static web UI handler.
type InstallOptions ¶
type InstallOptions struct {
// ExpectedSHA256 is the archive's expected digest, lowercase hex. "" checks none.
ExpectedSHA256 string
Source DigestSource
}
InstallOptions are the expectations an install verifies.
type Installed ¶
type Installed struct {
Manifest Manifest
Dir string
ArchiveSHA256 string
Source DigestSource
// Reused is true when the same version was already installed and verified.
Reused bool
}
Installed is the outcome of an install.
type Manifest ¶
type Manifest struct {
Schema string `json:"schema"`
Name string `json:"name"`
Version string `json:"version"`
Requires Requirements `json:"requires"`
Build BuildInfo `json:"build"`
Files []ManifestFileEntry `json:"files"`
}
Manifest is manifest.json of a web UI archive.
func ParseManifest ¶
ParseManifest reads and validates manifest.json.
type ManifestFileEntry ¶
type ManifestFileEntry struct {
Path string `json:"path"`
Size int64 `json:"size"`
SHA256 string `json:"sha256"`
}
ManifestFileEntry is one file the archive holds besides manifest.json.
type ReleaseSource ¶
type ReleaseSource struct {
Repo string
APIBase string // https://api.github.com
DownloadBase string // https://github.com
Client *http.Client
}
ReleaseSource finds and downloads frontend releases on GitHub. It is used only when the person asks for a download (`web-ui install --latest`, `web-ui update`); nothing else in this package touches the network.
type Requirements ¶
type Requirements struct {
// LocalAPI is a range over the agent's local API contract version, e.g. ">=1.0 <2".
LocalAPI string `json:"localApi"`
}
Requirements is what a frontend needs of the agent it runs against.
type RuntimeConfig ¶
type RuntimeConfig struct {
Mode string `json:"mode"`
AgentPath string `json:"agentPath"`
LocalAPI string `json:"localApi"`
CLIVersion string `json:"cliVersion"`
Version string `json:"webUiVersion"`
Telemetry bool `json:"telemetry"`
}
RuntimeConfig is injected into index.html as <meta name="datatug-runtime">. It tells the frontend it runs in local mode and where the agent is; it grants nothing — the agent decides every permission per request.
type State ¶
type State struct {
Pinned string `json:"pinned,omitempty"`
Active string `json:"active,omitempty"`
Previous string `json:"previous,omitempty"`
}
State is which version is pinned, served last, and served before that.
type Store ¶
type Store struct{ Dir string }
Store is the directory of installed web UI versions and their selection state.
func DefaultStore ¶
func DefaultStore() Store
DefaultStore is ~/datatug/web-ui, or $DATATUG_WEB_UI_DIR.
func (Store) InstallArchive ¶
func (s Store) InstallArchive(archivePath string, opts InstallOptions) (Installed, error)
InstallArchive verifies the archive at archivePath and installs it as versions/<version>. Nothing appears under versions/ unless every check passes.
func (Store) List ¶
List returns installed versions, newest first. A directory whose manifest cannot be read is skipped: it is not a usable install.
func (Store) MarkActive ¶
MarkActive records that version is now being served.
func (Store) Select ¶
Select picks the version to serve: requested, else pinned, else the newest compatible one. A requested or pinned version that is missing or incompatible is an error: it never silently falls back. The chosen version is re-verified.