Documentation
¶
Overview ¶
Package setup implements host detection and bootstrap for `dexaflow setup` and `dexaflow doctor`: it determines the platform, which dependencies are present, and which operating tier is achievable, preferring relocatable downloads into ~/.dexaflow over system package managers.
Index ¶
- func EnsureManagedPython(ctx context.Context, o EnsureOpts) (string, error)
- func EnsureMonaco(ctx context.Context, client *http.Client, home string, ...) (string, error)
- func EnsurePostgres(ctx context.Context, o EnsureOpts) (string, error)
- func EnsurePython(ctx context.Context, o EnsureOpts) (string, error)
- func ExtractFS(fsys fs.FS, dest string) error
- func GenerateHumanPassword() (string, error)
- func ManagedPythonInstalled(home string) bool
- func ManagedPythonPath(home string) string
- func MonacoDir(home string) string
- func ParsePythonVersion(s string) (major, minor int, err error)
- func PythonCandidates() []string
- func PythonMajorMinor(ver string) (major, minor int, err error)
- func PythonVersion(ctx context.Context, py string) (major, minor int, err error)
- type EnsureOpts
- type HostPython
- type PostgresBuild
- type Probe
- type PythonBuild
- type Report
- type Tier
- type VersionFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureManagedPython ¶ added in v0.5.5
func EnsureManagedPython(ctx context.Context, o EnsureOpts) (string, error)
EnsureManagedPython returns the managed CPython under Home, downloading and verifying the pinned build when it is absent or not the pinned version. It never returns a host interpreter: callers use it when a DAG declares the pinned minor and no host interpreter reports it (#1700).
func EnsureMonaco ¶
func EnsureMonaco(ctx context.Context, client *http.Client, home string, logf func(string, ...any)) (string, error)
EnsureMonaco makes the pinned Monaco bundle available under MonacoDir(home) and returns that directory. It is a no-op when already provisioned; otherwise it downloads the pinned npm tarball, verifies its SHA-256, and extracts only the min/vs subtree.
func EnsurePostgres ¶
func EnsurePostgres(ctx context.Context, o EnsureOpts) (string, error)
EnsurePostgres returns the bin directory of a managed relocatable PostgreSQL (Home/postgres/bin), downloading + verifying + extracting the pinned build if it is not already present. Unlike Python there is NO system fallback: Lite manages its own Postgres so the version and on-disk layout are predictable and — the point of Fase 2 — it needs no Docker. The data directory and process lifecycle are the caller's concern (see the Lite runner).
func EnsurePython ¶
func EnsurePython(ctx context.Context, o EnsureOpts) (string, error)
EnsurePython returns the interpreter `dexaflow setup` points the parser at: the managed relocatable CPython if a current one is already installed under Home, otherwise any host interpreter reporting Python 3.11 to 3.13 (see FindHostPython), and only when neither exists a freshly downloaded and verified pinned build.
The parser shim is stdlib-only (ADR 0024), so a host 3.12 or 3.13 parses as well as the pinned 3.11. Requiring python3.11 by name made every host without it download about 50 MB on first setup, a hard failure behind a proxy or offline (#1700). The managed build is still fetched, lazily, when a DAG venv needs a 3.11 the host lacks (EnsureManagedPython).
func ExtractFS ¶
ExtractFS writes every file in fsys into dest, preserving the directory structure. It is used to materialize the embedded Python sources into ~/.dexaflow so a binary-only install can pip-install them.
func GenerateHumanPassword ¶
GenerateHumanPassword returns a short, human-readable admin password: a random word followed by 2–4 random digits, lowercase letters and digits only, at most ten characters. It is easy to write down and unambiguous, while still drawn from crypto/rand so it is not guessable.
func ManagedPythonInstalled ¶ added in v0.5.5
ManagedPythonInstalled reports whether home holds a complete managed CPython at the pinned version, the install EnsurePython returns before probing the host.
func ManagedPythonPath ¶ added in v0.5.5
ManagedPythonPath returns where the managed CPython interpreter lives under home (e.g. ~/.dexaflow).
func MonacoDir ¶
MonacoDir returns the directory the pinned Monaco bundle is served from (home/assets/monaco/<version>). The editor loads /ide/vs from <dir>/vs.
func ParsePythonVersion ¶ added in v0.5.5
ParsePythonVersion extracts the major and minor from a `python --version` line such as "Python 3.11.15" (the version token may carry a patch and a pre-release suffix, e.g. "3.12.0rc1").
func PythonCandidates ¶
func PythonCandidates() []string
PythonCandidates returns the interpreter binary names Detect probes for, in preference order. It exists so `dexaflow lite` and `dexaflow validate` resolve an interpreter from the SAME list `dexaflow setup` and `dexaflow doctor` report on (#1092): the two used to disagree, so doctor could name a python3.13 that dev never probed for. The slice is copied because callers are in another package and a shared backing array would let one of them reorder the gate's literal.
func PythonMajorMinor ¶ added in v0.5.6
PythonMajorMinor is the one parser for a dotted Python version: it returns the numeric major and minor of "3.11", "3.11.15", "3.12.0rc1" or the "3.13.1.final.0" a pyvenv.cfg records. Whatever follows the minor is ignored, so callers that need a stricter form (the python_version field) check it themselves before calling.
Types ¶
type EnsureOpts ¶
type EnsureOpts struct {
Home string // the managed root, e.g. ~/.dexaflow
GOOS string
GOARCH string
Libc string
LookPath func(string) (string, error)
RunVersion VersionFunc // probes a host interpreter's version; nil runs `--version`
Stat func(string) (os.FileInfo, error)
Client *http.Client
Logf func(string, ...any) // optional progress callback
}
EnsureOpts configures EnsurePython and EnsureManagedPython.
type HostPython ¶ added in v0.5.5
type HostPython struct {
Path string // absolute path LookPath returned
Minor int // the 3.x minor the interpreter reported
}
HostPython is a host interpreter `dexaflow setup` can use for the parser.
func FindHostPython ¶ added in v0.5.5
func FindHostPython(ctx context.Context, lookPath func(string) (string, error), runVersion VersionFunc) (HostPython, bool)
FindHostPython returns the first host interpreter, in hostPythonNames order, that reports a Python 3.11 to 3.13. ok is false when none qualifies, which is the only case where setup still has to download the managed CPython.
type PostgresBuild ¶
PostgresBuild is a relocatable PostgreSQL release asset and its checksum.
func ResolvePostgres ¶
func ResolvePostgres(goos, goarch, libc string) (PostgresBuild, error)
ResolvePostgres returns the pinned relocatable PostgreSQL asset for the host, or an error if the platform is unsupported (e.g. Windows, where WSL2 is the path).
type Probe ¶
type Probe struct {
GOOS string
GOARCH string
LookPath func(string) (string, error) // os/exec.LookPath
Stat func(string) (fs.FileInfo, error)
Getwd func() (string, error)
}
Probe carries the host facts Detect needs. The function fields are injected so detection is testable without touching the real filesystem or PATH.
type PythonBuild ¶
PythonBuild is a relocatable CPython release asset and its expected checksum.
func ResolvePython ¶
func ResolvePython(goos, goarch, libc string) (PythonBuild, error)
ResolvePython returns the pinned relocatable CPython asset for the host, or an error if the platform is unsupported (e.g. Windows, where WSL2 is the path).
type Report ¶
type Report struct {
OS string
Arch string
Libc string // "glibc" or "musl" on linux; empty on darwin
PythonAvailable bool // a usable Python 3.11+ interpreter is on PATH
PythonPath string // path to the chosen interpreter; empty when none is on PATH
// SetupPython is the host interpreter `dexaflow setup` will point the
// parser at (FindHostPython: the first of python3.13, python3.12,
// python3.11 and python3 that reports 3.11 to 3.13). Empty Path means setup
// downloads the managed CPython instead. Detect leaves it empty, because it
// runs nothing; ProbeSetupPython fills it.
//
// It is separate from PythonPath because the two answer different
// questions. PythonPath answers "what can parse a dag.py" by binary name,
// across a wider range; this answers "will `dexaflow setup` download", by
// running the same probe setup runs. Answering both in one sentence is how
// `doctor` and `setup --dry-run` once promised no download and then setup
// downloaded (#1224).
SetupPython HostPython
// Python311Path is a host interpreter reporting 3.11, empty when there is
// none. Without one, the first DAG venv that declares python_version 3.11
// (the default) downloads the managed CPython 3.11 when it is built
// (#1700), so `doctor` and `setup --dry-run` say so up front.
Python311Path string
Docker bool
K3d bool
Kubectl bool
UnderMnt bool // cwd under /mnt (WSL 9p mount): inotify hot-reload is unreliable
Tier Tier
}
Report is the outcome of Detect: the platform, which tools are present, and the highest achievable tier.
func Detect ¶
Detect inspects the host and reports the achievable tier. Docker presence makes the Kubernetes tier achievable (k3d and kubectl are fetched on demand); without Docker the host falls back to the subprocess tier.
func (*Report) ProbeSetupPython ¶ added in v0.5.5
func (r *Report) ProbeSetupPython(ctx context.Context, lookPath func(string) (string, error), runVersion VersionFunc)
ProbeSetupPython fills SetupPython by running the same version probe `dexaflow setup` runs, and widens Python311Path to a bare python3 that reports 3.11 (the DAG venv resolver accepts any name on the version it reports, so such a host needs no lazy download for a default DAG).
type Tier ¶
type Tier int
Tier is an operating mode, ordered by the infrastructure it needs.
const ( // TierSubprocess runs the agent directly on the host with no isolation — the // dev-only escape hatch (ADR 0015). Fastest loop; no Docker or Kubernetes. TierSubprocess Tier = iota // TierK8s runs each task in an ephemeral pod via client-go, on a local // single-node cluster (k3d) or a real cluster. The sole container path // (ADR 0015); Docker is only the engine that hosts the local cluster, never // an executor itself. TierK8s )
Source Files