Add run lifecycle report projection

2026-08-06 20:35:13 +08:00
parent 4e78957a60
commit 68921b3f68
13 changed files with 270 additions and 8 deletions
@@ -142,6 +142,7 @@ func TestRunHTTPEnvelopeRequiresValidSignatureAndRejectsReplay(t *testing.T) {
 	assertErrorResponse(t, staleClaim, http.StatusUnauthorized, errorCodeUnauthorized)

 	privateUpdateBodies := map[string]any{
+		"/api/v1/run/lifecycle/report":             dto.RunLifecycleReportRequest{RunEndpointID: "run-local", SessionToken: token, ServerInstanceID: "server-signed", Capability: domain.LifecycleCapabilityStart, State: domain.JobStateSucceeded, Progress: dto.JobProgressBody{Percent: 100}, ExecutionResult: dto.RunJobExecutionResultBody{Kind: "process", ProcessState: "running"}},
 		"/api/v1/run/jobs/dependency-input":        dto.DependencyExecutionInputRequest{RunEndpointID: "run-local", SessionToken: token, JobID: "job-signed", LeaseToken: "lease", Attempt: 1},
 		"/api/v1/run/jobs/protected-request-input": dto.ProtectedRequestExecutionInputRequest{RunEndpointID: "run-local", SessionToken: token, JobID: "job-signed", LeaseToken: "lease", Attempt: 1, FencingToken: 1},
 		"/api/v1/run/jobs/source-rcon-input":       dto.SourceRCONExecutionInputRequest{RunEndpointID: "run-local", SessionToken: token, JobID: "job-signed", LeaseToken: "lease", Attempt: 1},
@@ -42,6 +42,28 @@ func TestRunControlAPIHelloHeartbeatWorkflow(t *testing.T) {
 	}
 }

+func TestRunLifecycleReportAPIProjectsServerState(t *testing.T) {
+	router := newTestRouter()
+	adminSession := createAdminSession(t, router)
+	postJSON[dto.GamePluginResponse](t, router, "/api/v1/game-plugins", validGamePluginRequest())
+	helloRequest := validRunControlHelloRequest()
+	helloRequest.CapabilityReport.Capabilities = append(helloRequest.CapabilityReport.Capabilities, domain.LifecycleCapabilityInstall, domain.LifecycleCapabilityStart, domain.LifecycleCapabilityStop, "logs.read")
+	helloRequest.CapabilityReport.Fingerprint = "cap-lifecycle-report"
+	hello := decodeBody[dto.RunControlHelloResponse](t, performRunControlHello(t, router, helloRequest))
+	server := postJSONWithAuth[dto.ServerInstanceResponse](t, router, "/api/v1/server-instances", dto.ServerInstanceCreateRequest{ID: "server-lifecycle-report-api", PluginID: "server.scum", RunEndpointID: "run-local", Name: "Lifecycle Report API", State: domain.ServerInstanceStateReady}, adminSession)
+
+	recorder := performJSON(t, router, http.MethodPost, "/api/v1/run/lifecycle/report", dto.RunLifecycleReportRequest{RunEndpointID: "run-local", SessionToken: hello.SessionToken, ServerInstanceID: server.ID, Capability: domain.LifecycleCapabilityStart, State: domain.JobStateSucceeded, Progress: dto.JobProgressBody{Percent: 100, Message: "autonomous start complete"}, Message: "autonomous start complete", ExecutionResult: dto.RunJobExecutionResultBody{Kind: "process", ProcessState: "running", AuditSummary: "private supervised process identity"}})
+	assertStatus(t, recorder, http.StatusOK)
+	response := decodeBody[dto.RunLifecycleReportResponse](t, recorder)
+	if !response.Accepted || response.ProjectedState != domain.ServerInstanceStateRunning {
+		t.Fatalf("expected lifecycle report projection, got %+v", response)
+	}
+	updated := getJSONWithAuth[dto.ServerInstanceResponse](t, router, "/api/v1/server-instances/"+server.ID, adminSession)
+	if updated.State != domain.ServerInstanceStateRunning {
+		t.Fatalf("expected server state projected running, got %+v", updated)
+	}
+}
+
 func TestRunControlAPIReRegistrationRotatesToken(t *testing.T) {
 	router := newTestRouter()
 	first := decodeBody[dto.RunControlHelloResponse](t, performRunControlHello(t, router, validRunControlHelloRequest()))
@@ -120,6 +120,7 @@ func (h *coreHandlers) register(mux *http.ServeMux) {
 	mux.HandleFunc("/api/v1/server-instances/{id}", h.serverInstanceDetail)
 	mux.HandleFunc("/api/v1/run/control/hello", h.runControlHello)
 	mux.HandleFunc("/api/v1/run/control/heartbeat", h.requireRunSignature(h.runControlHeartbeat))
+	mux.HandleFunc("/api/v1/run/lifecycle/report", h.requireRunSignature(h.runLifecycleReport))
 	mux.HandleFunc("/api/v1/run/jobs/claim", h.requireRunSignature(h.runJobClaim))
 	mux.HandleFunc("/api/v1/run/jobs/ack", h.requireRunSignature(h.runJobAck))
 	mux.HandleFunc("/api/v1/run/jobs/progress", h.requireRunSignature(h.runJobProgress))
@@ -1697,6 +1698,35 @@ func (h *coreHandlers) runControlHeartbeat(w http.ResponseWriter, r *http.Reques
 	writeJSON(w, http.StatusOK, dto.RunControlHeartbeatFromDomain(result))
 }

+// runLifecycleReport godoc
+// @Summary Report autonomous run lifecycle result
+// @Description Lets a registered run endpoint report an observed lifecycle terminal result without a platform-assigned job lease.
+// @Tags run
+// @Accept json
+// @Produce json
+// @Param body body dto.RunLifecycleReportRequest true "Run lifecycle report request"
+// @Success 200 {object} dto.RunLifecycleReportResponse
+// @Failure 400 {object} dto.ErrorResponse
+// @Failure 405 {object} dto.ErrorResponse
+// @Router /api/v1/run/lifecycle/report [post]
+func (h *coreHandlers) runLifecycleReport(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		writeMethodNotAllowed(w, http.MethodPost)
+		return
+	}
+	request, err := decodeJSON[dto.RunLifecycleReportRequest](r)
+	if err != nil {
+		writeDecodeError(w, err)
+		return
+	}
+	result, err := h.core.ReportRunLifecycle(request.ToDomain())
+	if err != nil {
+		writeServiceError(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, dto.RunLifecycleReportFromDomain(result))
+}
+
 // runJobClaim godoc
 // @Summary Claim one run job
 // @Description Lets a registered run endpoint claim one queued job assigned to it using the active session token.
@@ -53,6 +53,26 @@ type RunControlHeartbeatResult struct {
 	ServerTime           time.Time
 }

+type RunLifecycleReport struct {
+	RunEndpointID    string
+	SessionToken     string
+	ServerInstanceID string
+	Capability       string
+	State            JobState
+	Progress         RunJobProgressReport
+	Message          string
+	ErrorCode        string
+	ExecutionResult  JobExecutionResult
+}
+
+type RunLifecycleReportResult struct {
+	Accepted         bool
+	RunEndpointID    string
+	ServerInstanceID string
+	ProjectedState   ServerInstanceState
+	ServerTime       time.Time
+}
+
 type RunControlSession struct {
 	RunEndpointID            string
 	SessionToken             string `json:"-"`
@@ -103,6 +123,16 @@ func CopyRunControlHeartbeatResult(result RunControlHeartbeatResult) RunControlH
 	return result
 }

+func CopyRunLifecycleReport(report RunLifecycleReport) RunLifecycleReport {
+	report.ExecutionResult.ServerDeploymentEvidence = CopyServerDeploymentEvidence(report.ExecutionResult.ServerDeploymentEvidence)
+	report.ExecutionResult.DeploymentReceipt = CopyServerDeploymentExecutionReceipt(report.ExecutionResult.DeploymentReceipt)
+	return report
+}
+
+func CopyRunLifecycleReportResult(result RunLifecycleReportResult) RunLifecycleReportResult {
+	return result
+}
+
 func CopyRunControlSession(session RunControlSession) RunControlSession {
 	session.UsedNonces = CopyStringSlice(session.UsedNonces)
 	return session
@@ -57,6 +57,26 @@ type RunControlHeartbeatResponse struct {
 	ServerTime           time.Time `json:"serverTime"`
 }

+type RunLifecycleReportRequest struct {
+	RunEndpointID    string                    `json:"runEndpointId"`
+	SessionToken     string                    `json:"sessionToken"`
+	ServerInstanceID string                    `json:"serverInstanceId"`
+	Capability       string                    `json:"capability"`
+	State            domain.JobState           `json:"state"`
+	Progress         JobProgressBody           `json:"progress"`
+	Message          string                    `json:"message,omitempty"`
+	ErrorCode        string                    `json:"errorCode,omitempty"`
+	ExecutionResult  RunJobExecutionResultBody `json:"executionResult,omitempty"`
+}
+
+type RunLifecycleReportResponse struct {
+	Accepted         bool                       `json:"accepted"`
+	RunEndpointID    string                     `json:"runEndpointId"`
+	ServerInstanceID string                     `json:"serverInstanceId"`
+	ProjectedState   domain.ServerInstanceState `json:"projectedState,omitempty"`
+	ServerTime       time.Time                  `json:"serverTime"`
+}
+
 func (request RunControlHelloRequest) ToDomain() domain.RunControlHello {
 	return domain.RunControlHello{
 		RegistrationToken: request.RegistrationToken,
@@ -92,6 +112,20 @@ func (request RunControlHeartbeatRequest) ToDomain() domain.RunControlHeartbeat
 	}
 }

+func (request RunLifecycleReportRequest) ToDomain() domain.RunLifecycleReport {
+	return domain.RunLifecycleReport{
+		RunEndpointID:    request.RunEndpointID,
+		SessionToken:     request.SessionToken,
+		ServerInstanceID: request.ServerInstanceID,
+		Capability:       request.Capability,
+		State:            request.State,
+		Progress:         progressReportToDomain(request.Progress),
+		Message:          request.Message,
+		ErrorCode:        request.ErrorCode,
+		ExecutionResult:  domain.JobExecutionResult{Kind: request.ExecutionResult.Kind, ProcessState: request.ExecutionResult.ProcessState, ExitClassification: request.ExecutionResult.ExitClassification, ExitCode: request.ExecutionResult.ExitCode, Version: request.ExecutionResult.Version, Checksum: request.ExecutionResult.Checksum, SizeBytes: request.ExecutionResult.SizeBytes, AuditSummary: request.ExecutionResult.AuditSummary, Content: request.ExecutionResult.Content, ServerDeploymentEvidence: serverDeploymentEvidenceToDomain(request.ExecutionResult.ServerDeploymentEvidence), DeploymentReceipt: deploymentReceiptToDomain(request.ExecutionResult.DeploymentReceipt)},
+	}
+}
+
 func RunControlHelloFromDomain(result domain.RunControlHelloResult) RunControlHelloResponse {
 	result = domain.CopyRunControlHelloResult(result)
 	return RunControlHelloResponse{
@@ -114,3 +148,8 @@ func RunControlHeartbeatFromDomain(result domain.RunControlHeartbeatResult) RunC
 		ServerTime:           result.ServerTime,
 	}
 }
+
+func RunLifecycleReportFromDomain(result domain.RunLifecycleReportResult) RunLifecycleReportResponse {
+	result = domain.CopyRunLifecycleReportResult(result)
+	return RunLifecycleReportResponse{Accepted: result.Accepted, RunEndpointID: result.RunEndpointID, ServerInstanceID: result.ServerInstanceID, ProjectedState: result.ProjectedState, ServerTime: result.ServerTime}
+}
@@ -63,6 +63,8 @@ Platform-owned Run distribution builds embed an autonomous lifecycle plan for th

 The plan is build input for the generated package, not a machine-side job-channel payload. Generated Run registration must not be treated as a trigger to enqueue `process.start`, `process.install`, or `process.status` work; Platform state converges from Run heartbeats, logs, lifecycle reports, supervised process facts, and terminal job/report messages. Platform and Run must not add game-specific hardcoding to interpret the plan.

+Autonomous lifecycle reports use `POST /api/v1/run/lifecycle/report` with the active Run session and signed envelope when required. The route accepts only bounded terminal lifecycle facts for `process.install`, `process.start`, `process.stop`, or `process.status`; it validates the server/run binding, records audit evidence, and projects server state from Run-reported process facts without creating or completing a Platform job.
+
 ## Log Ingest

 Implemented HTTP JSON routes:
@@ -432,6 +432,38 @@ func TestCoreServiceGeneratedSCUMRunRegistrationDoesNotQueueGuidedStart(t *testi
 	}
 }

+func TestCoreServiceRunLifecycleReportProjectsGeneratedRunFacts(t *testing.T) {
+	svc := newTestCoreService()
+	plugin := createGeneratedRunStatusPlugin(t, svc)
+	instance := domain.ServerInstance{ID: "managed-autonomous-start", PluginID: plugin.ID, PluginVersion: plugin.Version, RunEndpointID: dedicatedRunEndpointID("managed-autonomous-start"), Name: "Managed Autonomous Start", State: domain.ServerInstanceStateDraft, ConfigVersion: 1, Deployment: domain.ServerDeploymentDefinition{Mode: domain.ServerDeploymentModeGuided, ProfileKey: "run-local", ServerRoot: `D:\scum-autonomous`, Revision: 1}}
+	if err := svc.store.ServerInstances().Create(instance); err != nil {
+		t.Fatalf("create autonomous server: %v", err)
+	}
+	registered := registerGeneratedRunForStatusTest(t, svc, instance, plugin.ID)
+
+	reported, err := svc.ReportRunLifecycle(domain.RunLifecycleReport{RunEndpointID: instance.RunEndpointID, SessionToken: registered.SessionToken, ServerInstanceID: instance.ID, Capability: domain.LifecycleCapabilityStart, State: domain.JobStateSucceeded, Progress: domain.RunJobProgressReport{Percent: 100, Message: "autonomous start complete"}, Message: "autonomous start complete", ExecutionResult: domain.JobExecutionResult{Kind: "process", ProcessState: "running", AuditSummary: "private supervised process identity"}})
+	if err != nil || !reported.Accepted || reported.ProjectedState != domain.ServerInstanceStateRunning {
+		t.Fatalf("expected accepted lifecycle report projected running, result=%+v err=%v", reported, err)
+	}
+	stored, err := svc.GetServerInstance(instance.ID)
+	if err != nil || stored.State != domain.ServerInstanceStateRunning {
+		t.Fatalf("expected Run report to project server running, server=%+v err=%v", stored, err)
+	}
+	jobs, err := svc.store.Jobs().List(domain.JobFilter{ServerInstanceID: instance.ID})
+	if err != nil || len(jobs) != 0 {
+		t.Fatalf("autonomous lifecycle report must not create platform jobs, jobs=%+v err=%v", jobs, err)
+	}
+
+	other := domain.ServerInstance{ID: "managed-autonomous-other", PluginID: plugin.ID, PluginVersion: plugin.Version, RunEndpointID: dedicatedRunEndpointID("managed-autonomous-other"), Name: "Managed Autonomous Other", State: domain.ServerInstanceStateDraft, ConfigVersion: 1}
+	if err := svc.store.ServerInstances().Create(other); err != nil {
+		t.Fatalf("create other server: %v", err)
+	}
+	_, err = svc.ReportRunLifecycle(domain.RunLifecycleReport{RunEndpointID: instance.RunEndpointID, SessionToken: registered.SessionToken, ServerInstanceID: other.ID, Capability: domain.LifecycleCapabilityStart, State: domain.JobStateSucceeded, Progress: domain.RunJobProgressReport{Percent: 100}, ExecutionResult: domain.JobExecutionResult{Kind: "process", ProcessState: "running"}})
+	if err == nil || !strings.Contains(err.Error(), "runEndpointId must match server instance") {
+		t.Fatalf("expected report for another server binding to be rejected, err=%v", err)
+	}
+}
+
 func TestCoreServiceGeneratedRunRegistrationDoesNotDispatchStatusReconciliation(t *testing.T) {
 	svc := newTestCoreService()
 	plugin := createGeneratedRunStatusPlugin(t, svc)
@@ -139,6 +139,7 @@ type Core interface {
 	AckRunJob(domain.RunJobAck) (domain.RunJobAckResult, error)
 	UpdateRunJobProgress(domain.RunJobProgress) (domain.RunJobProgressResult, error)
 	CompleteRunJob(domain.RunJobResult) (domain.RunJobResultResult, error)
+	ReportRunLifecycle(domain.RunLifecycleReport) (domain.RunLifecycleReportResult, error)
 	GetDistributionBuildInput(domain.DistributionBuildInputRequest) (domain.DistributionBuildInput, error)
 	GetDependencyExecutionInput(domain.DependencyExecutionInputRequest) (domain.DependencyExecutionInput, error)
 	DispatchSourceRCONCommandForSession(string, domain.SourceRCONCommandRequest) (domain.SourceRCONCommandDispatch, error)
@@ -2,13 +2,65 @@ package service

 import (
 	"strings"
-
 	"time"

 	"browser.local/platform/domain"
 	"browser.local/platform/validator"
 )

+func (svc *CoreService) ReportRunLifecycle(report domain.RunLifecycleReport) (domain.RunLifecycleReportResult, error) {
+	report = domain.CopyRunLifecycleReport(report)
+	if err := validator.ValidateRunLifecycleReport(report); err != nil {
+		return domain.RunLifecycleReportResult{}, err
+	}
+	if _, err := svc.validatedRunSession(report.RunEndpointID, report.SessionToken); err != nil {
+		return domain.RunLifecycleReportResult{}, err
+	}
+	instance, err := svc.store.ServerInstances().Get(report.ServerInstanceID)
+	if err != nil {
+		return domain.RunLifecycleReportResult{}, err
+	}
+	if instance.RunEndpointID != report.RunEndpointID {
+		return domain.RunLifecycleReportResult{}, validationError("runEndpointId must match server instance")
+	}
+	if instance.State == domain.ServerInstanceStateDeleted {
+		return domain.RunLifecycleReportResult{}, validationError("server instance must not be deleted")
+	}
+
+	stamp := svc.now()
+	nextState, projected := lifecycleProjectedState(report.Capability, report.State, report.ExecutionResult)
+	if projected {
+		instance.State = nextState
+		instance.UpdatedAt = stamp
+		if err := validator.ValidateServerInstance(instance); err != nil {
+			return domain.RunLifecycleReportResult{}, err
+		}
+		if err := svc.store.ServerInstances().Update(instance); err != nil {
+			return domain.RunLifecycleReportResult{}, err
+		}
+	}
+	auditResult := domain.AuditResultSuccess
+	if report.State == domain.JobStateFailed || report.State == domain.JobStateCancelled {
+		auditResult = domain.AuditResultFailed
+	}
+	if err := svc.recordAuditEvent("run:"+report.RunEndpointID, "lifecycle.report", "server-instance", instance.ID, auditResult, lifecycleReportSummary(report, nextState, projected)); err != nil {
+		return domain.RunLifecycleReportResult{}, err
+	}
+	return domain.CopyRunLifecycleReportResult(domain.RunLifecycleReportResult{Accepted: true, RunEndpointID: report.RunEndpointID, ServerInstanceID: report.ServerInstanceID, ProjectedState: nextState, ServerTime: stamp}), nil
+}
+
+func lifecycleReportSummary(report domain.RunLifecycleReport, projectedState domain.ServerInstanceState, projected bool) string {
+	for _, candidate := range []string{report.ExecutionResult.AuditSummary, report.Progress.Message, report.Message, report.ErrorCode} {
+		if strings.TrimSpace(candidate) != "" {
+			return candidate
+		}
+	}
+	if projected {
+		return "run reported " + report.Capability + " " + string(report.State) + "; projected server state " + string(projectedState)
+	}
+	return "run reported " + report.Capability + " " + string(report.State)
+}
+
 func (svc *CoreService) projectRemoteAdapterJobResult(job domain.Job, stamp time.Time) error {
 	if !strings.HasPrefix(job.Capability, "remote.") || job.ServerInstanceID == "" || !isTerminalJobState(job.State) {
 		return nil
@@ -54,6 +54,30 @@ func ValidateRunJobResult(result domain.RunJobResult) error {
 	return finish(violations)
 }

+func ValidateRunLifecycleReport(report domain.RunLifecycleReport) error {
+	var violations []string
+	violations = appendRequired(violations, "runEndpointId", report.RunEndpointID)
+	violations = appendRequired(violations, "sessionToken", report.SessionToken)
+	violations = appendRequired(violations, "serverInstanceId", report.ServerInstanceID)
+	violations = appendRequired(violations, "capability", report.Capability)
+	if !validLifecycleReportCapability(report.Capability) {
+		violations = append(violations, "capability must be process.install, process.start, process.stop, or process.status")
+	}
+	if !validTerminalJobState(report.State) {
+		violations = append(violations, "state must be succeeded, failed, or cancelled")
+	}
+	violations = appendProgressViolations(violations, report.Progress)
+	violations = appendMessageLength(violations, "message", report.Message)
+	violations = appendMessageLength(violations, "errorCode", report.ErrorCode)
+	if len([]byte(report.ExecutionResult.Content)) > maxJobChannelMessageLength*256 {
+		violations = append(violations, "executionResult.content is too large")
+	}
+	if report.ExecutionResult.Checksum != "" && !validSHA256Checksum(report.ExecutionResult.Checksum) {
+		violations = append(violations, "executionResult.checksum must be sha256:<hex>")
+	}
+	return finish(violations)
+}
+
 func ValidateDistributionBuildInputRequest(request domain.DistributionBuildInputRequest) error {
 	var violations []string
 	violations = appendLeaseFields(violations, request.RunEndpointID, request.SessionToken, request.JobID, request.LeaseToken, request.Attempt)
@@ -159,7 +183,7 @@ func appendProgressViolations(violations []string, progress domain.RunJobProgres

 func validDeploymentProgressPhase(phase string) bool {
 	switch phase {
-	case "queued", "claimed", "preflight", "install", "configure", "start", "health":
+	case "queued", "claimed", "preflight", "install", "configure", "start", "stop", "status", "health":
 		return true
 	default:
 		return false
@@ -181,3 +205,12 @@ func validTerminalJobState(state domain.JobState) bool {
 		return false
 	}
 }
+
+func validLifecycleReportCapability(capability string) bool {
+	switch capability {
+	case domain.LifecycleCapabilityInstall, domain.LifecycleCapabilityStart, domain.LifecycleCapabilityStop, domain.LifecycleCapabilityStatus:
+		return true
+	default:
+		return false
+	}
+}