feat(platform): show which startup step is running, with progress and ETA (#3813)

Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com>
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
Henry
2026-09-20 07:06:19 +08:00
committed by GitHub
parent 1727435c14
commit 8779c88d79
124 changed files with 7527 additions and 347 deletions
@@ -12,6 +12,7 @@ import (
"github.com/kandev/kandev/internal/agent/executor"
"github.com/kandev/kandev/internal/agentctl/tracing"
agentctltypes "github.com/kandev/kandev/internal/agentctl/types"
"github.com/kandev/kandev/internal/startup"
"github.com/kandev/kandev/internal/task/models"
v1 "github.com/kandev/kandev/pkg/api/v1"
)
@@ -52,6 +53,7 @@ func (m *Manager) Start(ctx context.Context) error {
// Read the live standalone recovery-inventory records (startup step 3,
// AC-EXECUTORS-SURVIVAL-002.8) before recovery contacts any control
// server, and hand them to every runtime's RecoverInstances unchanged.
startup.BeginStep(ctx, startup.StepSessionsRecovery)
records, listErr := m.ListLiveStandaloneExecutorsRunning(ctx)
m.runRecoveryErr = listErr
if listErr != nil {
@@ -69,6 +71,11 @@ func (m *Manager) Start(ctx context.Context) error {
m.logger.Error("skipping recovery: live standalone recovery-inventory records could not be read, so no live instance can be correlated to a session",
zap.Error(listErr))
records = nil
// The corpus is unknown, not zero: a failed read is not the same as
// an empty inventory, so this activation is locked opaque (never
// promoted to counted) rather than reporting SetTotal(0), which
// would claim a known-empty corpus.
startup.Degrade(ctx, startup.StepSessionsRecovery)
}
// Take a recovery guard for every named session except a confirmed
@@ -95,6 +102,9 @@ func (m *Manager) Start(ctx context.Context) error {
// (ListLiveStandaloneExecutorsRunning), and StandaloneExecutor is the
// only backend that reads them, so this narrows nothing else.
records = recoverableRecords(records, guardedSessions)
if listErr == nil {
startup.SetTotal(ctx, startup.StepSessionsRecovery, int64(len(records)))
}
// AC-EXECUTORS-SURVIVAL-003.7: bound this pass's
// adoption+enumeration+reconstruction work with a single deadline, clocked
@@ -132,6 +142,7 @@ func (m *Manager) Start(ctx context.Context) error {
zap.String("instance_id", ri.InstanceID),
zap.String("session_id", ri.SessionID))
m.dispatchUnreconstructableStop(&stopWG, ri)
startup.Advance(ctx, startup.StepSessionsRecovery, 1)
continue
}
execution := &AgentExecution{
@@ -183,6 +194,7 @@ func (m *Manager) Start(ctx context.Context) error {
zap.String("instance_id", execution.ID),
zap.String("session_id", execution.SessionID))
m.dispatchUnreconstructableStop(&stopWG, ri)
startup.Advance(ctx, startup.StepSessionsRecovery, 1)
continue
}
// A recovered instance is resuming a live provider session (its
@@ -200,6 +212,7 @@ func (m *Manager) Start(ctx context.Context) error {
zap.String("session_id", execution.SessionID),
zap.Error(err))
m.dispatchUnreconstructableStop(&stopWG, ri)
startup.Advance(ctx, startup.StepSessionsRecovery, 1)
continue
}
// AC-EXECUTORS-SURVIVAL-002.14: Office profile identity is a new key
@@ -225,6 +238,7 @@ func (m *Manager) Start(ctx context.Context) error {
zap.String("agent_profile_id", execution.AgentProfileID),
zap.Error(err))
m.dispatchUnreconstructableStop(&stopWG, ri)
startup.Advance(ctx, startup.StepSessionsRecovery, 1)
continue
}
// AC-EXECUTORS-SURVIVAL-004.2/004.5: retrieve this instance's
@@ -239,6 +253,7 @@ func (m *Manager) Start(ctx context.Context) error {
zap.String("instance_id", execution.ID),
zap.String("session_id", execution.SessionID))
m.dispatchUnreconstructableStop(&stopWG, ri)
startup.Advance(ctx, startup.StepSessionsRecovery, 1)
continue
}
// Create trace span for the recovered session
@@ -268,6 +283,7 @@ func (m *Manager) Start(ctx context.Context) error {
}
execution.EndSessionSpan()
initSpan.End()
startup.Advance(ctx, startup.StepSessionsRecovery, 1)
continue
}
m.setRuntimeInterest(execution.SessionID, true)
@@ -320,6 +336,7 @@ func (m *Manager) Start(ctx context.Context) error {
go m.streamManager.ReconnectAll(execution)
initSpan.End()
startup.Advance(ctx, startup.StepSessionsRecovery, 1)
}
m.logger.Info("recovered executions", zap.Int("count", len(recovered)))
}
@@ -333,6 +350,7 @@ func (m *Manager) Start(ctx context.Context) error {
// before returning) so Start remains synchronous overall and
// ReleaseAllExceptRetained below never races a still-resolving stop.
stopWG.Wait()
startup.EndStep(ctx, startup.StepSessionsRecovery)
// Recovery is synchronous above: by this point every guarded session's
// outcome (re-tracked or not) is already decided, so every guard still
@@ -3,6 +3,7 @@ package lifecycle
import (
"context"
"errors"
"sync"
"testing"
"time"
@@ -20,6 +21,9 @@ type deadlineRecoveringExecutor struct {
name executor.Name
recovered []*ExecutorInstance
stopWithRetryCalls []string
stopStarted chan struct{}
allowStop chan struct{}
stopStartOnce sync.Once
}
func (e *deadlineRecoveringExecutor) Name() executor.Name { return e.name }
@@ -39,6 +43,10 @@ func (e *deadlineRecoveringExecutor) ShouldApplyPreferredShell() bool
func (e *deadlineRecoveringExecutor) IsAlwaysResumable() bool { return false }
func (e *deadlineRecoveringExecutor) stopWithRetry(_ context.Context, instanceID string) error {
e.stopWithRetryCalls = append(e.stopWithRetryCalls, instanceID)
if e.stopStarted != nil {
e.stopStartOnce.Do(func() { close(e.stopStarted) })
<-e.allowStop
}
return nil
}
@@ -0,0 +1,239 @@
package lifecycle
import (
"context"
"errors"
"testing"
"time"
"go.uber.org/zap"
"go.uber.org/zap/zaptest/observer"
"github.com/kandev/kandev/internal/agent/executor"
agentctlclient "github.com/kandev/kandev/internal/agent/runtime/agentctl"
"github.com/kandev/kandev/internal/common/logger"
"github.com/kandev/kandev/internal/startup"
"github.com/kandev/kandev/internal/task/models"
)
// newObservedSessionsRecoveryReporter builds a startup.Reporter whose own
// logger is independent of the Manager's -- Manager.Start's
// startup.BeginStep/Advance/Degrade/EndStep calls all go through the
// context-carried Reporter, not m.logger, so observing it needs no changes
// to how the Manager under test is constructed.
func newObservedSessionsRecoveryReporter(t *testing.T) (*startup.Reporter, *observer.ObservedLogs) {
t.Helper()
core, logs := observer.New(zap.InfoLevel)
log, err := logger.NewFromZap(zap.New(core))
if err != nil {
t.Fatal(err)
}
return startup.New(log), logs
}
// completedStepFields returns the ContextMap of the last "Startup step
// completed" entry for wantStep, or fails the test if there is none.
func completedStepFields(t *testing.T, logs *observer.ObservedLogs, wantStep startup.StepID) map[string]interface{} {
t.Helper()
var fields map[string]interface{}
for _, entry := range logs.All() {
if entry.Message != "Startup step completed" {
continue
}
if entry.ContextMap()["step"] != string(wantStep) {
continue
}
fields = entry.ContextMap()
}
if fields == nil {
t.Fatalf("no \"Startup step completed\" entry for step %q", wantStep)
}
return fields
}
// TestManagerStartRecoverySessionsStepReportsCountedProgress covers the
// sessions.recovery half of AC-PLATFORM-STARTUP-PROGRESS-005.2/.8 on the
// ordinary (successful inventory read) path: the step totals from the
// post-recoverableRecords record count, and the consumer loop's Advance(1)
// call fires even on a record that is immediately refused (empty TaskID),
// since that record was still consumed from the corpus that SetTotal
// counted.
func TestManagerStartRecoverySessionsStepReportsCountedProgress(t *testing.T) {
log := newTestLogger()
registry := NewExecutorRegistry(log)
backend := &MockExecutor{
name: executor.NameStandalone,
recoverInstances: []*ExecutorInstance{{
InstanceID: "instance-1",
SessionID: "session-1",
TaskID: "", // refused immediately (AC-EXECUTORS-SURVIVAL-002.4), but still one unit of progress
RuntimeName: executor.NameStandalone,
}},
}
registry.Register(backend)
mgr := NewManager(newTestRegistry(), &MockEventBus{}, registry, &MockCredentialsManager{}, &MockProfileResolver{}, nil,
ExecutorFallbackWarn, "", log)
cleanupManagerStopCh(t, mgr)
t.Cleanup(func() { _ = mgr.Stop() })
mgr.SetExecutorRunningWriter(&listingWriter{rows: []*models.ExecutorRunning{{SessionID: "session-1"}}})
reporter, logs := newObservedSessionsRecoveryReporter(t)
reporter.Set(startup.RecoveringSessions)
ctx := startup.WithReporter(context.Background(), reporter)
if err := mgr.Start(ctx); err != nil {
t.Fatalf("Start() error = %v", err)
}
if snap := reporter.Snapshot(); snap.Step != nil {
t.Fatalf("Step after Start = %+v, want nil (step closed)", snap.Step)
}
fields := completedStepFields(t, logs, startup.StepSessionsRecovery)
if got := fields["measure"]; got != "counted" {
t.Fatalf("measure = %v, want \"counted\": a successful non-empty inventory read must promote past opaque", got)
}
if got, ok := fields["done"].(int64); !ok || got != 1 {
t.Fatalf("done = %v, want 1", fields["done"])
}
if got, ok := fields["total"].(int64); !ok || got != 1 {
t.Fatalf("total = %v, want 1", fields["total"])
}
}
// TestManagerStartRecoverySessionsStepReportsZeroTotalOnEmptyInventory
// covers the successful-but-empty boundary: a SUCCESSFUL read returning no
// records is authoritative (TestManagerStartEmptyRecoveryInventoryStillStopsOrphans
// pins the orphan-stop side of this same scenario), so SetTotal(0) reports a
// known-empty corpus rather than the unreadable path's Degrade.
func TestManagerStartRecoverySessionsStepReportsZeroTotalOnEmptyInventory(t *testing.T) {
control := newStandaloneControlServer(t, true)
control.listInstances = []*agentctlclient.InstanceInfo{
{ID: "instance-1", SessionID: "session-1"},
}
mgr := newLivenessTestManager(t, control)
t.Cleanup(func() { _ = mgr.Stop() })
registerRecoveryTestAgentProfile(t, mgr)
mgr.SetExecutorRunningWriter(&listingWriter{rows: []*models.ExecutorRunning{}})
mgr.SetRecoveryDeadline(5 * time.Second)
reporter, logs := newObservedSessionsRecoveryReporter(t)
reporter.Set(startup.RecoveringSessions)
ctx := startup.WithReporter(context.Background(), reporter)
if err := mgr.Start(ctx); err != nil {
t.Fatalf("Start() error = %v", err)
}
for _, entry := range logs.All() {
if entry.Message == "Startup step warning" && entry.ContextMap()["step"] == string(startup.StepSessionsRecovery) && entry.ContextMap()["condition"] == "degrade" {
t.Fatalf("unexpected degrade warning on an authoritative empty inventory: %+v", entry.ContextMap())
}
}
fields := completedStepFields(t, logs, startup.StepSessionsRecovery)
if got := fields["measure"]; got != "opaque" {
t.Fatalf("measure = %v, want \"opaque\": SetTotal(0) seals the activation opaque", got)
}
if got, ok := fields["total"].(int64); !ok || got != 0 {
t.Fatalf("total = %v, want 0", fields["total"])
}
}
func TestManagerStartKeepsRecoveryStepUntilStopWorkersFinish(t *testing.T) {
log := newTestLogger()
execRegistry := NewExecutorRegistry(log)
backend := &deadlineRecoveringExecutor{
name: executor.NameStandalone,
stopStarted: make(chan struct{}),
allowStop: make(chan struct{}),
recovered: []*ExecutorInstance{{
InstanceID: "exec-1",
TaskID: "task-1",
SessionID: "session-1",
RuntimeName: executor.NameStandalone,
StandaloneInstanceID: "standalone-1",
}},
}
execRegistry.Register(backend)
mgr := NewManager(newTestRegistry(), &MockEventBus{}, execRegistry, &MockCredentialsManager{}, &MockProfileResolver{}, nil,
ExecutorFallbackWarn, "", log)
cleanupManagerStopCh(t, mgr)
mgr.SetExecutorRunningWriter(&listingWriter{rows: []*models.ExecutorRunning{{SessionID: "session-1"}}})
mgr.SetRecoveryDeadlineStart(time.Now().Add(-time.Hour))
mgr.SetRecoveryDeadline(time.Millisecond)
reporter, _ := newObservedSessionsRecoveryReporter(t)
reporter.Set(startup.RecoveringSessions)
ctx := startup.WithReporter(context.Background(), reporter)
done := make(chan error, 1)
go func() { done <- mgr.Start(ctx) }()
select {
case <-backend.stopStarted:
case <-time.After(2 * time.Second):
t.Fatal("recovery stop worker did not start")
}
if snap := reporter.Snapshot(); snap.Step == nil {
t.Fatal("recovery step ended before the stop worker finished")
}
close(backend.allowStop)
if err := <-done; err != nil {
t.Fatalf("Start() error = %v", err)
}
if snap := reporter.Snapshot(); snap.Step != nil {
t.Fatalf("Step after Start = %+v, want nil (step closed)", snap.Step)
}
}
// TestManagerStartRecoverySessionsStepLocksOpaqueOnUnreadableInventory
// covers the AC-EXECUTORS-SURVIVAL-002.6/002.12 unreadable-inventory path
// this same file's sibling manager_recovery_inventory_unknown_test.go pins
// the orphan-stop behavior for: the corpus is unknown, not empty, so the
// step never promotes past opaque and Degrade logs a "degrade" warning
// distinguishing this boot from a genuinely empty one.
func TestManagerStartRecoverySessionsStepLocksOpaqueOnUnreadableInventory(t *testing.T) {
control := newStandaloneControlServer(t, true)
control.listInstances = []*agentctlclient.InstanceInfo{
{ID: "instance-1", SessionID: "session-1"},
}
mgr := newLivenessTestManager(t, control)
t.Cleanup(func() { _ = mgr.Stop() })
registerRecoveryTestAgentProfile(t, mgr)
mgr.SetExecutorRunningWriter(&listingWriter{err: errors.New("database unavailable")})
mgr.SetRecoveryDeadline(5 * time.Second)
reporter, logs := newObservedSessionsRecoveryReporter(t)
reporter.Set(startup.RecoveringSessions)
ctx := startup.WithReporter(context.Background(), reporter)
if err := mgr.Start(ctx); err != nil {
t.Fatalf("Start() error = %v", err)
}
var sawDegradeWarning bool
for _, entry := range logs.All() {
if entry.Message != "Startup step warning" {
continue
}
if entry.ContextMap()["step"] == string(startup.StepSessionsRecovery) && entry.ContextMap()["condition"] == "degrade" {
sawDegradeWarning = true
}
}
if !sawDegradeWarning {
t.Fatal("expected a \"Startup step warning\" entry with condition=degrade for an unreadable inventory")
}
fields := completedStepFields(t, logs, startup.StepSessionsRecovery)
if got := fields["measure"]; got != "opaque" {
t.Fatalf("measure = %v, want \"opaque\": an unreadable inventory must never promote past opaque", got)
}
if got, ok := fields["total"].(int64); !ok || got != 0 {
t.Fatalf("total = %v, want 0 (SetTotal is never called on this path)", fields["total"])
}
}
@@ -14,6 +14,7 @@ import (
analyticsservice "github.com/kandev/kandev/internal/analytics/service"
"github.com/kandev/kandev/internal/db"
"github.com/kandev/kandev/internal/persistence/requiredstores"
"github.com/kandev/kandev/internal/startup"
)
const availabilityWorkspaceID = statsReferenceWorkspaceID
@@ -125,6 +126,7 @@ func newAnalyticsAvailabilityHealth(t *testing.T, fixture statsReferenceFixture)
ID: "analytics",
OwnerPackage: "internal/analytics/repository",
RequiredTables: []string{"tasks"},
Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker failed: %v", err)
@@ -220,32 +220,32 @@ func stringContains(value, want string) bool {
func newCanvasEditTestDependencies() (*fakeCanvasEditTaskStore, *fakeCanvasEditCanvasStore, *fakeCanvasEditReleaseStore, *fakeCanvasEditArtifactStore) {
return &fakeCanvasEditTaskStore{
workspace: &models.Workspace{
ID: "workspace-a",
DefaultAgentProfileID: stringPointer("profile-default"),
DefaultExecutorID: stringPointer("executor-default"),
},
}, &fakeCanvasEditCanvasStore{canvas: &canvas.Canvas{
ID: "canvas-a",
PluginInstanceID: "instance-a",
WorkspaceID: "workspace-a",
ScopeKind: canvas.ScopeWorkspace,
Status: instances.StatusActive,
ActiveReleaseID: "release-a",
ActiveReleaseStatus: instances.ValidationValid,
EffectiveGrants: []canvas.GrantProjection{{
PermissionKind: "api_read", Resource: "tasks", ScopeCeiling: instances.ScopeWorkspace,
}},
}}, &fakeCanvasEditReleaseStore{release: instances.Release{
ID: "release-a",
InstanceID: "instance-a",
PackageDigest: "digest-a",
ArtifactPath: "releases/digest-a",
ValidationStatus: instances.ValidationValid,
}}, &fakeCanvasEditArtifactStore{files: map[string][]byte{
"manifest.yaml": []byte("manifest"),
"index.html": []byte("index"),
}}
workspace: &models.Workspace{
ID: "workspace-a",
DefaultAgentProfileID: stringPointer("profile-default"),
DefaultExecutorID: stringPointer("executor-default"),
},
}, &fakeCanvasEditCanvasStore{canvas: &canvas.Canvas{
ID: "canvas-a",
PluginInstanceID: "instance-a",
WorkspaceID: "workspace-a",
ScopeKind: canvas.ScopeWorkspace,
Status: instances.StatusActive,
ActiveReleaseID: "release-a",
ActiveReleaseStatus: instances.ValidationValid,
EffectiveGrants: []canvas.GrantProjection{{
PermissionKind: "api_read", Resource: "tasks", ScopeCeiling: instances.ScopeWorkspace,
}},
}}, &fakeCanvasEditReleaseStore{release: instances.Release{
ID: "release-a",
InstanceID: "instance-a",
PackageDigest: "digest-a",
ArtifactPath: "releases/digest-a",
ValidationStatus: instances.ValidationValid,
}}, &fakeCanvasEditArtifactStore{files: map[string][]byte{
"manifest.yaml": []byte("manifest"),
"index.html": []byte("index"),
}}
}
func stringPointer(value string) *string { return &value }
@@ -0,0 +1,33 @@
package backendapp
import (
"net/http"
"os"
"github.com/gin-gonic/gin"
"github.com/kandev/kandev/internal/common/logger"
"github.com/kandev/kandev/internal/startup"
)
// registerE2EStartupPageFixtureRoute exposes writeStartupPage, the same
// renderer newBootstrapHandler uses while the real router is still coming
// up, as a fixture endpoint. The bootstrap window closes as soon as this
// process finishes starting, so a browser test has no other way to reach
// that markup and embedded poll script against a caller-supplied snapshot.
// Gated the same way as registerE2EResetRoutes.
func registerE2EStartupPageFixtureRoute(router *gin.Engine, log *logger.Logger) {
mockMode := os.Getenv("KANDEV_MOCK_AGENT")
if mockMode != "true" && mockMode != "only" {
return
}
router.POST("/api/v1/e2e/startup-page-fixture", func(c *gin.Context) {
var snap startup.Snapshot
if err := c.ShouldBindJSON(&snap); err != nil {
c.JSON(http.StatusBadRequest, gin.H{errKey: "invalid startup snapshot"})
return
}
writeStartupPage(c.Writer, c.Request, snap)
})
log.Info("registered E2E startup page fixture route (test-only)")
}
@@ -0,0 +1,93 @@
package backendapp
import (
"net/http/httptest"
"strings"
"testing"
"github.com/gin-gonic/gin"
"go.uber.org/zap"
"github.com/kandev/kandev/internal/common/logger"
)
func newE2EStartupPageFixtureRouter(t *testing.T) *gin.Engine {
t.Helper()
gin.SetMode(gin.TestMode)
log, err := logger.NewFromZap(zap.NewNop())
if err != nil {
t.Fatalf("logger.NewFromZap: %v", err)
}
router := gin.New()
registerE2EStartupPageFixtureRoute(router, log)
return router
}
func TestE2EStartupPageFixtureRendersRealTemplate(t *testing.T) {
t.Setenv("KANDEV_MOCK_AGENT", "only")
router := newE2EStartupPageFixtureRouter(t)
body := strings.NewReader(`{
"phase": "applying_migrations",
"boot": 1,
"seq": 1,
"elapsed_ms": 12000,
"phase_elapsed_ms": 12000,
"step": {
"id": "stores.repositories",
"label_key": "startup.step.stores_repositories",
"measure": "counted",
"unit": "stores",
"elapsed_ms": 12000,
"done": 400,
"total": 1000,
"eta_ms": 30000,
"stalled": false
}
}`)
req := httptest.NewRequest("POST", "/api/v1/e2e/startup-page-fixture", body)
req.Header.Set("Content-Type", "application/json")
resp := httptest.NewRecorder()
router.ServeHTTP(resp, req)
if resp.Code != 503 {
t.Fatalf("status = %d, want 503", resp.Code)
}
html := resp.Body.String()
if !strings.Contains(html, `id="startup-data"`) {
t.Fatalf("response does not contain the embedded poll script's data island: %s", html)
}
if !strings.Contains(html, "400 of 1000") {
t.Fatalf("response does not render the step's counted progress: %s", html)
}
}
func TestE2EStartupPageFixtureRejectsUnparseableBody(t *testing.T) {
t.Setenv("KANDEV_MOCK_AGENT", "only")
router := newE2EStartupPageFixtureRouter(t)
req := httptest.NewRequest("POST", "/api/v1/e2e/startup-page-fixture", strings.NewReader(`not json`))
req.Header.Set("Content-Type", "application/json")
resp := httptest.NewRecorder()
router.ServeHTTP(resp, req)
if resp.Code != 400 {
t.Fatalf("status = %d, want 400", resp.Code)
}
}
func TestE2EStartupPageFixtureRouteHiddenOutsideMockAgent(t *testing.T) {
t.Setenv("KANDEV_MOCK_AGENT", "")
router := newE2EStartupPageFixtureRouter(t)
req := httptest.NewRequest("POST", "/api/v1/e2e/startup-page-fixture", strings.NewReader(`{}`))
resp := httptest.NewRecorder()
router.ServeHTTP(resp, req)
if resp.Code != 404 {
t.Fatalf("status = %d, want 404 when KANDEV_MOCK_AGENT is unset", resp.Code)
}
}
@@ -11,6 +11,7 @@ import (
authhttpmw "github.com/kandev/kandev/internal/auth/httpmw"
"github.com/kandev/kandev/internal/persistence/requiredstores"
"github.com/kandev/kandev/internal/startup"
"github.com/kandev/kandev/internal/system/info"
)
@@ -113,11 +114,55 @@ func TestReadyHandlerBodyShapesByReadiness(t *testing.T) {
}
}
// TestReadyHandlerIncludesStartupSnapshot covers the AC-PLATFORM-STARTUP-
// PROGRESS-005 requirement that /ready carry the startup snapshot in both
// its starting 503 and its ready 200 bodies, never 404, whenever a
// *startup.Reporter is wired into routeParams.
func TestReadyHandlerIncludesStartupSnapshot(t *testing.T) {
gin.SetMode(gin.TestMode)
reporter := startup.New(testLogger(t))
reporter.Set(startup.RecoveringSessions)
setReadyForTest(t, false)
router := gin.New()
router.GET("/ready", readyHandler(routeParams{version: "1.2.3", progress: reporter}))
startingRec := httptest.NewRecorder()
router.ServeHTTP(startingRec, httptest.NewRequest(http.MethodGet, "/ready", nil))
var startingBody map[string]interface{}
if err := json.Unmarshal(startingRec.Body.Bytes(), &startingBody); err != nil {
t.Fatalf("decode starting body: %v", err)
}
startingSnap, ok := startingBody["startup"].(map[string]interface{})
if !ok {
t.Fatalf("starting body missing \"startup\" snapshot: %#v", startingBody)
}
if startingSnap["phase"] != string(startup.RecoveringSessions) {
t.Fatalf("starting startup.phase = %v, want %v", startingSnap["phase"], startup.RecoveringSessions)
}
setReadyForTest(t, true)
readyRec := httptest.NewRecorder()
router.ServeHTTP(readyRec, httptest.NewRequest(http.MethodGet, "/ready", nil))
var readyBody map[string]interface{}
if err := json.Unmarshal(readyRec.Body.Bytes(), &readyBody); err != nil {
t.Fatalf("decode ready body: %v", err)
}
readySnap, ok := readyBody["startup"].(map[string]interface{})
if !ok {
t.Fatalf("ready body missing \"startup\" snapshot: %#v", readyBody)
}
if readySnap["phase"] != string(startup.RecoveringSessions) {
t.Fatalf("ready startup.phase = %v, want %v", readySnap["phase"], startup.RecoveringSessions)
}
}
func TestReadyHandlerReportsPersistenceFailure(t *testing.T) {
gin.SetMode(gin.TestMode)
setReadyForTest(t, true)
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{{
ID: "task", OwnerPackage: "internal/task", RequiredTables: []string{"tasks"},
Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker: %v", err)
+18 -17
View File
@@ -84,6 +84,7 @@ import (
"github.com/kandev/kandev/internal/sentry"
spriteshandlers "github.com/kandev/kandev/internal/sprites"
sshhandlers "github.com/kandev/kandev/internal/ssh"
"github.com/kandev/kandev/internal/startup"
systemsvc "github.com/kandev/kandev/internal/system"
"github.com/kandev/kandev/internal/system/storage/tempartifacts"
taskdto "github.com/kandev/kandev/internal/task/dto"
@@ -729,6 +730,7 @@ type routeParams struct {
homeDir string
interimSettingsInterlockToken string
log *logger.Logger
progress *startup.Reporter
}
// registerRoutes sets up all HTTP and WebSocket routes on the given router.
@@ -1015,29 +1017,27 @@ func healthHandler(p routeParams) gin.HandlerFunc {
func readyHandler(p routeParams) gin.HandlerFunc {
version := resolveVersion(p)
return func(c *gin.Context) {
body := gin.H{
serviceFieldKey: kandevName,
versionFieldKey: version,
}
if p.progress != nil {
body["startup"] = p.progress.Snapshot()
}
if !ready.Load() {
c.JSON(http.StatusServiceUnavailable, gin.H{
statusKey: startingStatus,
serviceFieldKey: kandevName,
versionFieldKey: version,
})
body[statusKey] = startingStatus
c.JSON(http.StatusServiceUnavailable, body)
return
}
if p.persistenceHealth != nil && !p.persistenceHealth.Healthy() {
c.JSON(http.StatusServiceUnavailable, gin.H{
statusKey: startingStatus,
serviceFieldKey: kandevName,
versionFieldKey: version,
"reason": "persistence",
"store_ids": p.persistenceHealth.UnhealthyStoreIDs(),
})
body[statusKey] = startingStatus
body["reason"] = "persistence"
body["store_ids"] = p.persistenceHealth.UnhealthyStoreIDs()
c.JSON(http.StatusServiceUnavailable, body)
return
}
c.JSON(http.StatusOK, gin.H{
statusKey: "ok",
serviceFieldKey: kandevName,
versionFieldKey: version,
})
body[statusKey] = "ok"
c.JSON(http.StatusOK, body)
}
}
@@ -1598,6 +1598,7 @@ func registerSecondaryRoutes(
registerE2EResetRoutes(
p.router, p.taskRepo, p.taskSvc, automationSvc, p.services.GitHub, p.services.GitLab, p.eventBus, p.log,
)
registerE2EStartupPageFixtureRoute(p.router, p.log)
if officetestharness.Enabled() {
var officeAgentSvc *officeagents.AgentService
+16 -5
View File
@@ -13,6 +13,7 @@ import (
"github.com/kandev/kandev/internal/common/config"
"github.com/kandev/kandev/internal/common/logger"
"github.com/kandev/kandev/internal/startup"
"github.com/kandev/kandev/internal/webapp"
"go.uber.org/zap"
)
@@ -53,11 +54,16 @@ func (hs *handlerSwitch) ServeHTTP(w http.ResponseWriter, r *http.Request) {
// token header, if configured) so the launcher's liveness probe
// (internal/launcher/health.go) succeeds regardless of startup progress —
// making liveness depend on readiness here would bring back the crash loop
// this handler exists to fix. Every other path returns a deterministic 503
// with a parseable "starting" body instead of hanging, resetting, or 404ing.
// GET /health's body is identical to healthHandler's in helpers.go (status
// "ok", service, mode, version) since /health is a pure liveness probe and
// its shape must not depend on startup progress.
// this handler exists to fix. GET /health's body is identical to
// healthHandler's in helpers.go (status "ok", service, mode, version) since
// /health is a pure liveness probe and its shape must not depend on startup
// progress.
//
// A GET on an application route (per webapp.IsSPARoute, excluding /ready
// itself — see AC-PLATFORM-STARTUP-PROGRESS-003.3) whose Accept header
// prefers HTML gets the server-rendered startup page instead of the
// machine-readable body. Every other request gets a deterministic 503 with
// a parseable "starting" body instead of hanging, resetting, or 404ing.
func newBootstrapHandler(version string, reporters ...*startup.Reporter) http.Handler {
progress := startup.New(nil)
if len(reporters) > 0 {
@@ -65,6 +71,11 @@ func newBootstrapHandler(version string, reporters ...*startup.Reporter) http.Ha
}
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet || r.URL.Path != healthRoutePath {
if r.Method == http.MethodGet && r.URL.Path != readyRoutePath &&
webapp.IsSPARoute(r.URL.Path) && webapp.PrefersHTML(r.Header.Get("Accept")) {
writeStartupPage(w, r, progress.Snapshot())
return
}
body := map[string]any{
statusKey: startingStatus,
serviceFieldKey: kandevName,
@@ -22,7 +22,7 @@ func TestBuildHTTPServerAbortsWhenInterlockTokenGenerationFails(t *testing.T) {
newInterimSettingsInterlockToken = func() (string, error) { return "", wantErr }
t.Cleanup(func() { newInterimSettingsInterlockToken = original })
server, err := buildHTTPServer(&config.Config{}, testLogger(t), nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
server, err := buildHTTPServer(&config.Config{}, testLogger(t), nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil)
if !errors.Is(err, wantErr) {
t.Fatalf("buildHTTPServer error = %v, want %v", err, wantErr)
}
+47 -15
View File
@@ -138,6 +138,7 @@ import (
// System pages (status / database / backups / logs / updates / about)
systemsvc "github.com/kandev/kandev/internal/system"
"github.com/kandev/kandev/internal/system/sessioncapacity"
storagepkg "github.com/kandev/kandev/internal/system/storage"
"github.com/kandev/kandev/internal/system/storage/tempartifacts"
// Database
@@ -716,7 +717,7 @@ func startAgentInfrastructure(
log.Info("Initializing Orchestrator...")
sessionCapacityEnvironment := sessioncapacity.ReadEnvironment()
orchestratorSvc, msgCreator, err := provideOrchestrator(cfg, log, dbPool, eventBus, repos.Task, services.Task, services.User,
orchestratorSvc, msgCreator, err := provideOrchestrator(ctx, cfg, log, dbPool, eventBus, repos.Task, services.Task, services.User,
lifecycleMgr, agentRegistry, services.Workflow, userSecretStore, repoCloner, services.Prompts, services.GitHub, services.GitCredentials,
repos.SystemSettings, sessionCapacityEnvironment, repos.RequiredStores)
if err != nil {
@@ -892,7 +893,7 @@ func startAgentInfrastructure(
// the ledger's foreign keys require them present at CREATE TABLE time
// on PostgreSQL. services.Task satisfies delivery.CheckoutResolver.
_, deliveryCleanup, deliveryErr := delivery.Provide(dbPool.Writer(), dbPool.Reader(), services.Task, log)
if recordErr := recordRequiredStore(repos.RequiredStores, "delivery", deliveryErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, repos.RequiredStores, "delivery", deliveryErr); recordErr != nil {
log.Error("delivery ledger initialization failed", zap.Error(recordErr))
return false
}
@@ -908,6 +909,27 @@ func startAgentInfrastructure(
// in-memory bus while Service.Start is still doing its startup reconciliation.
// Service.Start calls Watcher.Start again; the watcher is idempotent and keeps
// these subscriptions.
//
// storage is stores.services's last admission chronologically, so it has
// to happen here, immediately before the phase transition and
// lifecycleMgr.Start below (which is what actually runs
// sessions.recovery's BeginStep/Advance/EndStep sequence): its old
// position deep inside startGatewayAndServe ran chronologically after
// sessions.recovery had already begun, so BeginStep force-closed
// stores.services early and every admission after that point --
// including storage's own -- silently no-op'd.
storageStore, err := provideStorageStore(ctx, dbPool, repos.RequiredStores)
if err != nil {
log.Error("Failed to initialize storage store", zap.Error(err))
return false
}
// The phase transition must happen here, immediately before
// lifecycleMgr.Start below (which is what actually runs
// sessions.recovery's BeginStep/Advance/EndStep sequence) rather than
// later at HTTP listener bind time in startGatewayAndServe: that point
// runs well after this recovery work has already completed.
startup.SetPhase(ctx, startup.RecoveringSessions)
if err := orchestratorSvc.StartEventWatcher(ctx); err != nil {
log.Error("Failed to start orchestrator event watcher for agent recovery", zap.Error(err))
return false
@@ -920,7 +942,7 @@ func startAgentInfrastructure(
return startGatewayAndServe(ctx, cfg, log, eventBus, agentRuntimeAvailability, dbPool, repos, services,
agentSettingsController, lifecycleMgr, agentRegistry, orchestratorSvc, msgCreator, repoCloner, agentctlBinaryPath,
sessionCapacityEnvironment, func(fn func() error) { addRuntimeCleanup(fn) }, runCleanups, cancelWorkers,
sessionCapacityEnvironment, storageStore, func(fn func() error) { addRuntimeCleanup(fn) }, runCleanups, cancelWorkers,
restoreCleanups, databaseQuiesce)
}
@@ -985,6 +1007,7 @@ func startGatewayAndServe(
repoCloner *repoclone.Cloner,
agentctlBinaryPath string,
sessionCapacityEnvironment sessioncapacity.Environment,
storageStore *storagepkg.Store,
addCleanup func(func() error),
runCleanups func(),
cancelWorkers context.CancelFunc,
@@ -1073,7 +1096,7 @@ func startGatewayAndServe(
bootstrap := ctx.Value(bootstrapContextKey{}).(*bootstrapRuntime)
handler, server, listeners := bootstrap.handler, bootstrap.server, bootstrap.listeners
bindListeners := func() error { startup.SetPhase(ctx, startup.RecoveringSessions); return ctx.Err() }
bindListeners := func() error { return ctx.Err() }
if err := startOrchestratorAndAutomationConsumers(
bindListeners,
@@ -1219,7 +1242,7 @@ func startGatewayAndServe(
cfg, dbPool, systemSvc.Jobs, eventBus, lifecycleMgr, services.WorktreeMgr, services.Task,
log,
func(message string, err error) { log.Error(message, zap.Error(err)) },
repos.RequiredStores, repos.SystemSettings,
storageStore, repos.SystemSettings,
)
if err != nil {
log.Error("Failed to initialize storage maintenance", zap.Error(err))
@@ -1326,7 +1349,7 @@ func startGatewayAndServe(
builtServer, err := buildHTTPServer(cfg, log, gateway, repos, services, agentSettingsController,
lifecycleMgr, eventBus, orchestratorSvc, notificationCtrl, msgCreator, agentRegistry, hostUtilityMgr,
addCleanup, repoCloner, systemSvc, storageComposition.workspaceRestorer,
storageComposition.tempArtifacts, dbPool, agentRuntimeAvailability, persistenceHealth)
storageComposition.tempArtifacts, dbPool, agentRuntimeAvailability, startup.FromContext(ctx), persistenceHealth)
if err != nil {
log.Error("Failed to build HTTP server", zap.Error(err))
closeBoundListeners(server, listeners, log)
@@ -1352,23 +1375,30 @@ func startGatewayAndServe(
return false
}
// Flip readiness before swapping in the fully wired router — see
// publishReadiness for why the order matters and
// TestPublishReadinessFlipsReadyBeforeSwappingHandler for the regression
// test pinning it.
if !bootstrap.beginReadinessPublication(ctx) {
return false
}
publishReadiness(func() {
ready.Store(true)
bootstrap.ready.Store(true)
}, func() { handler.Store(builtServer.Handler) })
startup.SetPhase(ctx, startup.Ready)
markStartupReady(func() { startup.SetPhase(ctx, startup.Ready) }, func() {
publishReadiness(func() {
ready.Store(true)
bootstrap.ready.Store(true)
}, func() { handler.Store(builtServer.Handler) })
})
awaitShutdown(ctx, server, listeners, scheduling, orchestratorSvc, lifecycleMgr, runCleanups, log)
return true
}
// markStartupReady transitions the startup phase to Ready and then publishes
// readiness, in that order — never the reverse. A GET /ready request racing
// the two must never observe a successful status against a snapshot that
// still reports an earlier phase (AC-PLATFORM-STARTUP-PROGRESS-002.3).
func markStartupReady(setPhaseReady func(), publish func()) {
setPhaseReady()
publish()
}
// publishReadiness flips readiness and then swaps in the fully wired router,
// in that order — never the reverse. A request landing between the two must
// never observe the real router while ready is still false: readyHandler
@@ -2568,6 +2598,7 @@ func buildHTTPServer(
temporaryArtifacts *tempartifacts.Registry,
dbPool *db.Pool,
agentRuntimeAvailability *agentctlclient.Availability,
progress *startup.Reporter,
persistenceHealth ...*requiredstores.Health,
) (*http.Server, error) {
gin.SetMode(gin.ReleaseMode)
@@ -2699,6 +2730,7 @@ func buildHTTPServer(
homeDir: cfg.ResolvedHomeDir(),
interimSettingsInterlockToken: interimSettingsInterlockToken,
log: log,
progress: progress,
})
// Addr is intentionally left unset: bind addresses are resolved from
@@ -58,6 +58,7 @@ const (
const defaultEventNamespace = "default"
func provideOrchestrator(
ctx context.Context,
cfg *config.Config,
log *logger.Logger,
pool *db.Pool,
@@ -116,7 +117,7 @@ func provideOrchestrator(
queueRepo, err := messagequeue.NewSQLiteRepository(pool.Writer(), pool.Reader())
if len(trackers) > 0 && trackers[0] != nil {
if recordErr := recordRequiredStore(trackers[0], "message-queue", err); recordErr != nil {
if recordErr := recordRequiredStore(ctx, trackers[0], "message-queue", err); recordErr != nil {
return nil, nil, fmt.Errorf("message queue store: %w", recordErr)
}
}
@@ -1221,10 +1222,6 @@ func (a *repositoryResolverAdapter) persistDetectedDefaultBranch(
// later write succeeds — and this call site retries with the same
// detected value on every future invocation, so a rejection driven by
// validation (as opposed to a transient DB error) will repeat forever.
// Review round 3, finding #4: this used to log at Warn and nothing
// else, making that permanent degradation invisible. Error level plus
// the dedicated counter make it observable the same way ancestry/write
// failures already are in internal/delivery/metrics.go.
if _, err := a.taskSvc.UpdateRepository(ctx, repo.ID, &taskservice.UpdateRepositoryRequest{
DefaultBranch: &detected,
}); err != nil {
@@ -21,6 +21,7 @@ import (
"github.com/kandev/kandev/internal/common/logger"
"github.com/kandev/kandev/internal/db"
"github.com/kandev/kandev/internal/persistence/requiredstores"
"github.com/kandev/kandev/internal/startup"
"github.com/kandev/kandev/internal/system/maintenance"
userstore "github.com/kandev/kandev/internal/user/store"
)
@@ -40,6 +41,7 @@ func TestPersistenceMiddlewareRemainsAvailableDuringManagedMaintenance(t *testin
pool := db.NewPool(conn, conn)
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{{
ID: "task", OwnerPackage: "internal/task", RequiredTables: []string{"tasks"},
Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker: %v", err)
@@ -98,6 +100,7 @@ func TestRequiredPersistenceMiddlewareBlocksStatefulTrafficButAllowsDiagnostics(
gin.SetMode(gin.TestMode)
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{{
ID: "task", OwnerPackage: "internal/task", RequiredTables: []string{"tasks"},
Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker: %v", err)
@@ -150,6 +153,7 @@ func TestRequiredPersistenceMiddlewareRunsBeforeAuthentication(t *testing.T) {
gin.SetMode(gin.TestMode)
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{{
ID: "task", OwnerPackage: "internal/task", RequiredTables: []string{"tasks"},
Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker: %v", err)
@@ -217,6 +221,7 @@ func TestRequiredPersistenceMiddlewarePrecedesDatabaseBackedAuthentication(t *te
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{{
ID: "task", OwnerPackage: "internal/task", RequiredTables: []string{"tasks"},
Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker: %v", err)
@@ -12,6 +12,7 @@ import (
"github.com/kandev/kandev/internal/events/bus"
"github.com/kandev/kandev/internal/persistence/requiredstores"
"github.com/kandev/kandev/internal/secrets"
"github.com/kandev/kandev/internal/startup"
)
// TestProvideServicesWiresPluginsKandevVersion pins the production wiring of
@@ -50,12 +51,13 @@ func TestRequiredStoreBootstrapCompleteness(t *testing.T) {
func TestRequiredStoreFailure(t *testing.T) {
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{{
ID: "task", OwnerPackage: "internal/task", RequiredTables: []string{"tasks"},
Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker: %v", err)
}
constructorErr := errors.New("schema constructor failed")
got := recordRequiredStore(tracker, "task", constructorErr)
got := recordRequiredStore(context.Background(), tracker, "task", constructorErr)
if !errors.Is(got, constructorErr) {
t.Fatalf("recordRequiredStore() error = %v, want %v", got, constructorErr)
}
+31 -25
View File
@@ -95,7 +95,7 @@ func provideServices(ctx context.Context, cfg *config.Config, log *logger.Logger
agentSettingsController.SetSecretStore(userSecretStore)
agentSettingsController.SetManagedRuntimeSelectionStore(managedRuntimeSelections)
core, err := initCoreTaskServices(cfg, repos, dbPool, eventBus, agentRegistry, storeTracker, log)
core, err := initCoreTaskServices(ctx, cfg, repos, dbPool, eventBus, agentRegistry, storeTracker, log)
if err != nil {
return nil, nil, err
}
@@ -103,7 +103,7 @@ func provideServices(ctx context.Context, cfg *config.Config, log *logger.Logger
wireTaskWorkflowCrossReferences(taskSvc, workflowSvc, userSecretStore, repos, log)
providers, err := initThirdPartyProviders(cfg, dbPool, eventBus, repos, storeTracker, taskSvc, promptSvc, workflowSvc, log)
providers, err := initThirdPartyProviders(ctx, cfg, dbPool, eventBus, repos, storeTracker, taskSvc, promptSvc, workflowSvc, log)
if err != nil {
return nil, nil, err
}
@@ -193,6 +193,7 @@ type coreTaskServices struct {
}
func initCoreTaskServices(
ctx context.Context,
cfg *config.Config,
repos *Repositories,
dbPool *db.Pool,
@@ -212,13 +213,13 @@ func initCoreTaskServices(
_, ok := agentRegistry.GetInferenceAgent(agentID)
return ok
}))
dynamicResolver, dynamicBindingResolver, err := initDynamicRuntimeResolver(context.Background(), repos, cfg, log)
dynamicResolver, dynamicBindingResolver, err := initDynamicRuntimeResolver(ctx, repos, cfg, log)
if err != nil {
return nil, err
}
utilitySvc.SetExecutionProfileResolver(dynamicResolver)
workflowSvc := workflowservice.NewService(repos.Workflow, log)
pendingActionProjectionEpoch, err := repos.Task.NextPendingActionProjectionEpoch(context.Background())
pendingActionProjectionEpoch, err := repos.Task.NextPendingActionProjectionEpoch(ctx)
if err != nil {
return nil, fmt.Errorf("allocate pending-action projection epoch: %w", err)
}
@@ -269,7 +270,7 @@ func initCoreTaskServices(
// Workspace membership needs to resolve colleague names and reject
// disabled or unknown accounts before writing a row.
taskSvc.SetUserDirectory(newUserDirectoryAdapter(repos.UserAccounts))
orgSvc, unitSvc, err := initOrgAndUnitServices(cfg, dbPool, repos, storeTracker, taskSvc, log)
orgSvc, unitSvc, err := initOrgAndUnitServices(ctx, cfg, dbPool, repos, storeTracker, taskSvc, log)
if err != nil {
return nil, err
}
@@ -356,6 +357,7 @@ func initDynamicRuntimeResolver(
// services, runs the one-time tenancy migration that creates the default
// organization, and wires the unit tree back into the task and org services.
func initOrgAndUnitServices(
ctx context.Context,
cfg *config.Config,
dbPool *db.Pool,
repos *Repositories,
@@ -367,19 +369,19 @@ func initOrgAndUnitServices(
// company name to borrow, and an operator renames it in one click.
const defaultOrgName = "Default organization"
orgSvc, orgErr := buildOrgService(cfg, dbPool, repos, taskSvc, log)
if recordErr := recordRequiredStore(storeTracker, "organizations", orgErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "organizations", orgErr); recordErr != nil {
return nil, nil, fmt.Errorf("initialize organizations: %w", recordErr)
}
// The tenancy migration runs once at boot: it creates the default
// organization and puts every pre-tenancy user and workspace into it.
if _, err := orgSvc.EnsureDefaultOrg(context.Background(), defaultOrgName); err != nil {
if _, err := orgSvc.EnsureDefaultOrg(ctx, defaultOrgName); err != nil {
return nil, nil, fmt.Errorf("organization migration: %w", err)
}
// The unit tree is built after the tenancy migration, which is what stamps
// organization ids: placing a workspace before it knows its organization
// would put it under the wrong root.
unitSvc, unitErr := buildOrgUnitService(dbPool, repos.Task, repos.UserAccounts, log)
if recordErr := recordRequiredStore(storeTracker, "organization-units", unitErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "organization-units", unitErr); recordErr != nil {
return nil, nil, fmt.Errorf("initialize organization units: %w", recordErr)
}
taskSvc.SetUnitPlacer(unitSvc)
@@ -429,17 +431,17 @@ func initIntegrationWiring(
_ = pluginsCleanup()
}
}()
canvasSvc, canvasDistributionSvc, err := initCanvasWiring(cfg, dbPool, eventBus, storeTracker, taskSvc, pluginsSvc, version, log)
canvasSvc, canvasDistributionSvc, err := initCanvasWiring(ctx, cfg, dbPool, eventBus, storeTracker, taskSvc, pluginsSvc, version, log)
if err != nil {
return nil, err
}
gitCredentialBroker, shareHTTP, err := initGitCredentialAndRemoteWiring(
cfg, dbPool, repos, storeTracker, taskSvc, githubSvc, pluginsSvc, version, log,
ctx, cfg, dbPool, repos, storeTracker, taskSvc, githubSvc, pluginsSvc, version, log,
)
if err != nil {
return nil, err
}
automationComponents, err := initAutomationWiring(dbPool, eventBus, githubSvc, storeTracker, taskSvc, workflowSvc, repos, log)
automationComponents, err := initAutomationWiring(ctx, dbPool, eventBus, githubSvc, storeTracker, taskSvc, workflowSvc, repos, log)
if err != nil {
return nil, err
}
@@ -525,6 +527,7 @@ type thirdPartyProviders struct {
}
func initThirdPartyProviders(
ctx context.Context,
cfg *config.Config,
dbPool *db.Pool,
eventBus bus.EventBus,
@@ -536,7 +539,7 @@ func initThirdPartyProviders(
log *logger.Logger,
) (*thirdPartyProviders, error) {
githubSvc, _, githubErr := initGitHubServiceRequired(cfg, dbPool, eventBus, repos.Secrets, log)
if recordErr := recordRequiredStore(storeTracker, "github", githubErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "github", githubErr); recordErr != nil {
return nil, fmt.Errorf("initialize github: %w", recordErr)
}
if githubSvc != nil {
@@ -549,7 +552,7 @@ func initThirdPartyProviders(
}
}
gitlabSvc, gitlabCleanup, gitlabErr := initGitLabServiceRequiredWithSettings(repos.SystemSettings, dbPool, eventBus, repos.Secrets, log)
if recordErr := recordRequiredStore(storeTracker, "gitlab", gitlabErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "gitlab", gitlabErr); recordErr != nil {
return nil, fmt.Errorf("initialize gitlab: %w", recordErr)
}
if gitlabSvc != nil {
@@ -557,7 +560,7 @@ func initThirdPartyProviders(
gitlabSvc.SetComparisonTargetObserver(taskSvc)
}
azureDevOpsSvc, _, azureDevOpsErr := initAzureDevOpsServiceRequired(dbPool, eventBus, repos.Secrets, log)
if recordErr := recordRequiredStore(storeTracker, "azure-devops", azureDevOpsErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "azure-devops", azureDevOpsErr); recordErr != nil {
return nil, fmt.Errorf("initialize azure devops: %w", recordErr)
}
if azureDevOpsSvc != nil {
@@ -565,19 +568,19 @@ func initThirdPartyProviders(
azureDevOpsSvc.SetWorkspaceAuthorizer(taskSvc.AuthorizeWorkspaceAccess)
}
jiraSvc, _, jiraErr := initJiraServiceRequired(dbPool, eventBus, repos.Secrets, log)
if recordErr := recordRequiredStore(storeTracker, "jira", jiraErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "jira", jiraErr); recordErr != nil {
return nil, fmt.Errorf("initialize jira: %w", recordErr)
}
linearSvc, _, linearErr := initLinearServiceRequired(dbPool, eventBus, repos.Secrets, log)
if recordErr := recordRequiredStore(storeTracker, "linear", linearErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "linear", linearErr); recordErr != nil {
return nil, fmt.Errorf("initialize linear: %w", recordErr)
}
sentrySvc, _, sentryErr := initSentryServiceRequired(dbPool, eventBus, repos.Secrets, log)
if recordErr := recordRequiredStore(storeTracker, "sentry", sentryErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "sentry", sentryErr); recordErr != nil {
return nil, fmt.Errorf("initialize sentry: %w", recordErr)
}
workflowSyncSvc, _, workflowSyncErr := initWorkflowSyncServiceRequired(dbPool, githubSvc, gitlabSvc, workflowSvc, taskSvc, log)
if recordErr := recordRequiredStore(storeTracker, "workflow-sync", workflowSyncErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "workflow-sync", workflowSyncErr); recordErr != nil {
return nil, fmt.Errorf("initialize workflow sync: %w", recordErr)
}
return &thirdPartyProviders{
@@ -605,7 +608,7 @@ func initPluginsWiring(
log *logger.Logger,
) (*plugins.Service, func() error, *taskservice.AgentConversationService, error) {
pluginsSvc, pluginsCleanup, pluginStoreErrors := initPluginsServiceRequired(ctx, cfg, dbPool, eventBus, repos.Secrets, log)
if recordErr := recordPluginStores(storeTracker, pluginStoreErrors); recordErr != nil {
if recordErr := recordPluginStores(ctx, storeTracker, pluginStoreErrors); recordErr != nil {
if pluginsCleanup != nil {
_ = pluginsCleanup()
}
@@ -642,6 +645,7 @@ func initPluginsWiring(
// initCanvasWiring constructs the canvas service and, when the canvases
// feature is enabled, the canvas distribution service that depends on it.
func initCanvasWiring(
ctx context.Context,
cfg *config.Config,
dbPool *db.Pool,
eventBus bus.EventBus,
@@ -652,7 +656,7 @@ func initCanvasWiring(
log *logger.Logger,
) (*canvasservice.Service, *canvasservice.DistributionService, error) {
canvasRepo, canvasErr := canvasservice.NewRepository(dbPool)
if recordErr := recordRequiredStore(storeTracker, "canvas", canvasErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "canvas", canvasErr); recordErr != nil {
return nil, nil, fmt.Errorf("initialize canvas: %w", recordErr)
}
canvasSvc, err := initCanvasServiceWithRepository(cfg.Features.Canvases, canvasRepo, eventBus, pluginsSvc, taskSvc, log)
@@ -685,6 +689,7 @@ func initCanvasWiring(
// initAutomationWiring constructs the automation service stack and wires its
// cross-service lookups back into the task and workflow services.
func initAutomationWiring(
ctx context.Context,
dbPool *db.Pool,
eventBus bus.EventBus,
githubSvc *github.Service,
@@ -695,7 +700,7 @@ func initAutomationWiring(
log *logger.Logger,
) (*automation.Components, error) {
automationComponents, automationErr := automation.Provide(dbPool.Writer(), dbPool.Reader(), eventBus, githubSvc, log)
if recordErr := recordRequiredStore(storeTracker, "automation", automationErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "automation", automationErr); recordErr != nil {
return nil, fmt.Errorf("initialize automation: %w", recordErr)
}
if automationComponents == nil {
@@ -733,6 +738,7 @@ func initAutomationWiring(
// and task-share HTTP handlers, then wires code-host branch listing, PR
// resolution, and fresh-workspace defaults into the task service.
func initGitCredentialAndRemoteWiring(
ctx context.Context,
cfg *config.Config,
dbPool *db.Pool,
repos *Repositories,
@@ -751,11 +757,11 @@ func initGitCredentialAndRemoteWiring(
githubSvc.SetCredentialBroker(github.NewCredentialBrokerFromBroker(gitCredentialBroker))
}
shareHTTP, _, shareErr := initShareHandlersRequired(dbPool, repos.Task, taskSvc, githubSvc, log, version)
if recordErr := recordRequiredStore(storeTracker, "task-share", shareErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "task-share", shareErr); recordErr != nil {
return nil, nil, fmt.Errorf("initialize task share: %w", recordErr)
}
_, officeConfigErr := officeconfigsync.NewStore(dbPool.Writer(), dbPool.Reader())
if recordErr := recordRequiredStore(storeTracker, "office-config-sync", officeConfigErr); recordErr != nil {
if recordErr := recordRequiredStore(ctx, storeTracker, "office-config-sync", officeConfigErr); recordErr != nil {
return nil, nil, fmt.Errorf("initialize office config sync: %w", recordErr)
}
@@ -1725,7 +1731,7 @@ func initPluginsServiceRequired(
return plugins.ProvideWithStoreErrors(cfg, dbPool, secretadapter.New(secretsStore), eventBus, log)
}
func recordPluginStores(tracker *requiredstores.Tracker, initErrors plugins.StoreInitErrors) error {
func recordPluginStores(ctx context.Context, tracker *requiredstores.Tracker, initErrors plugins.StoreInitErrors) error {
var failures []error
for _, id := range []string{
"plugin-instances",
@@ -1735,7 +1741,7 @@ func recordPluginStores(tracker *requiredstores.Tracker, initErrors plugins.Stor
"plugin-instance-state",
"plugin-user-state",
} {
if err := recordRequiredStore(tracker, id, initErrors[id]); err != nil {
if err := recordRequiredStore(ctx, tracker, id, initErrors[id]); err != nil {
failures = append(failures, err)
}
}
@@ -95,6 +95,25 @@ func TestPublishReadinessFlipsReadyBeforeSwappingHandler(t *testing.T) {
}
}
// TestMarkStartupReadySetsPhaseBeforePublishingReadiness is the regression
// test for AC-PLATFORM-STARTUP-PROGRESS-002.3: a GET /ready request racing
// startGatewayAndServe's completion must never observe a successful status
// against a snapshot that still reports an earlier phase, so the phase must
// reach Ready before the readiness flag flips, never the reverse.
func TestMarkStartupReadySetsPhaseBeforePublishingReadiness(t *testing.T) {
var order []string
markStartupReady(
func() { order = append(order, "phase") },
func() { order = append(order, "publish") },
)
want := []string{"phase", "publish"}
if !reflect.DeepEqual(order, want) {
t.Fatalf("markStartupReady order = %v, want %v", order, want)
}
}
func TestShouldLogStartupOrchestratorErrorSkipsExpectedShutdownErrors(t *testing.T) {
for _, test := range []struct {
name string
@@ -0,0 +1,464 @@
package backendapp
import (
"bytes"
"encoding/json"
"fmt"
"html/template"
"net/http"
"strings"
"github.com/kandev/kandev/internal/i18n"
"github.com/kandev/kandev/internal/startup"
)
// writeStartupPage renders the self-contained HTML startup page
// (AC-PLATFORM-STARTUP-PROGRESS-003.1) directly from the in-process
// reporter snapshot. It embeds no bundle: markup, styling, and the polling
// script that keeps the page live all live in startupPageTemplate. The
// caller (newBootstrapHandler) has already decided the request qualifies
// per AC-003.3.
func writeStartupPage(w http.ResponseWriter, r *http.Request, snap startup.Snapshot) {
locale := i18n.FromRequest(r)
view := buildStartupPageView(locale, snap)
var buf bytes.Buffer
if err := startupPageTemplate.Execute(&buf, view); err != nil {
writeBootstrapJSON(w, http.StatusServiceUnavailable, map[string]any{
statusKey: startingStatus,
serviceFieldKey: kandevName,
})
return
}
// AC-PLATFORM-STARTUP-PROGRESS-003.12: no-store so no intermediary keeps
// serving this page after startup completes. Status stays 503 throughout,
// matching every other bootstrap-handler branch.
w.Header().Set("Content-Type", "text/html; charset=utf-8")
w.Header().Set("Cache-Control", "no-store")
w.WriteHeader(http.StatusServiceUnavailable)
_, _ = w.Write(buf.Bytes())
}
// startupStepView is the rendered form of one StepSnapshot, resolved for a
// single locale so the template stays free of measure-branching logic.
type startupStepView struct {
Label string
Progress string
ETA string
HasETA bool
HasBar bool
PercentDoneStr string
Stalled bool
StalledText string
}
// startupPageView is the html/template data for startupPageTemplate.
type startupPageView struct {
Locale string
Title string
PhaseLabel string
Elapsed string
HasStep bool
Step startupStepView
DataJSON template.JS
}
func buildStartupPageView(locale string, snap startup.Snapshot) startupPageView {
view := startupPageView{
Locale: locale,
Title: i18n.T(locale, "startup.page.title"),
PhaseLabel: i18n.T(locale, "startup.phase."+string(snap.Phase)),
Elapsed: formatElapsed(locale, snap.ElapsedMS),
}
if snap.Step != nil {
view.HasStep = true
view.Step = buildStepView(locale, snap.Step)
}
view.DataJSON = marshalStartupData(locale, snap)
return view
}
func buildStepView(locale string, step *startup.StepSnapshot) startupStepView {
view := startupStepView{Label: i18n.T(locale, step.LabelKey)}
switch step.Measure {
case startup.MeasureOpaque:
view.Progress = i18n.T(locale, "startup.page.progressUnavailable")
case startup.MeasureCounting:
view.Progress = countingProgressText(locale, step)
case startup.MeasureCounted:
applyCountedProgress(locale, step, &view)
}
if step.Stalled && step.SinceAdvanceMS != nil {
view.Stalled = true
view.StalledText = i18n.Tf(locale, "startup.page.stalled", map[string]any{tfVarDuration: formatDuration(locale, *step.SinceAdvanceMS)})
}
return view
}
// Tf variable names, factored out because the i18n placeholder names
// ("{{count}}", "{{total}}", ...) that the catalog strings interpolate
// against must match these literals exactly.
const (
tfVarCount = "count"
tfVarTotal = "total"
tfVarDone = "done"
tfVarUnit = "unit"
tfVarDuration = "duration"
)
func countingProgressText(locale string, step *startup.StepSnapshot) string {
done := stepDone(step)
unit := i18n.Tf(locale, "startup.unit."+string(step.Unit), map[string]any{tfVarCount: done})
return i18n.Tf(locale, "startup.page.countingProgress", map[string]any{tfVarDone: done, tfVarUnit: unit})
}
func applyCountedProgress(locale string, step *startup.StepSnapshot, view *startupStepView) {
done, total := stepDone(step), stepTotal(step)
unit := i18n.Tf(locale, "startup.unit."+string(step.Unit), map[string]any{tfVarCount: total})
view.Progress = i18n.Tf(locale, "startup.page.countedProgress", map[string]any{
tfVarDone: done, tfVarTotal: total, tfVarUnit: unit,
})
if total > 0 {
view.HasBar = true
view.PercentDoneStr = fmt.Sprintf("%.2f", percentDone(done, total))
}
if step.ETAMS != nil {
view.HasETA = true
view.ETA = i18n.Tf(locale, "startup.page.eta", map[string]any{tfVarDuration: formatDuration(locale, *step.ETAMS)})
}
}
func stepDone(step *startup.StepSnapshot) int64 {
if step.Done == nil {
return 0
}
return *step.Done
}
func stepTotal(step *startup.StepSnapshot) int64 {
if step.Total == nil {
return 0
}
return *step.Total
}
func percentDone(done, total int64) float64 {
pct := float64(done) / float64(total) * 100
switch {
case pct < 0:
return 0
case pct > 100:
return 100
default:
return pct
}
}
// formatDuration mirrors startup.EstimateComponents's rounding rule
// (AC-PLATFORM-STARTUP-PROGRESS-003.10): whole seconds rounded up with a
// floor of one second at or below 60000 ms, whole minutes rounded up above
// that. The embedded poll script (startupPageScript) re-implements the same
// rule in JavaScript for subsequent reads, since the page has no bundle to
// share Go code with.
func formatDuration(locale string, ms int64) string {
value, minutes := startup.EstimateComponents(ms)
key := "startup.duration.seconds"
if minutes {
key = "startup.duration.minutes"
}
return i18n.Tf(locale, key, map[string]any{tfVarCount: value})
}
func formatElapsed(locale string, ms int64) string {
return i18n.Tf(locale, "startup.page.elapsed", map[string]any{tfVarDuration: formatDuration(locale, ms)})
}
// startupPageKeys lists every catalog key the page's initial render or its
// client-side re-poll can need. Keeping it explicit (rather than embedding
// the whole catalog) means the translations island carries only what this
// page uses.
func startupPageKeys() []string {
keys := []string{
"startup.page.title", "startup.page.waiting", "startup.page.lastKnown",
"startup.page.progressUnavailable", "startup.page.countedProgress",
"startup.page.countingProgress", "startup.page.elapsed", "startup.page.eta",
"startup.page.stalled",
"startup.phase.opening_database", "startup.phase.backing_up_database",
"startup.phase.applying_migrations", "startup.phase.initializing_services",
"startup.phase.recovering_sessions", "startup.phase.ready",
"startup.duration.seconds_one", "startup.duration.seconds_other",
"startup.duration.minutes_one", "startup.duration.minutes_other",
}
for _, unit := range []startup.Unit{
startup.UnitRows, startup.UnitMessages, startup.UnitTurns,
startup.UnitSessions, startup.UnitBytes, startup.UnitStores,
} {
keys = append(keys, "startup.unit."+string(unit)+"_one", "startup.unit."+string(unit)+"_other")
}
for _, spec := range startup.Registry() {
keys = append(keys, spec.LabelKey)
}
return keys
}
func translationsFor(locale string) map[string]string {
out := make(map[string]string, len(startupPageKeys()))
for _, key := range startupPageKeys() {
out[key] = i18n.T(locale, key)
}
return out
}
// marshalStartupData embeds the resolved translations plus the initial
// snapshot as a JSON island the poll script reads on load, so every
// subsequent /ready read can be rendered client-side without another
// server round trip for markup. The "</" escape defends against a
// catalog string that could otherwise prematurely close the script tag.
func marshalStartupData(locale string, snap startup.Snapshot) template.JS {
payload := map[string]any{
"translations": translationsFor(locale),
"snapshot": snap,
}
encoded, err := json.Marshal(payload)
if err != nil {
encoded = []byte(`{"translations":{},"snapshot":null}`)
}
return template.JS(strings.ReplaceAll(string(encoded), "</", "<\\/")) //nolint:gosec // JSON-only, no HTML
}
var startupPageTemplate = template.Must(template.New("startup-page").Parse(startupPageTemplateSource))
const startupPageTemplateSource = `<!DOCTYPE html>
<html lang="{{.Locale}}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="robots" content="noindex">
<title>{{.Title}}</title>
<style>
:root { color-scheme: light dark; }
body {
font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
display: flex; align-items: center; justify-content: center;
min-height: 100vh; margin: 0; padding: 1.5rem; box-sizing: border-box;
background: Canvas; color: CanvasText;
}
main { max-width: 26rem; width: 100%; text-align: center; }
h1 { font-size: 1.05rem; font-weight: 600; margin: 0 0 1rem; }
p { margin: 0.35rem 0; opacity: 0.85; }
.bar { height: 6px; border-radius: 3px; background: color-mix(in srgb, CanvasText 15%, transparent); overflow: hidden; margin-top: 1rem; }
.bar > span { display: block; height: 100%; background: #6c9eff; transition: width 300ms ease; }
@media (prefers-reduced-motion: reduce) { .bar > span { transition: none; } }
.last-known { font-size: 0.8rem; opacity: 0.6; margin-top: 0.5rem; }
.hidden { display: none; }
</style>
</head>
<body>
<main>
<h1>{{.Title}}</h1>
<div id="startup-status" role="status" aria-live="polite">
<p id="startup-phase">{{.PhaseLabel}}</p>
<p id="startup-elapsed">{{.Elapsed}}</p>
<p id="startup-step-label" class="{{if not .HasStep}}hidden{{end}}">{{.Step.Label}}</p>
<p id="startup-progress" class="{{if not .HasStep}}hidden{{end}}">{{.Step.Progress}}</p>
<p id="startup-eta" class="{{if not .Step.HasETA}}hidden{{end}}">{{.Step.ETA}}</p>
<div id="startup-bar" class="bar {{if not .Step.HasBar}}hidden{{end}}"><span id="startup-bar-fill" style="width:{{.Step.PercentDoneStr}}%"></span></div>
<p id="startup-stalled" class="{{if not .Step.Stalled}}hidden{{end}}">{{.Step.StalledText}}</p>
<p id="startup-last-known" class="last-known hidden"></p>
</div>
</main>
<script id="startup-data" type="application/json">{{.DataJSON}}</script>
<script>` + startupPageScript + `</script>
</body>
</html>
`
// startupPageScript keeps the page live after the initial server render.
// It polls /ready on the AC-PLATFORM-STARTUP-PROGRESS-003.2 cadence — one
// request in flight, abandoned after 5000 ms, any tick skipped while one is
// outstanding — and never gives up while the page is open. It reloads once
// the polled snapshot itself reports the ready phase (not merely a
// successful HTTP status, since AC-PLATFORM-STARTUP-PROGRESS-002.3 allows a
// post-startup degraded response that still carries a ready snapshot).
const startupPageScript = `
(function () {
"use strict";
var POLL_MS = 1000;
var TIMEOUT_MS = 5000;
var dataEl = document.getElementById("startup-data");
var data = JSON.parse(dataEl.textContent);
var t = data.translations;
var inFlight = false;
var phases = {
opening_database: true,
backing_up_database: true,
applying_migrations: true,
initializing_services: true,
recovering_sessions: true,
ready: true
};
var measures = { opaque: true, counting: true, counted: true };
var units = { rows: true, messages: true, turns: true, sessions: true, bytes: true, stores: true };
function nonNegativeInteger(value) {
return typeof value === "number" && isFinite(value) && value >= 0 && Math.floor(value) === value;
}
function nonNegativeNumber(value) {
return typeof value === "number" && isFinite(value) && value >= 0;
}
function validStartupStep(step) {
if (!step || typeof step !== "object" ||
typeof step.id !== "string" || !step.id ||
typeof step.label_key !== "string" || !step.label_key ||
!measures[step.measure] || !units[step.unit] ||
!nonNegativeInteger(step.elapsed_ms) || typeof step.stalled !== "boolean") {
return false;
}
for (var i = 0; i < ["done", "total", "eta_ms", "since_advance_ms"].length; i++) {
var key = ["done", "total", "eta_ms", "since_advance_ms"][i];
if (step[key] !== undefined && !nonNegativeInteger(step[key])) return false;
}
return step.rate_per_second === undefined || nonNegativeNumber(step.rate_per_second);
}
function validStartupSnapshot(snapshot) {
if (!snapshot || typeof snapshot !== "object" || !phases[snapshot.phase] ||
!nonNegativeInteger(snapshot.boot) || !nonNegativeInteger(snapshot.seq) ||
!nonNegativeInteger(snapshot.elapsed_ms) || !nonNegativeInteger(snapshot.phase_elapsed_ms)) {
return false;
}
return snapshot.step === undefined || validStartupStep(snapshot.step);
}
function el(id) { return document.getElementById(id); }
function setText(id, text) { var e = el(id); if (e) e.textContent = text || ""; }
function toggle(id, show) { var e = el(id); if (e) e.classList.toggle("hidden", !show); }
function interpolate(message, vars) {
if (!message) return "";
return message.replace(/\{\{(\w+)\}\}/g, function (_, name) {
return Object.prototype.hasOwnProperty.call(vars, name) ? vars[name] : "";
});
}
function pluralLookup(base, count) {
var key = base + (count === 1 ? "_one" : "_other");
return t[key] || t[base] || "";
}
function ceilDiv(numerator, denominator) {
if (numerator <= 0) return 0;
return Math.floor((numerator + denominator - 1) / denominator);
}
function estimateComponents(ms) {
if (ms <= 60000) {
var seconds = ceilDiv(ms, 1000);
if (seconds < 1) seconds = 1;
return { value: seconds, minutes: false };
}
return { value: ceilDiv(ms, 60000), minutes: true };
}
function durationLabel(ms) {
var c = estimateComponents(ms);
var key = c.minutes ? "startup.duration.minutes" : "startup.duration.seconds";
return interpolate(pluralLookup(key, c.value), { count: c.value });
}
function unitLabel(unit, count) {
return pluralLookup("startup.unit." + unit, count);
}
function progressText(step) {
if (step.measure === "opaque") return t["startup.page.progressUnavailable"];
if (step.measure === "counting") {
var done = step.done || 0;
return interpolate(t["startup.page.countingProgress"], { done: done, unit: unitLabel(step.unit, done) });
}
var counted = step.done || 0;
var total = step.total || 0;
return interpolate(t["startup.page.countedProgress"], { done: counted, total: total, unit: unitLabel(step.unit, total) });
}
function renderStep(step) {
toggle("startup-step-label", !!step);
toggle("startup-progress", !!step);
toggle("startup-eta", false);
toggle("startup-bar", false);
toggle("startup-stalled", false);
if (!step) return;
setText("startup-step-label", t[step.label_key]);
setText("startup-progress", progressText(step));
if (step.measure === "counted" && step.eta_ms != null) {
setText("startup-eta", interpolate(t["startup.page.eta"], { duration: durationLabel(step.eta_ms) }));
toggle("startup-eta", true);
}
if (step.measure === "counted" && step.total) {
var pct = Math.max(0, Math.min(100, (step.done || 0) / step.total * 100));
var fill = el("startup-bar-fill");
if (fill) fill.style.width = pct + "%";
toggle("startup-bar", true);
}
if (step.stalled && step.since_advance_ms != null) {
setText("startup-stalled", interpolate(t["startup.page.stalled"], { duration: durationLabel(step.since_advance_ms) }));
toggle("startup-stalled", true);
}
}
function render(snapshot) {
setText("startup-phase", t["startup.phase." + snapshot.phase]);
setText("startup-elapsed", interpolate(t["startup.page.elapsed"], { duration: durationLabel(snapshot.elapsed_ms) }));
renderStep(snapshot.step || null);
}
function markLastKnown(isLastKnown) {
setText("startup-last-known", isLastKnown ? t["startup.page.lastKnown"] : "");
toggle("startup-last-known", isLastKnown);
}
function handleBody(ok, body) {
var snapshot = body && body.startup;
if (!validStartupSnapshot(snapshot)) {
// AC-PLATFORM-STARTUP-PROGRESS-002.6: no parseable snapshot means the
// status code is authoritative.
if (ok) { window.location.reload(); return; }
markLastKnown(true);
return;
}
markLastKnown(false);
if (snapshot.phase === "ready") { window.location.reload(); return; }
render(snapshot);
}
function poll() {
if (inFlight) return;
inFlight = true;
var controller = ("AbortController" in window) ? new AbortController() : null;
var timeoutId = controller ? setTimeout(function () { controller.abort(); }, TIMEOUT_MS) : null;
fetch("/ready", { cache: "no-store", signal: controller ? controller.signal : undefined })
.then(function (res) {
return res
.json()
.then(function (body) { return { ok: res.ok, body: body }; })
.catch(function () { return { ok: res.ok, body: null }; });
})
.then(function (result) {
if (timeoutId) clearTimeout(timeoutId);
inFlight = false;
handleBody(result.ok, result.body);
})
.catch(function () {
if (timeoutId) clearTimeout(timeoutId);
inFlight = false;
markLastKnown(true);
});
}
setInterval(poll, POLL_MS);
})();
`
@@ -0,0 +1,262 @@
package backendapp
import (
"encoding/json"
"net/http/httptest"
"strings"
"testing"
"github.com/kandev/kandev/internal/startup"
)
func int64Ptr(v int64) *int64 { return &v }
// @covers AC-PLATFORM-STARTUP-PROGRESS-003.13
func TestBuildStartupPageViewNoStep(t *testing.T) {
view := buildStartupPageView("en", startup.Snapshot{Phase: startup.ApplyingMigrations, ElapsedMS: 4200})
if view.HasStep {
t.Fatal("no-step snapshot must not render a step")
}
if view.PhaseLabel != "Applying migrations" {
t.Fatalf("phase label = %q, want %q", view.PhaseLabel, "Applying migrations")
}
if view.Elapsed != "5 seconds elapsed" {
t.Fatalf("elapsed = %q, want the rounded-up elapsed string", view.Elapsed)
}
}
func TestBuildStartupPageViewOpaqueStep(t *testing.T) {
snap := startup.Snapshot{
Phase: startup.ApplyingMigrations,
Step: &startup.StepSnapshot{
LabelKey: "startup.step.prompt_seq",
Measure: startup.MeasureOpaque,
Unit: startup.UnitRows,
},
}
view := buildStartupPageView("en", snap)
if !view.HasStep {
t.Fatal("want a step")
}
if view.Step.Label != "Prompt sequence numbers" {
t.Fatalf("step label = %q", view.Step.Label)
}
if view.Step.Progress != "Progress cannot be measured for this step." {
t.Fatalf("opaque progress = %q", view.Step.Progress)
}
if view.Step.HasBar || view.Step.HasETA {
t.Fatal("opaque step must render no bar and no ETA")
}
}
func TestBuildStartupPageViewCountingStep(t *testing.T) {
snap := startup.Snapshot{
Phase: startup.BackingUpDatabase,
Step: &startup.StepSnapshot{
LabelKey: "startup.step.database_backup",
Measure: startup.MeasureCounting,
Unit: startup.UnitBytes,
Done: int64Ptr(1),
},
}
view := buildStartupPageView("en", snap)
if view.Step.Progress != "1 byte" {
t.Fatalf("counting progress = %q, want singular unit", view.Step.Progress)
}
if view.Step.HasBar {
t.Fatal("counting step (no total) must render no bar")
}
}
func TestBuildStartupPageViewCountedStepWithETA(t *testing.T) {
snap := startup.Snapshot{
Phase: startup.ApplyingMigrations,
Step: &startup.StepSnapshot{
LabelKey: "startup.step.stores_repositories",
Measure: startup.MeasureCounted,
Unit: startup.UnitTurns,
Done: int64Ptr(5),
Total: int64Ptr(10),
ETAMS: int64Ptr(30000),
},
}
view := buildStartupPageView("en", snap)
if view.Step.Progress != "5 of 10 turns" {
t.Fatalf("counted progress = %q, want plural unit from total", view.Step.Progress)
}
if !view.Step.HasBar || view.Step.PercentDoneStr != "50.00" {
t.Fatalf("bar = %v %q, want 50.00%%", view.Step.HasBar, view.Step.PercentDoneStr)
}
if !view.Step.HasETA || view.Step.ETA != "About 30 seconds remaining" {
t.Fatalf("eta = %v %q", view.Step.HasETA, view.Step.ETA)
}
}
// @covers AC-PLATFORM-STARTUP-PROGRESS-004.6
func TestBuildStartupPageViewStalledStep(t *testing.T) {
snap := startup.Snapshot{
Phase: startup.ApplyingMigrations,
Step: &startup.StepSnapshot{
LabelKey: "startup.step.stores_repositories",
Measure: startup.MeasureCounted,
Unit: startup.UnitTurns,
Done: int64Ptr(5),
Total: int64Ptr(10),
SinceAdvanceMS: int64Ptr(125000),
Stalled: true,
},
}
view := buildStartupPageView("en", snap)
if !view.Step.Stalled {
t.Fatal("want the step view to report stalled")
}
if view.Step.StalledText != "Stalled for 3 minutes" {
t.Fatalf("stalled text = %q, want the rounded-up duration", view.Step.StalledText)
}
}
// @covers AC-PLATFORM-STARTUP-PROGRESS-004.5
func TestBuildStartupPageViewRunningStepHasNoStalledText(t *testing.T) {
snap := startup.Snapshot{
Phase: startup.ApplyingMigrations,
Step: &startup.StepSnapshot{
LabelKey: "startup.step.stores_repositories",
Measure: startup.MeasureCounted,
Unit: startup.UnitTurns,
Done: int64Ptr(5),
Total: int64Ptr(10),
SinceAdvanceMS: int64Ptr(500),
Stalled: false,
},
}
view := buildStartupPageView("en", snap)
if view.Step.Stalled || view.Step.StalledText != "" {
t.Fatalf("running step must render no stalled state, got Stalled=%v StalledText=%q", view.Step.Stalled, view.Step.StalledText)
}
}
func TestBuildStartupPageViewCountedStepSingularTotal(t *testing.T) {
snap := startup.Snapshot{
Phase: startup.ApplyingMigrations,
Step: &startup.StepSnapshot{
LabelKey: "startup.step.stores_repositories",
Measure: startup.MeasureCounted,
Unit: startup.UnitTurns,
Done: int64Ptr(1),
Total: int64Ptr(1),
},
}
view := buildStartupPageView("en", snap)
if view.Step.Progress != "1 of 1 turn" {
t.Fatalf("counted progress = %q, want singular unit from total=1", view.Step.Progress)
}
}
func TestWriteStartupPageHeadersAndStatus(t *testing.T) {
w := httptest.NewRecorder()
writeStartupPage(w, httptest.NewRequest("GET", "/", nil), startup.Snapshot{Phase: startup.OpeningDatabase})
if w.Code != 503 {
t.Fatalf("status = %d, want 503", w.Code)
}
if got := w.Header().Get("Cache-Control"); got != "no-store" {
t.Fatalf("Cache-Control = %q, want no-store", got)
}
if got := w.Header().Get("Content-Type"); !strings.HasPrefix(got, "text/html") {
t.Fatalf("Content-Type = %q, want text/html", got)
}
body := w.Body.String()
if !strings.Contains(body, "Opening database") {
t.Fatalf("body missing phase label: %s", body)
}
if !strings.Contains(body, `role="status" aria-live="polite"`) {
t.Fatal("body missing the live region required by AC-PLATFORM-STARTUP-PROGRESS-003.11")
}
if !strings.Contains(body, "prefers-reduced-motion") {
t.Fatal("body missing the reduced-motion accommodation required by AC-PLATFORM-STARTUP-PROGRESS-003.11")
}
dataStart := strings.Index(body, `<script id="startup-data" type="application/json">`)
if dataStart < 0 {
t.Fatal("body missing the startup-data JSON island")
}
dataStart += len(`<script id="startup-data" type="application/json">`)
dataEnd := strings.Index(body[dataStart:], "</script>")
if dataEnd < 0 {
t.Fatal("unterminated startup-data script")
}
var island struct {
Translations map[string]string `json:"translations"`
Snapshot startup.Snapshot `json:"snapshot"`
}
if err := json.Unmarshal([]byte(body[dataStart:dataStart+dataEnd]), &island); err != nil {
t.Fatalf("startup-data island did not parse as JSON: %v", err)
}
if island.Snapshot.Phase != startup.OpeningDatabase {
t.Fatalf("embedded snapshot phase = %q, want %q", island.Snapshot.Phase, startup.OpeningDatabase)
}
if island.Translations["startup.phase.opening_database"] != "Opening database" {
t.Fatalf("embedded translations missing phase key, got %#v", island.Translations)
}
}
// @covers AC-PLATFORM-STARTUP-PROGRESS-003.3
func TestNewBootstrapHandlerServesStartupPageForHTMLPreferringSPARequest(t *testing.T) {
handler := newBootstrapHandler("test")
req := httptest.NewRequest("GET", "/tasks", nil)
req.Header.Set("Accept", "text/html")
w := httptest.NewRecorder()
handler.ServeHTTP(w, req)
if got := w.Header().Get("Content-Type"); !strings.HasPrefix(got, "text/html") {
t.Fatalf("Content-Type = %q, want text/html for an HTML-preferring SPA route request", got)
}
}
func TestNewBootstrapHandlerKeepsJSONForReadyEvenWhenHTMLPreferred(t *testing.T) {
handler := newBootstrapHandler("test")
req := httptest.NewRequest("GET", "/ready", nil)
req.Header.Set("Accept", "text/html")
w := httptest.NewRecorder()
handler.ServeHTTP(w, req)
if got := w.Header().Get("Content-Type"); !strings.HasPrefix(got, "application/json") {
t.Fatalf("Content-Type = %q, want JSON: /ready must keep answering the snapshot even when HTML is preferred", got)
}
}
func TestNewBootstrapHandlerKeepsJSONForNonSPARoute(t *testing.T) {
handler := newBootstrapHandler("test")
req := httptest.NewRequest("GET", "/api/v1/features", nil)
req.Header.Set("Accept", "text/html")
w := httptest.NewRecorder()
handler.ServeHTTP(w, req)
if got := w.Header().Get("Content-Type"); !strings.HasPrefix(got, "application/json") {
t.Fatalf("Content-Type = %q, want JSON for a non-application route", got)
}
}
func TestNewBootstrapHandlerKeepsJSONWhenJSONPreferred(t *testing.T) {
handler := newBootstrapHandler("test")
req := httptest.NewRequest("GET", "/tasks", nil)
req.Header.Set("Accept", "application/json")
w := httptest.NewRecorder()
handler.ServeHTTP(w, req)
if got := w.Header().Get("Content-Type"); !strings.HasPrefix(got, "application/json") {
t.Fatalf("Content-Type = %q, want JSON when the client prefers it", got)
}
}
func TestNewBootstrapHandlerKeepsJSONForNonGETMethod(t *testing.T) {
handler := newBootstrapHandler("test")
req := httptest.NewRequest("POST", "/tasks", nil)
req.Header.Set("Accept", "text/html")
w := httptest.NewRecorder()
handler.ServeHTTP(w, req)
if got := w.Header().Get("Content-Type"); !strings.HasPrefix(got, "application/json") {
t.Fatalf("Content-Type = %q, want JSON for a non-GET method", got)
}
}
+47 -29
View File
@@ -61,35 +61,45 @@ func provideRepositories(ctx context.Context, cfg *config.Config, log *logger.Lo
cleanups = append(cleanups, cleanup)
startup.SetPhase(ctx, startup.ApplyingMigrations)
writer, reader := pool.Writer(), pool.Reader()
if err := checkStartupContext(ctx, "schema metadata"); err != nil {
return nil, nil, nil, err
}
if err := recordRequiredStore(tracker, "schema-meta", nil); err != nil {
return nil, nil, nil, err
}
if err := checkStartupContext(ctx, "task repository"); err != nil {
return nil, nil, nil, err
}
taskRepoImpl, cleanup, err := repository.ProvideContext(ctx, writer, reader, log)
if err := recordRequiredStore(tracker, "task", err); err != nil {
// repository.ProvideContext's own migrations and backfills open and
// close several of their own steps under this same ApplyingMigrations
// phase (journal turns/messages, prompt_seq, message_timestamps,
// subagent_context). It must finish before the sweep step below opens:
// steps must never overlap, so any of those steps beginning while
// stores.repositories was already active would silently end the sweep
// and turn every later recordRequiredStore call in this function into a
// no-op against a step that is no longer current.
taskRepoImpl, cleanup, taskRepoErr := repository.ProvideContext(ctx, writer, reader, log)
cleanups = append(cleanups, cleanup)
startup.BeginStep(ctx, startup.StepStoresRepositories)
startup.SetTotal(ctx, startup.StepStoresRepositories, int64(tracker.SweepTotal(startup.StepStoresRepositories)))
if err := checkStartupContext(ctx, "schema metadata"); err != nil {
return nil, nil, nil, err
}
if err := recordRequiredStore(ctx, tracker, "schema-meta", nil); err != nil {
return nil, nil, nil, err
}
if err := recordRequiredStore(ctx, tracker, "task", taskRepoErr); err != nil {
return nil, nil, nil, fmt.Errorf("task store: %w", err)
}
cleanups = append(cleanups, cleanup)
// Workflow repo must be initialized before analytics repo because
// analytics creates indexes on the workflow_steps table.
if err := checkStartupContext(ctx, "workflow repository"); err != nil {
return nil, nil, nil, err
}
workflowRepo, err := workflowrepository.NewWithDB(writer, reader, log)
if err := recordRequiredStore(tracker, "workflow", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "workflow", err); err != nil {
return nil, nil, nil, fmt.Errorf("workflow store: %w", err)
}
if err := checkStartupContext(ctx, "analytics repository"); err != nil {
return nil, nil, nil, err
}
analyticsRepo, cleanup, err := analyticsrepository.Provide(writer, reader)
if err := recordRequiredStore(tracker, "analytics", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "analytics", err); err != nil {
return nil, nil, nil, fmt.Errorf("analytics store: %w", err)
}
cleanups = append(cleanups, cleanup)
@@ -97,7 +107,7 @@ func provideRepositories(ctx context.Context, cfg *config.Config, log *logger.Lo
return nil, nil, nil, err
}
agentSettingsRepo, cleanup, err := settingsstore.Provide(writer, reader, log)
if err := recordRequiredStore(tracker, "agent-settings", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "agent-settings", err); err != nil {
return nil, nil, nil, fmt.Errorf("agent settings store: %w", err)
}
cleanups = append(cleanups, cleanup)
@@ -114,7 +124,7 @@ func provideRepositories(ctx context.Context, cfg *config.Config, log *logger.Lo
return nil, nil, nil, err
}
officeRepo, officeCleanup, err := office.Provide(writer, reader, log)
if err := recordRequiredStore(tracker, "office", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "office", err); err != nil {
return nil, nil, nil, fmt.Errorf("office repo: %w", err)
}
cleanups = append(cleanups, officeCleanup)
@@ -122,21 +132,21 @@ func provideRepositories(ctx context.Context, cfg *config.Config, log *logger.Lo
return nil, nil, nil, err
}
terminalRepoImpl, err := terminalrepo.NewWithDB(writer, reader, log)
if err := recordRequiredStore(tracker, "terminal", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "terminal", err); err != nil {
return nil, nil, nil, fmt.Errorf("terminal repo: %w", err)
}
if err := checkStartupContext(ctx, "quick terminal repository"); err != nil {
return nil, nil, nil, err
}
quickTerminalRepoImpl, err := quickterminalrepository.NewWithDB(writer, reader)
if err := recordRequiredStore(tracker, "quick-terminal", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "quick-terminal", err); err != nil {
return nil, nil, nil, fmt.Errorf("quick terminal repo: %w", err)
}
if err := checkStartupContext(ctx, "runtime flags repository"); err != nil {
return nil, nil, nil, err
}
runtimeFlagsStore, err := runtimeflags.NewSQLiteStore(writer, reader)
if err := recordRequiredStore(tracker, "runtime-flags", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "runtime-flags", err); err != nil {
return nil, nil, nil, fmt.Errorf("runtime flags store: %w", err)
}
@@ -144,7 +154,7 @@ func provideRepositories(ctx context.Context, cfg *config.Config, log *logger.Lo
return nil, nil, nil, err
}
authRepo, err := authstore.New(writer, reader)
if err := recordRequiredStore(tracker, "auth", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "auth", err); err != nil {
return nil, nil, nil, fmt.Errorf("auth store: %w", err)
}
if err := checkStartupContext(ctx, "secret repository"); err != nil {
@@ -158,7 +168,7 @@ func provideRepositories(ctx context.Context, cfg *config.Config, log *logger.Lo
return nil, nil, nil, err
}
secretStore, cleanup, err := secrets.Provide(writer, reader, masterKeyProvider)
if err := recordRequiredStore(tracker, "secrets", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "secrets", err); err != nil {
return nil, nil, nil, fmt.Errorf("secret store: %w", err)
}
cleanups = append(cleanups, cleanup)
@@ -167,14 +177,14 @@ func provideRepositories(ctx context.Context, cfg *config.Config, log *logger.Lo
return nil, nil, nil, err
}
systemSettings, err := systemsettings.NewStore(pool)
if err := recordRequiredStore(tracker, "system-settings", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "system-settings", err); err != nil {
return nil, nil, nil, fmt.Errorf("system settings store: %w", err)
}
if err := checkStartupContext(ctx, "hostname repository"); err != nil {
return nil, nil, nil, err
}
hostnameCache, err := hostnames.NewStore(writer, reader)
if err := recordRequiredStore(tracker, "auth-hostnames", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "auth-hostnames", err); err != nil {
return nil, nil, nil, fmt.Errorf("hostname cache store: %w", err)
}
@@ -182,7 +192,7 @@ func provideRepositories(ctx context.Context, cfg *config.Config, log *logger.Lo
return nil, nil, nil, err
}
telemetryStore, err := telemetrycontract.NewWithDB(writer, reader)
if err := recordRequiredStore(tracker, "telemetry-contract", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "telemetry-contract", err); err != nil {
return nil, nil, nil, fmt.Errorf("telemetry contract store: %w", err)
}
activateTelemetryContracts(ctx, telemetryStore, log)
@@ -212,7 +222,10 @@ func provideRepositories(ctx context.Context, cfg *config.Config, log *logger.Lo
return nil, nil, nil, err
}
initialized = true
startup.EndStep(ctx, startup.StepStoresRepositories)
startup.SetPhase(ctx, startup.InitializingServices)
startup.BeginStep(ctx, startup.StepStoresServices)
startup.SetTotal(ctx, startup.StepStoresServices, int64(tracker.SweepTotal(startup.StepStoresServices)))
return pool, repos, cleanups, nil
}
@@ -246,7 +259,7 @@ func provideSupportRepos(ctx context.Context, writer, reader *sqlx.DB, tracker *
}
userRepo, cleanup, err := userstore.Provide(writer, reader)
cleanups = append(cleanups, cleanup)
if err := recordRequiredStore(tracker, "user", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "user", err); err != nil {
return repos, cleanups, err
}
repos.user = userRepo
@@ -258,7 +271,7 @@ func provideSupportRepos(ctx context.Context, writer, reader *sqlx.DB, tracker *
}
notificationRepo, cleanup, err := notificationstore.Provide(ctx, writer, reader)
cleanups = append(cleanups, cleanup)
if err := recordRequiredStore(tracker, "notification", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "notification", err); err != nil {
return repos, cleanups, err
}
repos.notification = notificationRepo
@@ -268,7 +281,7 @@ func provideSupportRepos(ctx context.Context, writer, reader *sqlx.DB, tracker *
}
editorRepo, cleanup, err := editorstore.Provide(writer, reader)
cleanups = append(cleanups, cleanup)
if err := recordRequiredStore(tracker, "editor", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "editor", err); err != nil {
return repos, cleanups, err
}
repos.editor = editorRepo
@@ -278,7 +291,7 @@ func provideSupportRepos(ctx context.Context, writer, reader *sqlx.DB, tracker *
}
promptRepo, cleanup, err := promptstore.Provide(writer, reader)
cleanups = append(cleanups, cleanup)
if err := recordRequiredStore(tracker, "prompts", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "prompts", err); err != nil {
return repos, cleanups, err
}
repos.prompts = promptRepo
@@ -288,7 +301,7 @@ func provideSupportRepos(ctx context.Context, writer, reader *sqlx.DB, tracker *
}
utilityRepo, cleanup, err := utilitystore.Provide(writer, reader)
cleanups = append(cleanups, cleanup)
if err := recordRequiredStore(tracker, "utility", err); err != nil {
if err := recordRequiredStore(ctx, tracker, "utility", err); err != nil {
return repos, cleanups, err
}
repos.utility = utilityRepo
@@ -297,14 +310,19 @@ func provideSupportRepos(ctx context.Context, writer, reader *sqlx.DB, tracker *
}
// recordRequiredStore records a constructor result before the process can
// expose readiness. Initialization failures remain fatal to the caller.
func recordRequiredStore(tracker *requiredstores.Tracker, id string, initErr error) error {
// expose readiness. Initialization failures remain fatal to the caller. A
// successful admission advances the store-admission sweep step its catalog
// descriptor names, by one.
func recordRequiredStore(ctx context.Context, tracker *requiredstores.Tracker, id string, initErr error) error {
if trackerErr := tracker.Record(id, initErr); trackerErr != nil {
return trackerErr
}
if initErr != nil {
return fmt.Errorf("required store %q: %w", id, initErr)
}
if sweep, ok := tracker.DescriptorSweep(id); ok {
startup.Advance(ctx, sweep, 1)
}
return nil
}
@@ -18,6 +18,7 @@ import (
"github.com/kandev/kandev/internal/events"
"github.com/kandev/kandev/internal/events/bus"
"github.com/kandev/kandev/internal/persistence/requiredstores"
"github.com/kandev/kandev/internal/startup"
"github.com/kandev/kandev/internal/system/jobs"
systemmetrics "github.com/kandev/kandev/internal/system/metrics"
systemsettings "github.com/kandev/kandev/internal/system/settings"
@@ -58,20 +59,29 @@ type storageDependencies struct {
providers []storagepkg.CleanupProvider
}
func provideStorageComposition(
cfg *config.Config,
// provideStorageStore constructs the storage system's persistence store and
// closes stores.services's required-store sweep. storage is stores.
// services's last admission chronologically (after services.go,
// orchestrator.go, and main.go's delivery), so this is where the sweep step
// closes. Callers must run this before sessions.recovery's BeginStep: steps
// must never overlap, and BeginStep unconditionally ends whatever step is
// currently active, which would silently truncate the sweep.
func provideStorageStore(
ctx context.Context,
pool *db.Pool,
tracker *jobs.Tracker,
eventBus bus.EventBus,
lifecycleMgr *lifecycle.Manager,
worktreeMgr *worktree.Manager,
taskSvc *taskservice.Service,
log *logger.Logger,
logError func(string, error),
) (*storageComposition, error) {
return provideStorageCompositionWithDependencies(
cfg, pool, tracker, eventBus, lifecycleMgr, worktreeMgr, taskSvc, log, logError, nil, nil,
)
requiredTracker *requiredstores.Tracker,
) (*storagepkg.Store, error) {
store, err := storagepkg.NewStore(pool)
if requiredTracker != nil {
if recordErr := recordRequiredStore(ctx, requiredTracker, "storage", err); recordErr != nil {
return nil, fmt.Errorf("initialize storage store: %w", recordErr)
}
startup.EndStep(ctx, startup.StepStoresServices)
}
if err != nil {
return nil, fmt.Errorf("initialize storage store: %w", err)
}
return store, nil
}
func provideStorageCompositionWithDependencies(
@@ -84,11 +94,11 @@ func provideStorageCompositionWithDependencies(
taskSvc *taskservice.Service,
log *logger.Logger,
logError func(string, error),
requiredTracker *requiredstores.Tracker,
store *storagepkg.Store,
providedSettings *systemsettings.Store,
) (*storageComposition, error) {
dependencies, err := prepareStorageDependencies(
cfg, pool, requiredTracker, eventBus, lifecycleMgr, worktreeMgr, taskSvc, log, logError, providedSettings,
cfg, pool, store, eventBus, lifecycleMgr, worktreeMgr, taskSvc, log, logError, providedSettings,
)
if err != nil {
return nil, err
@@ -136,7 +146,7 @@ func provideStorageCompositionWithDependencies(
func prepareStorageDependencies(
cfg *config.Config,
pool *db.Pool,
requiredTracker *requiredstores.Tracker,
store *storagepkg.Store,
eventBus bus.EventBus,
lifecycleMgr *lifecycle.Manager,
worktreeMgr *worktree.Manager,
@@ -154,15 +164,6 @@ func prepareStorageDependencies(
return nil, fmt.Errorf("initialize storage settings: %w", err)
}
settings := storagepkg.NewSettingsStore(rawSettings)
store, err := storagepkg.NewStore(pool)
if requiredTracker != nil {
if recordErr := recordRequiredStore(requiredTracker, "storage", err); recordErr != nil {
return nil, fmt.Errorf("initialize storage store: %w", recordErr)
}
}
if err != nil {
return nil, fmt.Errorf("initialize storage store: %w", err)
}
tempArtifacts := tempartifacts.NewRegistry(tempartifacts.Config{Store: store, TempRoot: os.TempDir()})
if err := tempArtifacts.Reconcile(context.Background()); err != nil {
logError("reconcile temporary artifact registry", err)
@@ -0,0 +1,263 @@
package backendapp
import (
"context"
"errors"
"testing"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
"go.uber.org/zap/zaptest/observer"
"github.com/kandev/kandev/internal/agent/registry"
"github.com/kandev/kandev/internal/common/config"
"github.com/kandev/kandev/internal/common/logger"
"github.com/kandev/kandev/internal/events/bus"
"github.com/kandev/kandev/internal/persistence/requiredstores"
"github.com/kandev/kandev/internal/startup"
)
// TestRecordRequiredStoreAdvancesItsDescriptorsSweep is the unit-level half
// of AC-PLATFORM-STARTUP-PROGRESS-005.7 ("recordRequiredStore advances the
// sweep its descriptor names, by one"): a successful admission advances the
// active sweep step by exactly one, and a failed admission - fatal to the
// caller - advances nothing.
func TestRecordRequiredStoreAdvancesItsDescriptorsSweep(t *testing.T) {
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}, Sweep: startup.StepStoresRepositories},
})
if err != nil {
t.Fatalf("NewTracker: %v", err)
}
reporter := startup.New(nil)
ctx := startup.WithReporter(context.Background(), reporter)
reporter.BeginStep(startup.StepStoresRepositories)
reporter.SetTotal(startup.StepStoresRepositories, 2)
if err := recordRequiredStore(ctx, tracker, "first", nil); err != nil {
t.Fatalf("recordRequiredStore(first): %v", err)
}
if done := *reporter.Snapshot().Step.Done; done != 1 {
t.Fatalf("Done after first admission = %d, want 1", done)
}
failErr := errors.New("boom")
if err := recordRequiredStore(ctx, tracker, "second", failErr); err == nil {
t.Fatal("recordRequiredStore(second, failErr) = nil error, want failErr")
}
if done := *reporter.Snapshot().Step.Done; done != 1 {
t.Fatalf("Done after failed admission = %d, want unchanged at 1", done)
}
}
// TestProvideRepositoriesReportsStoresRepositoriesSweep covers the
// stores.repositories half of AC-PLATFORM-STARTUP-PROGRESS-005.2/.7: every
// admission in provideRepositories (including the five inside
// provideSupportRepos) advances the sweep step its catalog descriptor names,
// and the sweep closes and hands off to stores.services at the same
// storage.go:215 boundary that already switches the phase - this is
// completeness test 4 (declared Phase matches the real call site) for these
// two steps, exercised end to end rather than centrally.
func TestProvideRepositoriesReportsStoresRepositoriesSweep(t *testing.T) {
cfg := &config.Config{
HomeDir: t.TempDir(),
Database: config.DatabaseConfig{Driver: "sqlite"},
}
reporter := startup.New(nil)
ctx := startup.WithReporter(context.Background(), reporter)
_, _, cleanups, err := provideRepositories(ctx, cfg, newTestLogger(), "test")
if err != nil {
t.Fatalf("provideRepositories: %v", err)
}
t.Cleanup(func() {
for i := len(cleanups) - 1; i >= 0; i-- {
if cleanups[i] != nil {
_ = cleanups[i]()
}
}
})
wantRepositoriesTotal := int64(requiredstoresSweepTotal(t, startup.StepStoresRepositories))
wantServicesTotal := int64(requiredstoresSweepTotal(t, startup.StepStoresServices))
snap := reporter.Snapshot()
if snap.Phase != startup.InitializingServices {
t.Fatalf("Phase = %q, want %q", snap.Phase, startup.InitializingServices)
}
if snap.Step == nil {
t.Fatal("Step = nil, want stores.services active after provideRepositories returns")
}
if snap.Step.ID != startup.StepStoresServices {
t.Fatalf("Step.ID = %q, want %q (stores.repositories must have closed at the InitializingServices boundary)", snap.Step.ID, startup.StepStoresServices)
}
if snap.Step.Done == nil || *snap.Step.Done != 0 {
t.Fatalf("Step.Done = %v, want 0 (stores.services has admitted nothing yet)", snap.Step.Done)
}
if snap.Step.Total == nil || *snap.Step.Total != wantServicesTotal {
t.Fatalf("Step.Total = %v, want %d", snap.Step.Total, wantServicesTotal)
}
if wantRepositoriesTotal != 19 {
t.Fatalf("stores.repositories catalog total = %d, want 19 (sanity check on the fixture)", wantRepositoriesTotal)
}
}
// TestProvideRepositoriesStoresRepositoriesSweepReachesFullTotal covers the
// interleaving between the stores.repositories sweep and
// repository.ProvideContext's own migrations/backfills, which open and close
// several finer-grained steps (journal turns/messages, prompt_seq,
// message_timestamps, subagent_context) under the same ApplyingMigrations
// phase. On a fresh database (first-ever boot) every one of those backfill
// steps actually opens, so if stores.repositories's own BeginStep/EndStep
// window still overlapped theirs, its later recordRequiredStore admissions
// would silently no-op against a step that had already been ended out from
// under it, and it would never log "Startup step completed" at all. This
// asserts the sweep both logs its completion and reaches done == total ==
// 19, proving every admission after the nested steps still landed.
func TestProvideRepositoriesStoresRepositoriesSweepReachesFullTotal(t *testing.T) {
cfg := &config.Config{
HomeDir: t.TempDir(),
Database: config.DatabaseConfig{Driver: "sqlite"},
}
core, logs := observer.New(zapcore.InfoLevel)
log, err := logger.NewFromZap(zap.New(core))
if err != nil {
t.Fatalf("observer logger: %v", err)
}
reporter := startup.New(log)
ctx := startup.WithReporter(context.Background(), reporter)
_, _, cleanups, err := provideRepositories(ctx, cfg, log, "test")
if err != nil {
t.Fatalf("provideRepositories: %v", err)
}
t.Cleanup(func() {
for i := len(cleanups) - 1; i >= 0; i-- {
if cleanups[i] != nil {
_ = cleanups[i]()
}
}
})
var sawNestedStep bool
var completedFields map[string]interface{}
for _, entry := range logs.All() {
fields := entry.ContextMap()
if entry.Message == "Startup step started" && fields["step"] != string(startup.StepStoresRepositories) {
sawNestedStep = true
}
if entry.Message == "Startup step completed" && fields["step"] == string(startup.StepStoresRepositories) {
completedFields = fields
}
}
if !sawNestedStep {
t.Fatal("no nested step opened during provideRepositories on a fresh database; this test no longer exercises the interleaving it targets")
}
if completedFields == nil {
t.Fatal(`no "Startup step completed" entry for stores.repositories: EndStep silently no-op'd against a step already ended by a nested BeginStep`)
}
wantTotal := int64(requiredstoresSweepTotal(t, startup.StepStoresRepositories))
done, _ := completedFields["done"].(int64)
total, _ := completedFields["total"].(int64)
if done != wantTotal || total != wantTotal {
t.Fatalf("stores.repositories completed with done=%v total=%v, want both %d", done, total, wantTotal)
}
}
// TestStoresServicesSweepReachesFullTotalAfterStorageAdmission is the
// stores.services sibling of
// TestProvideRepositoriesStoresRepositoriesSweepReachesFullTotal. storage is
// stores.services's last admission chronologically, constructed by
// provideStorageStore. Production runs provideStorageStore (and the plugins
// journal mirror sync that must follow it) immediately before
// sessions.recovery's BeginStep specifically so that BeginStep never finds
// stores.services still open: were the order reversed, BeginStep would
// force-close stores.services early and every admission recorded up to that
// point -- including storage's own -- would be silently lost. This asserts
// the sweep both logs its completion and reaches done == total == 22 when
// admitted in that order, with no interleaving step in between.
func TestStoresServicesSweepReachesFullTotalAfterStorageAdmission(t *testing.T) {
cfg := &config.Config{
HomeDir: t.TempDir(),
Database: config.DatabaseConfig{Driver: "sqlite"},
}
core, logs := observer.New(zapcore.InfoLevel)
log, err := logger.NewFromZap(zap.New(core))
if err != nil {
t.Fatalf("observer logger: %v", err)
}
reporter := startup.New(log)
ctx := startup.WithReporter(context.Background(), reporter)
pool, repos, cleanups, err := provideRepositories(ctx, cfg, log, "test")
if err != nil {
t.Fatalf("provideRepositories: %v", err)
}
t.Cleanup(func() {
for i := len(cleanups) - 1; i >= 0; i-- {
if cleanups[i] != nil {
_ = cleanups[i]()
}
}
})
agentRegistry, registryCleanup, err := registry.Provide(log)
if err != nil {
t.Fatalf("registry.Provide: %v", err)
}
t.Cleanup(func() {
if registryCleanup != nil {
_ = registryCleanup()
}
})
services, _, err := provideServices(ctx, cfg, log, repos, pool, bus.NewMemoryEventBus(log), agentRegistry, "test")
if err != nil {
t.Fatalf("provideServices: %v", err)
}
if services.PluginsCleanup != nil {
t.Cleanup(func() { _ = services.PluginsCleanup() })
}
// message-queue and delivery are recorded in production by
// provideOrchestrator and startAgentInfrastructure respectively; record
// them the same way here without standing up the full orchestrator and
// lifecycle manager.
if err := recordRequiredStore(ctx, repos.RequiredStores, "message-queue", nil); err != nil {
t.Fatalf("recordRequiredStore(message-queue): %v", err)
}
if err := recordRequiredStore(ctx, repos.RequiredStores, "delivery", nil); err != nil {
t.Fatalf("recordRequiredStore(delivery): %v", err)
}
if _, err := provideStorageStore(ctx, pool, repos.RequiredStores); err != nil {
t.Fatalf("provideStorageStore: %v", err)
}
var completedFields map[string]interface{}
for _, entry := range logs.All() {
fields := entry.ContextMap()
if entry.Message == "Startup step completed" && fields["step"] == string(startup.StepStoresServices) {
completedFields = fields
}
}
if completedFields == nil {
t.Fatal(`no "Startup step completed" entry for stores.services: EndStep silently no-op'd against a step already ended`)
}
wantTotal := int64(requiredstoresSweepTotal(t, startup.StepStoresServices))
done, _ := completedFields["done"].(int64)
total, _ := completedFields["total"].(int64)
if done != wantTotal || total != wantTotal {
t.Fatalf("stores.services completed with done=%v total=%v, want both %d", done, total, wantTotal)
}
}
func requiredstoresSweepTotal(t *testing.T, sweep startup.StepID) int {
t.Helper()
tracker, err := requiredstores.NewCatalogTracker()
if err != nil {
t.Fatalf("NewCatalogTracker: %v", err)
}
return tracker.SweepTotal(sweep)
}
@@ -0,0 +1,86 @@
package i18n
import (
"net/http/httptest"
"testing"
)
func TestParseAcceptLanguageExcludesUnparseableQValue(t *testing.T) {
t.Parallel()
got := parseAcceptLanguage("fr;q=not-a-number, en;q=0.5")
if len(got) != 1 || got[0] != "en" {
t.Fatalf("parseAcceptLanguage = %v, want only [en]: an unparseable q must exclude the tag, not promote it to 1.0", got)
}
}
func TestParseAcceptLanguageExcludesZeroQValue(t *testing.T) {
t.Parallel()
got := parseAcceptLanguage("fr;q=0, en;q=0.5")
if len(got) != 1 || got[0] != "en" {
t.Fatalf("parseAcceptLanguage = %v, want only [en]: q=0 means not acceptable per RFC 7231", got)
}
}
func TestParseAcceptLanguageExcludesNegativeQValue(t *testing.T) {
t.Parallel()
got := parseAcceptLanguage("fr;q=-1, en;q=0.5")
if len(got) != 1 || got[0] != "en" {
t.Fatalf("parseAcceptLanguage = %v, want only [en]", got)
}
}
func TestParseAcceptLanguageExcludesQValueAboveOne(t *testing.T) {
t.Parallel()
got := parseAcceptLanguage("zh-cn;q=2, en;q=1")
if len(got) != 1 || got[0] != "en" {
t.Fatalf("parseAcceptLanguage = %v, want only [en]: q>1 is outside HTTP quality's [0,1] range and must not outrank a valid entry", got)
}
}
func TestParseAcceptLanguageExcludesTrailingGarbageQValue(t *testing.T) {
t.Parallel()
got := parseAcceptLanguage("fr;q=1abc, en;q=0.5")
if len(got) != 1 || got[0] != "en" {
t.Fatalf("parseAcceptLanguage = %v, want only [en]: a numeric prefix followed by garbage must not parse as valid", got)
}
}
func TestParseAcceptLanguageExcludesNonFiniteQValue(t *testing.T) {
t.Parallel()
got := parseAcceptLanguage("fr;q=NaN, en;q=0.5")
if len(got) != 1 || got[0] != "en" {
t.Fatalf("parseAcceptLanguage = %v, want only [en]: NaN must not enter the priority sort", got)
}
}
func TestParseAcceptLanguageOrdersDescendingByQValue(t *testing.T) {
t.Parallel()
got := parseAcceptLanguage("en;q=0.3, zh-cn;q=0.9, pt-pt;q=0.6")
want := []string{"zh-cn", "pt-pt", "en"}
if len(got) != len(want) {
t.Fatalf("parseAcceptLanguage = %v, want %v", got, want)
}
for i := range want {
if got[i] != want[i] {
t.Fatalf("parseAcceptLanguage = %v, want %v", got, want)
}
}
}
func TestParseAcceptLanguageDefaultsMissingQTo1(t *testing.T) {
t.Parallel()
got := parseAcceptLanguage("en, zh-cn;q=0.5")
want := []string{"en", "zh-cn"}
if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
t.Fatalf("parseAcceptLanguage = %v, want %v", got, want)
}
}
func TestFromRequestFallsThroughAMalformedQValueToTheNextTag(t *testing.T) {
t.Parallel()
r := httptest.NewRequest("GET", "/", nil)
r.Header.Set("Accept-Language", "fr;q=bogus, zh-cn;q=0.8")
if got := FromRequest(r); got != "zh-cn" {
t.Fatalf("FromRequest = %q, want %q: a malformed q must not win priority", got, "zh-cn")
}
}
+30 -10
View File
@@ -24,7 +24,9 @@ import (
"embed"
"encoding/json"
"fmt"
"math"
"net/http"
"strconv"
"strings"
"sync"
)
@@ -120,7 +122,9 @@ func FromRequest(r *http.Request) string {
}
// parseAcceptLanguage returns the header's tags in descending q-value order.
// Malformed entries are skipped rather than failing the request.
// Malformed entries, and any entry whose q-value is unparseable or not
// positive, are excluded rather than falling through to the request's
// default acceptability of 1.0.
func parseAcceptLanguage(header string) []string {
if header == "" {
return nil
@@ -136,15 +140,9 @@ func parseAcceptLanguage(header string) []string {
if tag == "" {
continue
}
q := 1.0
for _, field := range fields[1:] {
field = strings.TrimSpace(field)
if !strings.HasPrefix(field, "q=") {
continue
}
if _, err := fmt.Sscanf(field, "q=%f", &q); err != nil {
q = 1.0
}
q, ok := acceptLanguageQuality(fields[1:])
if !ok || q <= 0 {
continue
}
items = append(items, weighted{tag: tag, q: q})
}
@@ -161,6 +159,28 @@ func parseAcceptLanguage(header string) []string {
return tags
}
// acceptLanguageQuality reads the q parameter from one Accept-Language
// field's ";"-separated parameters, defaulting to 1.0 when none is present.
// It reports ok=false for a q parameter that is present but unparseable, not
// a finite number, or outside HTTP quality's [0,1] range, so the caller
// excludes the tag instead of promoting a malformed value to the highest
// priority or letting it outrank well-formed entries.
func acceptLanguageQuality(params []string) (float64, bool) {
q := 1.0
for _, field := range params {
field = strings.TrimSpace(field)
if !strings.HasPrefix(field, "q=") {
continue
}
parsed, err := strconv.ParseFloat(strings.TrimPrefix(field, "q="), 64)
if err != nil || math.IsNaN(parsed) || math.IsInf(parsed, 0) || parsed < 0 || parsed > 1 {
return 0, false
}
q = parsed
}
return q, true
}
// T returns the message for key in locale, falling back to DefaultLocale and
// finally to the key itself. A missing key therefore degrades to
// visible-but-wrong rather than blank — the same contract as the frontend.
@@ -30,6 +30,44 @@
"share.toolOutput": "Tool output",
"share.toolOutputTruncated": "Tool output (truncated)",
"share.untitledTask": "Untitled task",
"startup.duration.minutes_one": "{{count}} minute",
"startup.duration.minutes_other": "{{count}} minutes",
"startup.duration.seconds_one": "{{count}} second",
"startup.duration.seconds_other": "{{count}} seconds",
"startup.page.countedProgress": "{{done}} of {{total}} {{unit}}",
"startup.page.countingProgress": "{{done}} {{unit}}",
"startup.page.elapsed": "{{duration}} elapsed",
"startup.page.eta": "About {{duration}} remaining",
"startup.page.lastKnown": "Last known",
"startup.page.progressUnavailable": "Progress cannot be measured for this step.",
"startup.page.stalled": "Stalled for {{duration}}",
"startup.page.title": "Kandev is starting",
"startup.page.waiting": "Kandev is starting and not yet reachable.",
"startup.phase.applying_migrations": "Applying migrations",
"startup.phase.backing_up_database": "Backing up database",
"startup.phase.initializing_services": "Initializing services",
"startup.phase.opening_database": "Opening database",
"startup.phase.ready": "Ready",
"startup.phase.recovering_sessions": "Recovering sessions",
"startup.step.database_backup": "Database backup",
"startup.step.message_timestamps": "Message timestamps",
"startup.step.prompt_seq": "Prompt sequence numbers",
"startup.step.session_recovery": "Session recovery",
"startup.step.stores_repositories": "Repository stores",
"startup.step.stores_services": "Service stores",
"startup.step.subagent_context": "Subagent context",
"startup.unit.bytes_one": "byte",
"startup.unit.bytes_other": "bytes",
"startup.unit.messages_one": "message",
"startup.unit.messages_other": "messages",
"startup.unit.rows_one": "row",
"startup.unit.rows_other": "rows",
"startup.unit.sessions_one": "session",
"startup.unit.sessions_other": "sessions",
"startup.unit.stores_one": "store",
"startup.unit.stores_other": "stores",
"startup.unit.turns_one": "turn",
"startup.unit.turns_other": "turns",
"webapp.assetReadFailed": "Could not read a web asset.",
"webapp.devServerUnavailable": "The Vite dev server is unavailable.",
"webapp.shellUnavailable": "The Kandev web app is unavailable."
@@ -30,6 +30,44 @@
"share.toolOutput": "Ţōōĺ ōũţƥũţ",
"share.toolOutputTruncated": "Ţōōĺ ōũţƥũţ (ţŕũńćàţēď)",
"share.untitledTask": "Ũńţĩţĺēď ţàśķ",
"startup.duration.minutes_one": "{{count}} ḿĩńũţē",
"startup.duration.minutes_other": "{{count}} ḿĩńũţēś",
"startup.duration.seconds_one": "{{count}} śēćōńď",
"startup.duration.seconds_other": "{{count}} śēćōńďś",
"startup.page.countedProgress": "{{done}} ōƒ {{total}} {{unit}}",
"startup.page.countingProgress": "{{done}} {{unit}}",
"startup.page.elapsed": "{{duration}} ēĺàƥśēď",
"startup.page.eta": "Àƀōũţ {{duration}} ŕēḿàĩńĩńĝ",
"startup.page.lastKnown": "Ĺàśţ ķńōŵń",
"startup.page.progressUnavailable": "Ƥŕōĝŕēśś ćàńńōţ ƀē ḿēàśũŕēď ƒōŕ ţĥĩś śţēƥ.",
"startup.page.stalled": "Śţàĺĺēď ƒōŕ {{duration}}",
"startup.page.title": "Ķàńďēv ĩś śţàŕţĩńĝ",
"startup.page.waiting": "Ķàńďēv ĩś śţàŕţĩńĝ àńď ńōţ ŷēţ ŕēàćĥàƀĺē.",
"startup.phase.applying_migrations": "Àƥƥĺŷĩńĝ ḿĩĝŕàţĩōńś",
"startup.phase.backing_up_database": "Ɓàćķĩńĝ ũƥ ďàţàƀàśē",
"startup.phase.initializing_services": "Ĩńĩţĩàĺĩźĩńĝ śēŕvĩćēś",
"startup.phase.opening_database": "Ōƥēńĩńĝ ďàţàƀàśē",
"startup.phase.ready": "Ŕēàďŷ",
"startup.phase.recovering_sessions": "Ŕēćōvēŕĩńĝ śēśśĩōńś",
"startup.step.database_backup": "Ďàţàƀàśē ƀàćķũƥ",
"startup.step.message_timestamps": "Ḿēśśàĝē ţĩḿēśţàḿƥś",
"startup.step.prompt_seq": "Ƥŕōḿƥţ śēqũēńćē ńũḿƀēŕś",
"startup.step.session_recovery": "Śēśśĩōń ŕēćōvēŕŷ",
"startup.step.stores_repositories": "Ŕēƥōśĩţōŕŷ śţōŕēś",
"startup.step.stores_services": "Śēŕvĩćē śţōŕēś",
"startup.step.subagent_context": "Śũƀàĝēńţ ćōńţēxţ",
"startup.unit.bytes_one": "ƀŷţē",
"startup.unit.bytes_other": "ƀŷţēś",
"startup.unit.messages_one": "ḿēśśàĝē",
"startup.unit.messages_other": "ḿēśśàĝēś",
"startup.unit.rows_one": "ŕōŵ",
"startup.unit.rows_other": "ŕōŵś",
"startup.unit.sessions_one": "śēśśĩōń",
"startup.unit.sessions_other": "śēśśĩōńś",
"startup.unit.stores_one": "śţōŕē",
"startup.unit.stores_other": "śţōŕēś",
"startup.unit.turns_one": "ţũŕń",
"startup.unit.turns_other": "ţũŕńś",
"webapp.assetReadFailed": "Ćōũĺď ńōţ ŕēàď à ŵēƀ àśśēţ.",
"webapp.devServerUnavailable": "Ţĥē Vĩţē ďēv śēŕvēŕ ĩś ũńàvàĩĺàƀĺē.",
"webapp.shellUnavailable": "Ţĥē Ķàńďēv ŵēƀ àƥƥ ĩś ũńàvàĩĺàƀĺē."
@@ -30,6 +30,44 @@
"share.toolOutput": "Saída da ferramenta",
"share.toolOutputTruncated": "Saída da ferramenta (truncada)",
"share.untitledTask": "Tarefa sem título",
"startup.duration.minutes_one": "{{count}} minuto",
"startup.duration.minutes_other": "{{count}} minutos",
"startup.duration.seconds_one": "{{count}} segundo",
"startup.duration.seconds_other": "{{count}} segundos",
"startup.page.countedProgress": "{{done}} de {{total}} {{unit}}",
"startup.page.countingProgress": "{{done}} {{unit}}",
"startup.page.elapsed": "Tempo decorrido: {{duration}}",
"startup.page.eta": "Tempo restante aproximado: {{duration}}",
"startup.page.lastKnown": "Último valor conhecido",
"startup.page.progressUnavailable": "Não é possível medir o progresso deste passo.",
"startup.page.stalled": "Parado há {{duration}}",
"startup.page.title": "O Kandev está a iniciar",
"startup.page.waiting": "O Kandev está a iniciar e ainda não está acessível.",
"startup.phase.applying_migrations": "A aplicar migrações",
"startup.phase.backing_up_database": "A fazer cópia de segurança da base de dados",
"startup.phase.initializing_services": "A inicializar serviços",
"startup.phase.opening_database": "A abrir a base de dados",
"startup.phase.ready": "Pronto",
"startup.phase.recovering_sessions": "A recuperar sessões",
"startup.step.database_backup": "Cópia de segurança da base de dados",
"startup.step.message_timestamps": "Carimbos de data/hora das mensagens",
"startup.step.prompt_seq": "Números de sequência de prompts",
"startup.step.session_recovery": "Recuperação de sessões",
"startup.step.stores_repositories": "Armazenamentos de repositórios",
"startup.step.stores_services": "Armazenamentos de serviços",
"startup.step.subagent_context": "Contexto de subagentes",
"startup.unit.bytes_one": "byte",
"startup.unit.bytes_other": "bytes",
"startup.unit.messages_one": "mensagem",
"startup.unit.messages_other": "mensagens",
"startup.unit.rows_one": "linha",
"startup.unit.rows_other": "linhas",
"startup.unit.sessions_one": "sessão",
"startup.unit.sessions_other": "sessões",
"startup.unit.stores_one": "armazenamento",
"startup.unit.stores_other": "armazenamentos",
"startup.unit.turns_one": "turno",
"startup.unit.turns_other": "turnos",
"webapp.assetReadFailed": "Não foi possível ler um recurso web.",
"webapp.devServerUnavailable": "O servidor de desenvolvimento do Vite não está disponível.",
"webapp.shellUnavailable": "A aplicação web do Kandev não está disponível."
@@ -30,6 +30,44 @@
"share.toolOutput": "工具输出",
"share.toolOutputTruncated": "工具输出(已截断)",
"share.untitledTask": "未命名任务",
"startup.duration.minutes_one": "{{count}} 分钟",
"startup.duration.minutes_other": "{{count}} 分钟",
"startup.duration.seconds_one": "{{count}} 秒",
"startup.duration.seconds_other": "{{count}} 秒",
"startup.page.countedProgress": "{{done}} / {{total}} {{unit}}",
"startup.page.countingProgress": "{{done}} {{unit}}",
"startup.page.elapsed": "已用时 {{duration}}",
"startup.page.eta": "预计还需 {{duration}}",
"startup.page.lastKnown": "最后已知状态",
"startup.page.progressUnavailable": "无法测量此步骤的进度。",
"startup.page.stalled": "已停滞 {{duration}}",
"startup.page.title": "Kandev 正在启动",
"startup.page.waiting": "Kandev 正在启动,尚无法访问。",
"startup.phase.applying_migrations": "正在应用迁移",
"startup.phase.backing_up_database": "正在备份数据库",
"startup.phase.initializing_services": "正在初始化服务",
"startup.phase.opening_database": "正在打开数据库",
"startup.phase.ready": "就绪",
"startup.phase.recovering_sessions": "正在恢复会话",
"startup.step.database_backup": "数据库备份",
"startup.step.message_timestamps": "消息时间戳",
"startup.step.prompt_seq": "提示序列号",
"startup.step.session_recovery": "会话恢复",
"startup.step.stores_repositories": "仓库存储",
"startup.step.stores_services": "服务存储",
"startup.step.subagent_context": "子智能体上下文",
"startup.unit.bytes_one": "字节",
"startup.unit.bytes_other": "字节",
"startup.unit.messages_one": "条消息",
"startup.unit.messages_other": "条消息",
"startup.unit.rows_one": "行",
"startup.unit.rows_other": "行",
"startup.unit.sessions_one": "个会话",
"startup.unit.sessions_other": "个会话",
"startup.unit.stores_one": "个存储",
"startup.unit.stores_other": "个存储",
"startup.unit.turns_one": "个轮次",
"startup.unit.turns_other": "个轮次",
"webapp.assetReadFailed": "无法读取网页资源。",
"webapp.devServerUnavailable": "Vite 开发服务器不可用。",
"webapp.shellUnavailable": "Kandev Web 应用不可用。"
@@ -30,6 +30,44 @@
"share.toolOutput": "工具輸出",
"share.toolOutputTruncated": "工具輸出(已截斷)",
"share.untitledTask": "未命名任務",
"startup.duration.minutes_one": "{{count}} 分鐘",
"startup.duration.minutes_other": "{{count}} 分鐘",
"startup.duration.seconds_one": "{{count}} 秒",
"startup.duration.seconds_other": "{{count}} 秒",
"startup.page.countedProgress": "{{done}} / {{total}} {{unit}}",
"startup.page.countingProgress": "{{done}} {{unit}}",
"startup.page.elapsed": "已用時 {{duration}}",
"startup.page.eta": "預計還需 {{duration}}",
"startup.page.lastKnown": "最後已知狀態",
"startup.page.progressUnavailable": "無法測量此步驟的進度。",
"startup.page.stalled": "已停滯 {{duration}}",
"startup.page.title": "Kandev 正在啓動",
"startup.page.waiting": "Kandev 正在啓動,尚無法存取。",
"startup.phase.applying_migrations": "正在應用遷移",
"startup.phase.backing_up_database": "正在備份數據庫",
"startup.phase.initializing_services": "正在初始化服務",
"startup.phase.opening_database": "正在開啟數據庫",
"startup.phase.ready": "就緒",
"startup.phase.recovering_sessions": "正在恢復工作階段",
"startup.step.database_backup": "數據庫備份",
"startup.step.message_timestamps": "訊息時間戳",
"startup.step.prompt_seq": "提示序列號",
"startup.step.session_recovery": "工作階段恢復",
"startup.step.stores_repositories": "儲存庫存儲",
"startup.step.stores_services": "服務存儲",
"startup.step.subagent_context": "子代理程式上下文",
"startup.unit.bytes_one": "字節",
"startup.unit.bytes_other": "字節",
"startup.unit.messages_one": "條訊息",
"startup.unit.messages_other": "條訊息",
"startup.unit.rows_one": "行",
"startup.unit.rows_other": "行",
"startup.unit.sessions_one": "個工作階段",
"startup.unit.sessions_other": "個工作階段",
"startup.unit.stores_one": "個存儲",
"startup.unit.stores_other": "個存儲",
"startup.unit.turns_one": "個輪次",
"startup.unit.turns_other": "個輪次",
"webapp.assetReadFailed": "無法讀取網頁資源。",
"webapp.devServerUnavailable": "Vite 開發伺服器不可用。",
"webapp.shellUnavailable": "Kandev Web 應用不可用。"
@@ -30,6 +30,44 @@
"share.toolOutput": "工具輸出",
"share.toolOutputTruncated": "工具輸出(已截斷)",
"share.untitledTask": "未命名任務",
"startup.duration.minutes_one": "{{count}} 分鐘",
"startup.duration.minutes_other": "{{count}} 分鐘",
"startup.duration.seconds_one": "{{count}} 秒",
"startup.duration.seconds_other": "{{count}} 秒",
"startup.page.countedProgress": "{{done}} / {{total}} {{unit}}",
"startup.page.countingProgress": "{{done}} {{unit}}",
"startup.page.elapsed": "已用時 {{duration}}",
"startup.page.eta": "預計還需 {{duration}}",
"startup.page.lastKnown": "最後已知狀態",
"startup.page.progressUnavailable": "無法測量此步驟的進度。",
"startup.page.stalled": "已停滯 {{duration}}",
"startup.page.title": "Kandev 正在啟動",
"startup.page.waiting": "Kandev 正在啟動,尚無法存取。",
"startup.phase.applying_migrations": "正在應用遷移",
"startup.phase.backing_up_database": "正在備份資料庫",
"startup.phase.initializing_services": "正在初始化服務",
"startup.phase.opening_database": "正在開啟資料庫",
"startup.phase.ready": "就緒",
"startup.phase.recovering_sessions": "正在恢復工作階段",
"startup.step.database_backup": "資料庫備份",
"startup.step.message_timestamps": "訊息時間戳",
"startup.step.prompt_seq": "提示序列號",
"startup.step.session_recovery": "工作階段恢復",
"startup.step.stores_repositories": "儲存庫儲存",
"startup.step.stores_services": "服務儲存",
"startup.step.subagent_context": "子代理程式上下文",
"startup.unit.bytes_one": "位元組",
"startup.unit.bytes_other": "位元組",
"startup.unit.messages_one": "條訊息",
"startup.unit.messages_other": "條訊息",
"startup.unit.rows_one": "行",
"startup.unit.rows_other": "行",
"startup.unit.sessions_one": "個工作階段",
"startup.unit.sessions_other": "個工作階段",
"startup.unit.stores_one": "個儲存",
"startup.unit.stores_other": "個儲存",
"startup.unit.turns_one": "個輪次",
"startup.unit.turns_other": "個輪次",
"webapp.assetReadFailed": "無法讀取網頁資源。",
"webapp.devServerUnavailable": "Vite 開發伺服器不可用。",
"webapp.shellUnavailable": "Kandev Web 應用不可用。"
+83 -6
View File
@@ -15,6 +15,7 @@ import (
"time"
"github.com/kandev/kandev/internal/common/config"
"github.com/kandev/kandev/internal/i18n"
"github.com/kandev/kandev/internal/startup"
)
@@ -23,6 +24,12 @@ const (
healthProbeTimeout = 2 * time.Second
)
// startupProgressReportFloor is the maximum interval between AC-PLATFORM-
// STARTUP-PROGRESS-003.5 progress lines when neither phase, sequence number,
// nor stall state has changed. A package-level var (not const) so tests can
// override it instead of waiting out 15 real seconds.
var startupProgressReportFloor = 15 * time.Second
// healthProbeClient bounds every individual health request. http.DefaultClient
// has no timeout, so a backend that accepts the connection but never answers
// would otherwise block the launcher forever. Launcher readiness is local to
@@ -362,27 +369,38 @@ func safeProbeError(err error) string {
// in flight. Do not fold this into waitForHealth's timeout — that would
// recreate the crash loop docs/specs/startup-listener-before-recovery/spec.md
// exists to fix.
//
// Per AC-PLATFORM-STARTUP-PROGRESS-003.5, a line is written on a phase
// change, a sequence-number change (every step start/end), or a stall-state
// transition, and otherwise at most once per startupProgressReportFloor.
func waitForReady(ctx context.Context, baseURL string, proc childState) error {
readyURL := baseURL + "/ready"
var last startup.Snapshot
var lastStalled bool
var reported time.Time
exitError := func(code int) error {
if label := last.Phase.Label(); label != "" {
return fmt.Errorf("backend exited (code %d) during %s (elapsed %.1fs); check backend logs for the initialization error", code, label, float64(last.ElapsedMS)/1000)
label := last.Phase.Label()
if label == "" {
return fmt.Errorf("backend exited (code %d) before it reported ready; check backend logs for the initialization error", code)
}
return fmt.Errorf("backend exited (code %d) before it reported ready; check backend logs for the initialization error", code)
if last.Step != nil {
label = fmt.Sprintf("%s (%s)", label, i18n.T(i18n.DefaultLocale, last.Step.LabelKey))
}
return fmt.Errorf("backend exited (code %d) during %s (elapsed %.1fs); check backend logs for the initialization error", code, label, float64(last.ElapsedMS)/1000)
}
for ctx.Err() == nil {
if exited, code := proc.Exited(); exited {
return exitError(code)
}
isReady, snapshot := probeReadyStatus(ctx, readyURL)
isReady, snapshot := probeReadyStatusFn(ctx, readyURL)
if snapshot.Phase.Label() != "" {
if snapshot.Phase != last.Phase || time.Since(reported) >= 15*time.Second {
fmt.Fprintf(os.Stderr, "[kandev] %s (elapsed %.1fs; phase %.1fs)\n", snapshot.Phase.Label(), float64(snapshot.ElapsedMS)/1000, float64(snapshot.PhaseElapsedMS)/1000)
stalled := snapshot.Step != nil && snapshot.Step.Stalled
if snapshot.Phase != last.Phase || snapshot.Seq != last.Seq || stalled != lastStalled || time.Since(reported) >= startupProgressReportFloor {
fmt.Fprintf(os.Stderr, "[kandev] %s\n", formatStartupLine(snapshot))
reported = time.Now()
}
last = snapshot
lastStalled = stalled
}
if isReady {
if err := ctx.Err(); err != nil {
@@ -401,6 +419,60 @@ func waitForReady(ctx context.Context, baseURL string, proc childState) error {
return fmt.Errorf("backend readiness wait canceled at %s: %w", readyURL, ctx.Err())
}
// formatStartupLine renders one AC-PLATFORM-STARTUP-PROGRESS-003.5 progress
// line: phase, elapsed time, and — when a step is active — its name plus
// whichever of done, total, rate, and estimate the snapshot carries, rather
// than only for a `counted` step, since a `counting` step (for example
// database.backup) carries a done count and a rate with no total. An opaque
// step states plainly that it cannot report progress
// (AC-PLATFORM-STARTUP-PROGRESS-001.5) instead of a bar at any position, and
// a stalled step states how long it has gone without progress
// (AC-PLATFORM-STARTUP-PROGRESS-004.6).
func formatStartupLine(snapshot startup.Snapshot) string {
line := fmt.Sprintf("%s (elapsed %.1fs; phase %.1fs)", snapshot.Phase.Label(), float64(snapshot.ElapsedMS)/1000, float64(snapshot.PhaseElapsedMS)/1000)
step := snapshot.Step
if step == nil {
return line
}
name := i18n.T(i18n.DefaultLocale, step.LabelKey)
if step.Measure == startup.MeasureOpaque {
return fmt.Sprintf("%s: %s (progress not available)", line, name)
}
detail := name
switch {
case step.Done != nil && step.Total != nil:
detail += fmt.Sprintf(": %d/%d", *step.Done, *step.Total)
case step.Done != nil:
detail += fmt.Sprintf(": %d", *step.Done)
}
if step.RatePerSecond != nil {
detail += fmt.Sprintf(" (%.1f/s)", *step.RatePerSecond)
}
if step.ETAMS != nil {
detail += fmt.Sprintf(", ~%s remaining", formatDurationEstimate(*step.ETAMS))
}
if step.Stalled && step.SinceAdvanceMS != nil {
detail += fmt.Sprintf(", stalled for %s", formatDurationEstimate(*step.SinceAdvanceMS))
}
return fmt.Sprintf("%s: %s", line, detail)
}
// formatDurationEstimate renders a millisecond duration per
// AC-PLATFORM-STARTUP-PROGRESS-003.10: 60000ms or less renders in whole
// seconds rounded up with a floor of one second, anything longer in whole
// minutes rounded up, never sub-second.
func formatDurationEstimate(ms int64) string {
if ms <= 60000 {
seconds := (ms + 999) / 1000
if seconds < 1 {
seconds = 1
}
return fmt.Sprintf("%ds", seconds)
}
minutes := (ms + 59999) / 60000
return fmt.Sprintf("%dm", minutes)
}
// probeReady reports whether a single readiness request returned 2xx. Unlike
// probeHealth, it does not check the desktop health token: readyHandler never
// sets X-Kandev-Desktop-Health-Token (that header is /health-only, see
@@ -410,6 +482,11 @@ func probeReady(ctx context.Context, readyURL string) bool {
return ready
}
// probeReadyStatusFn is a seam for waitForReady's polling loop, overridden in
// tests that need a synctest-safe stub: real HTTP I/O sits outside the
// synctest fake-time bubble and would prevent synctest.Wait from settling.
var probeReadyStatusFn = probeReadyStatus
func probeReadyStatus(ctx context.Context, readyURL string) (bool, startup.Snapshot) {
var body struct {
Startup startup.Snapshot `json:"startup"`
@@ -0,0 +1,275 @@
package launcher
import (
"bytes"
"context"
"io"
"net/http"
"net/http/httptest"
"os"
"strings"
"testing"
"testing/synctest"
"time"
"github.com/kandev/kandev/internal/startup"
)
// TestFormatDurationEstimate covers AC-PLATFORM-STARTUP-PROGRESS-003.10: 60s
// or less renders in whole seconds rounded up with a floor of one second, a
// longer duration renders in whole minutes rounded up, never sub-second.
func TestFormatDurationEstimate(t *testing.T) {
cases := []struct {
ms int64
want string
}{
{ms: 1, want: "1s"},
{ms: 999, want: "1s"},
{ms: 1000, want: "1s"},
{ms: 1001, want: "2s"},
{ms: 60000, want: "60s"},
{ms: 60001, want: "2m"},
{ms: 90000, want: "2m"},
{ms: 120000, want: "2m"},
}
for _, tc := range cases {
if got := formatDurationEstimate(tc.ms); got != tc.want {
t.Errorf("formatDurationEstimate(%d) = %q, want %q", tc.ms, got, tc.want)
}
}
}
// TestFormatStartupLineNoStep covers AC-PLATFORM-STARTUP-PROGRESS-003.13-
// adjacent behavior for the launcher: with no active step the line carries
// only phase and elapsed time.
func TestFormatStartupLineNoStep(t *testing.T) {
snapshot := startup.Snapshot{Phase: startup.OpeningDatabase, ElapsedMS: 1500, PhaseElapsedMS: 500}
got := formatStartupLine(snapshot)
want := "Opening database (elapsed 1.5s; phase 0.5s)"
if got != want {
t.Fatalf("formatStartupLine() = %q, want %q", got, want)
}
}
// TestFormatStartupLineOpaqueStepStatesProgressUnavailable covers F74/
// AC-PLATFORM-STARTUP-PROGRESS-001.5: an opaque step never carries done or
// total, and the launcher line states plainly that it cannot report
// progress rather than showing a bar at any position.
func TestFormatStartupLineOpaqueStepStatesProgressUnavailable(t *testing.T) {
snapshot := startup.Snapshot{
Phase: startup.InitializingServices, ElapsedMS: 2000, PhaseElapsedMS: 1000,
Step: &startup.StepSnapshot{LabelKey: "startup.step.prompt_seq", Measure: startup.MeasureOpaque},
}
got := formatStartupLine(snapshot)
want := "Initializing services (elapsed 2.0s; phase 1.0s): Prompt sequence numbers (progress not available)"
if got != want {
t.Fatalf("formatStartupLine() = %q, want %q", got, want)
}
}
// TestFormatStartupLineCountingStepWithNoTotal covers the design's
// database.backup example: a `counting` step carries a done count and a
// rate with no total, and the line must gain both rather than waiting for a
// `counted` step.
func TestFormatStartupLineCountingStepWithNoTotal(t *testing.T) {
done := int64(42)
rate := 3.5
snapshot := startup.Snapshot{
Phase: startup.BackingUpDatabase, ElapsedMS: 5000, PhaseElapsedMS: 5000,
Step: &startup.StepSnapshot{
LabelKey: "startup.step.database_backup", Measure: startup.MeasureCounting,
Done: &done, RatePerSecond: &rate,
},
}
got := formatStartupLine(snapshot)
want := "Backing up database (elapsed 5.0s; phase 5.0s): Database backup: 42 (3.5/s)"
if got != want {
t.Fatalf("formatStartupLine() = %q, want %q", got, want)
}
}
// TestFormatStartupLineCountedStepWithEstimate covers the full counted case:
// done, total, rate, and estimate all present.
func TestFormatStartupLineCountedStepWithEstimate(t *testing.T) {
done, total := int64(12), int64(50)
rate := 2.0
eta := int64(19000)
snapshot := startup.Snapshot{
Phase: startup.RecoveringSessions, ElapsedMS: 6000, PhaseElapsedMS: 6000,
Step: &startup.StepSnapshot{
LabelKey: "startup.step.session_recovery", Measure: startup.MeasureCounted,
Done: &done, Total: &total, RatePerSecond: &rate, ETAMS: &eta,
},
}
got := formatStartupLine(snapshot)
want := "Recovering sessions (elapsed 6.0s; phase 6.0s): Session recovery: 12/50 (2.0/s), ~19s remaining"
if got != want {
t.Fatalf("formatStartupLine() = %q, want %q", got, want)
}
}
// TestFormatStartupLineStalledStepStatesDuration covers F75/
// AC-PLATFORM-STARTUP-PROGRESS-004.6: a stalled step states how long it has
// gone without progress.
func TestFormatStartupLineStalledStepStatesDuration(t *testing.T) {
done, total := int64(3), int64(10)
sinceAdvance := int64(125000)
snapshot := startup.Snapshot{
Phase: startup.RecoveringSessions, ElapsedMS: 130000, PhaseElapsedMS: 130000,
Step: &startup.StepSnapshot{
LabelKey: "startup.step.session_recovery", Measure: startup.MeasureCounted,
Done: &done, Total: &total, SinceAdvanceMS: &sinceAdvance, Stalled: true,
},
}
got := formatStartupLine(snapshot)
want := "Recovering sessions (elapsed 130.0s; phase 130.0s): Session recovery: 3/10, stalled for 3m"
if got != want {
t.Fatalf("formatStartupLine() = %q, want %q", got, want)
}
}
// TestFormatStartupLineNonStalledStepOmitsStallStatement is the negative
// case for the same AC: a step short of the stall threshold prints no
// stall statement at all.
func TestFormatStartupLineNonStalledStepOmitsStallStatement(t *testing.T) {
done, total := int64(3), int64(10)
sinceAdvance := int64(500)
snapshot := startup.Snapshot{
Phase: startup.RecoveringSessions, ElapsedMS: 1000, PhaseElapsedMS: 1000,
Step: &startup.StepSnapshot{
LabelKey: "startup.step.session_recovery", Measure: startup.MeasureCounted,
Done: &done, Total: &total, SinceAdvanceMS: &sinceAdvance, Stalled: false,
},
}
got := formatStartupLine(snapshot)
if strings.Contains(got, "stalled") {
t.Fatalf("formatStartupLine() = %q, want no stall statement below the threshold", got)
}
}
// TestReadinessExitNamesLastObservedStep covers AC-PLATFORM-STARTUP-
// PROGRESS-003.6: when the backend exits during startup, the launcher names
// the last observed step as well as the last observed phase.
func TestReadinessExitNamesLastObservedStep(t *testing.T) {
var child toggledChild
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusServiceUnavailable)
_, _ = w.Write([]byte(`{"status":"starting","startup":{"phase":"recovering_sessions","elapsed_ms":1234,"phase_elapsed_ms":1000,"step":{"id":"sessions.recovery","label_key":"startup.step.session_recovery","measure":"counted","unit":"sessions","elapsed_ms":1000,"done":3,"total":10,"stalled":false}}}`))
child.code.Store(3)
child.exited.Store(true)
}))
defer srv.Close()
err := waitForReady(context.Background(), srv.URL, &child)
if err == nil || !strings.Contains(err.Error(), "Recovering sessions") {
t.Fatalf("missing startup phase in error: %v", err)
}
if !strings.Contains(err.Error(), "Session recovery") {
t.Fatalf("error = %v, want it to name the last observed step", err)
}
}
// TestWaitForReadyReprintsOnReportFloorWithoutOtherChanges covers
// AC-PLATFORM-STARTUP-PROGRESS-003.5's floor trigger: with phase, seq, and
// stall state all unchanged, a line is written again only once
// startupProgressReportFloor has elapsed since the last one, and not on
// every intervening poll. Stubs probeReadyStatusFn rather than using a real
// httptest.Server: real HTTP I/O sits outside synctest's fake-time bubble
// and would prevent the 15-second floor from fast-forwarding (see
// internal/system/updates/service_test.go's TestService_StartPoller_
// TicksEvery6h for the same convention).
func TestWaitForReadyReprintsOnReportFloorWithoutOtherChanges(t *testing.T) {
synctest.Test(t, func(t *testing.T) {
oldProbe := probeReadyStatusFn
t.Cleanup(func() { probeReadyStatusFn = oldProbe })
start := time.Now()
probeReadyStatusFn = func(context.Context, string) (bool, startup.Snapshot) {
if time.Since(start) >= 40*time.Second {
return true, startup.Snapshot{}
}
return false, startup.Snapshot{Phase: startup.RecoveringSessions, Seq: 1, ElapsedMS: 1, PhaseElapsedMS: 1}
}
var err error
output := captureStderr(t, func() {
err = waitForReady(context.Background(), "http://probe.invalid", fakeChild{})
})
if err != nil {
t.Fatalf("waitForReady() = %v, want nil", err)
}
lines := strings.Count(output, "Recovering sessions")
if lines != 3 {
t.Fatalf("stderr output = %q, want exactly 3 progress lines (initial + two floor reprints at 15s and 30s), got %d", output, lines)
}
})
}
// captureStderr swaps os.Stderr for the duration of fn and returns what was
// written to it. The launcher test package never runs tests in parallel, so
// this global swap is safe.
func captureStderr(t *testing.T, fn func()) string {
t.Helper()
read, write, err := os.Pipe()
if err != nil {
t.Fatalf("os.Pipe() = %v", err)
}
oldStderr := os.Stderr
os.Stderr = write
defer func() { os.Stderr = oldStderr }()
fn()
if err := write.Close(); err != nil {
t.Fatalf("close stderr writer: %v", err)
}
var output bytes.Buffer
if _, err := io.Copy(&output, read); err != nil {
t.Fatalf("read captured stderr: %v", err)
}
if err := read.Close(); err != nil {
t.Fatalf("close stderr reader: %v", err)
}
return output.String()
}
// TestWaitForReadyReprintsOnSeqChangeWithoutPhaseChange covers
// AC-PLATFORM-STARTUP-PROGRESS-003.5's sequence-number trigger: a step
// beginning or ending bumps `seq` without necessarily changing phase, and
// that alone must produce an immediate line rather than waiting for the
// 15-second floor or a phase change.
func TestWaitForReadyReprintsOnSeqChangeWithoutPhaseChange(t *testing.T) {
var calls int
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
calls++
switch calls {
case 1:
w.WriteHeader(http.StatusServiceUnavailable)
_, _ = w.Write([]byte(`{"startup":{"phase":"recovering_sessions","seq":1,"elapsed_ms":1,"phase_elapsed_ms":1}}`))
case 2:
// Same phase, same seq: within the 15s floor, no reprint expected.
w.WriteHeader(http.StatusServiceUnavailable)
_, _ = w.Write([]byte(`{"startup":{"phase":"recovering_sessions","seq":1,"elapsed_ms":2,"phase_elapsed_ms":2}}`))
case 3:
// seq bumped (a step ended) with no phase change: must reprint.
w.WriteHeader(http.StatusServiceUnavailable)
_, _ = w.Write([]byte(`{"startup":{"phase":"recovering_sessions","seq":2,"elapsed_ms":3,"phase_elapsed_ms":3}}`))
default:
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte(`{"status":"ok"}`))
}
}))
t.Cleanup(srv.Close)
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
var err error
output := captureStderr(t, func() {
err = waitForReady(ctx, srv.URL, fakeChild{})
})
if err != nil {
t.Fatalf("waitForReady() = %v, want nil", err)
}
lines := strings.Count(output, "Recovering sessions")
if lines != 2 {
t.Fatalf("stderr output = %q, want exactly 2 progress lines (initial + seq change), got %d", output, lines)
}
}
@@ -299,13 +299,13 @@ func (s *Sweeper) sweepRuns(ctx context.Context, q queryer, cfg TableSettings, n
}}, satelliteResults{}
}
return SweptTableResult{TableSweepResult: TableSweepResult{
Deleted: result.RunsDeleted,
Backlog: eligible > int64(batchLimit),
}}, satelliteResults{
RunEvents: TableSweepResult{Deleted: result.RunEventsDeleted},
RouteAttempts: TableSweepResult{Deleted: result.RouteAttemptsDeleted},
RunSkills: TableSweepResult{Deleted: result.RunSkillsDeleted},
}
Deleted: result.RunsDeleted,
Backlog: eligible > int64(batchLimit),
}}, satelliteResults{
RunEvents: TableSweepResult{Deleted: result.RunEventsDeleted},
RouteAttempts: TableSweepResult{Deleted: result.RouteAttemptsDeleted},
RunSkills: TableSweepResult{Deleted: result.RunSkillsDeleted},
}
}
// retentionCutoff turns a table's configured window into the instant a
@@ -0,0 +1,121 @@
package persistence
import (
"context"
"os"
"path/filepath"
"testing"
"testing/synctest"
"time"
"github.com/kandev/kandev/internal/startup"
)
func newBackupStepContext() (context.Context, *startup.Reporter) {
r := startup.New(nil)
ctx := startup.WithReporter(context.Background(), r)
startup.BeginStep(ctx, startup.StepDatabaseBackup)
return ctx, r
}
func TestReportBackupProgressAdvancesOnSizeIncrease(t *testing.T) {
ctx, r := newBackupStepContext()
path := filepath.Join(t.TempDir(), "staging.db")
if err := os.WriteFile(path, make([]byte, 100), 0o600); err != nil {
t.Fatalf("write staged file: %v", err)
}
lastSize, degraded := reportBackupProgress(ctx, path, 0, false)
if lastSize != 100 {
t.Fatalf("lastSize = %d, want 100", lastSize)
}
if degraded {
t.Fatal("degraded = true, want false")
}
snap := r.Snapshot()
if snap.Step == nil || snap.Step.Done == nil || *snap.Step.Done != 100 {
t.Fatalf("Step = %+v, want Done=100", snap.Step)
}
if err := os.WriteFile(path, make([]byte, 100), 0o600); err != nil {
t.Fatalf("rewrite staged file: %v", err)
}
lastSize, degraded = reportBackupProgress(ctx, path, lastSize, degraded)
if lastSize != 100 {
t.Fatalf("lastSize after unchanged size = %d, want 100 (no regression, no duplicate advance)", lastSize)
}
if degraded {
t.Fatal("degraded = true after unchanged size, want false")
}
}
func TestReportBackupProgressIgnoresMissingFile(t *testing.T) {
ctx, r := newBackupStepContext()
path := filepath.Join(t.TempDir(), "not-yet-created.db")
lastSize, degraded := reportBackupProgress(ctx, path, 0, false)
if lastSize != 0 {
t.Fatalf("lastSize = %d, want 0 (VACUUM INTO has not created the file yet)", lastSize)
}
if degraded {
t.Fatal("degraded = true on ENOENT, want false: not yet started is not a measurement failure")
}
if snap := r.Snapshot(); snap.Step == nil || snap.Step.Done == nil || *snap.Step.Done != 0 {
t.Fatalf("Step = %+v, want Done=0 (no advance recorded)", r.Snapshot().Step)
}
}
func TestReportBackupProgressDegradesOnceOnRealStatError(t *testing.T) {
ctx, _ := newBackupStepContext()
// Stat-ing a path under a regular file (not a directory) fails with
// ENOTDIR, which os.IsNotExist reports as false - a genuine stat error
// distinct from "VACUUM INTO has not created the file yet".
regularFile := filepath.Join(t.TempDir(), "not-a-directory")
if err := os.WriteFile(regularFile, []byte("x"), 0o600); err != nil {
t.Fatalf("write regular file: %v", err)
}
path := filepath.Join(regularFile, "staging.db")
lastSize, degraded := reportBackupProgress(ctx, path, 0, false)
if !degraded {
t.Fatal("degraded = false after a real stat error, want true")
}
if lastSize != 0 {
t.Fatalf("lastSize = %d, want 0", lastSize)
}
// A second tick against the same failing path must not degrade again
// (Degrade only warns once per activation; this call proves the helper
// itself does not re-invoke it once already degraded).
lastSize, degraded = reportBackupProgress(ctx, path, lastSize, degraded)
if !degraded {
t.Fatal("degraded flag reset itself, want it to stay true")
}
if lastSize != 0 {
t.Fatalf("lastSize = %d, want 0", lastSize)
}
}
func TestTrackBackupProgressReportsGrowthAndStopsCleanly(t *testing.T) {
synctest.Test(t, func(t *testing.T) {
ctx, r := newBackupStepContext()
path := filepath.Join(t.TempDir(), "staging.db")
stop := trackBackupProgress(ctx, path)
if err := os.WriteFile(path, make([]byte, 42), 0o600); err != nil {
t.Fatalf("write staged file: %v", err)
}
time.Sleep(backupProgressTickInterval)
synctest.Wait()
snap := r.Snapshot()
if snap.Step == nil || snap.Step.Done == nil || *snap.Step.Done != 42 {
t.Fatalf("Step = %+v, want Done=42 after one tick", snap.Step)
}
stop()
synctest.Wait()
})
}
@@ -105,7 +105,9 @@ func provideSQLite(ctx context.Context, cfg *config.Config, log *logger.Logger,
_ = pool.Close()
return nil, nil, fmt.Errorf("create backup dir: %w", err)
}
startup.BeginStep(ctx, startup.StepDatabaseBackup)
path, size, err := createPreMigrationBackup(ctx, writer, backupDir, storedVersion)
startup.EndStep(ctx, startup.StepDatabaseBackup)
if err != nil {
_ = pool.Close()
return nil, nil, err
@@ -150,7 +152,9 @@ func createPreMigrationBackup(ctx context.Context, writer *sqlx.DB, backupDir, s
defer func() { _ = os.RemoveAll(stagingDir) }()
stagedPath := filepath.Join(stagingDir, filepath.Base(path))
stopTracking := trackBackupProgress(ctx, stagedPath)
size, err := snapshotSQLiteContext(ctx, writer, stagedPath)
stopTracking()
if err != nil {
return "", 0, fmt.Errorf("pre-migration backup failed: %w", err)
}
@@ -172,6 +176,60 @@ func createPreMigrationBackup(ctx context.Context, writer *sqlx.DB, backupDir, s
return path, size, nil
}
// backupProgressTickInterval is how often trackBackupProgress stats the
// staging file. VACUUM INTO gives no row-level progress, so this is the only
// signal the counting step has.
const backupProgressTickInterval = 250 * time.Millisecond
// trackBackupProgress polls stagedPath's size while a VACUUM INTO writes it
// and reports the increase to the database.backup step. VACUUM INTO creates
// the file only once it starts writing, so ENOENT before that point is
// expected and not a measurement failure; any other stat error degrades the
// step once, not on every tick. The returned stop function cancels the
// goroutine and waits for it to exit before returning.
func trackBackupProgress(ctx context.Context, stagedPath string) func() {
tickerCtx, cancel := context.WithCancel(ctx)
stopped := make(chan struct{})
go func() {
defer close(stopped)
ticker := time.NewTicker(backupProgressTickInterval)
defer ticker.Stop()
var lastSize int64
var degraded bool
for {
select {
case <-tickerCtx.Done():
return
case <-ticker.C:
lastSize, degraded = reportBackupProgress(ctx, stagedPath, lastSize, degraded)
}
}
}()
return func() {
cancel()
<-stopped
}
}
// reportBackupProgress stats stagedPath once and advances the step by the
// size increase since lastSize, returning the updated size and degraded
// state for the next tick.
func reportBackupProgress(ctx context.Context, stagedPath string, lastSize int64, degraded bool) (int64, bool) {
info, err := os.Stat(stagedPath)
if err != nil {
if !os.IsNotExist(err) && !degraded {
startup.Degrade(ctx, startup.StepDatabaseBackup)
degraded = true
}
return lastSize, degraded
}
if delta := info.Size() - lastSize; delta > 0 {
startup.Advance(ctx, startup.StepDatabaseBackup, delta)
lastSize = info.Size()
}
return lastSize, degraded
}
func providePostgres(cfg *config.Config, log *logger.Logger) (*db.Pool, func() error, error) {
dsn := cfg.Database.DSN()
dbConn, err := db.OpenPostgres(dsn, cfg.Database.MaxConns, cfg.Database.MinConns)
@@ -5,6 +5,8 @@ package requiredstores
import (
"fmt"
"strings"
"github.com/kandev/kandev/internal/startup"
)
// Capability identifies a SQL behavior that a store conformance adapter must
@@ -25,6 +27,19 @@ var validCapabilities = map[Capability]struct{}{
CapabilityTransaction: {},
}
// Store IDs referenced from multiple catalog entries, either as their own ID
// or as another entry's DependsOn, kept as constants so the two never drift.
const (
storeIDSchemaMeta = "schema-meta"
storeIDTask = "task"
storeIDWorkflow = "workflow"
storeIDAgentSettings = "agent-settings"
storeIDUser = "user"
storeIDPluginInstances = "plugin-instances"
pkgPluginsState = "internal/plugins/state"
)
// Descriptor is the immutable metadata for one built-in SQL schema owner.
// RequiredTables are the table names used by runtime persistence probes.
type Descriptor struct {
@@ -33,53 +48,61 @@ type Descriptor struct {
RequiredTables []string
DependsOn []string
Capabilities []Capability
// Sweep names which store-admission startup step (stores.repositories or
// stores.services) claims this entry's `recordRequiredStore` call. Runtime
// admission order decides the owner, not file or definition line, so this
// is the single declared source both sweeps' totals read at BeginStep and
// what the catalog/registry completeness check asserts is total and
// non-overlapping.
Sweep startup.StepID
}
// catalog is ordered in the same dependency order used by backend startup.
// Keep entries for stores whose feature is disabled: their schema remains part
// of the database contract and must be initialized before readiness.
var catalog = []Descriptor{
{ID: "schema-meta", OwnerPackage: "internal/persistence", RequiredTables: []string{"kandev_meta"}},
{ID: "task", OwnerPackage: "internal/task/repository/sqlite", RequiredTables: []string{"workspaces", "tasks", "task_workflow_session_bindings"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}},
{ID: "workflow", OwnerPackage: "internal/workflow/repository", RequiredTables: []string{"workflow_templates", "workflow_steps"}, DependsOn: []string{"task"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}},
{ID: "analytics", OwnerPackage: "internal/analytics/repository", RequiredTables: []string{"tasks"}, DependsOn: []string{"task", "workflow"}, Capabilities: []Capability{CapabilityTimestamp}},
{ID: "agent-settings", OwnerPackage: "internal/agent/settings/store", RequiredTables: []string{"agents", "agent_profiles"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "user", OwnerPackage: "internal/user/store", RequiredTables: []string{"users"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "notification", OwnerPackage: "internal/notifications/store", RequiredTables: []string{"notification_providers"}, DependsOn: []string{"user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "editor", OwnerPackage: "internal/editors/store", RequiredTables: []string{"editors"}, DependsOn: []string{"user"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}},
{ID: "prompts", OwnerPackage: "internal/prompts/store", RequiredTables: []string{"custom_prompts"}, DependsOn: []string{"user"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}},
{ID: "utility", OwnerPackage: "internal/utility/store", RequiredTables: []string{"utility_agents"}, DependsOn: []string{"agent-settings"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "office", OwnerPackage: "internal/office/repository/sqlite", RequiredTables: []string{"office_projects", "runs"}, DependsOn: []string{"task", "agent-settings"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}},
{ID: "terminal", OwnerPackage: "internal/terminal/repository", RequiredTables: []string{"user_terminals"}, DependsOn: []string{"user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "quick-terminal", OwnerPackage: "internal/quickterminal/repository", RequiredTables: []string{"quick_terminal_tabs"}, DependsOn: []string{"user"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}},
{ID: "runtime-flags", OwnerPackage: "internal/runtimeflags", RequiredTables: []string{"runtime_flag_overrides"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "auth", OwnerPackage: "internal/auth/store", RequiredTables: []string{"auth_identities", "auth_sessions"}, DependsOn: []string{"user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}},
{ID: "secrets", OwnerPackage: "internal/secrets", RequiredTables: []string{"secrets"}, DependsOn: []string{"task"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}},
{ID: "system-settings", OwnerPackage: "internal/system/settings", RequiredTables: []string{"settings"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}},
{ID: "auth-hostnames", OwnerPackage: "internal/auth/hostnames", RequiredTables: []string{"auth_hostname_cache"}, DependsOn: []string{"auth"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}},
{ID: "organizations", OwnerPackage: "internal/org", RequiredTables: []string{"orgs"}, DependsOn: []string{"user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "organization-units", OwnerPackage: "internal/orgunit", RequiredTables: []string{"org_units"}, DependsOn: []string{"organizations"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}},
{ID: "message-queue", OwnerPackage: "internal/orchestrator/messagequeue", RequiredTables: []string{"queued_messages", "queue_admission_receipts"}, DependsOn: []string{"task"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}},
{ID: "task-share", OwnerPackage: "internal/task/share", RequiredTables: []string{"task_shares"}, DependsOn: []string{"task"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}},
{ID: "telemetry-contract", OwnerPackage: "internal/telemetrycontract", RequiredTables: []string{"telemetry_activations"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}},
{ID: "delivery", OwnerPackage: "internal/delivery", RequiredTables: []string{"task_delivery_ledger"}, DependsOn: []string{"task"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}},
{ID: "storage", OwnerPackage: "internal/system/storage", RequiredTables: []string{"storage_maintenance_runs", "storage_quarantine_entries"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}},
{ID: "plugin-instances", OwnerPackage: "internal/plugins/instances", RequiredTables: []string{"plugin_instances"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "plugin-marketplace", OwnerPackage: "internal/plugins/marketplace", RequiredTables: []string{"plugin_marketplace_source"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "plugin-settings", OwnerPackage: "internal/plugins", RequiredTables: []string{"plugin_settings"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "plugin-state", OwnerPackage: "internal/plugins/state", RequiredTables: []string{"plugin_state"}, DependsOn: []string{"schema-meta"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "plugin-instance-state", OwnerPackage: "internal/plugins/state", RequiredTables: []string{"plugin_instance_state"}, DependsOn: []string{"plugin-instances"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "plugin-user-state", OwnerPackage: "internal/plugins/state", RequiredTables: []string{"plugin_user_state"}, DependsOn: []string{"user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "canvas", OwnerPackage: "internal/canvas", RequiredTables: []string{"canvas_lifecycle_metadata", "canvas_creation_authority", "canvas_install_receipts"}, DependsOn: []string{"plugin-instances"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}},
{ID: "github", OwnerPackage: "internal/github", RequiredTables: []string{"github_pr_watches"}, DependsOn: []string{"task", "user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "gitlab", OwnerPackage: "internal/gitlab", RequiredTables: []string{"gitlab_configs"}, DependsOn: []string{"task", "user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "jira", OwnerPackage: "internal/jira", RequiredTables: []string{"jira_configs"}, DependsOn: []string{"task", "user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "linear", OwnerPackage: "internal/linear", RequiredTables: []string{"linear_configs"}, DependsOn: []string{"task", "user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "sentry", OwnerPackage: "internal/sentry", RequiredTables: []string{"sentry_configs"}, DependsOn: []string{"task", "user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "azure-devops", OwnerPackage: "internal/azuredevops", RequiredTables: []string{"azure_devops_configs"}, DependsOn: []string{"task", "user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "workflow-sync", OwnerPackage: "internal/workflowsync", RequiredTables: []string{"workflow_sync_configs"}, DependsOn: []string{"workflow"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "office-config-sync", OwnerPackage: "internal/office/configsync", RequiredTables: []string{"office_config_sync_configs"}, DependsOn: []string{"office"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}},
{ID: "automation", OwnerPackage: "internal/automation", RequiredTables: []string{"automations", "automation_runs"}, DependsOn: []string{"task", "user"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}},
{ID: storeIDSchemaMeta, OwnerPackage: "internal/persistence", RequiredTables: []string{"kandev_meta"}, Sweep: startup.StepStoresRepositories},
{ID: storeIDTask, OwnerPackage: "internal/task/repository/sqlite", RequiredTables: []string{"workspaces", "tasks", "task_workflow_session_bindings"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}, Sweep: startup.StepStoresRepositories},
{ID: storeIDWorkflow, OwnerPackage: "internal/workflow/repository", RequiredTables: []string{"workflow_templates", "workflow_steps"}, DependsOn: []string{storeIDTask}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}, Sweep: startup.StepStoresRepositories},
{ID: "analytics", OwnerPackage: "internal/analytics/repository", RequiredTables: []string{"tasks"}, DependsOn: []string{storeIDTask, storeIDWorkflow}, Capabilities: []Capability{CapabilityTimestamp}, Sweep: startup.StepStoresRepositories},
{ID: storeIDAgentSettings, OwnerPackage: "internal/agent/settings/store", RequiredTables: []string{"agents", "agent_profiles"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: storeIDUser, OwnerPackage: "internal/user/store", RequiredTables: []string{"users"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "notification", OwnerPackage: "internal/notifications/store", RequiredTables: []string{"notification_providers"}, DependsOn: []string{storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "editor", OwnerPackage: "internal/editors/store", RequiredTables: []string{"editors"}, DependsOn: []string{storeIDUser}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "prompts", OwnerPackage: "internal/prompts/store", RequiredTables: []string{"custom_prompts"}, DependsOn: []string{storeIDUser}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "utility", OwnerPackage: "internal/utility/store", RequiredTables: []string{"utility_agents"}, DependsOn: []string{storeIDAgentSettings}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "office", OwnerPackage: "internal/office/repository/sqlite", RequiredTables: []string{"office_projects", "runs"}, DependsOn: []string{storeIDTask, storeIDAgentSettings}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}, Sweep: startup.StepStoresRepositories},
{ID: "terminal", OwnerPackage: "internal/terminal/repository", RequiredTables: []string{"user_terminals"}, DependsOn: []string{storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "quick-terminal", OwnerPackage: "internal/quickterminal/repository", RequiredTables: []string{"quick_terminal_tabs"}, DependsOn: []string{storeIDUser}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "runtime-flags", OwnerPackage: "internal/runtimeflags", RequiredTables: []string{"runtime_flag_overrides"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "auth", OwnerPackage: "internal/auth/store", RequiredTables: []string{"auth_identities", "auth_sessions"}, DependsOn: []string{storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}, Sweep: startup.StepStoresRepositories},
{ID: "secrets", OwnerPackage: "internal/secrets", RequiredTables: []string{"secrets"}, DependsOn: []string{storeIDTask}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}, Sweep: startup.StepStoresRepositories},
{ID: "system-settings", OwnerPackage: "internal/system/settings", RequiredTables: []string{"settings"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "auth-hostnames", OwnerPackage: "internal/auth/hostnames", RequiredTables: []string{"auth_hostname_cache"}, DependsOn: []string{"auth"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "organizations", OwnerPackage: "internal/org", RequiredTables: []string{"orgs"}, DependsOn: []string{storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "organization-units", OwnerPackage: "internal/orgunit", RequiredTables: []string{"org_units"}, DependsOn: []string{"organizations"}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "message-queue", OwnerPackage: "internal/orchestrator/messagequeue", RequiredTables: []string{"queued_messages", "queue_admission_receipts"}, DependsOn: []string{storeIDTask}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}, Sweep: startup.StepStoresServices},
{ID: "task-share", OwnerPackage: "internal/task/share", RequiredTables: []string{"task_shares"}, DependsOn: []string{storeIDTask}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "telemetry-contract", OwnerPackage: "internal/telemetrycontract", RequiredTables: []string{"telemetry_activations"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresRepositories},
{ID: "delivery", OwnerPackage: "internal/delivery", RequiredTables: []string{"task_delivery_ledger"}, DependsOn: []string{storeIDTask}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}, Sweep: startup.StepStoresServices},
{ID: "storage", OwnerPackage: "internal/system/storage", RequiredTables: []string{"storage_maintenance_runs", "storage_quarantine_entries"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}, Sweep: startup.StepStoresServices},
{ID: storeIDPluginInstances, OwnerPackage: "internal/plugins/instances", RequiredTables: []string{"plugin_instances"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "plugin-marketplace", OwnerPackage: "internal/plugins/marketplace", RequiredTables: []string{"plugin_marketplace_source"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "plugin-settings", OwnerPackage: "internal/plugins", RequiredTables: []string{"plugin_settings"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "plugin-state", OwnerPackage: pkgPluginsState, RequiredTables: []string{"plugin_state"}, DependsOn: []string{storeIDSchemaMeta}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "plugin-instance-state", OwnerPackage: pkgPluginsState, RequiredTables: []string{"plugin_instance_state"}, DependsOn: []string{storeIDPluginInstances}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "plugin-user-state", OwnerPackage: pkgPluginsState, RequiredTables: []string{"plugin_user_state"}, DependsOn: []string{storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "canvas", OwnerPackage: "internal/canvas", RequiredTables: []string{"canvas_lifecycle_metadata", "canvas_creation_authority", "canvas_install_receipts"}, DependsOn: []string{storeIDPluginInstances}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}, Sweep: startup.StepStoresServices},
{ID: "github", OwnerPackage: "internal/github", RequiredTables: []string{"github_pr_watches"}, DependsOn: []string{storeIDTask, storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "gitlab", OwnerPackage: "internal/gitlab", RequiredTables: []string{"gitlab_configs"}, DependsOn: []string{storeIDTask, storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "jira", OwnerPackage: "internal/jira", RequiredTables: []string{"jira_configs"}, DependsOn: []string{storeIDTask, storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "linear", OwnerPackage: "internal/linear", RequiredTables: []string{"linear_configs"}, DependsOn: []string{storeIDTask, storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "sentry", OwnerPackage: "internal/sentry", RequiredTables: []string{"sentry_configs"}, DependsOn: []string{storeIDTask, storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "azure-devops", OwnerPackage: "internal/azuredevops", RequiredTables: []string{"azure_devops_configs"}, DependsOn: []string{storeIDTask, storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "workflow-sync", OwnerPackage: "internal/workflowsync", RequiredTables: []string{"workflow_sync_configs"}, DependsOn: []string{storeIDWorkflow}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "office-config-sync", OwnerPackage: "internal/office/configsync", RequiredTables: []string{"office_config_sync_configs"}, DependsOn: []string{"office"}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict}, Sweep: startup.StepStoresServices},
{ID: "automation", OwnerPackage: "internal/automation", RequiredTables: []string{"automations", "automation_runs"}, DependsOn: []string{storeIDTask, storeIDUser}, Capabilities: []Capability{CapabilityBoolean, CapabilityTimestamp, CapabilityConflict, CapabilityTransaction}, Sweep: startup.StepStoresServices},
}
// Catalog returns a deep copy of the authoritative store catalog.
@@ -113,6 +136,9 @@ func ValidateCatalog(descriptors []Descriptor) error {
if len(descriptor.RequiredTables) == 0 {
return fmt.Errorf("catalog entry %q has no required tables", descriptor.ID)
}
if descriptor.Sweep != startup.StepStoresRepositories && descriptor.Sweep != startup.StepStoresServices {
return fmt.Errorf("catalog entry %q has invalid sweep %q", descriptor.ID, descriptor.Sweep)
}
if err := validateNames(descriptor); err != nil {
return err
}
@@ -10,6 +10,7 @@ import (
_ "github.com/mattn/go-sqlite3"
"github.com/kandev/kandev/internal/db"
"github.com/kandev/kandev/internal/startup"
"github.com/kandev/kandev/internal/system/maintenance"
)
@@ -43,7 +44,7 @@ func holdWriter(t *testing.T, conn *sqlx.DB) *sqlx.Tx {
func TestRuntimeHealthDefersDuringMaintenance(t *testing.T) {
conn, pool, tracker, health := newSQLiteHealthFixture(t, []Descriptor{{
ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"},
ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories,
}})
if _, err := conn.Exec("CREATE TABLE first (id TEXT PRIMARY KEY)"); err != nil {
t.Fatalf("create first table: %v", err)
@@ -80,8 +81,8 @@ func TestRuntimeHealthDefersDuringMaintenance(t *testing.T) {
func TestRuntimeHealthDeferralPreservesMixedStoreStates(t *testing.T) {
conn, pool, tracker, health := newSQLiteHealthFixture(t, []Descriptor{
{ID: "healthy", OwnerPackage: "owner/healthy", RequiredTables: []string{"healthy"}},
{ID: "unhealthy", OwnerPackage: "owner/unhealthy", RequiredTables: []string{"unhealthy"}},
{ID: "healthy", OwnerPackage: "owner/healthy", RequiredTables: []string{"healthy"}, Sweep: startup.StepStoresRepositories},
{ID: "unhealthy", OwnerPackage: "owner/unhealthy", RequiredTables: []string{"unhealthy"}, Sweep: startup.StepStoresRepositories},
})
if _, err := conn.Exec("CREATE TABLE healthy (id TEXT PRIMARY KEY)"); err != nil {
t.Fatalf("create healthy table: %v", err)
@@ -118,7 +119,7 @@ func TestRuntimeHealthDeferralPreservesMixedStoreStates(t *testing.T) {
func TestStartupHealthDoesNotDefer(t *testing.T) {
conn, pool, tracker, health := newSQLiteHealthFixture(t, []Descriptor{{
ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"},
ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories,
}})
if _, err := conn.Exec("CREATE TABLE first (id TEXT PRIMARY KEY)"); err != nil {
t.Fatalf("create first table: %v", err)
@@ -160,7 +161,7 @@ func TestStartupHealthDoesNotDefer(t *testing.T) {
func TestRuntimeHealthResumesAfterMaintenance(t *testing.T) {
conn, pool, tracker, health := newSQLiteHealthFixture(t, []Descriptor{{
ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"},
ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories,
}})
if _, err := conn.Exec("CREATE TABLE first (id TEXT PRIMARY KEY)"); err != nil {
t.Fatalf("create first table: %v", err)
@@ -231,7 +232,7 @@ func TestHealthCheckMarksMissingTableUnhealthyAndRecovers(t *testing.T) {
}
tracker, err := NewTracker([]Descriptor{{
ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"},
ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker: %v", err)
@@ -278,7 +279,7 @@ func TestProbeTablesHonorsContextDeadline(t *testing.T) {
}
tracker, err := NewTracker([]Descriptor{{
ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"},
ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker: %v", err)
@@ -0,0 +1,42 @@
package requiredstores
import (
"testing"
"github.com/kandev/kandev/internal/startup"
)
// TestCatalogSweepAssignmentIsCompleteAndNonOverlapping is completeness test 1
// from docs/specs/platform/system-design/startup-progress-visibility.md:
// every requiredstores.Catalog() entry is claimed by exactly one store-
// admission sweep step (AC-PLATFORM-STARTUP-PROGRESS-005.2). A Descriptor's
// Sweep field can only ever hold one value, so "exactly one" reduces to
// "a valid one"; this test also locks in the current runtime-order split
// (19 stores.repositories admissions in storage.go, 22 stores.services
// admissions elsewhere) so a future catalog entry silently landing on the
// wrong side of storage.go:215 fails loudly instead of only at startup.
func TestCatalogSweepAssignmentIsCompleteAndNonOverlapping(t *testing.T) {
catalog := Catalog()
var repositories, services int
for _, descriptor := range catalog {
switch descriptor.Sweep {
case startup.StepStoresRepositories:
repositories++
case startup.StepStoresServices:
services++
default:
t.Errorf("catalog entry %q has sweep %q, want one of stores.repositories/stores.services", descriptor.ID, descriptor.Sweep)
}
}
if total := repositories + services; total != len(catalog) {
t.Fatalf("sweep-claimed entries = %d, want %d (every catalog entry claimed exactly once)", total, len(catalog))
}
if repositories != 19 {
t.Errorf("stores.repositories claims %d catalog entries, want 19", repositories)
}
if services != 22 {
t.Errorf("stores.services claims %d catalog entries, want 22", services)
}
}
@@ -4,6 +4,8 @@ import (
"fmt"
"sync"
"time"
"github.com/kandev/kandev/internal/startup"
)
// State is the initialization or probe state of a required store.
@@ -250,6 +252,33 @@ func (t *Tracker) Status(id string) (Status, bool) {
return status, true
}
// DescriptorSweep returns the store-admission sweep step that claims id, per
// its catalog descriptor. A sweep cannot infer its own share at runtime, so
// this is the declared source recordRequiredStore advances against.
func (t *Tracker) DescriptorSweep(id string) (startup.StepID, bool) {
t.mu.RLock()
defer t.mu.RUnlock()
index, exists := t.byID[id]
if !exists {
return "", false
}
return t.catalog[index].Sweep, true
}
// SweepTotal returns how many catalog entries claim sweep. This is the
// sweep's total, read once at BeginStep.
func (t *Tracker) SweepTotal(sweep startup.StepID) int {
t.mu.RLock()
defer t.mu.RUnlock()
total := 0
for _, descriptor := range t.catalog {
if descriptor.Sweep == sweep {
total++
}
}
return total
}
func statusFor(descriptor Descriptor, state State) Status {
return Status{
ID: descriptor.ID,
@@ -1,14 +1,15 @@
package requiredstores
import (
"github.com/kandev/kandev/internal/startup"
"strings"
"testing"
)
func TestTrackerRejectsUnknownDuplicateAndOutOfOrderResults(t *testing.T) {
tracker, err := NewTracker([]Descriptor{
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}, DependsOn: []string{"first"}},
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}, DependsOn: []string{"first"}, Sweep: startup.StepStoresRepositories},
})
if err != nil {
t.Fatalf("NewTracker() error = %v", err)
@@ -24,8 +25,8 @@ func TestTrackerRejectsUnknownDuplicateAndOutOfOrderResults(t *testing.T) {
func TestTrackerSnapshotUsesCatalogOrderAndDetectsFailures(t *testing.T) {
tracker, err := NewTracker([]Descriptor{
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}, DependsOn: []string{"first"}},
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}, DependsOn: []string{"first"}, Sweep: startup.StepStoresRepositories},
})
if err != nil {
t.Fatalf("NewTracker() error = %v", err)
@@ -54,8 +55,8 @@ func TestTrackerSnapshotUsesCatalogOrderAndDetectsFailures(t *testing.T) {
func TestTrackerDetectsMissingResults(t *testing.T) {
tracker, err := NewTracker([]Descriptor{
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}},
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}, Sweep: startup.StepStoresRepositories},
})
if err != nil {
t.Fatalf("NewTracker() error = %v", err)
@@ -70,8 +71,8 @@ func TestTrackerDetectsMissingResults(t *testing.T) {
func TestTrackerProbeStateRecoversAndReportsUnavailableStores(t *testing.T) {
tracker, err := NewTracker([]Descriptor{
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}},
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}, Sweep: startup.StepStoresRepositories},
})
if err != nil {
t.Fatalf("NewTracker() error = %v", err)
@@ -0,0 +1,16 @@
package persistence
import (
"testing"
"go.uber.org/goleak"
)
// TestMain wraps the persistence package's test suite in goleak so the
// backup-progress ticker goroutine (trackBackupProgress) is verified to
// join on stop. Matches the goleak convention already used by
// internal/gateway/websocket, agentctl/server/process, and the runtime
// lifecycle package.
func TestMain(m *testing.M) {
goleak.VerifyTestMain(m)
}
+25
View File
@@ -0,0 +1,25 @@
package startup
// EstimateComponents converts an ETA in milliseconds into the whole count and
// unit AC-PLATFORM-STARTUP-PROGRESS-003.10 requires a rendering surface to
// use: 60000 ms or less rounds up to whole seconds with a floor of one second
// while work remains; anything longer rounds up to whole minutes. Never
// sub-second. Both the Go-rendered startup page and the web dialog mirror
// this rule so the two surfaces never disagree on the same snapshot.
func EstimateComponents(ms int64) (value int64, minutes bool) {
if ms <= 60000 {
seconds := ceilDiv(ms, 1000)
if seconds < 1 {
seconds = 1
}
return seconds, false
}
return ceilDiv(ms, 60000), true
}
func ceilDiv(numerator, denominator int64) int64 {
if numerator <= 0 {
return 0
}
return (numerator + denominator - 1) / denominator
}
@@ -0,0 +1,30 @@
package startup
import "testing"
func TestEstimateComponents(t *testing.T) {
cases := []struct {
name string
ms int64
wantValue int64
wantMinutes bool
}{
{"zero floors to one second", 0, 1, false},
{"sub-second floors to one second", 250, 1, false},
{"exact second stays whole", 1000, 1, false},
{"partial second rounds up", 1001, 2, false},
{"boundary of 60000ms renders in seconds", 60000, 60, false},
{"just over the boundary renders in minutes", 60001, 2, true},
{"exact minute stays whole", 120000, 2, true},
{"partial minute rounds up", 120001, 3, true},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
value, minutes := EstimateComponents(tc.ms)
if value != tc.wantValue || minutes != tc.wantMinutes {
t.Fatalf("EstimateComponents(%d) = (%d, %v), want (%d, %v)",
tc.ms, value, minutes, tc.wantValue, tc.wantMinutes)
}
})
}
}
+42 -5
View File
@@ -3,6 +3,8 @@ package startup
import (
"context"
cryptorand "crypto/rand"
"encoding/binary"
"sync"
"time"
@@ -42,9 +44,12 @@ func (p Phase) Label() string {
}
type Snapshot struct {
Phase Phase `json:"phase"`
ElapsedMS int64 `json:"elapsed_ms"`
PhaseElapsedMS int64 `json:"phase_elapsed_ms"`
Phase Phase `json:"phase"`
Boot int64 `json:"boot"`
Seq uint64 `json:"seq"`
ElapsedMS int64 `json:"elapsed_ms"`
PhaseElapsedMS int64 `json:"phase_elapsed_ms"`
Step *StepSnapshot `json:"step,omitempty"`
}
type Reporter struct {
@@ -52,13 +57,34 @@ type Reporter struct {
started, phaseStarted time.Time
phase Phase
log *logger.Logger
boot int64
seq uint64
active *stepActivation
unregisteredWarned map[StepID]bool
mismatchWarned map[mismatchKey]bool
}
type contextKey struct{}
func New(log *logger.Logger) *Reporter {
now := time.Now()
return &Reporter{started: now, phaseStarted: now, phase: OpeningDatabase, log: log}
return &Reporter{started: now, phaseStarted: now, phase: OpeningDatabase, log: log, boot: newBoot()}
}
// newBoot draws a positive, non-guessable, per-process identifier below 2^53
// so every value decodes exactly when a consumer reads JSON numbers as
// doubles. crypto/rand.Read never errors on the Go version this module
// requires, which is what lets New keep its error-free signature.
func newBoot() int64 {
var buf [8]byte
for {
_, _ = cryptorand.Read(buf[:])
v := int64(binary.BigEndian.Uint64(buf[:]) & ((1 << 53) - 1))
if v != 0 {
return v
}
}
}
func WithReporter(ctx context.Context, r *Reporter) context.Context {
return context.WithValue(ctx, contextKey{}, r)
@@ -75,7 +101,18 @@ func SetPhase(ctx context.Context, phase Phase) {
func (r *Reporter) Snapshot() Snapshot {
r.mu.Lock()
defer r.mu.Unlock()
return Snapshot{Phase: r.phase, ElapsedMS: time.Since(r.started).Milliseconds(), PhaseElapsedMS: time.Since(r.phaseStarted).Milliseconds()}
now := time.Now()
snap := Snapshot{
Phase: r.phase,
Boot: r.boot,
Seq: r.seq,
ElapsedMS: now.Sub(r.started).Milliseconds(),
PhaseElapsedMS: now.Sub(r.phaseStarted).Milliseconds(),
}
if r.active != nil {
snap.Step = r.active.snapshot(now)
}
return snap
}
func (r *Reporter) Set(phase Phase) {
r.mu.Lock()
@@ -0,0 +1,208 @@
package startup
import (
"encoding/json"
"os"
"path/filepath"
"runtime"
"strings"
"testing"
"github.com/kandev/kandev/internal/i18n"
)
// TestRegisteredIdentifiersMatchAC005_3 is completeness test 2: the registered
// identifier set equals AC-PLATFORM-STARTUP-PROGRESS-005.3's list exactly, in
// both directions.
func TestRegisteredIdentifiersMatchAC005_3(t *testing.T) {
want := map[StepID]bool{
StepDatabaseBackup: true,
StepStoresRepositories: true,
StepStoresServices: true,
StepPromptSeqBackfill: true,
StepMessageTimestampsBackfill: true,
StepSubagentContextBackfill: true,
StepSessionsRecovery: true,
}
got := map[StepID]bool{}
for _, spec := range Registry() {
got[spec.ID] = true
}
for id := range want {
if !got[id] {
t.Errorf("AC-005.3 identifier %q is not registered", id)
}
}
for id := range got {
if !want[id] {
t.Errorf("registered identifier %q is absent from the AC-005.3 list", id)
}
}
}
// TestEveryLabelKeyResolvesInEveryLocale is completeness test 3: every
// LabelKey resolves in every supported backend locale and every supported web
// locale. The backend half asserts the key is defined in the `en` catalog;
// i18n's own TestCatalogsHaveMatchingKeys already asserts every other backend
// locale carries an identical key set, so that transitively covers pt-pt,
// zh-cn, zh-tw, zh-hk, and pseudo. The web half reads the `startup` namespace's
// `en` catalog directly (the LabelKey with its leading "startup." stripped,
// matching the web resolution convention `t(key, { ns: "startup" })`); the
// repo's own i18n:check gate transitively covers the other web locales the
// same way.
func TestEveryLabelKeyResolvesInEveryLocale(t *testing.T) {
backendKeys := map[string]bool{}
for _, key := range i18n.Keys() {
backendKeys[key] = true
}
webCatalog := readWebStartupCatalog(t)
for _, spec := range Registry() {
if !backendKeys[spec.LabelKey] {
t.Errorf("step %q label key %q is missing from the backend en catalog", spec.ID, spec.LabelKey)
}
webKey := strings.TrimPrefix(spec.LabelKey, "startup.")
if _, ok := webCatalog[webKey]; !ok {
t.Errorf("step %q label key %q (web key %q) is missing from apps/web/src/locales/en/startup.json", spec.ID, spec.LabelKey, webKey)
}
}
}
func readWebStartupCatalog(t *testing.T) map[string]string {
t.Helper()
_, sourceFile, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("locate startup package")
}
// internal/startup -> internal -> backend -> apps -> repo root
repoRoot := filepath.Join(filepath.Dir(sourceFile), "..", "..", "..", "..")
path := filepath.Join(repoRoot, "apps", "web", "src", "locales", "en", "startup.json")
data, err := os.ReadFile(path)
if err != nil {
t.Fatalf("read web startup catalog: %v", err)
}
catalog := map[string]string{}
if err := json.Unmarshal(data, &catalog); err != nil {
t.Fatalf("parse web startup catalog: %v", err)
}
return catalog
}
// TestRegisteredStepsDeclarePhaseMatchesCallSite is completeness test 4:
// each step's declared Phase equals the phase active at its production
// BeginStep call site (AC-PLATFORM-STARTUP-PROGRESS-005.7). The right-hand
// side of callSitePhase is derived from each call site's governing SetPhase
// transition, not copied from the registry, so a call site moving to a
// different phase without a matching registry update (or vice versa) fails
// here instead of only warning silently at runtime.
func TestRegisteredStepsDeclarePhaseMatchesCallSite(t *testing.T) {
callSitePhase := map[StepID]Phase{
// persistence/provider.go:101 sets backing_up_database immediately
// before :108's BeginStep.
StepDatabaseBackup: BackingUpDatabase,
// backendapp/storage.go:62 sets applying_migrations immediately
// before :63's BeginStep.
StepStoresRepositories: ApplyingMigrations,
// backendapp/storage.go:218 sets initializing_services immediately
// before :219's BeginStep.
StepStoresServices: InitializingServices,
// task/repository/sqlite/base_migrations.go:211/:477 and
// subagent_context_backfill.go:68, reached from the same
// runMigrations call chain during repository construction.
StepMessageTimestampsBackfill: ApplyingMigrations,
StepPromptSeqBackfill: ApplyingMigrations,
StepSubagentContextBackfill: ApplyingMigrations,
// agent/runtime/lifecycle/manager_lifecycle.go:56, inside
// Manager.Start, called from backendapp/main.go's
// startAgentInfrastructure immediately after that function's own
// SetPhase(RecoveringSessions) transition (not the later
// bindListeners closure in startGatewayAndServe, which runs after
// recovery has already completed).
StepSessionsRecovery: RecoveringSessions,
}
for _, spec := range Registry() {
want, ok := callSitePhase[spec.ID]
if !ok {
t.Errorf("step %q has no call-site phase recorded in this test's table", spec.ID)
continue
}
if spec.Phase != want {
t.Errorf("step %q declares Phase=%q but its call site runs under %q", spec.ID, spec.Phase, want)
}
}
if len(callSitePhase) != len(Registry()) {
t.Errorf("call-site phase table has %d entries, want %d (one per registered step)", len(callSitePhase), len(Registry()))
}
}
// TestRetiredIdentifiersCannotBeReRegistered is completeness test 5: the three
// identifiers retired with their work by 2eee90d38 are recorded in the
// append-only retired list, are absent from the registry, and panic through
// init()'s own guard if re-registered (AC-PLATFORM-STARTUP-PROGRESS-005.6).
func TestRetiredIdentifiersCannotBeReRegistered(t *testing.T) {
wantRetired := []StepID{
"task.journal.turns.backfill",
"task.journal.messages.backfill",
"plugins.session_events.mirror",
}
if len(retiredStepIDs) != len(wantRetired) {
t.Errorf("retiredStepIDs has %d entries, want %d: %v", len(retiredStepIDs), len(wantRetired), retiredStepIDs)
}
registered := map[StepID]bool{}
for _, spec := range Registry() {
registered[spec.ID] = true
}
for _, id := range wantRetired {
if !IsRetired(id) {
t.Errorf("IsRetired(%q) = false, want true", id)
}
if registered[id] {
t.Errorf("retired identifier %q is still registered", id)
}
if !panicsOnRegistration(id) {
t.Errorf("re-registering retired identifier %q did not panic", id)
}
}
}
// panicsOnRegistration reports whether init()'s production guard rejects a
// registry that reuses id. It calls assertNoRetiredRegistrations rather than
// re-implementing the check, so the test cannot drift from the guard.
func panicsOnRegistration(id StepID) (panicked bool) {
defer func() {
if recover() != nil {
panicked = true
}
}()
assertNoRetiredRegistrations([]StepSpec{{ID: id}})
return false
}
// TestRegistryDeclarationsMatchMeasure is completeness test 6: a counting or
// counted entry declares a non-empty Corpus; an opaque entry declares none of
// Corpus/Outstanding/Order; a non-empty Outstanding requires Measure==counted.
func TestRegistryDeclarationsMatchMeasure(t *testing.T) {
for _, spec := range Registry() {
switch spec.Measure {
case MeasureOpaque:
if spec.Corpus != "" || spec.Outstanding != "" || len(spec.Order) != 0 {
t.Errorf("step %q is opaque but declares Corpus=%q Outstanding=%q Order=%v", spec.ID, spec.Corpus, spec.Outstanding, spec.Order)
}
case MeasureCounting, MeasureCounted:
if spec.Corpus == "" {
t.Errorf("step %q has measure %q but declares no Corpus", spec.ID, spec.Measure)
}
default:
t.Errorf("step %q has unknown measure %q", spec.ID, spec.Measure)
}
if spec.Outstanding != "" && spec.Measure != MeasureCounted {
t.Errorf("step %q declares Outstanding but measure is %q, want counted", spec.ID, spec.Measure)
}
}
}
@@ -0,0 +1,87 @@
package startup
import (
"encoding/json"
"testing"
)
func TestSnapshotBootIsStableAndPositive(t *testing.T) {
r := New(nil)
first := r.Snapshot().Boot
second := r.Snapshot().Boot
if first != second {
t.Fatalf("boot changed within one process: %d -> %d", first, second)
}
if first <= 0 || first >= (1<<53) {
t.Fatalf("boot = %d, want a positive integer below 2^53", first)
}
}
func TestSnapshotSeqStartsAtZeroAndIncrementsPerStepTransition(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
if got := r.Snapshot().Seq; got != 0 {
t.Fatalf("seq = %d, want 0 before any step transition", got)
}
r.BeginStep(StepStoresRepositories)
if got := r.Snapshot().Seq; got != 1 {
t.Fatalf("seq = %d, want 1 after one BeginStep", got)
}
r.EndStep(StepStoresRepositories)
if got := r.Snapshot().Seq; got != 2 {
t.Fatalf("seq = %d, want 2 after one EndStep", got)
}
}
func TestSnapshotSeqUnaffectedByPhaseTransitions(t *testing.T) {
r := New(nil)
r.Set(BackingUpDatabase)
r.Set(ApplyingMigrations)
if got := r.Snapshot().Seq; got != 0 {
t.Fatalf("seq = %d, want 0: phase transitions alone must not move it", got)
}
}
func TestSnapshotJSONOmitsStepWhenNoneActive(t *testing.T) {
r := New(nil)
raw, err := json.Marshal(r.Snapshot())
if err != nil {
t.Fatalf("marshal: %v", err)
}
var decoded map[string]json.RawMessage
if err := json.Unmarshal(raw, &decoded); err != nil {
t.Fatalf("unmarshal: %v", err)
}
if _, present := decoded["step"]; present {
t.Fatalf("step must be omitted entirely with none active, got %s", raw)
}
for _, field := range []string{"phase", "boot", "seq", "elapsed_ms", "phase_elapsed_ms"} {
if _, present := decoded[field]; !present {
t.Fatalf("expected top-level field %q in %s", field, raw)
}
}
}
func TestStepSnapshotJSONFieldPresenceByMeasure(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 100)
r.Advance(StepStoresRepositories, 10)
raw, err := json.Marshal(r.Snapshot())
if err != nil {
t.Fatalf("marshal: %v", err)
}
var decoded struct {
Step map[string]json.RawMessage `json:"step"`
}
if err := json.Unmarshal(raw, &decoded); err != nil {
t.Fatalf("unmarshal: %v", err)
}
for _, field := range []string{"id", "label_key", "measure", "unit", "elapsed_ms", "done", "total", "rate_per_second", "since_advance_ms", "stalled"} {
if _, present := decoded.Step[field]; !present {
t.Fatalf("counted, advanced step should carry %q, got %s", field, raw)
}
}
}
+180
View File
@@ -0,0 +1,180 @@
package startup
// StepID identifies a registered, named unit of startup work. The registry is
// the only source of valid identifiers (AC-PLATFORM-STARTUP-PROGRESS-005.1).
type StepID string
const (
StepDatabaseBackup StepID = "database.backup"
StepStoresRepositories StepID = "stores.repositories"
StepStoresServices StepID = "stores.services"
StepPromptSeqBackfill StepID = "task.prompt_seq.backfill"
StepMessageTimestampsBackfill StepID = "task.message_timestamps.backfill"
StepSubagentContextBackfill StepID = "task.subagent_context.backfill"
StepSessionsRecovery StepID = "sessions.recovery"
)
// Measure is the ladder a step's reported progress can occupy: counted (done
// and total both known) > counting (done known, no total) > opaque (neither).
type Measure string
const (
MeasureOpaque Measure = "opaque"
MeasureCounting Measure = "counting"
MeasureCounted Measure = "counted"
)
// Unit names the noun a step's count is measured in. It is an enum, not a
// free string, so the localized noun and its plural belong to the rendering
// surface rather than the wire payload.
type Unit string
const (
UnitRows Unit = "rows"
UnitMessages Unit = "messages"
UnitTurns Unit = "turns"
UnitSessions Unit = "sessions"
UnitBytes Unit = "bytes"
UnitStores Unit = "stores"
)
// Dialect is a database backend a step can apply under.
type Dialect string
const (
DialectSQLite Dialect = "sqlite"
DialectPostgres Dialect = "postgres"
)
var bothDialects = []Dialect{DialectSQLite, DialectPostgres}
// StepSpec is a registry entry declaring everything about one step that does
// not vary between activations.
type StepSpec struct {
ID StepID
Phase Phase
Measure Measure
Unit Unit
LabelKey string
Dialects []Dialect
// Corpus names the record set a reported count covers. Empty when Measure
// is opaque.
Corpus string
// Outstanding names the predicate selecting work still outstanding.
// Non-empty only for a step that seeds its done count from durable state.
Outstanding string
// Order lists the loop query's existing ordering and tiebreak columns,
// outermost first. Empty when the loop walks no query-ordered row set.
Order []string
}
// registry is the complete, exhaustive set of registered steps
// (AC-PLATFORM-STARTUP-PROGRESS-005.3).
var registry = []StepSpec{
{
ID: StepDatabaseBackup,
Phase: BackingUpDatabase,
Measure: MeasureCounting,
Unit: UnitBytes,
LabelKey: "startup.step.database_backup",
Dialects: []Dialect{DialectSQLite},
Corpus: "staging file size in bytes",
},
{
ID: StepStoresRepositories,
Phase: ApplyingMigrations,
Measure: MeasureCounted,
Unit: UnitStores,
LabelKey: "startup.step.stores_repositories",
Dialects: bothDialects,
Corpus: "catalog entries whose descriptor names this sweep",
},
{
ID: StepStoresServices,
Phase: InitializingServices,
Measure: MeasureCounted,
Unit: UnitStores,
LabelKey: "startup.step.stores_services",
Dialects: bothDialects,
Corpus: "catalog entries whose descriptor names this sweep",
},
{
ID: StepPromptSeqBackfill,
Phase: ApplyingMigrations,
Measure: MeasureOpaque,
Unit: UnitRows,
LabelKey: "startup.step.prompt_seq",
Dialects: bothDialects,
},
{
ID: StepMessageTimestampsBackfill,
Phase: ApplyingMigrations,
Measure: MeasureOpaque,
Unit: UnitRows,
LabelKey: "startup.step.message_timestamps",
Dialects: bothDialects,
},
{
ID: StepSubagentContextBackfill,
Phase: ApplyingMigrations,
Measure: MeasureOpaque,
Unit: UnitRows,
LabelKey: "startup.step.subagent_context",
Dialects: bothDialects,
},
{
ID: StepSessionsRecovery,
Phase: RecoveringSessions,
Measure: MeasureCounted,
Unit: UnitSessions,
LabelKey: "startup.step.session_recovery",
Dialects: bothDialects,
Corpus: "the executors_running record set read before the sweep",
},
}
// retiredStepIDs is append-only: a removed identifier is listed here forever
// and can never be re-registered (AC-PLATFORM-STARTUP-PROGRESS-005.6).
var retiredStepIDs = map[StepID]struct{}{
"task.journal.turns.backfill": {},
"task.journal.messages.backfill": {},
"plugins.session_events.mirror": {},
}
func init() {
assertNoRetiredRegistrations(registry)
}
// assertNoRetiredRegistrations panics if any spec reuses a retired identifier
// (AC-PLATFORM-STARTUP-PROGRESS-005.6).
func assertNoRetiredRegistrations(specs []StepSpec) {
for _, spec := range specs {
if _, retired := retiredStepIDs[spec.ID]; retired {
panic("startup: registered step reuses a retired identifier: " + string(spec.ID))
}
}
}
// Registry returns a copy of the complete step registry.
func Registry() []StepSpec {
out := make([]StepSpec, len(registry))
copy(out, registry)
return out
}
// IsRetired reports whether id was once registered and has since been
// retired, and so must never be reused.
func IsRetired(id StepID) bool {
_, retired := retiredStepIDs[id]
return retired
}
func lookupStep(id StepID) (StepSpec, bool) {
for _, spec := range registry {
if spec.ID == id {
return spec, true
}
}
return StepSpec{}, false
}
@@ -0,0 +1,338 @@
package startup
import (
"context"
"math"
"time"
"go.uber.org/zap"
)
const (
stallThresholdMS = 120000
rateWindow = 30 * time.Second
maxETAMs = 86400000
maxRateSamples = 64
)
type rateSample struct {
at time.Time
delta int64
}
// stepActivation is the mutable state of one BeginStep..EndStep lifetime. A
// fresh one is created on every BeginStep, so nothing here survives past the
// next activation of the same step.
type stepActivation struct {
spec StepSpec
startedAt time.Time
measure Measure
promotionBlocked bool
hasTotal bool
total int64
done int64
anchorDone int64
hasAdvancedOnce bool
lastAdvanceAt time.Time
samples []rateSample
warned map[string]bool
}
// BeginStep ends the currently active step, if any, and opens id as the new
// active step, as a single sequence-number transition. A call naming the
// already-active step is a no-op. A call naming an unregistered identifier
// opens no step and records one warning.
func (r *Reporter) BeginStep(id StepID) {
r.mu.Lock()
defer r.mu.Unlock()
spec, ok := lookupStep(id)
if !ok {
r.warnUnregisteredLocked(id)
return
}
if r.active != nil && r.active.spec.ID == id {
return
}
r.endActiveLocked()
a := &stepActivation{spec: spec, startedAt: time.Now(), measure: MeasureOpaque, warned: map[string]bool{}}
if spec.Measure == MeasureCounting {
a.measure = MeasureCounting
}
r.active = a
r.seq++
if spec.Phase != r.phase {
r.warnActivationLocked(a, "phase_mismatch")
}
if r.log != nil {
r.log.Info("Startup step started", zap.String("step", string(id)), zap.String("measure", string(a.measure)))
}
}
// EndStep closes the active step if it is the one named. A call naming a
// step that is not active changes nothing.
func (r *Reporter) EndStep(id StepID) {
r.mu.Lock()
defer r.mu.Unlock()
if r.active == nil || r.active.spec.ID != id {
return
}
r.endActiveLocked()
r.seq++
}
func (r *Reporter) endActiveLocked() {
a := r.active
if a == nil {
return
}
if r.log != nil {
r.log.Info("Startup step completed",
zap.String("step", string(a.spec.ID)), zap.String("measure", string(a.measure)),
zap.Int64("done", a.done), zap.Int64("total", a.total))
if a.measure == MeasureCounted && a.hasTotal && a.done < a.total {
r.log.Warn("Startup step ended below its total",
zap.String("step", string(a.spec.ID)), zap.Int64("done", a.done), zap.Int64("total", a.total))
}
}
r.active = nil
}
// SeedDone assigns the active step's done count outright from durably
// applied work, without appending a rate sample or touching the
// last-advance clock. Rejected once the total is set or the step has
// advanced.
func (r *Reporter) SeedDone(id StepID, done int64) {
r.mu.Lock()
defer r.mu.Unlock()
a := r.active
if a == nil || a.spec.ID != id {
r.warnMismatchLocked(id, "seed_done")
return
}
if done < 0 {
r.warnActivationLocked(a, "seed_done_negative")
return
}
if a.hasTotal || a.hasAdvancedOnce {
r.warnActivationLocked(a, "seed_done_rejected")
return
}
if done == a.done {
return
}
a.done = done
a.anchorDone = done
}
// SetTotal accepts the active step's total, the single promotion point for a
// step whose registry entry declares counted. A total of zero seals the
// activation opaque; any other accepted total promotes it.
func (r *Reporter) SetTotal(id StepID, total int64) {
r.mu.Lock()
defer r.mu.Unlock()
a := r.active
if a == nil || a.spec.ID != id {
r.warnMismatchLocked(id, "set_total")
return
}
if total < 0 {
r.warnActivationLocked(a, "set_total_negative")
return
}
if a.hasTotal {
if total != a.total {
r.warnActivationLocked(a, "set_total_rejected")
}
return
}
a.hasTotal = true
a.total = total
if a.done > total {
a.done = total
}
if total == 0 {
a.promotionBlocked = true
return
}
if !a.promotionBlocked && a.spec.Measure == MeasureCounted {
a.measure = MeasureCounted
}
}
// Advance adds delta to the active step's done count, saturating at the
// total when one is known. Only the actual increase - never the requested
// delta - resets the stall clock and feeds the rate sample.
func (r *Reporter) Advance(id StepID, delta int64) {
r.mu.Lock()
defer r.mu.Unlock()
a := r.active
if a == nil || a.spec.ID != id {
r.warnMismatchLocked(id, "advance")
return
}
if delta <= 0 {
return
}
newDone := saturatingAdd(a.done, delta)
if a.hasTotal && newDone > a.total {
newDone = a.total
r.warnActivationLocked(a, "advance_exceeds_total")
}
increase := newDone - a.done
a.done = newDone
if increase <= 0 {
return
}
now := time.Now()
a.hasAdvancedOnce = true
a.lastAdvanceAt = now
samples, droppedDelta := appendSample(a.samples, rateSample{at: now, delta: increase})
a.samples = samples
a.anchorDone += droppedDelta
}
// Degrade moves the active step's measure down one rung (counted->counting,
// counting->opaque) and permanently blocks re-promotion for the rest of this
// activation, including when it is called while already opaque.
func (r *Reporter) Degrade(id StepID) {
r.mu.Lock()
defer r.mu.Unlock()
a := r.active
if a == nil || a.spec.ID != id {
r.warnMismatchLocked(id, "degrade")
return
}
switch a.measure {
case MeasureCounted:
a.measure = MeasureCounting
case MeasureCounting:
a.measure = MeasureOpaque
case MeasureOpaque:
// already at the floor; only the latch below changes.
}
a.promotionBlocked = true
r.warnActivationLocked(a, "degrade")
}
func (r *Reporter) warnActivationLocked(a *stepActivation, condition string) {
if a.warned[condition] {
return
}
a.warned[condition] = true
if r.log != nil {
r.log.Warn("Startup step warning", zap.String("step", string(a.spec.ID)), zap.String("condition", condition))
}
}
func (r *Reporter) warnUnregisteredLocked(id StepID) {
if r.unregisteredWarned == nil {
r.unregisteredWarned = map[StepID]bool{}
}
if r.unregisteredWarned[id] {
return
}
r.unregisteredWarned[id] = true
if r.log != nil {
r.log.Warn("Startup step begin for unregistered identifier", zap.String("step", string(id)))
}
}
// mismatchKey dedupes a "called for a step that isn't active" warning per
// (target step, operation): a caller bug of this shape typically repeats on
// every record in a loop, and only the first occurrence is informative.
type mismatchKey struct {
id StepID
op string
}
func (r *Reporter) warnMismatchLocked(id StepID, op string) {
if r.mismatchWarned == nil {
r.mismatchWarned = map[mismatchKey]bool{}
}
key := mismatchKey{id: id, op: op}
if r.mismatchWarned[key] {
return
}
r.mismatchWarned[key] = true
if r.log != nil {
var active StepID
if r.active != nil {
active = r.active.spec.ID
}
r.log.Warn("Startup step call for a step that is not active",
zap.String("step", string(id)), zap.String("op", op), zap.String("active_step", string(active)))
}
}
func saturatingAdd(a, b int64) int64 {
sum := a + b
if sum < a {
return math.MaxInt64
}
return sum
}
// appendSample appends s to samples, trimming from the front once the ring
// exceeds maxRateSamples. It also returns the sum of the trimmed samples'
// deltas so the caller can fold it into anchorDone: rateWindowStart's
// cumulative-sum walk assumes anchorDone is the done value immediately
// before the first sample still in the slice, and silently dropping old
// samples without that adjustment understates the window's baseline,
// overstating the rate it produces.
func appendSample(samples []rateSample, s rateSample) ([]rateSample, int64) {
samples = append(samples, s)
var droppedDelta int64
if len(samples) > maxRateSamples {
trimCount := len(samples) - maxRateSamples
for _, dropped := range samples[:trimCount] {
droppedDelta += dropped.delta
}
samples = samples[trimCount:]
}
return samples, droppedDelta
}
// Package-level helpers follow the existing SetPhase pattern: a no-op when
// ctx carries no reporter, which keeps every call site safe in tests and
// embedded use.
func BeginStep(ctx context.Context, id StepID) {
if r := FromContext(ctx); r != nil {
r.BeginStep(id)
}
}
func EndStep(ctx context.Context, id StepID) {
if r := FromContext(ctx); r != nil {
r.EndStep(id)
}
}
func SeedDone(ctx context.Context, id StepID, done int64) {
if r := FromContext(ctx); r != nil {
r.SeedDone(id, done)
}
}
func SetTotal(ctx context.Context, id StepID, total int64) {
if r := FromContext(ctx); r != nil {
r.SetTotal(id, total)
}
}
func Advance(ctx context.Context, id StepID, delta int64) {
if r := FromContext(ctx); r != nil {
r.Advance(id, delta)
}
}
func Degrade(ctx context.Context, id StepID) {
if r := FromContext(ctx); r != nil {
r.Degrade(id)
}
}
@@ -0,0 +1,376 @@
package startup
import (
"context"
"testing"
"time"
"go.uber.org/zap"
"go.uber.org/zap/zaptest/observer"
"github.com/kandev/kandev/internal/common/logger"
)
func TestBeginStepOpensRegisteredStepOpaqueOrCounting(t *testing.T) {
r := New(nil)
r.Set(BackingUpDatabase)
r.BeginStep(StepDatabaseBackup)
snap := r.Snapshot()
if snap.Step == nil {
t.Fatal("expected an active step")
}
if snap.Step.ID != StepDatabaseBackup {
t.Fatalf("step id = %q, want %q", snap.Step.ID, StepDatabaseBackup)
}
if snap.Step.Measure != MeasureCounting {
t.Fatalf("database.backup should open counting, got %q", snap.Step.Measure)
}
r2 := New(nil)
r2.Set(ApplyingMigrations)
r2.BeginStep(StepStoresRepositories)
snap2 := r2.Snapshot()
if snap2.Step.Measure != MeasureOpaque {
t.Fatalf("counted-declared step should open opaque, got %q", snap2.Step.Measure)
}
}
func TestBeginStepUnregisteredIdentifierOpensNoStep(t *testing.T) {
r := New(nil)
seqBefore := r.Snapshot().Seq
r.BeginStep(StepID("not.a.real.step"))
snap := r.Snapshot()
if snap.Step != nil {
t.Fatal("unregistered identifier must not open a step")
}
if snap.Seq != seqBefore {
t.Fatalf("seq changed on unregistered begin: before=%d after=%d", seqBefore, snap.Seq)
}
}
func TestBeginStepAlreadyActiveIsNoOp(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SeedDone(StepStoresRepositories, 5)
r.SetTotal(StepStoresRepositories, 50)
seqAfterFirst := r.Snapshot().Seq
r.BeginStep(StepStoresRepositories)
snap := r.Snapshot()
if snap.Seq != seqAfterFirst {
t.Fatalf("re-beginning the active step changed seq: %d -> %d", seqAfterFirst, snap.Seq)
}
if *snap.Step.Done != 5 {
t.Fatalf("re-beginning the active step reset counts: done=%d", *snap.Step.Done)
}
}
func TestBeginStepEndsPriorAsOneTransition(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
seq0 := r.Snapshot().Seq
r.BeginStep(StepPromptSeqBackfill)
snap := r.Snapshot()
if snap.Seq != seq0+1 {
t.Fatalf("switching active steps should increment seq by exactly one, got %d -> %d", seq0, snap.Seq)
}
if snap.Step.ID != StepPromptSeqBackfill {
t.Fatalf("active step = %q, want %q", snap.Step.ID, StepPromptSeqBackfill)
}
}
func TestEndStepClosesOnlyTheActiveStep(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
seq0 := r.Snapshot().Seq
r.EndStep(StepStoresServices) // not active: no-op
if r.Snapshot().Seq != seq0 {
t.Fatal("ending a non-active step must not change seq")
}
if r.Snapshot().Step == nil {
t.Fatal("ending a non-active step must not close the active one")
}
r.EndStep(StepStoresRepositories)
snap := r.Snapshot()
if snap.Seq != seq0+1 {
t.Fatalf("ending the active step should increment seq by one, got %d -> %d", seq0, snap.Seq)
}
if snap.Step != nil {
t.Fatal("snapshot must retain no step after EndStep")
}
}
func TestSeedDoneAssignsUntilTotalOrAdvance(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SeedDone(StepStoresRepositories, -1) // rejected; still opaque, done unexposed
if got := r.Snapshot().Step; got.Measure != MeasureOpaque {
t.Fatalf("negative seed must be rejected without promoting, measure = %q", got.Measure)
}
r.SeedDone(StepStoresRepositories, 10)
r.SetTotal(StepStoresRepositories, 100) // promotes: done should reflect the seed
if *r.Snapshot().Step.Done != 10 {
t.Fatalf("done = %d, want 10", *r.Snapshot().Step.Done)
}
r.SeedDone(StepStoresRepositories, 20) // rejected: total already set
if *r.Snapshot().Step.Done != 10 {
t.Fatalf("seed after total must be rejected, done = %d", *r.Snapshot().Step.Done)
}
}
func TestSeedDoneRejectedAfterAdvance(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 100)
r.Advance(StepStoresRepositories, 5)
r.SeedDone(StepStoresRepositories, 50)
if *r.Snapshot().Step.Done != 5 {
t.Fatalf("seed after advance must be rejected, done = %d", *r.Snapshot().Step.Done)
}
}
func TestSetTotalPromotesAndClampsSeededDone(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SeedDone(StepStoresRepositories, 90)
r.SetTotal(StepStoresRepositories, -1)
if r.Snapshot().Step.Measure != MeasureOpaque {
t.Fatal("negative total must be rejected without promoting")
}
r.SetTotal(StepStoresRepositories, 50) // below the seeded done: clamp
snap := r.Snapshot().Step
if snap.Measure != MeasureCounted {
t.Fatalf("measure = %q, want counted", snap.Measure)
}
if *snap.Done != 50 {
t.Fatalf("seeded done should clamp to total, got %d", *snap.Done)
}
if *snap.Total != 50 {
t.Fatalf("total = %d, want 50", *snap.Total)
}
}
func TestSetTotalZeroSealsOpaqueForActivation(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 0)
if snap := r.Snapshot().Step; snap.Measure != MeasureOpaque {
t.Fatalf("total of zero must seal the step opaque, got %q", snap.Measure)
}
r.SetTotal(StepStoresRepositories, 10) // later different total must not revive it
if snap := r.Snapshot().Step; snap.Measure != MeasureOpaque {
t.Fatalf("a later total must not revive a zero-total step, got %q", snap.Measure)
}
}
func TestSetTotalRejectsADifferentTotalOnceAccepted(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 100)
r.SetTotal(StepStoresRepositories, 100) // equal: no-op, no warning
r.SetTotal(StepStoresRepositories, 200) // different: rejected
if *r.Snapshot().Step.Total != 100 {
t.Fatalf("total = %d, want 100 (unchanged)", *r.Snapshot().Step.Total)
}
}
func TestAdvanceClampsToTotalAndSaturates(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 10)
r.Advance(StepStoresRepositories, 0) // no-op
if *r.Snapshot().Step.Done != 0 {
t.Fatal("advance of zero must be a no-op")
}
r.Advance(StepStoresRepositories, -5) // no-op
if *r.Snapshot().Step.Done != 0 {
t.Fatal("negative advance must be a no-op")
}
r.Advance(StepStoresRepositories, 999)
if *r.Snapshot().Step.Done != 10 {
t.Fatalf("advance exceeding total must clamp, done = %d", *r.Snapshot().Step.Done)
}
}
func TestAdvanceOnNonActiveIdentifierIsNoOp(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 10)
r.Advance(StepStoresServices, 5) // not the active step
if *r.Snapshot().Step.Done != 0 {
t.Fatal("advance naming a non-active identifier must change nothing")
}
}
// TestMismatchOnNonActiveStepWarnsOncePerOperation covers
// SeedDone/SetTotal/Advance/Degrade calls naming a step that isn't active:
// without a warning these are silent no-ops, leaving an operator no way to
// learn a caller has drifted from the reporter's real active step. Each
// mismatched call must log exactly one warning per (step, operation) pair,
// not once per call.
func TestMismatchOnNonActiveStepWarnsOncePerOperation(t *testing.T) {
core, observed := observer.New(zap.InfoLevel)
log, err := logger.NewFromZap(zap.New(core))
if err != nil {
t.Fatalf("observer logger: %v", err)
}
r := New(log)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SeedDone(StepStoresServices, 5)
r.SeedDone(StepStoresServices, 5) // repeat: must not log again
r.SetTotal(StepStoresServices, 10)
r.Advance(StepStoresServices, 1)
r.Degrade(StepStoresServices)
wantOps := map[string]bool{"seed_done": false, "set_total": false, "advance": false, "degrade": false}
var mismatchCount int
for _, entry := range observed.All() {
if entry.Message != "Startup step call for a step that is not active" {
continue
}
mismatchCount++
fields := entry.ContextMap()
if fields["step"] != string(StepStoresServices) {
t.Fatalf("warning step = %v, want %q", fields["step"], StepStoresServices)
}
if fields["active_step"] != string(StepStoresRepositories) {
t.Fatalf("warning active_step = %v, want %q", fields["active_step"], StepStoresRepositories)
}
op, _ := fields["op"].(string)
if _, known := wantOps[op]; !known {
t.Fatalf("unexpected op %q in mismatch warning", op)
}
wantOps[op] = true
}
if mismatchCount != 4 {
t.Fatalf("mismatch warning count = %d, want 4 (one per operation, repeat suppressed)", mismatchCount)
}
for op, seen := range wantOps {
if !seen {
t.Fatalf("no mismatch warning logged for op %q", op)
}
}
}
func TestDegradeMovesDownOneRungAndNeverBack(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
if r.Snapshot().Step.Measure != MeasureOpaque {
t.Fatal("precondition: step should open opaque")
}
r.SetTotal(StepStoresRepositories, 10) // promotes to counted
r.Degrade(StepStoresRepositories)
if got := r.Snapshot().Step.Measure; got != MeasureCounting {
t.Fatalf("measure after one degrade = %q, want counting", got)
}
r.Degrade(StepStoresRepositories)
if got := r.Snapshot().Step.Measure; got != MeasureOpaque {
t.Fatalf("measure after two degrades = %q, want opaque", got)
}
r.SetTotal(StepStoresRepositories, 20) // must never re-promote this activation
if got := r.Snapshot().Step.Measure; got != MeasureOpaque {
t.Fatalf("measure after SetTotal post-degrade = %q, want opaque (no re-promotion)", got)
}
}
func TestDegradeBeforeSetTotalBlocksLaterPromotion(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.Degrade(StepStoresRepositories) // fails counter query before total is known
r.SetTotal(StepStoresRepositories, 100)
if got := r.Snapshot().Step.Measure; got != MeasureOpaque {
t.Fatalf("measure = %q, want opaque: a pre-total degrade must block promotion", got)
}
}
func TestSnapshotHasNoStepAfterEndStep(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.EndStep(StepStoresRepositories)
if r.Snapshot().Step != nil {
t.Fatal("snapshot must not retain an earlier step's identifier")
}
}
// TestRateSampleTrimFoldsDeltaIntoAnchorDone covers the rate-sample ring:
// once it exceeds maxRateSamples, appendSample drops the oldest entries. If
// that drop left anchorDone stale, rateWindowStart's cumulative-sum walk
// would understate "done at the window's older edge" by exactly the dropped
// samples' total delta, overstating the rate reported for a fast sweep that
// advances more than maxRateSamples times within one 30s window (e.g.
// storage.go's required-store sweeps).
func TestRateSampleTrimFoldsDeltaIntoAnchorDone(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 1000)
const advances = maxRateSamples + 36
for i := 0; i < advances; i++ {
r.Advance(StepStoresRepositories, 1)
}
if got := len(r.active.samples); got != maxRateSamples {
t.Fatalf("retained samples = %d, want %d (ring capped)", got, maxRateSamples)
}
wantDropped := int64(advances - maxRateSamples)
if r.active.anchorDone != wantDropped {
t.Fatalf("anchorDone = %d, want %d (the %d trimmed samples' folded delta)", r.active.anchorDone, wantDropped, wantDropped)
}
_, windowDone := r.active.rateWindowStart(time.Now())
if windowDone != wantDropped {
t.Fatalf("rateWindowStart done = %d, want %d: a stale anchorDone understates the window baseline and overstates the rate", windowDone, wantDropped)
}
}
func TestPackageLevelHelpersAreNoOpsWithoutReporter(t *testing.T) {
ctx := context.Background() // no reporter attached
BeginStep(ctx, StepStoresRepositories)
SeedDone(ctx, StepStoresRepositories, 1)
SetTotal(ctx, StepStoresRepositories, 1)
Advance(ctx, StepStoresRepositories, 1)
Degrade(ctx, StepStoresRepositories)
EndStep(ctx, StepStoresRepositories) // must not panic
}
func TestPackageLevelHelpersDelegateToReporter(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
ctx := WithReporter(context.Background(), r)
BeginStep(ctx, StepStoresRepositories)
SetTotal(ctx, StepStoresRepositories, 10)
Advance(ctx, StepStoresRepositories, 3)
if *r.Snapshot().Step.Done != 3 {
t.Fatalf("done = %d, want 3", *r.Snapshot().Step.Done)
}
EndStep(ctx, StepStoresRepositories)
if r.Snapshot().Step != nil {
t.Fatal("expected no active step after EndStep")
}
}
@@ -0,0 +1,115 @@
package startup
import "time"
// StepSnapshot is the wire shape of the currently active step. Fields are
// pointers so an absent value (per the measure's boundary rules) is omitted
// from JSON rather than rendered as a misleading zero.
type StepSnapshot struct {
ID StepID `json:"id"`
LabelKey string `json:"label_key"`
Measure Measure `json:"measure"`
Unit Unit `json:"unit"`
ElapsedMS int64 `json:"elapsed_ms"`
Done *int64 `json:"done,omitempty"`
Total *int64 `json:"total,omitempty"`
RatePerSecond *float64 `json:"rate_per_second,omitempty"`
ETAMS *int64 `json:"eta_ms,omitempty"`
SinceAdvanceMS *int64 `json:"since_advance_ms,omitempty"`
Stalled bool `json:"stalled"`
}
func (a *stepActivation) snapshot(now time.Time) *StepSnapshot {
s := &StepSnapshot{
ID: a.spec.ID,
LabelKey: a.spec.LabelKey,
Measure: a.measure,
Unit: a.spec.Unit,
ElapsedMS: now.Sub(a.startedAt).Milliseconds(),
}
if a.measure == MeasureOpaque {
return s
}
done := a.done
s.Done = &done
if a.measure == MeasureCounted && a.hasTotal {
total := a.total
s.Total = &total
}
sinceAdvance := a.sinceAdvanceMS(now)
s.SinceAdvanceMS = &sinceAdvance
s.Stalled = sinceAdvance >= stallThresholdMS
if a.hasAdvancedOnce {
rate := a.rate(now)
s.RatePerSecond = &rate
if rate > 0 && a.measure == MeasureCounted && a.hasTotal {
if eta, ok := a.etaMS(rate); ok {
s.ETAMS = &eta
}
}
}
return s
}
func (a *stepActivation) sinceAdvanceMS(now time.Time) int64 {
base := a.startedAt
if a.hasAdvancedOnce {
base = a.lastAdvanceAt
}
return now.Sub(base).Milliseconds()
}
func (a *stepActivation) etaMS(rate float64) (int64, bool) {
remaining := a.total - a.done
if remaining < 0 {
remaining = 0
}
ms := float64(remaining) / rate * 1000
if ms > maxETAMs {
return 0, false
}
return int64(ms), true
}
// rate is the mean units-per-second increase over a trailing 30 s window,
// falling back to the step's start below two samples so a burst of very
// early advances cannot spike the estimate.
func (a *stepActivation) rate(now time.Time) float64 {
windowStart, windowDone := a.rateWindowStart(now)
elapsed := now.Sub(windowStart)
if elapsed < time.Millisecond {
elapsed = time.Millisecond
}
delta := a.done - windowDone
if delta < 0 {
delta = 0
}
return float64(delta) / elapsed.Seconds()
}
// rateWindowStart returns the time and cumulative done count at the older
// edge of the rate window: the oldest recorded sample no older than 30 s,
// or the step's start when fewer than two samples have ever been recorded.
// The returned timestamp is the point immediately before the first sample in
// the window, paired with the cumulative count at that point. When every
// sample is older than the window, it returns "now" paired with the current
// done count, which yields a zero rate rather than reviving a stale burst.
func (a *stepActivation) rateWindowStart(now time.Time) (time.Time, int64) {
if len(a.samples) < 2 {
return a.startedAt, a.anchorDone
}
cutoff := now.Add(-rateWindow)
cumulative := a.anchorDone
previousAt := a.startedAt
for _, s := range a.samples {
if !s.at.Before(cutoff) {
return previousAt, cumulative
}
cumulative += s.delta
previousAt = s.at
}
return now, a.done
}
@@ -0,0 +1,200 @@
package startup
import (
"testing"
"time"
)
func TestOpaqueStepOmitsCountsRateAndSinceAdvance(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepPromptSeqBackfill) // registry declares opaque
snap := r.Snapshot().Step
if snap.Done != nil || snap.Total != nil || snap.RatePerSecond != nil ||
snap.ETAMS != nil || snap.SinceAdvanceMS != nil {
t.Fatalf("opaque step must omit every numeric field, got %#v", snap)
}
if snap.Stalled {
t.Fatal("an opaque step must never report stalled")
}
}
func TestCountingStepCarriesDoneNoTotal(t *testing.T) {
r := New(nil)
r.Set(BackingUpDatabase)
r.BeginStep(StepDatabaseBackup)
r.Advance(StepDatabaseBackup, 1024)
snap := r.Snapshot().Step
if snap.Done == nil || *snap.Done != 1024 {
t.Fatalf("counting step should carry done=1024, got %v", snap.Done)
}
if snap.Total != nil {
t.Fatal("counting step must omit total")
}
if snap.ETAMS != nil {
t.Fatal("a step with no total must never carry an ETA")
}
}
func TestCountedStepCarriesDoneAndTotal(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 10)
r.Advance(StepStoresRepositories, 4)
snap := r.Snapshot().Step
if snap.Done == nil || *snap.Done != 4 {
t.Fatalf("done = %v, want 4", snap.Done)
}
if snap.Total == nil || *snap.Total != 10 {
t.Fatalf("total = %v, want 10", snap.Total)
}
}
func TestRateOmittedBeforeFirstAdvance(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 10)
snap := r.Snapshot().Step
if snap.RatePerSecond != nil {
t.Fatal("rate must be absent before the step has advanced at least once")
}
if snap.SinceAdvanceMS == nil {
t.Fatal("since_advance_ms must be present for a counted step even before its first advance")
}
}
func TestRatePresentAfterAdvanceEvenIfDecayedToZero(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 100)
r.Advance(StepStoresRepositories, 1)
// Force the only sample outside the 30s window and force the >=2-samples
// branch by injecting a second, older synthetic sample directly.
a := r.active
a.samples = []rateSample{
{at: time.Now().Add(-90 * time.Second), delta: 1},
{at: time.Now().Add(-40 * time.Second), delta: 1},
}
a.done = 2
snap := r.Snapshot().Step
if snap.RatePerSecond == nil {
t.Fatal("rate must remain present (even at zero) once the step has advanced")
}
if *snap.RatePerSecond != 0 {
t.Fatalf("rate should have decayed to zero with no samples inside the window, got %v", *snap.RatePerSecond)
}
if snap.ETAMS != nil {
t.Fatal("a zero rate must never carry an ETA")
}
}
func TestRateFallsBackToStepStartBelowTwoSamples(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 1000)
r.active.startedAt = time.Now().Add(-10 * time.Second)
r.Advance(StepStoresRepositories, 50) // exactly one sample
rate := r.Snapshot().Step.RatePerSecond
if rate == nil {
t.Fatal("expected a rate with one sample recorded")
}
// ~50 units over ~10s from the step's start, not from the single sample's
// own (near-zero) age.
if *rate <= 0 || *rate > 10 {
t.Fatalf("rate = %v, expected roughly 5/s using step start as the older point", *rate)
}
}
func TestRateWindowUsesThePointBeforeTheFirstInWindowSample(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
now := time.Now()
r.active.startedAt = now.Add(-50 * time.Second)
r.active.samples = []rateSample{
{at: now.Add(-40 * time.Second), delta: 100},
{at: now.Add(-10 * time.Second), delta: 10},
}
r.active.done = 110
rate := r.active.rate(now)
// The in-window sample contributes ten units over the interval from the
// preceding sample, rather than being divided by the near-zero age of its
// own timestamp.
if rate < 0.24 || rate > 0.26 {
t.Fatalf("rate = %v, want about 0.25 units/s", rate)
}
}
func TestETAOmittedAboveOneDay(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 1_000_000_000)
r.active.startedAt = time.Now().Add(-10 * time.Second)
r.Advance(StepStoresRepositories, 1) // a tiny rate projects far beyond a day
snap := r.Snapshot().Step
if snap.ETAMS != nil {
t.Fatalf("eta_ms must be omitted above 86400000ms, got %v", *snap.ETAMS)
}
}
func TestStallDetection(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 100)
r.Advance(StepStoresRepositories, 1)
r.active.lastAdvanceAt = time.Now().Add(-(stallThresholdMS + 1) * time.Millisecond)
snap := r.Snapshot().Step
if !snap.Stalled {
t.Fatal("expected stalled=true once since_advance_ms crosses the threshold")
}
r.Advance(StepStoresRepositories, 1) // real progress clears the stall
if r.Snapshot().Step.Stalled {
t.Fatal("an advance that increases done must clear stalled immediately")
}
}
func TestStallClockUnaffectedBySeedNoOpOrForeignAdvance(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 10)
r.active.startedAt = time.Now().Add(-500 * time.Millisecond)
before := *r.Snapshot().Step.SinceAdvanceMS
r.SeedDone(StepStoresRepositories, 0) // rejected: total already set
r.Advance(StepStoresServices, 5) // foreign identifier
r.Advance(StepStoresRepositories, 0) // zero advance: no-op
after := *r.Snapshot().Step.SinceAdvanceMS
if after < before {
t.Fatalf("since_advance_ms must not have reset: before=%d after=%d", before, after)
}
}
func TestAdvanceExceedingTotalOnlyCountsRealIncreaseAsASample(t *testing.T) {
r := New(nil)
r.Set(ApplyingMigrations)
r.BeginStep(StepStoresRepositories)
r.SetTotal(StepStoresRepositories, 10)
r.Advance(StepStoresRepositories, 5)
r.Advance(StepStoresRepositories, 999) // clamps to 10; actual increase is 5
if got := len(r.active.samples); got != 2 {
t.Fatalf("expected 2 recorded samples, got %d", got)
}
if r.active.samples[1].delta != 5 {
t.Fatalf("second sample delta = %d, want 5 (the actual increase, not the request)", r.active.samples[1].delta)
}
}
@@ -8,13 +8,14 @@ import (
"github.com/gin-gonic/gin"
"github.com/kandev/kandev/internal/persistence/requiredstores"
"github.com/kandev/kandev/internal/startup"
)
func TestHandlerReturnsStableRowsWithSanitizedErrors(t *testing.T) {
gin.SetMode(gin.TestMode)
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}},
{ID: "first", OwnerPackage: "owner/first", RequiredTables: []string{"first"}, Sweep: startup.StepStoresRepositories},
{ID: "second", OwnerPackage: "owner/second", RequiredTables: []string{"second"}, Sweep: startup.StepStoresRepositories},
})
if err != nil {
t.Fatalf("NewTracker: %v", err)
@@ -18,6 +18,7 @@ import (
"github.com/kandev/kandev/internal/common/logger"
"github.com/kandev/kandev/internal/db"
"github.com/kandev/kandev/internal/persistence/requiredstores"
"github.com/kandev/kandev/internal/startup"
"github.com/kandev/kandev/internal/system/jobs"
)
@@ -124,6 +125,7 @@ func TestProvideMarksPersistenceUnavailableForFactoryReset(t *testing.T) {
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{{
ID: "settings", OwnerPackage: "internal/system/settings", RequiredTables: []string{"settings"},
Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker: %v", err)
@@ -169,6 +171,7 @@ func TestProvideMarksPersistenceUnavailableForRestore(t *testing.T) {
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{{
ID: "settings", OwnerPackage: "internal/system/settings", RequiredTables: []string{"settings"},
Sweep: startup.StepStoresRepositories,
}})
if err != nil {
t.Fatalf("NewTracker: %v", err)
@@ -14,6 +14,7 @@ import (
"go.uber.org/zap"
"github.com/kandev/kandev/internal/db/dialect"
"github.com/kandev/kandev/internal/startup"
)
// migrateExecutorProfiles adds mcp_policy column and drops is_default from executor_profiles.
@@ -53,7 +54,9 @@ func (r *Repository) migrateSessionsAddCostColumns() {
}
// runMigrations applies idempotent ALTER TABLE migrations for schema evolution.
func (r *Repository) runMigrations() error {
//
//nolint:cyclop,funlen,maintidx // Legacy flat list of ~60 independent idempotent migration steps predating startup-step instrumentation; splitting it is out of scope here.
func (r *Repository) runMigrations(ctx context.Context) error {
if err := r.migrateTaskPriorityToTextPostgres(); err != nil {
return err
}
@@ -214,7 +217,9 @@ func (r *Repository) runMigrations() error {
// explicitly in CreateMessage/UpdateMessage. The backfill UPDATE is idempotent
// (WHERE updated_at IS NULL).
r.migrate.Apply("task_session_messages.updated_at", `ALTER TABLE task_session_messages ADD COLUMN updated_at TIMESTAMP`)
startup.BeginStep(ctx, startup.StepMessageTimestampsBackfill)
r.migrate.Apply("task_session_messages.updated_at.backfill", `UPDATE task_session_messages SET updated_at = created_at WHERE updated_at IS NULL`)
startup.EndStep(ctx, startup.StepMessageTimestampsBackfill)
r.migrate.Apply("idx_messages_session_updated", `CREATE INDEX IF NOT EXISTS idx_messages_session_updated ON task_session_messages(task_session_id, updated_at)`)
// task_session_commits gains a uniqueness constraint before its writer
@@ -378,7 +383,7 @@ func (r *Repository) runMigrations() error {
// table is not part of the supported upgrade path, so there is no
// intermediate-shape rebuild to run here. Only the historical-message
// backfill belongs in the migration phase.
r.migrateSubagentContextBackfill()
r.migrateSubagentContextBackfill(ctx)
// Durable per-session prompt ordinals. prompt_seq is allocated from a
// per-session sequence counter inside the create write boundary, so an
@@ -397,7 +402,7 @@ func (r *Repository) runMigrations() error {
task_session_id TEXT PRIMARY KEY,
last_seq INTEGER NOT NULL
)`)
if err := r.backfillPromptSeq(); err != nil {
if err := r.backfillPromptSeq(ctx); err != nil {
return err
}
@@ -504,7 +509,7 @@ func (r *Repository) backfillTaskSessionQueueIncarnations() error {
// session's sequence counter at its backfilled maximum. Idempotent: user rows
// already carrying a nonzero prompt_seq are untouched, and the counter seed
// ignores existing rows.
func (r *Repository) backfillPromptSeq() error {
func (r *Repository) backfillPromptSeq(ctx context.Context) error {
nmU := dialect.NormalizedMicrosecond(r.db.DriverName(), "u.created_at")
nmM := dialect.NormalizedMicrosecond(r.db.DriverName(), "task_session_messages.created_at")
update := fmt.Sprintf(`
@@ -516,7 +521,8 @@ func (r *Repository) backfillPromptSeq() error {
AND (%s < %s OR (%s = %s AND u.id <= task_session_messages.id))
)
WHERE author_type = 'user' AND prompt_seq = 0`, nmU, nmM, nmU, nmM)
ctx := r.migrationContext()
startup.BeginStep(ctx, startup.StepPromptSeqBackfill)
defer startup.EndStep(ctx, startup.StepPromptSeqBackfill)
if _, err := r.db.ExecContext(ctx, update); err != nil {
return fmt.Errorf("backfill prompt_seq: %w", err)
}
@@ -32,7 +32,7 @@ func TestBaseMigrationsDoNotInferProviderHostFromPartialRepositoryIdentity(t *te
t.Fatalf("create repository: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("run migrations: %v", err)
}
stored, err := repo.GetRepository(context.Background(), repository.ID)
@@ -0,0 +1,144 @@
package sqlite
import (
"context"
"testing"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
"go.uber.org/zap/zaptest/observer"
"github.com/kandev/kandev/internal/common/logger"
"github.com/kandev/kandev/internal/startup"
)
// TestBackfillPromptSeqReportsOpaqueStep covers the
// task.prompt_seq.backfill half of AC-PLATFORM-STARTUP-PROGRESS-005.2/.8:
// the opaque step brackets the whole statement pair (backfill UPDATE plus
// counter seed) with a start/completed pair, every boot, since the backfill
// itself is already idempotent (WHERE prompt_seq = 0) and has no separate
// runtime skip condition to respect.
func TestBackfillPromptSeqReportsOpaqueStep(t *testing.T) {
repo := newRepoForSessionTests(t)
reporter, logs := newObservedMigrationStepReporter(t)
ctx := startup.WithReporter(context.Background(), reporter)
if err := repo.backfillPromptSeq(ctx); err != nil {
t.Fatalf("backfillPromptSeq: %v", err)
}
assertNoPhaseMismatchWarnings(t, logs)
assertOpaqueStepBracket(t, logs, startup.StepPromptSeqBackfill)
if snap := reporter.Snapshot(); snap.Step != nil {
t.Fatalf("Step after backfillPromptSeq = %+v, want nil (step closed)", snap.Step)
}
}
// TestMessageTimestampsBackfillReportsOpaqueStep covers the
// task.message_timestamps.backfill half of the same ACs: runMigrations
// brackets its single backfill UPDATE the same way, every boot, since the
// statement is already idempotent (WHERE updated_at IS NULL) with no
// runtime skip condition.
func TestMessageTimestampsBackfillReportsOpaqueStep(t *testing.T) {
repo := newRepoForSessionTests(t)
reporter, logs := newObservedMigrationStepReporter(t)
ctx := startup.WithReporter(context.Background(), reporter)
if err := repo.runMigrations(ctx); err != nil {
t.Fatalf("runMigrations: %v", err)
}
assertNoPhaseMismatchWarnings(t, logs)
assertOpaqueStepBracket(t, logs, startup.StepMessageTimestampsBackfill)
}
// TestMigrateSubagentContextBackfillOpensStepOnlyOnFirstBoot covers F78's
// rule for a registered step whose work is conditionally skipped at
// runtime: migrateSubagentContextBackfill's guard means the real
// INSERT...SELECT (and therefore the step) only runs once per installation
// (AC-23a). The first call — the one that actually does the scan — must
// open and close the step; a later call, once both activation keys are
// already written, must never open it at all (matching
// TestInitConversationJournalSchemaSkipsStepsOnceBackfilled's rule for the
// journal steps).
func TestMigrateSubagentContextBackfillOpensStepOnlyOnFirstBoot(t *testing.T) {
repo, _ := newSubagentMigrationTestRepo(t)
firstReporter, firstLogs := newObservedMigrationStepReporter(t)
firstCtx := startup.WithReporter(context.Background(), firstReporter)
repo.migrateSubagentContextBackfill(firstCtx)
assertNoPhaseMismatchWarnings(t, firstLogs)
assertOpaqueStepBracket(t, firstLogs, startup.StepSubagentContextBackfill)
secondReporter, secondLogs := newObservedMigrationStepReporter(t)
secondCtx := startup.WithReporter(context.Background(), secondReporter)
repo.migrateSubagentContextBackfill(secondCtx)
for _, entry := range secondLogs.All() {
if entry.Message == "Startup step started" {
t.Fatalf("unexpected step start on an already-activated boot: %+v", entry.ContextMap())
}
}
}
// assertOpaqueStepBracket asserts exactly one "Startup step started" and one
// "Startup step completed" entry for wantStep, started before completed.
func assertOpaqueStepBracket(t *testing.T, logs *observer.ObservedLogs, wantStep startup.StepID) {
t.Helper()
var startedAt, completedAt = -1, -1
var startedCount, completedCount int
for i, entry := range logs.All() {
if entry.ContextMap()["step"] != string(wantStep) {
continue
}
switch entry.Message {
case "Startup step started":
startedCount++
startedAt = i
case "Startup step completed":
completedCount++
completedAt = i
}
}
if startedCount != 1 {
t.Fatalf("startup step %q started %d times, want 1", wantStep, startedCount)
}
if completedCount != 1 {
t.Fatalf("startup step %q completed %d times, want 1", wantStep, completedCount)
}
if startedAt == -1 {
t.Fatalf("no \"Startup step started\" entry for step %q", wantStep)
}
if completedAt == -1 {
t.Fatalf("no \"Startup step completed\" entry for step %q", wantStep)
}
if completedAt < startedAt {
t.Fatalf("step %q completed (index %d) before it started (index %d)", wantStep, completedAt, startedAt)
}
}
// newObservedMigrationStepReporter returns a reporter already in the
// applying_migrations phase, plus the observed log every step assertion in
// this file reads.
func newObservedMigrationStepReporter(t *testing.T) (*startup.Reporter, *observer.ObservedLogs) {
t.Helper()
core, logs := observer.New(zapcore.DebugLevel)
log, err := logger.NewFromZap(zap.New(core))
if err != nil {
t.Fatalf("observer logger: %v", err)
}
reporter := startup.New(log)
reporter.Set(startup.ApplyingMigrations)
return reporter, logs
}
// assertNoPhaseMismatchWarnings fails if any step opened under a phase other
// than the one its registry entry declares
// (AC-PLATFORM-STARTUP-PROGRESS-005.7).
func assertNoPhaseMismatchWarnings(t *testing.T, logs *observer.ObservedLogs) {
t.Helper()
for _, entry := range logs.All() {
if entry.Message == "Startup step warning" && entry.ContextMap()["condition"] == "phase_mismatch" {
t.Fatalf("unexpected phase_mismatch warning: %+v", entry.ContextMap())
}
}
}
@@ -46,7 +46,7 @@ func (r *Repository) initSchemaContext(ctx context.Context) error {
r.migrateTaskSessions,
r.ensureDefaultWorkspace,
r.ensureDefaultExecutorsAndEnvironments,
r.runMigrations,
func() error { return r.runMigrations(ctx) },
r.hideBuiltinWorkflows,
r.healBuiltinWorkflowStepFlags,
r.healBuiltinWorkflowStepParticipantSeats,
@@ -1,6 +1,9 @@
package sqlite
import "testing"
import (
"context"
"testing"
)
// clarification_resolutions was a durable-claim table designed during this
// feature's spec review but retired before ever shipping in favor of
@@ -27,7 +30,7 @@ func TestClarificationResolutionsTableNeverCreated(t *testing.T) {
}
// Migrations replay on every boot; the second pass must not resurrect it.
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations replay: %v", err)
}
if err := repo.db.QueryRow(
@@ -17,6 +17,7 @@ import (
"github.com/kandev/kandev/internal/db"
"github.com/kandev/kandev/internal/persistence"
"github.com/kandev/kandev/internal/persistence/requiredstores"
"github.com/kandev/kandev/internal/startup"
"github.com/kandev/kandev/internal/task/models"
)
@@ -160,7 +161,7 @@ func seedLargeLegacy(t *testing.T, repo *Repository) {
func runLargeUpgradeWriterLoad(t *testing.T, repo *Repository, pool *db.Pool) {
t.Helper()
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{{ID: "task", OwnerPackage: "internal/task", RequiredTables: []string{"tasks", "task_sessions", "task_session_messages", "task_session_turns", "conversation_session_revisions"}}})
tracker, err := requiredstores.NewTracker([]requiredstores.Descriptor{{ID: "task", OwnerPackage: "internal/task", RequiredTables: []string{"tasks", "task_sessions", "task_session_messages", "task_session_turns", "conversation_session_revisions"}, Sweep: startup.StepStoresRepositories}})
if err != nil {
t.Fatal(err)
}
@@ -300,10 +300,10 @@ func TestPostgresPlanRevisionWorkflowColumnsReplayMigration(t *testing.T) {
t.Fatalf("insert legacy plan revision: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("run legacy plan migrations: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay legacy plan migrations: %v", err)
}
var writeVersion string
@@ -70,10 +70,10 @@ func TestExecutionProfileColumnsReplayOnLegacySchema(t *testing.T) {
t.Fatalf("drop legacy %s.execution_profile_id: %v", table, err)
}
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations on legacy schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay runMigrations: %v", err)
}
@@ -288,7 +288,7 @@ func TestExecutorRunningLocalPIDMigrationOnLegacyDB(t *testing.T) {
// Re-run migrations, exactly as a boot of the new binary would. The
// idempotent ADD COLUMN must re-add local_pid without erroring.
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations on legacy DB: %v", err)
}
@@ -291,7 +291,7 @@ func TestPostgresSessionCommitsDedupeAndActivationMigration(t *testing.T) {
t.Fatalf("pre-migration commit rows = %d, want 3", got)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations: %v", err)
}
@@ -329,7 +329,7 @@ func TestPostgresSessionCommitsDedupeAndActivationMigration(t *testing.T) {
// Replay: must not error, must not duplicate the index, and must not
// move the activation marker (legacy rows must stay pinned to the
// original activation instant, not silently drift on every boot).
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations twice: %v", err)
}
if got := readCommitCaptureActivatedAt(t, repo); got != activatedAt {
@@ -39,10 +39,10 @@ func TestPostgresPlanCommentSchemaReplayAndCRUD(t *testing.T) {
if err := repo.initPlansSchema(); err != nil {
t.Fatalf("initialize plan schema on legacy database: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("migrate legacy database: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations: %v", err)
}
@@ -133,10 +133,10 @@ func TestPlanCommentSchemaReplaysOnLegacyDatabase(t *testing.T) {
if err := repo.initPlansSchema(); err != nil {
t.Fatalf("initialize plan children on legacy schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("migrate legacy schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations: %v", err)
}
@@ -652,10 +652,10 @@ func TestPlanRevisionWorkflowColumnsReplayMigration(t *testing.T) {
t.Fatalf("insert legacy plan revision: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("run legacy plan migrations: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay legacy plan migrations: %v", err)
}
@@ -115,7 +115,7 @@ func TestTaskPlanWriteVersionMigrationBackfillsAndReplays(t *testing.T) {
if _, err := repo.db.ExecContext(ctx, `ALTER TABLE task_plans DROP COLUMN write_version`); err != nil {
t.Fatalf("drop write_version for legacy fixture: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(ctx); err != nil {
t.Fatalf("runMigrations(backfill): %v", err)
}
migrated, err := repo.GetTaskPlan(ctx, plan.TaskID)
@@ -126,7 +126,7 @@ func TestTaskPlanWriteVersionMigrationBackfillsAndReplays(t *testing.T) {
t.Fatal("migration left legacy plan without a write version")
}
version := migrated.WriteVersion
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(ctx); err != nil {
t.Fatalf("runMigrations(replay): %v", err)
}
replayed, err := repo.GetTaskPlan(ctx, plan.TaskID)
@@ -80,7 +80,7 @@ func TestPostgresExecutorRunningLocalPIDMigration(t *testing.T) {
if _, err := db.Exec(`ALTER TABLE executors_running DROP COLUMN local_pid`); err != nil {
t.Fatalf("simulate legacy schema (drop local_pid): %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations on legacy postgres DB: %v", err)
}
@@ -185,10 +185,10 @@ func TestPostgresImproveKandevWorkflowIndexMigration(t *testing.T) {
t.Fatalf("seed legacy workflow %q: %v", id, err)
}
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("migrate legacy postgres workflow duplicates: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay postgres improve kandev migration: %v", err)
}
var count int
@@ -304,10 +304,10 @@ func TestPostgresExecutionProfileMigration(t *testing.T) {
t.Fatalf("drop %s.execution_profile_id: %v", table, err)
}
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations on legacy postgres schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay postgres migrations: %v", err)
}
@@ -586,10 +586,10 @@ func TestPostgresRepositorySecretBindingsSchemaReplay(t *testing.T) {
if _, err := db.Exec("DROP TABLE repository_secret_bindings"); err != nil {
t.Fatalf("drop repository secret bindings table: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay repository secret bindings migration: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay repository secret bindings migration twice: %v", err)
}
@@ -41,7 +41,7 @@ func insertPromptRowWithRawTimestamp(t *testing.T, repo *Repository, id, session
// serve after migration.
func backfillPromptSeqForTest(t *testing.T, repo *Repository) {
t.Helper()
if err := repo.backfillPromptSeq(); err != nil {
if err := repo.backfillPromptSeq(context.Background()); err != nil {
t.Fatalf("backfill prompt_seq: %v", err)
}
}
@@ -671,10 +671,10 @@ func TestDeleteRepositoryIfNoActiveTaskSessions(t *testing.T) {
// failures by design).
func TestRunMigrations_Idempotent(t *testing.T) {
repo := newRepoForEntityTests(t)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("second runMigrations call returned error: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("third runMigrations call returned error: %v", err)
}
}
@@ -698,10 +698,10 @@ func TestRunnerProjectionWorkflowStepColumnsReplayMigration(t *testing.T) {
t.Fatalf("drop legacy workflow_steps.%s: %v", column.name, err)
}
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations on legacy workflow_steps schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay runMigrations: %v", err)
}
@@ -741,10 +741,10 @@ func TestRunnerProjectionParticipantCreatedAtReplayMigration(t *testing.T) {
if _, err := repo.db.Exec(`ALTER TABLE workflow_step_participants DROP COLUMN created_at`); err != nil {
t.Fatalf("drop legacy workflow_step_participants.created_at: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations on legacy workflow_step_participants schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay runMigrations: %v", err)
}
@@ -56,7 +56,7 @@ func TestPostgresRepositorySetBaseBranchMigrationPreservesItems(t *testing.T) {
t.Fatalf("insert legacy repository-set item: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("run base-branch migration: %v", err)
}
assertBaseBranchColumn := func(stage string) {
@@ -74,7 +74,7 @@ func TestPostgresRepositorySetBaseBranchMigrationPreservesItems(t *testing.T) {
}
}
assertBaseBranchColumn("first")
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay base-branch migration: %v", err)
}
assertBaseBranchColumn("replayed")
@@ -101,10 +101,10 @@ func TestRepositorySetBaseBranchMigrationPreservesLegacyItems(t *testing.T) {
t.Fatalf("insert legacy repository-set item: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("run base-branch migration: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay base-branch migration: %v", err)
}
@@ -35,7 +35,7 @@ func TestSessionCommitsDedupeAndActivationMigration(t *testing.T) {
t.Fatalf("pre-migration commit rows = %d, want 3", got)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations: %v", err)
}
@@ -84,7 +84,7 @@ func TestSessionCommitsDedupeAndActivationMigration(t *testing.T) {
// Replay: must not error, must not duplicate the index, and must not
// move the activation marker (legacy rows must stay pinned to the
// original activation instant, not silently drift on every boot).
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations twice: %v", err)
}
if got := readCommitCaptureActivatedAt(t, repo); got != activatedAt {
@@ -1,6 +1,9 @@
package sqlite
import "testing"
import (
"context"
"testing"
)
// The in-tree Slack integration was replaced by kandev-plugin-slack. Its
// `slack_configs` row is merely dead, but its vault entries are live Slack
@@ -107,7 +110,7 @@ func TestDropRetiredSlackIntegrationReplays(t *testing.T) {
t.Fatalf("dropRetiredSlackIntegration pass %d: %v", i+1, err)
}
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations replay: %v", err)
}
}
@@ -137,7 +137,7 @@ func TestStartupMigrationCostsPopulated(t *testing.T) {
t.Fatalf("reset prompt sequence counters: %v", err)
}
promptSeqStarted := time.Now()
if err := replayRepo.backfillPromptSeq(); err != nil {
if err := replayRepo.backfillPromptSeq(context.Background()); err != nil {
_ = replayDB.Close()
t.Fatalf("measure prompt sequence backfill: %v", err)
}
@@ -333,7 +333,7 @@ func TestBackfillPromptSeqStopsOnCanceledContext(t *testing.T) {
migrate: dbpkg.NewRequiredMigrateLoggerContext(db, nil, ctx),
}
done := make(chan error, 1)
go func() { done <- repo.backfillPromptSeq() }()
go func() { done <- repo.backfillPromptSeq(ctx) }()
select {
case <-started:
case <-time.After(2 * time.Second):
@@ -30,7 +30,7 @@ func TestMarkerPositionsMigrationOnLegacyDB(t *testing.T) {
// Re-run migrations, exactly as a boot of the new binary would. The
// idempotent ADD COLUMN must re-add marker_positions without erroring.
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations on legacy DB: %v", err)
}
@@ -46,7 +46,7 @@ func TestPostgresMarkerPositionsMigrationOnLegacyDB(t *testing.T) {
if _, err := db.Exec(`ALTER TABLE workflow_step_entries DROP COLUMN marker_positions`); err != nil {
t.Fatalf("simulate legacy schema (drop marker_positions): %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations on legacy postgres DB: %v", err)
}
@@ -7,6 +7,7 @@ package sqlite
// is untouched by boot/replay, and there is no migration step to reverse.
import (
"context"
"path/filepath"
"testing"
"time"
@@ -52,10 +53,10 @@ func TestPreActivationTurnIsNotBackfilledWithStepStamp(t *testing.T) {
// Replay schema init/migrations twice more, mirroring a boot after
// activation. Nothing about this table's rows should change.
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations twice: %v", err)
}
@@ -5,6 +5,7 @@ package sqlite
// existing task gains no rows, and the schema-init step is replay-safe.
import (
"context"
"path/filepath"
"testing"
"time"
@@ -69,10 +70,10 @@ func TestStepTransitionsSchemaCreatesTableAndIsReplaySafe(t *testing.T) {
if err := repo.initStepTransitionsSchema(); err != nil {
t.Fatalf("replay initStepTransitionsSchema twice: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay runMigrations: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay runMigrations twice: %v", err)
}
@@ -12,6 +12,7 @@ import (
"github.com/jmoiron/sqlx"
"github.com/kandev/kandev/internal/db/dialect"
"github.com/kandev/kandev/internal/startup"
)
const (
@@ -45,7 +46,7 @@ func (r *Repository) warnSubagentContextMigration(name string, err error) {
// both, and having each key's own INSERT use ON CONFLICT DO NOTHING, is what
// lets a partial pre-existing pair repair itself on the next boot without a
// second mechanism.
func (r *Repository) migrateSubagentContextBackfill() {
func (r *Repository) migrateSubagentContextBackfill(ctx context.Context) {
capturePresent, err := r.subagentContextActivationKeyPresent(subagentContextCaptureSinceKey)
if err != nil {
r.warnSubagentContextMigration(subagentContextBackfillMigrationName+".guard", err)
@@ -57,9 +58,15 @@ func (r *Repository) migrateSubagentContextBackfill() {
return
}
if capturePresent && throughPresent {
// Both activation keys are already written: the backfill already
// completed on an earlier boot, so the step is never opened. Opening
// and immediately ending it here would flash a step at the operator
// on every normal boot after the first.
return
}
startup.BeginStep(ctx, startup.StepSubagentContextBackfill)
defer startup.EndStep(ctx, startup.StepSubagentContextBackfill)
if err := r.migrateSubagentContextBackfillUnsafe(); err != nil {
r.warnSubagentContextMigration(subagentContextBackfillMigrationName, err)
}
@@ -1,6 +1,7 @@
package sqlite
import (
"context"
"database/sql"
"encoding/json"
"path/filepath"
@@ -152,7 +153,7 @@ func newSubagentMigrationTestRepo(t *testing.T) (*Repository, *sqlx.DB) {
// against an empty database with no messages seeded yet, and claimed the
// two activation keys (AC-24) — correct for a genuinely fresh install,
// but not what this file's tests want: they seed subagent-shaped
// messages AFTER construction and then call repo.runMigrations() again,
// messages AFTER construction and then call repo.runMigrations(context.Background()) again,
// expecting THAT call to be the real (only) backfill run — mirroring a
// DB upgrade where historical messages predate this boot. Reset to
// "not yet activated" so every test in this file gets that semantics by
@@ -212,10 +213,10 @@ func TestSubagentContextSchemaFreshAndReplay(t *testing.T) {
t.Fatal("duplicate (task_session_id, tool_call_id) should violate UNIQUE constraint")
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations twice: %v", err)
}
if count := countSubagentContextRows(t, repo, "session-schema", "tc-schema"); count != 1 {
@@ -254,7 +255,7 @@ func TestSubagentContextBackfillAsyncLaunchedStoresNullNotZero(t *testing.T) {
createdAt, updatedAt,
)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
@@ -327,7 +328,7 @@ func TestSubagentContextBackfillReportedZeroToolUseCountSurvives(t *testing.T) {
ts, ts,
)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
@@ -354,7 +355,7 @@ func TestSubagentContextBackfillNegativeMetricBecomesNull(t *testing.T) {
ts, ts,
)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
@@ -384,7 +385,7 @@ func TestSubagentContextBackfillEmptyStringBecomesNull(t *testing.T) {
ts, ts,
)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
@@ -414,7 +415,7 @@ func TestSubagentContextBackfillMalformedMetadataDoesNotAbort(t *testing.T) {
ts, ts,
)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations must not abort on malformed metadata rows: %v", err)
}
@@ -440,7 +441,7 @@ func TestSubagentContextBackfillNonTerminalSettledAtNull(t *testing.T) {
ts, ts,
)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
@@ -485,7 +486,7 @@ func TestSubagentContextBackfillLiveRowWins(t *testing.T) {
t.Fatalf("seed pre-existing live row: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
@@ -528,7 +529,7 @@ func TestSubagentContextBackfillSkipsRowsWithoutIdentity(t *testing.T) {
ts, ts,
)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
@@ -553,7 +554,7 @@ func TestSubagentContextBackfillNestedParentToolCallID(t *testing.T) {
ts, ts,
)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
@@ -580,7 +581,7 @@ func TestSubagentContextActivationKeysWrittenOnce(t *testing.T) {
seedSubagentMessage(t, repo, "msg-activation-newest", "session-activation", "task-activation", "turn-activation",
"tc-activation-newest", "", "completed", map[string]interface{}{"status": "completed"}, newest, newest)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
@@ -604,7 +605,7 @@ func TestSubagentContextActivationKeysWrittenOnce(t *testing.T) {
t.Fatalf("subagent_context_backfill_through = %v, want newest message created_at %v", parsed, newest)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay runMigrations: %v", err)
}
captureSinceReplayed, _ := readMetaKey(t, db, "subagent_context_capture_since")
@@ -624,7 +625,7 @@ func TestSubagentContextActivationKeysWrittenOnce(t *testing.T) {
func TestSubagentContextActivationBackfillThroughEmptyWithNoMessages(t *testing.T) {
repo, db := newSubagentMigrationTestRepo(t)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
@@ -659,7 +660,7 @@ func TestSubagentContextBackfillDoesNotRescanOnceActivated(t *testing.T) {
ts, ts,
)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("first runMigrations (the real, one-time backfill): %v", err)
}
if count := countSubagentContextRows(t, repo, "session-once", "tc-once"); count != 1 {
@@ -671,7 +672,7 @@ func TestSubagentContextBackfillDoesNotRescanOnceActivated(t *testing.T) {
t.Fatalf("delete backfilled row: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("second runMigrations (a later boot): %v", err)
}
if count := countSubagentContextRows(t, repo, "session-once", "tc-once"); count != 0 {
@@ -728,7 +729,7 @@ func TestSubagentContextBackfillStatementFailureLogsWarnWithMigrationName(t *tes
t.Fatalf("drop updated_at column: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations must swallow the failure, not return it: %v", err)
}
@@ -771,7 +772,7 @@ func TestSubagentContextBackfillDoesNotRescanWhenBackfillThroughEmpty(t *testing
repo, db := newSubagentMigrationTestRepo(t)
seedForMsgTest(t, repo, "task-empty-guard", "session-empty-guard", "turn-empty-guard")
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("first runMigrations (activates with no messages): %v", err)
}
backfillThrough, ok := readMetaKey(t, db, "subagent_context_backfill_through")
@@ -786,7 +787,7 @@ func TestSubagentContextBackfillDoesNotRescanWhenBackfillThroughEmpty(t *testing
seedSubagentMessage(t, repo, "msg-empty-guard", "session-empty-guard", "task-empty-guard", "turn-empty-guard",
"tc-empty-guard", "", "completed", map[string]interface{}{"status": "completed"}, ts, ts)
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("second runMigrations (a later boot, message now exists): %v", err)
}
if count := countSubagentContextRows(t, repo, "session-empty-guard", "tc-empty-guard"); count != 0 {
@@ -80,10 +80,10 @@ func TestPostgresSubagentContextSchemaAndBackfill(t *testing.T) {
if _, err := db.Exec(`DELETE FROM kandev_meta WHERE key IN ('subagent_context_capture_since', 'subagent_context_backfill_through')`); err != nil {
t.Fatalf("reset activation keys: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay runMigrations: %v", err)
}
@@ -265,7 +265,7 @@ func TestPostgresSubagentContextBackfillJSONHelpers(t *testing.T) {
if _, err := db.Exec(`DELETE FROM kandev_meta WHERE key IN ('subagent_context_capture_since', 'subagent_context_backfill_through')`); err != nil {
t.Fatalf("reset activation keys: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("runMigrations must not abort on malformed metadata rows: %v", err)
}
@@ -1,6 +1,7 @@
package sqlite
import (
"context"
"path/filepath"
"testing"
"time"
@@ -63,10 +64,10 @@ func TestTaskExternalIDMigrationAddsColumnsAndIndex(t *testing.T) {
t.Fatalf("create task without external_id after migration: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations twice: %v", err)
}
}
@@ -46,10 +46,10 @@ func TestTaskRepositoryBranchPolicyMigrationPreservesLegacyRows(t *testing.T) {
}
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("migrate legacy task repository schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay legacy task repository migration: %v", err)
}
@@ -29,7 +29,7 @@ func TestPostgresTaskStatusSummarySchemaReplay(t *testing.T) {
if _, err := db.Exec(`DROP TABLE task_status_summaries`); err != nil {
t.Fatalf("drop summary table to simulate legacy schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay postgres migrations: %v", err)
}
@@ -66,10 +66,10 @@ func TestTaskStatusSummarySchemaReplayAndCascade(t *testing.T) {
t.Fatalf("summary rows after task deletion = %d, want 0", count)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations twice: %v", err)
}
}
@@ -201,10 +201,10 @@ func TestTaskWorkspaceFoldersMigrationReplaysAfterLegacyTableIsMissing(t *testin
if _, err := repo.DB().Exec(`DROP TABLE task_workspace_folders`); err != nil {
t.Fatalf("simulate legacy schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("migrate legacy schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay workspace-folder migration: %v", err)
}
var tableName string
@@ -28,7 +28,7 @@ func TestPostgresWorktreeBranchTemplateMigration(t *testing.T) {
if err := repo.CreateRepository(ctx, custom); err != nil {
t.Fatalf("create custom repository: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay custom template migration: %v", err)
}
assertPostgresWorktreeBranchTemplate(t, db, custom.ID, custom.WorktreeBranchTemplate)
@@ -56,10 +56,10 @@ func TestPostgresWorktreeBranchTemplateMigration(t *testing.T) {
if _, err := db.Exec(`ALTER TABLE repositories DROP COLUMN worktree_branch_template`); err != nil {
t.Fatalf("remove template column from legacy schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("migrate legacy postgres schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay legacy postgres migration: %v", err)
}
@@ -24,10 +24,10 @@ func TestWorktreeBranchTemplateMigrationPreservesCustomValue(t *testing.T) {
t.Fatalf("create repository: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay migrations: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("second replay migrations: %v", err)
}
@@ -76,10 +76,10 @@ func TestWorktreeBranchTemplateMigrationBackfillsLegacyPrefix(t *testing.T) {
if _, err := repo.db.Exec(`ALTER TABLE repositories DROP COLUMN worktree_branch_template`); err != nil {
t.Fatalf("remove template column from legacy schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("migrate legacy schema: %v", err)
}
if err := repo.runMigrations(); err != nil {
if err := repo.runMigrations(context.Background()); err != nil {
t.Fatalf("replay legacy migration: %v", err)
}
@@ -5,12 +5,14 @@ import (
"testing"
"github.com/kandev/kandev/internal/persistence/requiredstores"
"github.com/kandev/kandev/internal/startup"
)
func TestValidateAdaptersRejectsMissingCapability(t *testing.T) {
catalog := []requiredstores.Descriptor{{
ID: "store", OwnerPackage: "test/store", RequiredTables: []string{"values_table"},
Capabilities: []requiredstores.Capability{requiredstores.CapabilityBoolean},
Sweep: startup.StepStoresRepositories,
}}
adapter := Adapter{
ID: "store",
@@ -26,7 +28,7 @@ func TestValidateAdaptersRejectsMissingCapability(t *testing.T) {
}
func TestValidateAdaptersRejectsMissingEngine(t *testing.T) {
catalog := []requiredstores.Descriptor{{ID: "store", OwnerPackage: "test/store", RequiredTables: []string{"values_table"}}}
catalog := []requiredstores.Descriptor{{ID: "store", OwnerPackage: "test/store", RequiredTables: []string{"values_table"}, Sweep: startup.StepStoresRepositories}}
adapter := Adapter{
ID: "store",
Engines: map[EngineName]EngineAdapter{EngineSQLite: {Fresh: noop, Replay: noop}},
@@ -38,7 +40,7 @@ func TestValidateAdaptersRejectsMissingEngine(t *testing.T) {
}
func TestRunUsesStableEngineStoreScenarioNames(t *testing.T) {
catalog := []requiredstores.Descriptor{{ID: "store", OwnerPackage: "test/store", RequiredTables: []string{"values_table"}}}
catalog := []requiredstores.Descriptor{{ID: "store", OwnerPackage: "test/store", RequiredTables: []string{"values_table"}, Sweep: startup.StepStoresRepositories}}
seen := make(chan string, 3)
callback := func(name string) Scenario {
return func(s ScenarioContext) error {
@@ -75,6 +77,7 @@ func TestCapabilityScenarioUsesDatabase(t *testing.T) {
catalog := []requiredstores.Descriptor{{
ID: "store", OwnerPackage: "test/store", RequiredTables: []string{"values_table"},
Capabilities: []requiredstores.Capability{requiredstores.CapabilityTransaction},
Sweep: startup.StepStoresRepositories,
}}
adapter := Adapter{
ID: "store",
+107
View File
@@ -0,0 +1,107 @@
package webapp
import (
"strconv"
"strings"
)
// mediaRange is one comma-separated entry of a parsed Accept header.
type mediaRange struct {
typ, subtype string
q float64
}
// PrefersHTML reports whether header resolves text/html, by the most
// specific matching media range, to a quality strictly greater than the one
// it resolves for application/json (AC-PLATFORM-STARTUP-PROGRESS-003.3). An
// absent or malformed header, or one that does not clear that bar - including
// a bare */* - reports false rather than promoting an unparseable entry.
func PrefersHTML(header string) bool {
ranges := parseAccept(header)
return acceptQuality(ranges, "text", "html") > acceptQuality(ranges, "application", "json")
}
// parseAccept parses header into its media ranges, dropping any entry whose
// type/subtype or q parameter cannot be parsed rather than defaulting it to
// an acceptable quality. An explicit q=0 range is kept, not dropped: it is
// how a client excludes a specific type while still accepting a broader
// wildcard, and dropping it would let the wildcard's quality leak through
// for the type the client named as unacceptable.
func parseAccept(header string) []mediaRange {
if header == "" {
return nil
}
var ranges []mediaRange
for _, part := range strings.Split(header, ",") {
fields := strings.Split(strings.TrimSpace(part), ";")
typePair := strings.SplitN(strings.TrimSpace(fields[0]), "/", 2)
if len(typePair) != 2 || typePair[0] == "" || typePair[1] == "" {
continue
}
q, ok := acceptQualityParam(fields[1:])
if !ok {
continue
}
ranges = append(ranges, mediaRange{
typ: strings.ToLower(strings.TrimSpace(typePair[0])),
subtype: strings.ToLower(strings.TrimSpace(typePair[1])),
q: q,
})
}
return ranges
}
// acceptQualityParam reads the q parameter from one Accept field's
// ";"-separated parameters, defaulting to 1.0 when none is present. It
// reports ok=false for a q parameter present but unparseable - including a
// value with trailing garbage after the number, or one outside [0, 1] - so
// the caller excludes the range instead of promoting a malformed value to
// accepted. The parameter name is matched case-insensitively per RFC 7231.
func acceptQualityParam(params []string) (float64, bool) {
q := 1.0
for _, field := range params {
key, value, found := strings.Cut(strings.TrimSpace(field), "=")
if !found || !strings.EqualFold(strings.TrimSpace(key), "q") {
continue
}
parsed, err := strconv.ParseFloat(strings.TrimSpace(value), 64)
if err != nil || parsed < 0 || parsed > 1 {
return 0, false
}
q = parsed
}
return q, true
}
// acceptQuality resolves the quality ranges assigns to typ/subtype: the
// q-value of the highest-specificity matching range (exact type/subtype >
// type/* > */*), or 0 when nothing matches. A tie at the same specificity
// resolves to the highest q among the tied ranges.
func acceptQuality(ranges []mediaRange, typ, subtype string) float64 {
bestSpecificity := -1
var bestQ float64
for _, r := range ranges {
specificity, ok := matchSpecificity(r, typ, subtype)
if !ok {
continue
}
if specificity > bestSpecificity || (specificity == bestSpecificity && r.q > bestQ) {
bestSpecificity = specificity
bestQ = r.q
}
}
return bestQ
}
func matchSpecificity(r mediaRange, typ, subtype string) (int, bool) {
switch {
case r.typ == typ && r.subtype == subtype:
return 2, true
case r.typ == typ && r.subtype == "*":
return 1, true
case r.typ == "*" && r.subtype == "*":
return 0, true
default:
return 0, false
}
}
@@ -0,0 +1,39 @@
package webapp
import "testing"
func TestPrefersHTML(t *testing.T) {
cases := []struct {
name string
header string
want bool
}{
{"empty header stays JSON", "", false},
{"json preferred over html stays JSON", "application/json;q=1, text/html;q=0.1", false},
{"equal quality stays JSON", "text/html;q=0.5, application/json;q=0.5", false},
{"bare wildcard stays JSON", "*/*", false},
{"html only prefers HTML", "text/html", true},
{"typical browser navigation header prefers HTML", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", true},
{"specific html wildcard loses to a higher-quality catch-all", "text/*;q=0.9,*/*;q=1.0", false},
{"exact match beats type wildcard even at lower q", "text/html;q=0.6,text/*;q=0.9", true},
{"malformed q value ignored", "text/html;q=bogus", false},
{"malformed media type ignored", "not-a-media-type;q=1", false},
{"json wildcard beats html when html unlisted", "application/*;q=1", false},
{"zero quality html excluded", "text/html;q=0", false},
{
"explicit q=0 exclusion beats a higher-quality wildcard",
"text/html;q=0.5, application/json;q=0, */*;q=1",
true,
},
{"malformed q with trailing garbage ignored", "text/html;q=.5junk", false},
{"out-of-range q ignored, does not leak wildcard quality", "text/html;q=2, */*;q=0.5", false},
{"uppercase Q parameter name is honored", "text/html;Q=0.9", true},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if got := PrefersHTML(tc.header); got != tc.want {
t.Fatalf("PrefersHTML(%q) = %v, want %v", tc.header, got, tc.want)
}
})
}
}
@@ -0,0 +1,151 @@
import { cleanup, render, screen, waitFor } from "@testing-library/react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { StartupSnapshot } from "@/lib/startup-progress/types";
import { RestartProgressDialog } from "./restart-progress-dialog";
const mocks = vi.hoisted(() => ({ fetchJson: vi.fn() }));
vi.mock("@/lib/api/client", async (importOriginal) => {
const actual = await importOriginal<typeof import("@/lib/api/client")>();
return { ...actual, fetchJson: mocks.fetchJson };
});
function snapshot(overrides: Partial<StartupSnapshot> = {}): StartupSnapshot {
return {
phase: "applying_migrations",
boot: 1,
seq: 1,
elapsed_ms: 5000,
phase_elapsed_ms: 5000,
...overrides,
};
}
beforeEach(() => {
mocks.fetchJson.mockReset();
// Never resolves by default, so a test that doesn't care about the poll
// outcome sees the pre-first-read "waiting" state deterministically.
mocks.fetchJson.mockReturnValue(new Promise(() => {}));
});
afterEach(() => {
cleanup();
});
describe("RestartProgressDialog", () => {
it("renders nothing while idle", () => {
const { container } = render(
<RestartProgressDialog phase="idle" errorMessage={null} onDismiss={vi.fn()} />,
);
expect(container.firstChild).toBeNull();
});
it("shows the waiting state before the first /ready read resolves", async () => {
render(<RestartProgressDialog phase="restarting" errorMessage={null} onDismiss={vi.fn()} />);
expect(await screen.findByText("Kandev is starting and not yet reachable.")).not.toBeNull();
});
it("renders phase and elapsed time alone for a snapshot with no active step", async () => {
mocks.fetchJson.mockResolvedValue({ startup: snapshot() });
render(<RestartProgressDialog phase="restarting" errorMessage={null} onDismiss={vi.fn()} />);
expect(await screen.findByText("Applying migrations")).not.toBeNull();
expect(screen.getByText("5 seconds elapsed")).not.toBeNull();
expect(screen.queryByRole("progressbar")).toBeNull();
});
it("renders step-level detail from a polled snapshot", async () => {
mocks.fetchJson.mockResolvedValue({
startup: snapshot({
step: {
id: "stores.repositories",
label_key: "startup.step.stores_repositories",
measure: "counted",
unit: "turns",
elapsed_ms: 1000,
done: 5,
total: 10,
eta_ms: 30000,
stalled: false,
},
}),
});
render(<RestartProgressDialog phase="restarting" errorMessage={null} onDismiss={vi.fn()} />);
expect(await screen.findByText("Applying migrations")).not.toBeNull();
expect(screen.getByText("5 seconds elapsed")).not.toBeNull();
expect(screen.getByText("Repository stores")).not.toBeNull();
expect(screen.getByText("5 of 10 turns")).not.toBeNull();
expect(screen.getByText("About 30 seconds remaining")).not.toBeNull();
});
it("renders stalled-state detail for a step that has not advanced (AC-PLATFORM-STARTUP-PROGRESS-004.6)", async () => {
mocks.fetchJson.mockResolvedValue({
startup: snapshot({
step: {
id: "stores.repositories",
label_key: "startup.step.stores_repositories",
measure: "counted",
unit: "turns",
elapsed_ms: 1000,
done: 5,
total: 10,
since_advance_ms: 125000,
stalled: true,
},
}),
});
render(<RestartProgressDialog phase="restarting" errorMessage={null} onDismiss={vi.fn()} />);
expect(await screen.findByText("5 of 10 turns")).not.toBeNull();
expect(screen.getByText("Stalled for 3 minutes")).not.toBeNull();
});
it("renders no stalled-state text for a running step", async () => {
mocks.fetchJson.mockResolvedValue({
startup: snapshot({
step: {
id: "stores.repositories",
label_key: "startup.step.stores_repositories",
measure: "counted",
unit: "turns",
elapsed_ms: 1000,
done: 5,
total: 10,
since_advance_ms: 500,
stalled: false,
},
}),
});
render(<RestartProgressDialog phase="restarting" errorMessage={null} onDismiss={vi.fn()} />);
expect(await screen.findByText("5 of 10 turns")).not.toBeNull();
expect(screen.queryByText(/Stalled for/)).toBeNull();
});
it("shows the last-known note once a read has been lost after an earlier success", async () => {
mocks.fetchJson
.mockResolvedValueOnce({ startup: snapshot() })
.mockRejectedValue(new TypeError("fetch failed"));
render(<RestartProgressDialog phase="restarting" errorMessage={null} onDismiss={vi.fn()} />);
await screen.findByText("Applying migrations");
await waitFor(
() => {
expect(screen.getByText("Last known")).not.toBeNull();
},
{ timeout: 2000 },
);
});
it("does not render startup progress detail outside the restarting phase", () => {
render(<RestartProgressDialog phase="done" errorMessage={null} onDismiss={vi.fn()} />);
expect(screen.queryByText("Kandev is starting and not yet reachable.")).toBeNull();
expect(mocks.fetchJson).not.toHaveBeenCalled();
});
});
@@ -11,9 +11,21 @@ import {
DialogHeader,
DialogTitle,
} from "@kandev/ui/dialog";
import { Progress } from "@kandev/ui/progress";
import { Spinner } from "@kandev/ui/spinner";
import { IconAlertTriangle, IconCheck } from "@tabler/icons-react";
import type { KandevRestartPhase } from "@/hooks/domains/system/use-kandev-restart";
import { useStartupProgress } from "@/hooks/domains/system/use-startup-progress";
import {
formatElapsed,
formatEta,
formatPhaseLabel,
formatStalled,
formatStepLabel,
formatStepProgress,
percentDone,
} from "@/lib/startup-progress/format";
import type { StartupSnapshot, StartupStepSnapshot } from "@/lib/startup-progress/types";
type RestartProgressDialogProps = {
phase: KandevRestartPhase;
@@ -27,6 +39,7 @@ export function RestartProgressDialog({
onDismiss,
}: RestartProgressDialogProps) {
const { t } = useTranslation();
const startupProgress = useStartupProgress(phase === "restarting");
if (phase === "idle") return null;
const done = phase === "done";
const failed = phase === "error";
@@ -44,6 +57,13 @@ export function RestartProgressDialog({
</DialogTitle>
<DialogDescription>{restartDescription(phase, errorMessage, t)}</DialogDescription>
</DialogHeader>
{phase === "restarting" && (
<StartupProgressDetail
snapshot={startupProgress.snapshot}
lastKnown={startupProgress.lastKnown}
t={t}
/>
)}
{(done || failed) && (
<DialogFooter>
<Button
@@ -101,3 +121,43 @@ function restartDescription(
return "";
}
}
type StartupProgressDetailProps = {
snapshot: StartupSnapshot | null;
lastKnown: boolean;
t: TFunction;
};
/** Step-level detail for the "restarting" phase, polled by useStartupProgress (AC-PLATFORM-STARTUP-PROGRESS-003). */
function StartupProgressDetail({ snapshot, lastKnown, t }: StartupProgressDetailProps) {
if (!snapshot) {
return (
<p className="text-muted-foreground text-sm" role="status" aria-live="polite">
{t("startup:page.waiting")}
</p>
);
}
return (
<div className="text-muted-foreground space-y-1 text-sm" role="status" aria-live="polite">
<p>{formatPhaseLabel(t, snapshot.phase)}</p>
<p>{formatElapsed(t, snapshot.elapsed_ms)}</p>
{snapshot.step && <StartupStepDetail step={snapshot.step} t={t} />}
{lastKnown && <p className="opacity-60">{t("startup:page.lastKnown")}</p>}
</div>
);
}
function StartupStepDetail({ step, t }: { step: StartupStepSnapshot; t: TFunction }) {
const showBar = step.measure === "counted" && (step.total ?? 0) > 0;
const showEta = step.measure === "counted" && step.eta_ms != null;
const showStalled = step.stalled && step.since_advance_ms != null;
return (
<>
<p>{formatStepLabel(t, step)}</p>
<p>{formatStepProgress(t, step)}</p>
{showEta && <p>{formatEta(t, step.eta_ms as number)}</p>}
{showBar && <Progress value={percentDone(step.done ?? 0, step.total ?? 0)} />}
{showStalled && <p>{formatStalled(t, step.since_advance_ms as number)}</p>}
</>
);
}
@@ -0,0 +1,58 @@
import { expect, test } from "../../fixtures/test-base";
import {
setAgentRuntimeAvailability,
stubAgentRuntimeRestart,
} from "../../helpers/agent-runtime-availability";
import { assertNoDocumentHorizontalOverflow } from "../../helpers/layout-assertions";
const PROGRESS_BODY = {
status: "starting",
startup: {
phase: "applying_migrations",
boot: 1,
seq: 1,
elapsed_ms: 12_000,
phase_elapsed_ms: 12_000,
step: {
id: "stores.services",
label_key: "startup.step.stores_services",
measure: "counted",
unit: "messages",
elapsed_ms: 12_000,
done: 400,
total: 1000,
eta_ms: 30_000,
stalled: false,
},
},
};
test("renders startup progress in the mobile restart dialog", async ({ testPage }) => {
await stubAgentRuntimeRestart(testPage);
await testPage.route("**/ready", (route) =>
route.fulfill({
status: 503,
contentType: "application/json",
body: JSON.stringify(PROGRESS_BODY),
}),
);
await testPage.goto("/stats");
await expect(testPage.getByTestId("app-shell")).toBeVisible();
await setAgentRuntimeAvailability(testPage, {
status: "unavailable",
reason: "agentctl_exited",
occurred_at: "2026-09-18T00:00:00Z",
});
const alert = testPage.getByTestId("agent-runtime-alert");
await expect(alert).toBeVisible();
await alert.getByRole("button", { name: "Restart Kandev" }).tap();
const dialog = testPage.getByTestId("restart-progress-dialog");
await expect(dialog).toHaveAttribute("data-phase", "restarting");
await expect(dialog).toContainText("Service stores");
await expect(dialog).toContainText("400 of 1000 messages");
await expect(dialog.getByRole("progressbar")).toHaveAttribute("aria-valuenow", "40");
await assertNoDocumentHorizontalOverflow(testPage, "mobile startup progress dialog");
});
@@ -0,0 +1,184 @@
import { expect, test } from "../../fixtures/test-base";
import {
setAgentRuntimeAvailability,
stubAgentRuntimeRestart,
} from "../../helpers/agent-runtime-availability";
type ReadyMode = "progress" | "unreachable" | "ready";
const PROGRESS_BODY = {
service: "kandev",
version: "e2e-test",
status: "starting",
startup: {
phase: "applying_migrations",
boot: 1,
seq: 1,
elapsed_ms: 12_000,
phase_elapsed_ms: 12_000,
step: {
id: "stores.services",
label_key: "startup.step.stores_services",
measure: "counted",
unit: "messages",
elapsed_ms: 12_000,
done: 400,
total: 1000,
rate_per_second: 33.3,
eta_ms: 30_000,
since_advance_ms: 500,
stalled: false,
},
},
};
const UNREACHABLE_BODY = { error: "internal error" };
const READY_BODY = { service: "kandev", version: "e2e-test", status: "ok" };
const STALLED_BODY = {
service: "kandev",
version: "e2e-test",
status: "starting",
startup: {
phase: "applying_migrations",
boot: 1,
seq: 1,
elapsed_ms: 130_000,
phase_elapsed_ms: 130_000,
step: {
id: "stores.services",
label_key: "startup.step.stores_services",
measure: "counted",
unit: "messages",
elapsed_ms: 130_000,
done: 400,
total: 1000,
since_advance_ms: 125_000,
stalled: true,
},
},
};
/**
* Drives RestartProgressDialog through a real (fully stubbed) restart and
* asserts the step-level detail added on top of the base phase/elapsed
* rendering (AC-PLATFORM-STARTUP-PROGRESS-003): step label, counted
* progress text, ETA, and the AC-PLATFORM-STARTUP-PROGRESS-002.6 status-code
* fallback rule for a response with no parseable snapshot - a failing status
* falls back to last-known, a successful one does not.
*/
test.describe("Restart progress dialog startup detail", () => {
test("renders step label and progress, and resolves a snapshot-free response by status", async ({
testPage,
}) => {
test.setTimeout(60_000);
let readyMode: ReadyMode = "progress";
await stubAgentRuntimeRestart(testPage);
await testPage.route("**/ready", (route) => {
if (readyMode === "progress") {
return route.fulfill({
status: 503,
contentType: "application/json",
body: JSON.stringify(PROGRESS_BODY),
});
}
if (readyMode === "unreachable") {
return route.fulfill({
status: 500,
contentType: "application/json",
body: JSON.stringify(UNREACHABLE_BODY),
});
}
return route.fulfill({
status: 200,
contentType: "application/json",
body: JSON.stringify(READY_BODY),
});
});
await testPage.goto("/stats");
await expect(testPage.getByTestId("app-shell")).toBeVisible();
await setAgentRuntimeAvailability(testPage, {
status: "unavailable",
reason: "agentctl_exited",
occurred_at: "2026-09-18T00:00:00Z",
});
const alert = testPage.getByTestId("agent-runtime-alert");
await expect(alert).toBeVisible();
await alert.getByRole("button", { name: "Restart Kandev" }).click();
const dialog = testPage.getByTestId("restart-progress-dialog");
await expect(dialog).toHaveAttribute("data-phase", "restarting");
await expect(dialog).toContainText("Applying migrations");
await expect(dialog).toContainText("Service stores");
await expect(dialog).toContainText("400 of 1000 messages");
await expect(dialog).toContainText("About 30 seconds remaining");
await expect(dialog.getByRole("progressbar")).toHaveAttribute("aria-valuenow", "40");
await expect(dialog.getByText("Last known")).toHaveCount(0);
// A failing status with no parseable snapshot falls back to last-known
// (AC-PLATFORM-STARTUP-PROGRESS-002.6/003.13): the prior step detail
// stays on screen, labelled stale rather than cleared.
readyMode = "unreachable";
await expect(dialog.getByText("Last known")).toBeVisible();
await expect(dialog).toContainText("Service stores");
await expect(dialog).toContainText("400 of 1000 messages");
// A successful status with no parseable snapshot means ready, not stale
// (AC-PLATFORM-STARTUP-PROGRESS-002.6): the status code is authoritative,
// so "Last known" must clear even though this response has no snapshot
// either.
readyMode = "ready";
await expect(dialog.getByText("Last known")).toHaveCount(0);
});
/**
* Covers AC-PLATFORM-STARTUP-PROGRESS-004.6: the Settings restart dialog
* must distinguish a stalled step from a running one, state how long it has
* gone without progress, and clear that state within one refresh interval
* once the step advances again.
*/
test("shows a stalled step and clears it once progress resumes", async ({ testPage }) => {
test.setTimeout(60_000);
let stalled = true;
await stubAgentRuntimeRestart(testPage);
await testPage.route("**/ready", (route) => {
const body = stalled ? STALLED_BODY : PROGRESS_BODY;
return route.fulfill({
status: 503,
contentType: "application/json",
body: JSON.stringify(body),
});
});
await testPage.goto("/stats");
await expect(testPage.getByTestId("app-shell")).toBeVisible();
await setAgentRuntimeAvailability(testPage, {
status: "unavailable",
reason: "agentctl_exited",
occurred_at: "2026-09-18T00:00:00Z",
});
const alert = testPage.getByTestId("agent-runtime-alert");
await expect(alert).toBeVisible();
await alert.getByRole("button", { name: "Restart Kandev" }).click();
const dialog = testPage.getByTestId("restart-progress-dialog");
await expect(dialog).toHaveAttribute("data-phase", "restarting");
await expect(dialog).toContainText("400 of 1000 messages");
await expect(dialog).toContainText("Stalled for 3 minutes");
stalled = false;
await expect(dialog).not.toContainText("Stalled for 3 minutes");
await expect(dialog).toContainText("400 of 1000 messages");
});
});
@@ -0,0 +1,116 @@
import type { Route } from "@playwright/test";
import { expect, test } from "../../fixtures/test-base";
type StartupSnapshot = Record<string, unknown>;
const STARTING_SNAPSHOT: StartupSnapshot = {
phase: "applying_migrations",
boot: 1,
seq: 1,
elapsed_ms: 12_000,
phase_elapsed_ms: 12_000,
step: {
id: "stores.services",
label_key: "startup.step.stores_services",
measure: "counted",
unit: "messages",
elapsed_ms: 12_000,
done: 400,
total: 1000,
eta_ms: 30_000,
stalled: false,
},
};
const ADVANCED_BODY = {
status: "starting",
startup: {
...STARTING_SNAPSHOT,
seq: 2,
step: { ...(STARTING_SNAPSHOT.step as Record<string, unknown>), done: 700, eta_ms: 10_000 },
},
};
const READY_BODY = {
status: "ok",
startup: { phase: "ready", boot: 1, seq: 3, elapsed_ms: 20_000, phase_elapsed_ms: 500 },
};
const POST_RELOAD_HTML =
'<!DOCTYPE html><html><body><div data-testid="post-reload-marker">app is up</div></body></html>';
/**
* Drives the Go-rendered startup page (internal/backendapp/startup_page.go)
* through a real browser instead of httptest string-matching: the initial
* markup comes from the production renderer via the E2E-only fixture route,
* and only /ready and the app navigation are mocked, so the embedded poll
* script runs unmodified.
*/
test.describe("Startup page (real render)", () => {
test("polls for step progress and reloads once the snapshot reports ready", async ({
backend,
browser,
request,
}) => {
const startingHtml = await request
.post(`${backend.baseUrl}/api/v1/e2e/startup-page-fixture`, { data: STARTING_SNAPSHOT })
.then((res) => res.text());
const context = await browser.newContext({ baseURL: backend.frontendUrl });
const page = await context.newPage();
let readyBody: unknown = { status: "starting", startup: STARTING_SNAPSHOT };
let appIsReady = false;
const fulfillReady = (route: Route) =>
route.fulfill({
status: appIsReady ? 200 : 503,
contentType: "application/json",
body: JSON.stringify(readyBody),
});
const fulfillAppRoute = (route: Route) =>
appIsReady
? route.fulfill({ status: 200, contentType: "text/html", body: POST_RELOAD_HTML })
: route.fulfill({ status: 503, contentType: "text/html", body: startingHtml });
await page.route(
(url) => url.pathname === "/ready",
(route) => fulfillReady(route),
);
await page.route(
(url) => url.pathname === "/startup-page-e2e-fixture",
(route) => fulfillAppRoute(route),
);
await page.goto("/startup-page-e2e-fixture");
await expect(page.locator("#startup-phase")).toHaveText("Applying migrations");
await expect(page.locator("#startup-step-label")).toHaveText("Service stores");
await expect(page.locator("#startup-progress")).toHaveText("400 of 1000 messages");
await expect(page.locator("#startup-eta")).toHaveText("About 30 seconds remaining");
// A failing response with a malformed snapshot must keep the last valid
// detail and mark it as stale. The status code remains authoritative when
// the body shape cannot be trusted.
readyBody = { status: "starting", startup: { ...STARTING_SNAPSHOT, step: {} } };
await expect(page.getByText("Last known")).toBeVisible();
await expect(page.locator("#startup-step-label")).toHaveText("Service stores");
await expect(page.locator("#startup-progress")).toHaveText("400 of 1000 messages");
// Poll-driven update: the embedded script re-fetches /ready on its own
// schedule and re-renders in place, with no test-issued reload.
readyBody = ADVANCED_BODY;
await expect(page.locator("#startup-progress")).toHaveText("700 of 1000 messages");
await expect(page.locator("#startup-eta")).toHaveText("About 10 seconds remaining");
// Reload-on-ready: once a poll response's snapshot reports phase "ready",
// the script calls location.reload() itself; the re-navigation this test
// observes is the real app route being requested a second time.
appIsReady = true;
readyBody = READY_BODY;
await expect(page.getByTestId("post-reload-marker")).toBeVisible();
await context.close();
});
});
@@ -1,5 +1,5 @@
import { act, renderHook, waitFor } from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({
fetchSystemInfo: vi.fn(),
@@ -28,6 +28,10 @@ beforeEach(() => {
mocks.releaseBackendReloadOwner.mockReset();
});
afterEach(() => {
vi.useRealTimers();
});
describe("useKandevRestart", () => {
it("starts a restart and waits for a new boot id", async () => {
mocks.fetchSystemInfo
@@ -64,6 +68,28 @@ describe("useKandevRestart", () => {
expect(result.current.isRestarting).toBe(true);
});
it("keeps waiting when startup takes longer than three minutes", async () => {
vi.useFakeTimers();
mocks.fetchSystemInfo
.mockResolvedValueOnce({ boot_id: "boot-1" })
.mockRejectedValue(new Error("connection refused"));
mocks.requestRestart.mockResolvedValue({ accepted: true, message: "Restarting" });
const { result } = renderHook(() => useKandevRestart());
await act(async () => {
await result.current.start();
});
expect(result.current.phase).toBe("restarting");
await act(async () => {
await vi.advanceTimersByTimeAsync(180_001);
});
expect(result.current.phase).toBe("restarting");
expect(result.current.errorMessage).toBeNull();
});
it("reports an error when the restart request fails", async () => {
mocks.fetchSystemInfo.mockResolvedValueOnce({ boot_id: "boot-1" });
mocks.requestRestart.mockRejectedValue(new Error("unsupported launch mode"));
@@ -11,7 +11,6 @@ import { t } from "@/lib/i18n";
export type KandevRestartPhase = "idle" | "starting" | "restarting" | "done" | "error";
const POLL_INTERVAL_MS = 2000;
const MAX_DURATION_MS = 3 * 60 * 1000;
type UseKandevRestartArgs = {
onComplete?: () => void;
@@ -32,7 +31,6 @@ export function useKandevRestart({
const [errorMessage, setErrorMessage] = useState<string | null>(null);
const [previousBootID, setPreviousBootID] = useState<string | null>(null);
const activeRef = useRef(false);
const startedAtRef = useRef<number | null>(null);
const ownerReleaseRef = useRef<(() => void) | null>(null);
const claimReloadOwnership = useCallback(() => {
@@ -63,7 +61,6 @@ export function useKandevRestart({
try {
const before = await fetchSystemInfo({ cache: "no-store" });
setPreviousBootID(before.boot_id);
startedAtRef.current = Date.now();
await requestRestart();
setPhase("restarting");
} catch (e) {
@@ -77,7 +74,6 @@ export function useKandevRestart({
setPhase("idle");
setErrorMessage(null);
setPreviousBootID(null);
startedAtRef.current = null;
}, [releaseReloadOwnership]);
useEffect(() => releaseReloadOwnership, [releaseReloadOwnership]);
@@ -88,13 +84,6 @@ export function useKandevRestart({
let cancelled = false;
const tick = async () => {
const startedAt = startedAtRef.current ?? Date.now();
if (Date.now() - startedAt > MAX_DURATION_MS) {
if (!cancelled) {
fail(t("system:restartTimedOut"));
}
return;
}
try {
const info = await fetchSystemInfo({ cache: "no-store" });
if (cancelled) return;
@@ -0,0 +1,193 @@
import { act, renderHook, waitFor } from "@testing-library/react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { ApiError } from "@/lib/api/client";
import type { StartupSnapshot } from "@/lib/startup-progress/types";
const mocks = vi.hoisted(() => ({ fetchJson: vi.fn() }));
vi.mock("@/lib/api/client", async (importOriginal) => {
const actual = await importOriginal<typeof import("@/lib/api/client")>();
return { ...actual, fetchJson: mocks.fetchJson };
});
import { useStartupProgress } from "./use-startup-progress";
function snapshot(overrides: Partial<StartupSnapshot> = {}): StartupSnapshot {
return {
phase: "applying_migrations",
boot: 1,
seq: 1,
elapsed_ms: 1000,
phase_elapsed_ms: 1000,
...overrides,
};
}
beforeEach(() => {
mocks.fetchJson.mockReset();
});
afterEach(() => {
vi.useRealTimers();
});
describe("useStartupProgress", () => {
it("does not poll while disabled", async () => {
renderHook(() => useStartupProgress(false));
await Promise.resolve();
expect(mocks.fetchJson).not.toHaveBeenCalled();
});
it("applies the snapshot from a successful poll", async () => {
mocks.fetchJson.mockResolvedValue({ startup: snapshot() });
const { result } = renderHook(() => useStartupProgress(true));
await waitFor(() => expect(result.current.snapshot).not.toBeNull());
expect(result.current.snapshot?.phase).toBe("applying_migrations");
expect(result.current.lastKnown).toBe(false);
});
it("treats a parseable 503 body as fresh data, not a failure", async () => {
mocks.fetchJson.mockRejectedValue(
new ApiError("starting", 503, {
status: "starting",
startup: snapshot({ phase: "opening_database" }),
}),
);
const { result } = renderHook(() => useStartupProgress(true));
await waitFor(() => expect(result.current.snapshot?.phase).toBe("opening_database"));
expect(result.current.lastKnown).toBe(false);
});
it("falls back to last known on a response with no parseable snapshot", async () => {
vi.useFakeTimers();
mocks.fetchJson
.mockResolvedValueOnce({ startup: snapshot() })
.mockRejectedValueOnce(new TypeError("fetch failed"));
const { result } = renderHook(() => useStartupProgress(true));
await act(async () => {
await Promise.resolve();
});
expect(result.current.snapshot).not.toBeNull();
await act(async () => {
await vi.advanceTimersByTimeAsync(1000);
});
expect(result.current.lastKnown).toBe(true);
expect(result.current.snapshot?.phase).toBe("applying_migrations");
});
it("treats a successful response with no snapshot as ready, not last known", async () => {
vi.useFakeTimers();
mocks.fetchJson
.mockResolvedValueOnce({ startup: snapshot() })
.mockResolvedValueOnce({ service: "kandev", version: "e2e-test", status: "ok" });
const { result } = renderHook(() => useStartupProgress(true));
await act(async () => {
await Promise.resolve();
});
expect(result.current.snapshot).not.toBeNull();
await act(async () => {
await vi.advanceTimersByTimeAsync(1000);
});
expect(result.current.lastKnown).toBe(false);
});
it("treats invalid JSON from a successful response as ready", async () => {
vi.useFakeTimers();
mocks.fetchJson
.mockResolvedValueOnce({ startup: snapshot() })
.mockRejectedValueOnce(new ApiError("invalid JSON", 200, null));
const { result } = renderHook(() => useStartupProgress(true));
await act(async () => {
await Promise.resolve();
});
await act(async () => {
await vi.advanceTimersByTimeAsync(1000);
});
expect(result.current.lastKnown).toBe(false);
expect(result.current.snapshot).not.toBeNull();
});
});
describe("useStartupProgress validation and cleanup", () => {
it("keeps the last valid snapshot when a later body is malformed", async () => {
vi.useFakeTimers();
const first = snapshot();
mocks.fetchJson
.mockResolvedValueOnce({ startup: first })
.mockResolvedValueOnce({ startup: { ...first, step: {} } });
const { result } = renderHook(() => useStartupProgress(true));
await act(async () => {
await Promise.resolve();
});
expect(result.current.snapshot).toEqual(first);
await act(async () => {
await vi.advanceTimersByTimeAsync(1000);
});
expect(result.current.snapshot).toEqual(first);
expect(result.current.lastKnown).toBe(false);
});
it("skips a tick while the previous poll is still outstanding", async () => {
vi.useFakeTimers();
let resolveFirst!: (value: { startup: StartupSnapshot }) => void;
mocks.fetchJson.mockImplementationOnce(
() =>
new Promise((resolve) => {
resolveFirst = resolve;
}),
);
renderHook(() => useStartupProgress(true));
await act(async () => {
await vi.advanceTimersByTimeAsync(1000);
});
expect(mocks.fetchJson).toHaveBeenCalledTimes(1);
resolveFirst({ startup: snapshot() });
await act(async () => {
await Promise.resolve();
});
});
it("resets to null when disabled after being enabled", async () => {
mocks.fetchJson.mockResolvedValue({ startup: snapshot() });
const { result, rerender } = renderHook(({ enabled }) => useStartupProgress(enabled), {
initialProps: { enabled: true },
});
await waitFor(() => expect(result.current.snapshot).not.toBeNull());
rerender({ enabled: false });
expect(result.current.snapshot).toBeNull();
expect(result.current.lastKnown).toBe(false);
});
it("aborts an active request when disabled", async () => {
let signal: AbortSignal | undefined;
mocks.fetchJson.mockImplementation((_path: string, options: { init?: RequestInit }) => {
signal = options.init?.signal as AbortSignal | undefined;
return new Promise(() => {});
});
const { rerender } = renderHook(({ enabled }) => useStartupProgress(enabled), {
initialProps: { enabled: true },
});
await waitFor(() => expect(signal).toBeDefined());
rerender({ enabled: false });
expect(signal?.aborted).toBe(true);
});
});

Some files were not shown because too many files have changed in this diff Show More