feat!: release v2 (#6545)

Co-authored-by: Artur <145776561+arturict@users.noreply.github.com>
Co-authored-by: arturict <arturict@users.noreply.github.com>
Co-authored-by: Thomas <thomas@ajnart.fr>
Co-authored-by: Afonso Jorge Ramos <afonsojorgeramos@gmail.com>
Co-authored-by: Danura30082 <danura30082+github@gmail.com>
Co-authored-by: Kushie <122986913+kushiemoon-dev@users.noreply.github.com>
Co-authored-by: ajnart <thomas@ajnart.fr>
Co-authored-by: ajnart <thomas@ajnart.dev>
Co-authored-by: chenjun <chenjun@foxmail.com>
Co-authored-by: Wikibear <wikibear@users.noreply.github.com>
Co-authored-by: Bergasha <bergasha@gmail.com>
Co-authored-by: leafyelin <43306196+leafyelin@users.noreply.github.com>
Co-authored-by: Lucas Araujo <lucas.lra@gmail.com>
Co-authored-by: GreenMonito <86085570+GreenMonito@users.noreply.github.com>
Co-authored-by: Nerdy-Technician <roffo@nerdy-technician.social>
Co-authored-by: Jun <34545896+jcstrong@users.noreply.github.com>
Co-authored-by: Edmond Abraham <54119952+gitedmond@users.noreply.github.com>
Co-authored-by: thrawnx <tight.bulb9384@fastmail.com>
Co-authored-by: Chris <58918656+nordada@users.noreply.github.com>
Co-authored-by: yi111 <153097222+Yi-111-a@users.noreply.github.com>
Co-authored-by: Yanis <naamaneyanis@gmail.com>
Co-authored-by: Wikibear <me@sej.de>
Co-authored-by: alessiottavo <93441886+alessiottavo@users.noreply.github.com>
This commit is contained in:
3286 files changed
+284386 -139176

No files matched your search

@@ -0,0 +1,59 @@
package task
import (
"context"
"os"
"path/filepath"
"testing"
"github.com/homarr-labs/homarr/tools/homarr-dev/internal/docker"
)
// Exercises the real BuildKit streaming and parsing path against a small
// Dockerfile, so the step tracker is validated on genuine output.
func TestBuildImageStreamsRealSteps(t *testing.T) {
if testing.Short() || os.Getenv("HOMARR_INTEGRATION_TEST") != "1" {
t.Skip("skipping docker build probe test; set HOMARR_INTEGRATION_TEST=1 to run")
}
dir := t.TempDir()
dockerfile := `FROM alpine:3.20 AS base
RUN echo "hello from step two" && sleep 1
FROM base AS final
RUN echo "third step" > /out.txt
RUN cat /out.txt
`
if err := os.WriteFile(filepath.Join(dir, "Dockerfile"), []byte(dockerfile), 0o644); err != nil {
t.Fatal(err)
}
manager := NewManager()
task := manager.Build("build homarr:cli-probe", "homarr:cli-probe", docker.BuildOptions{
Context: dir, Tag: "cli-probe", Source: dir, Revision: "probe",
})
t.Cleanup(func() { _ = docker.RemoveImage(context.Background(), "homarr:cli-probe") })
for range 600 {
<-manager.Changed()
if snapshot, _ := manager.Snapshot(task.ID()); snapshot.State.Done() {
t.Logf("state=%s percent=%.2f detail=%q err=%v", snapshot.State, snapshot.Percent, snapshot.Detail, snapshot.Err)
for _, step := range snapshot.Steps {
t.Logf(" #%-3s done=%-5v %-46s %s", step.ID, step.Done, truncate(step.Label, 46), step.Note)
}
if snapshot.State != StateSucceeded {
t.Fatalf("build did not succeed: %v", snapshot.Err)
}
if len(snapshot.Steps) < 4 {
t.Fatalf("expected several build steps, got %d", len(snapshot.Steps))
}
return
}
}
t.Fatal("build did not finish")
}
func truncate(value string, width int) string {
if len(value) <= width {
return value
}
return value[:width]
}
+237
View File
@@ -0,0 +1,237 @@
package task
import (
"context"
"fmt"
"strings"
"time"
"github.com/homarr-labs/homarr/tools/homarr-dev/internal/docker"
)
// Pull downloads an image, preferring the Docker Engine API because it reports
// per-layer byte progress even when the CLI would not. If the socket is
// unreachable the plain `docker pull` output is parsed instead, which still
// yields per-layer state, just without byte counters.
func (m *Manager) Pull(title, target, image, platform string) *Task {
return m.Start(KindPull, title, target, func(ctx context.Context, report *Reporter) error {
return PullImage(ctx, report, image, platform)
})
}
// PullImage is the body of a pull, exported so callers can compose it with
// follow-up work — pulling and then starting a container reads better as one
// job than as two.
func PullImage(ctx context.Context, report *Reporter, image, platform string) error {
tracker := docker.NewPullTracker()
publish := throttled(report, func() {
report.SetSteps(pullSteps(tracker))
report.SetPercent(tracker.Percent())
report.SetDetail(pullDetail(tracker))
})
messages, err := docker.PullStream(ctx, image, platform)
if err != nil {
report.Log("engine API unavailable (" + err.Error() + "), falling back to docker pull")
return pullWithCLI(ctx, report, tracker, publish, image, platform)
}
for message := range messages {
if message.Error != "" {
return fmt.Errorf("pull %s: %s", image, message.Error)
}
tracker.Apply(message)
if message.ID == "" && message.Status != "" {
report.Log(message.Status)
}
publish(false)
}
if ctx.Err() != nil {
return ctx.Err()
}
publish(true)
return nil
}
func pullWithCLI(ctx context.Context, report *Reporter, tracker *docker.PullTracker, publish func(bool), image, platform string) error {
command := docker.PullCommandContext(ctx, image, platform)
command.Cancel = func() error { return command.Process.Kill() }
lines, err := docker.StreamCommand(command)
if err != nil {
return err
}
for line := range lines {
if line.Done {
if line.Err != nil {
return line.Err
}
break
}
tracker.ApplyLine(line.Text)
publish(false)
}
if ctx.Err() != nil {
return ctx.Err()
}
publish(true)
return nil
}
func pullSteps(tracker *docker.PullTracker) []Step {
layers := tracker.Layers()
steps := make([]Step, 0, len(layers))
for _, layer := range layers {
note := ""
if layer.Total > 0 && !layer.Done() {
note = docker.FormatSize(layer.Current) + "/" + docker.FormatSize(layer.Total)
} else if layer.Total > 0 {
note = docker.FormatSize(layer.Total)
}
steps = append(steps, Step{
ID: layer.ID,
Label: layer.ID,
Status: layer.Status,
Current: layer.Current,
Total: layer.Total,
Percent: layer.Fraction(),
Done: layer.Done(),
Note: note,
})
}
return steps
}
func pullDetail(tracker *docker.PullTracker) string {
complete, total := tracker.Complete()
parts := []string{fmt.Sprintf("%d/%d layers", complete, total)}
if current, size := tracker.Bytes(); size > 0 {
parts = append(parts, docker.FormatSize(current)+"/"+docker.FormatSize(size))
}
if rate := tracker.Rate(); rate > 0 {
parts = append(parts, docker.FormatSize(int64(rate))+"/s")
}
return strings.Join(parts, " · ")
}
// Build compiles an image, streaming BuildKit's plain progress so the UI can
// show which Dockerfile step is running and what it is printing.
func (m *Manager) Build(title, target string, options docker.BuildOptions) *Task {
return m.Start(KindBuild, title, target, func(ctx context.Context, report *Reporter) error {
return BuildImage(ctx, report, options)
})
}
// BuildFrom runs a caller-supplied preparation step (cloning a pull request,
// for example) before building. Preparation output is reported the same way as
// build output so the job reads as one continuous stream.
func (m *Manager) BuildFrom(title, target string, prepare func(ctx context.Context, report *Reporter) (docker.BuildOptions, error)) *Task {
return m.Start(KindBuild, title, target, func(ctx context.Context, report *Reporter) error {
options, err := prepare(ctx, report)
if err != nil {
return err
}
return BuildImage(ctx, report, options)
})
}
// BuildImage is the body of a build, exported for the same reason as PullImage.
func BuildImage(ctx context.Context, report *Reporter, options docker.BuildOptions) error {
command, err := docker.BuildCommandStreaming(ctx, options)
if err != nil {
return err
}
command.Cancel = func() error { return command.Process.Kill() }
lines, err := docker.StreamCommand(command)
if err != nil {
return err
}
tracker := docker.NewBuildTracker()
publish := throttled(report, func() {
report.SetSteps(buildSteps(tracker))
report.SetPercent(tracker.Percent())
report.SetDetail(buildDetail(tracker))
})
for line := range lines {
if line.Done {
if line.Err != nil {
if detail := tracker.LastMessage(); detail != "" && !strings.Contains(line.Err.Error(), detail) {
return fmt.Errorf("%w: %s", line.Err, detail)
}
return line.Err
}
break
}
tracker.ApplyLine(line.Text)
report.Log(line.Text)
publish(false)
}
if ctx.Err() != nil {
return ctx.Err()
}
publish(true)
return nil
}
func buildSteps(tracker *docker.BuildTracker) []Step {
steps := tracker.Steps()
converted := make([]Step, 0, len(steps))
for _, step := range steps {
label := step.Label
if label == "" {
label = "#" + step.ID
}
percent := 0.0
if step.Done && !step.Canceled && !step.Failed {
percent = 1
}
note := step.Elapsed
if step.Cached {
note = "cached"
}
converted = append(converted, Step{
ID: step.ID,
Label: label,
Status: step.Status,
Percent: percent,
Done: step.Done && !step.Canceled,
Failed: step.Failed,
Note: note,
})
}
return converted
}
func buildDetail(tracker *docker.BuildTracker) string {
complete, total := tracker.Complete()
detail := fmt.Sprintf("%d/%d steps", complete, total)
if active, running := tracker.Active(); running {
detail += " · " + active.Label
}
return detail
}
// Action runs a short operation such as stopping a container. It still goes
// through the manager so a slow daemon can never freeze the interface.
func (m *Manager) Action(title, target string, body func(ctx context.Context) error) *Task {
return m.Start(KindAction, title, target, func(ctx context.Context, report *Reporter) error {
return body(ctx)
})
}
// throttled limits how often a progress publisher runs. Docker emits progress
// far faster than a terminal can redraw, and every publish copies slices, so
// coalescing here keeps the cost proportional to the frame rate instead of to
// the daemon's chattiness. Passing force publishes regardless, which the caller
// does once at the end so the final state is never dropped.
func throttled(report *Reporter, publish func()) func(force bool) {
const interval = 80 * time.Millisecond
last := time.Time{}
return func(force bool) {
now := time.Now()
if !force && now.Sub(last) < interval {
return
}
last = now
publish()
}
}
+360
View File
@@ -0,0 +1,360 @@
// Package task runs the CLI's slow work — image pulls, local builds, container
// actions — on background goroutines and exposes it as immutable snapshots.
//
// Nothing in this package blocks the caller. A Manager owns every running job,
// coalesces their updates into a single wake-up channel, and hands the UI a
// consistent view whenever it asks for one. That separation is what keeps the
// terminal responsive while a fifteen minute Docker build streams output.
package task
import (
"context"
"sync"
"time"
)
// Kind classifies a job so the UI can pick an icon and a detail renderer.
type Kind int
const (
KindPull Kind = iota
KindBuild
KindAction
)
var kindNames = map[Kind]string{
KindPull: "pull",
KindBuild: "build",
KindAction: "action",
}
func (k Kind) String() string {
if name, found := kindNames[k]; found {
return name
}
return "action"
}
// State is the lifecycle stage of a job.
type State int
const (
StateRunning State = iota
StateSucceeded
StateFailed
StateCanceled
)
func (s State) Done() bool { return s != StateRunning }
var stateNames = map[State]string{
StateRunning: "running",
StateSucceeded: "succeeded",
StateFailed: "failed",
StateCanceled: "canceled",
}
func (s State) String() string {
if name, found := stateNames[s]; found {
return name
}
return "canceled"
}
// Step is one unit of progress inside a job: a Docker layer during a pull, or a
// BuildKit vertex during a build.
type Step struct {
ID string
Label string
Status string
Current int64
Total int64
Percent float64
Done bool
Failed bool
Note string
}
// Snapshot is an immutable view of a job. The UI only ever sees snapshots, so
// it can render without holding a lock or racing the worker goroutine.
type Snapshot struct {
ID int
Kind Kind
Title string
Target string
Detail string
State State
Err error
Percent float64
Steps []Step
Lines []string
Started time.Time
Ended time.Time
Cancellable bool
}
// Elapsed reports how long the job ran, or has been running.
func (s Snapshot) Elapsed() time.Duration {
if s.Ended.IsZero() {
return time.Since(s.Started)
}
return s.Ended.Sub(s.Started)
}
// Reporter is the handle a job body uses to publish progress. Every method is
// safe to call from any goroutine and never blocks on the UI.
type Reporter struct {
task *Task
}
// Log appends a line of output. Only the most recent lines are retained.
func (r *Reporter) Log(line string) {
r.task.mutate(func(t *Task) { t.lines = appendLine(t.lines, line) })
}
// SetSteps replaces the job's progress breakdown.
func (r *Reporter) SetSteps(steps []Step) {
r.task.mutate(func(t *Task) { t.steps = steps })
}
// SetPercent records overall progress in the range [0,1].
func (r *Reporter) SetPercent(percent float64) {
r.task.mutate(func(t *Task) { t.percent = clamp(percent) })
}
// SetDetail replaces the single-line summary shown next to the job.
func (r *Reporter) SetDetail(detail string) {
r.task.mutate(func(t *Task) { t.detail = detail })
}
// Lines returns the retained output, newest last.
func (r *Reporter) Lines() []string {
r.task.mu.Lock()
defer r.task.mu.Unlock()
return append([]string(nil), r.task.lines...)
}
// Body is the work a job performs. Returning an error fails the job; returning
// ctx.Err() after cancellation marks it canceled instead.
type Body func(ctx context.Context, report *Reporter) error
// Task is a single background job.
type Task struct {
mu sync.Mutex
manager *Manager
id int
kind Kind
title string
target string
detail string
state State
err error
percent float64
steps []Step
lines []string
started time.Time
ended time.Time
cancel context.CancelFunc
}
const retainedLines = 500
func appendLine(lines []string, line string) []string {
lines = append(lines, line)
if len(lines) > retainedLines {
lines = lines[len(lines)-retainedLines:]
}
return lines
}
func clamp(value float64) float64 {
if value < 0 {
return 0
}
if value > 1 {
return 1
}
return value
}
func (t *Task) mutate(apply func(*Task)) {
t.mu.Lock()
apply(t)
t.mu.Unlock()
t.manager.touch()
}
func (t *Task) snapshot() Snapshot {
t.mu.Lock()
defer t.mu.Unlock()
return Snapshot{
ID: t.id,
Kind: t.kind,
Title: t.title,
Target: t.target,
Detail: t.detail,
State: t.state,
Err: t.err,
Percent: t.percent,
Steps: append([]Step(nil), t.steps...),
Lines: append([]string(nil), t.lines...),
Started: t.started,
Ended: t.ended,
Cancellable: t.cancel != nil && t.state == StateRunning,
}
}
// ID returns the job's identifier, stable for the lifetime of the process.
func (t *Task) ID() int { return t.id }
// Manager owns every background job and notifies a single listener when any of
// them changes.
type Manager struct {
mu sync.Mutex
tasks []*Task
nextID int
notify chan struct{}
}
func NewManager() *Manager {
return &Manager{notify: make(chan struct{}, 1)}
}
// Changed is a coalescing wake-up channel. It receives at most one pending
// notification, so a job that emits thousands of progress updates per second
// still costs the UI a single redraw per frame.
func (m *Manager) Changed() <-chan struct{} { return m.notify }
func (m *Manager) touch() {
select {
case m.notify <- struct{}{}:
default:
}
}
// Start launches a job and returns immediately.
func (m *Manager) Start(kind Kind, title, target string, body Body) *Task {
ctx, cancel := context.WithCancel(context.Background())
m.mu.Lock()
m.nextID++
task := &Task{
manager: m,
id: m.nextID,
kind: kind,
title: title,
target: target,
state: StateRunning,
started: time.Now(),
cancel: cancel,
}
m.tasks = append(m.tasks, task)
m.mu.Unlock()
go func() {
err := body(ctx, &Reporter{task: task})
task.mu.Lock()
task.ended = time.Now()
task.cancel = nil
switch {
case ctx.Err() != nil:
task.state = StateCanceled
case err != nil:
task.state, task.err = StateFailed, err
default:
task.state, task.percent = StateSucceeded, 1
}
task.mu.Unlock()
cancel()
m.touch()
}()
m.touch()
return task
}
// Snapshots returns every job, oldest first.
func (m *Manager) Snapshots() []Snapshot {
m.mu.Lock()
tasks := append([]*Task(nil), m.tasks...)
m.mu.Unlock()
snapshots := make([]Snapshot, 0, len(tasks))
for _, task := range tasks {
snapshots = append(snapshots, task.snapshot())
}
return snapshots
}
// Snapshot returns a single job by identifier.
func (m *Manager) Snapshot(id int) (Snapshot, bool) {
m.mu.Lock()
defer m.mu.Unlock()
for _, task := range m.tasks {
if task.id == id {
return task.snapshot(), true
}
}
return Snapshot{}, false
}
// Cancel asks a running job to stop.
func (m *Manager) Cancel(id int) {
m.mu.Lock()
defer m.mu.Unlock()
for _, task := range m.tasks {
if task.id != id {
continue
}
task.mu.Lock()
cancel := task.cancel
task.mu.Unlock()
if cancel != nil {
cancel()
}
}
}
// CancelAll stops every running job, used when the program exits.
func (m *Manager) CancelAll() {
for _, snapshot := range m.Snapshots() {
if snapshot.State == StateRunning {
m.Cancel(snapshot.ID)
}
}
}
// Running counts jobs that have not finished.
func (m *Manager) Running() int {
count := 0
for _, snapshot := range m.Snapshots() {
if snapshot.State == StateRunning {
count++
}
}
return count
}
// RunningFor reports whether a job is already working on the given target, so
// the UI can refuse to start a duplicate build or pull.
func (m *Manager) RunningFor(target string) (Snapshot, bool) {
for _, snapshot := range m.Snapshots() {
if snapshot.State == StateRunning && snapshot.Target == target {
return snapshot, true
}
}
return Snapshot{}, false
}
// Prune drops finished jobs, keeping the history short.
func (m *Manager) Prune() {
m.mu.Lock()
kept := m.tasks[:0]
for _, task := range m.tasks {
if task.snapshot().State == StateRunning {
kept = append(kept, task)
}
}
m.tasks = kept
m.mu.Unlock()
m.touch()
}