1// Package deployment implements the app deployment engine: preflight,
2// journaled execution, and terminal-result computation.
3package deployment
4
5import (
6 "context"
7 "encoding/hex"
8 "errors"
9 "fmt"
10 "maps"
11 "sort"
12 "strings"
13 "sync"
14 "time"
15
16 "github.com/bnema/zerowrap"
17 "github.com/google/uuid"
18
19 "github.com/bnema/gordon/internal/boundaries/out"
20 "github.com/bnema/gordon/internal/domain"
21 "github.com/bnema/gordon/pkg/validation"
22)
23
24// Deps are the driven adapters owned by the deployment engine.
25type Deps struct {
26 State out.AppState
27 Runtime out.ContainerRuntime
28 Images out.ImageResolver
29 Secrets out.SecretProvider
30 // Registry configures image pulls from the installation registry.
31 // Domain scopes which refs pull with auth; empty disables pulling.
32 Registry RegistryConfig
33 // Networks is the installation network policy applied to every app
34 // workload: the prefix used to derive Gordon-owned network names and
35 // whether those networks block external egress.
36 Networks NetworkConfig
37 // Limits are the installation container resource limits applied on
38 // every create and recovery path. Zero means unlimited.
39 Limits ResourceLimits
40 // ImagePolicy restricts which registries and references may be
41 // resolved, pulled, or run. It is enforced on every path, including
42 // boot, restart, and recovery.
43 ImagePolicy domain.ImageSourcePolicy
44 // Traffic is the serialized HTTP/L4 publish boundary. Rebuilt after
45 // every activation (deploy/start/restart/stop/remove) so the proxy
46 // host index follows ACTIVE; recovery also withdraws one service
47 // fail-closed before touching a workload. Nil in tests that assert
48 // state effects only. Failures are reported to the caller.
49 Traffic out.AppTrafficRefresher
50 // SecretFiles stores file-delivered secrets on the host. Optional:
51 // nil is valid only while no service delivers secrets as files;
52 // preflight refuses such services otherwise.
53 SecretFiles out.SecretFileStore
54 // Guard is checked on every app container config right before the
55 // runtime create. The zero value still refuses host/shared network
56 // namespaces and host paths passed as volume names.
57 Guard domain.RuntimeGuard
58}
59
60// RegistryConfig carries the installation registry identity for pulls.
61type RegistryConfig struct {
62 Domain string
63 PullAddress string
64 Username string
65 Password string
66}
67
68// NetworkConfig carries the installation network policy for app workloads.
69type NetworkConfig struct {
70 // Prefix names the Gordon-owned networks. Empty uses the domain default.
71 Prefix string
72 // Internal blocks external egress from containers attached to those
73 // networks (Docker's Internal flag).
74 Internal bool
75}
76
77// ResourceLimits are the installation container limits applied on every
78// create and recovery path. Zero values mean unlimited.
79type ResourceLimits struct {
80 MemoryBytes int64
81 NanoCPUs int64
82 PidsLimit int64
83}
84
85// Service orchestrates captured-revision deploys.
86type Service struct {
87 deps Deps
88 log zerowrap.Logger
89 probes *ProbeDeps
90
91 // coord serializes workload mutations per app: deploy/start/
92 // restart/stop/remove/boot lock blocking, periodic reconciliation
93 // skips busy apps.
94 coord *appCoordinator
95 // barrier is the process-wide GC barrier. A shared lease covers
96 // every workload mutation from resource selection through durable
97 // protection publication; prune holds the exclusive lease.
98 barrier out.GCBarrier
99 // backoff is the in-memory, generation-scoped recovery budget.
100 backoff *recoveryBackoff
101 // publication holds the in-memory publication inhibition: a
102 // service whose fail-closed withdrawal could not be applied must be
103 // withdrawn again before any later publication.
104 publication publicationInhibition
105 // executions remembers the last observed execution start per
106 // generation, so a native restart is detected without restarting
107 // the workload ourselves.
108 executions executionTracker
109 // bindMu guards bindPolicies. A config reload replaces the whole
110 // map atomically; deploy paths read the current map without holding
111 // the lock.
112 bindMu sync.RWMutex
113 bindPolicies map[string]domain.AppBindPolicy
114 // deviceMu guards devicePolicies. A config reload replaces the whole
115 // map atomically; deploy paths read the current map without holding
116 // the lock.
117 deviceMu sync.RWMutex
118 devicePolicies map[string]domain.AppDevicePolicy
119 // liveMu guards liveOps. liveOps holds the operations this process
120 // owns between the StartDeploy claim and the end of ExecuteDeploy. It
121 // is in-memory only: a fresh Service (boot) starts empty and may
122 // reconcile every persisted non-terminal operation, while a
123 // foreground mutation must never finalize an operation a live
124 // goroutine still owns.
125 liveMu sync.Mutex
126 liveOps map[string]struct{}
127}
128
129// NewService creates the deployment engine. All deps are required;
130// Secrets may be nil only in tests that never reach secret preflight.
131func NewService(deps Deps, log zerowrap.Logger) *Service {
132 if deps.ImagePolicy.InstallationRegistry == "" {
133 deps.ImagePolicy.InstallationRegistry = deps.Registry.Domain
134 }
135 return &Service{
136 deps: deps,
137 log: log,
138 coord: newAppCoordinator(),
139 backoff: newRecoveryBackoff(time.Now),
140 }
141}
142
143// markOperationLive records that this process owns one operation from the
144// StartDeploy claim until ExecuteDeploy finishes. A live operation is the
145// single owner's in-flight work: a foreground reconciliation must not
146// finalize it, or the claim would be settled before the owner can execute it.
147func (s *Service) markOperationLive(app, op string) {
148 if app == "" || op == "" {
149 return
150 }
151 s.liveMu.Lock()
152 defer s.liveMu.Unlock()
153 if s.liveOps == nil {
154 s.liveOps = make(map[string]struct{})
155 }
156 s.liveOps[liveOperationKey(app, op)] = struct{}{}
157}
158
159// clearOperationLive drops the live marker. It is called once ExecuteDeploy
160// has recorded its outcome or left the claim recoverable, so a later
161// reconciliation can converge the operation instead of leaving it in flight.
162func (s *Service) clearOperationLive(app, op string) {
163 s.liveMu.Lock()
164 defer s.liveMu.Unlock()
165 delete(s.liveOps, liveOperationKey(app, op))
166}
167
168// operationLive reports whether this process still owns the operation.
169func (s *Service) operationLive(app, op string) bool {
170 s.liveMu.Lock()
171 defer s.liveMu.Unlock()
172 _, ok := s.liveOps[liveOperationKey(app, op)]
173 return ok
174}
175
176func liveOperationKey(app, op string) string {
177 return app + "\x00" + op
178}
179
180// WithGCBarrier wires the process-wide GC barrier. Every workload
181// mutation holds a shared lease from resource selection through the
182// durable publication of the resource's protection, so prune can never
183// observe a half-acquired resource. Nil is valid for tests that never
184// run prune.
185func (s *Service) WithGCBarrier(barrier out.GCBarrier) *Service {
186 s.barrier = barrier
187 return s
188}
189
190// WithBindPolicies supplies the initial administrative bind policies.
191func (s *Service) WithBindPolicies(policies map[string]domain.AppBindPolicy) *Service {
192 s.SetBindPolicies(policies)
193 return s
194}
195
196// SetBindPolicies atomically replaces the administrative bind policies used
197// to authorize service binds. The map is copied so later caller mutation
198// cannot race an in-flight deploy.
199func (s *Service) SetBindPolicies(policies map[string]domain.AppBindPolicy) {
200 copied := make(map[string]domain.AppBindPolicy, len(policies))
201 for name, policy := range policies {
202 copied[name] = policy
203 }
204 s.bindMu.Lock()
205 s.bindPolicies = copied
206 s.bindMu.Unlock()
207}
208
209// snapshotBindPolicies returns the current policy map. SetBindPolicies never
210// mutates a published map, so the snapshot stays safe after the lock drops.
211func (s *Service) snapshotBindPolicies() map[string]domain.AppBindPolicy {
212 s.bindMu.RLock()
213 defer s.bindMu.RUnlock()
214 return s.bindPolicies
215}
216
217// WithDevicePolicies supplies the initial administrative device policies.
218func (s *Service) WithDevicePolicies(policies map[string]domain.AppDevicePolicy) *Service {
219 s.SetDevicePolicies(policies)
220 return s
221}
222
223// SetDevicePolicies atomically replaces the administrative device policies
224// used to authorize service devices. The map and its slices are copied so
225// later caller mutation cannot race an in-flight deploy.
226func (s *Service) SetDevicePolicies(policies map[string]domain.AppDevicePolicy) {
227 copied := make(map[string]domain.AppDevicePolicy, len(policies))
228 for name, policy := range policies {
229 policy.CDI = append([]string(nil), policy.CDI...)
230 policy.AllowedApps = append([]string(nil), policy.AllowedApps...)
231 policy.AllowedServices = append([]string(nil), policy.AllowedServices...)
232 copied[name] = policy
233 }
234 s.deviceMu.Lock()
235 s.devicePolicies = copied
236 s.deviceMu.Unlock()
237}
238
239// snapshotDevicePolicies returns the current policy map. SetDevicePolicies
240// never mutates a published map, so the snapshot stays safe after the
241// lock drops.
242func (s *Service) snapshotDevicePolicies() map[string]domain.AppDevicePolicy {
243 s.deviceMu.RLock()
244 defer s.deviceMu.RUnlock()
245 return s.devicePolicies
246}
247
248// resolveServiceDevices resolves every declared logical device against the
249// current administrative policies into runtime CDI IDs. Errors name only
250// the app, service, and device: host inventory never appears.
251func (s *Service) resolveServiceDevices(app string, svc domain.AppService) ([]string, error) {
252 if len(svc.Devices) == 0 {
253 return nil, nil
254 }
255 ids, err := domain.ResolveAppDevices(app, svc.Name, svc.Devices, s.snapshotDevicePolicies())
256 if err != nil {
257 return nil, fmt.Errorf("deployment: %w", err)
258 }
259 return ids, nil
260}
261
262// resolveServiceBinds resolves every declared bind against the current
263// administrative policies into ephemeral runtime binds. Errors name only the
264// app, service, and mount: host source paths never appear.
265func (s *Service) resolveServiceBinds(app string, svc domain.AppService) ([]domain.ContainerBind, error) {
266 if len(svc.Binds) == 0 {
267 return nil, nil
268 }
269 policies := s.snapshotBindPolicies()
270 resolved := make([]domain.ContainerBind, 0, len(svc.Binds))
271 for _, bind := range svc.Binds {
272 policy, ok := policies[bind.Name]
273 if !ok {
274 return nil, fmt.Errorf("deployment: app %q service %q mount %q: no administrative mount policy configured: %w", app, svc.Name, bind.Name, domain.ErrBindPolicy)
275 }
276 r, err := policy.ResolveAppBind(app, svc.Name, bind)
277 if err != nil {
278 return nil, fmt.Errorf("deployment: app %q service %q mount %q: refused by administrative mount policy: %w", app, svc.Name, bind.Name, domain.ErrBindPolicy)
279 }
280 resolved = append(resolved, domain.ContainerBind(r))
281 }
282 // Apply the runtime guard here so a bind overlapping a protected
283 // Gordon path fails at preflight and before the serving generation is
284 // retired, not only at create time. createContainer keeps the full
285 // guard as the final check.
286 if err := s.deps.Guard.Check(&domain.ContainerConfig{Binds: resolved}); err != nil {
287 return nil, fmt.Errorf("deployment: app %q service %q: %w", app, svc.Name, err)
288 }
289 return resolved, nil
290}
291
292// acquireAppContext takes the GC shared lease first and the per-app
293// coordinator second, following the documented lock order
294// (GC barrier → per-app coordinator → registry lock → bbolt
295// transaction). The returned release drops both, coordinator first.
296func (s *Service) acquireAppContext(ctx context.Context, app string) (func(), error) {
297 lease, err := s.acquireSharedGC(ctx)
298 if err != nil {
299 return nil, err
300 }
301 release, err := s.coord.acquire(ctx, app)
302 if err != nil {
303 lease.Release()
304 return nil, err
305 }
306 return func() {
307 release()
308 lease.Release()
309 }, nil
310}
311
312// tryAcquireAppContext takes the GC shared lease, then tries the per-app
313// coordinator without blocking. ok is false when the app is busy; the
314// caller skips it. Periodic reconciliation still waits for an in-flight
315// prune, because a half-planned snapshot is exactly what must not be
316// raced.
317func (s *Service) tryAcquireAppContext(ctx context.Context, app string) (func(), bool) {
318 lease, err := s.acquireSharedGC(ctx)
319 if err != nil {
320 return nil, false
321 }
322 release, ok := s.coord.tryAcquire(app)
323 if !ok {
324 lease.Release()
325 return nil, false
326 }
327 return func() {
328 release()
329 lease.Release()
330 }, true
331}
332
333// acquireSharedGC takes a shared GC lease, or a no-op lease when no
334// barrier is wired.
335func (s *Service) acquireSharedGC(ctx context.Context) (out.GCLease, error) {
336 if s.barrier == nil {
337 return noopGCLease{}, nil
338 }
339 return s.barrier.AcquireShared(ctx)
340}
341
342// noopGCLease is the lease used when no barrier is wired.
343type noopGCLease struct{}
344
345func (noopGCLease) Release() {}
346
347// WithProbeDeps overrides readiness probing (tests inject a mock-backed
348// ProbeDeps via NewProbeDeps; production leaves it nil for the live
349// runtime adapter).
350func (s *Service) WithProbeDeps(probes ProbeDeps) *Service {
351 s.probes = &probes
352 return s
353}
354
355// DeployInput selects the revision and service scope.
356type DeployInput struct {
357 App string
358 Revision string
359 Service string
360 Op string
361}
362
363// DeployResult carries terminal per-service results and cleanup warnings.
364type DeployResult struct {
365 Op string
366 App string
367 Revision string
368 Outcome string
369 Services map[string]ServiceResult
370 CleanupWarnings []CleanupWarning
371 // Removed names services retired because the new revision no longer
372 // declares them.
373 Removed []string
374}
375
376// ServiceResultUnchanged marks a deploy step that kept the running
377// container because its image, spec, and environment were already current.
378const ServiceResultUnchanged = domain.AppServiceUnchanged
379
380// ServiceResult is one service's terminal deployment result.
381type ServiceResult struct {
382 Result string
383 EffectiveRevision string
384 Before string
385 After string
386 RestartUnsafe bool
387 Error string
388 // VerifiedStartedAt is the execution start of After observed before its
389 // readiness ran. The caller records it as a verified execution once the
390 // generation is published and routed. Zero when unknown.
391 VerifiedStartedAt time.Time
392 // SupersededRunning is set by an overlap replacement: the container in
393 // Before still runs beside After and carries a retirement-pending marker
394 // until it is retired.
395 SupersededRunning bool
396 // BackendBinds carries the created container's TCP loopback publishes
397 // (container port -> 127.0.0.1 host port) for the active record.
398 BackendBinds map[int]int
399 // UDPBackendBinds carries the created container's UDP loopback
400 // publishes for the active record. Nil when the service declares
401 // no UDP interface.
402 UDPBackendBinds map[int]int
403 // CleanupWarnings are bounded leftovers of this service's terminal
404 // path: a candidate that could not be removed, or a backend claim
405 // that could not be released.
406 CleanupWarnings []CleanupWarning
407 // Diagnostics is bounded, redacted failure output of the failed
408 // candidate. It is never embedded in Error and is persisted to the
409 // journal for logs-scoped retrieval only.
410 Diagnostics []string
411}
412
413// CleanupWarning records post-publication leftovers for operator action.
414type CleanupWarning struct {
415 Service string
416 Leftover string
417 Detail string
418}
419
420// pinnedService binds a service spec to its resolved digest plus the
421// captured revision's app-wide public env (injected into every service
422// alongside that service's own resolved secrets). appEnv is a copy owned
423// by this pin: never mutated, never persisted with secret values.
424type pinnedService struct {
425 name string
426 spec domain.AppService
427 digest string
428 runtimeImage string
429 appEnv map[string]string
430 appNetworks []domain.AppSharedNetwork
431 // sharedNetworks are the declared shared-network memberships this
432 // service joins. The private incarnation network is derived from the
433 // app UUID at create time so recovery and deploy agree.
434 sharedNetworks []domain.AppSharedNetwork
435}
436
437// newOpID allocates a time-ordered op- identifier (uuid v7).
438func newOpID() string {
439 id, err := uuid.NewV7()
440 if err != nil {
441 id = uuid.New()
442 }
443 var buf [32]byte
444 hex.Encode(buf[:], id[:])
445 return "op-" + string(buf[:])
446}
447
448// claimDeploymentLocked is the first phase of a deploy: it resolves the
449// requested revision, enforces the targeted-deploy convergence rules, and
450// claims the request key, persisting the non-terminal journal. It performs
451// no image pull and no workload mutation, so a crash after it leaves a
452// durable claim that reconciliation can converge. owned is true only for the
453// single claimer of the key; a replay returns the stored journal instead.
454// The caller holds the app lock and has already recovered the store.
455func (s *Service) claimDeploymentLocked(ctx context.Context, input DeployInput) (domain.AppDesiredRevision, domain.AppOperation, bool, error) {
456 rev, err := s.resolveRevision(ctx, input)
457 if err != nil {
458 return domain.AppDesiredRevision{}, domain.AppOperation{}, false, err
459 }
460 if input.Service != "" {
461 if err := s.checkConverged(ctx, input.App, input.Service, rev); err != nil {
462 return domain.AppDesiredRevision{}, domain.AppOperation{}, false, err
463 }
464 }
465
466 op := domain.AppOperation{
467 Kind: "deploy",
468 App: input.App,
469 InputRevision: rev.Revision,
470 StartedAt: time.Now().UTC(),
471 Request: domain.AppOperationRequestFor("deploy", input.App, input.Revision, input.Service),
472 }
473 op, owned, err := s.claimOperation(ctx, input.Op, op, []domain.AppOperationStep{{ID: "preflight", State: domain.AppStepPending}})
474 if err != nil {
475 return domain.AppDesiredRevision{}, domain.AppOperation{}, false, err
476 }
477 return rev, op, owned, nil
478}
479
480// pinPreflightLocked is the second preflight phase: it runs the image
481// pull/pin and resource gates of an already claimed operation and records the
482// pinned table (or the terminal preflight failure) in the journal. The
483// caller holds the app lock and owns the claimed, non-terminal operation.
484func (s *Service) pinPreflightLocked(ctx context.Context, app, onlyService string, rev domain.AppDesiredRevision, op *domain.AppOperation) ([]pinnedService, error) {
485 log := zerowrap.FromCtx(ctx)
486
487 pinned, err := s.preflightServices(ctx, app, rev, onlyService)
488 if err != nil {
489 op.Steps[0] = domain.AppOperationStep{ID: "preflight", State: domain.AppStepFailed, Error: err.Error()}
490 op.Outcome = domain.AppOutcomeFailed
491 if saveErr := s.deps.State.SaveOperation(ctx, *op); saveErr != nil {
492 log.Warn().Err(saveErr).Msg("deployment: failed to record preflight failure")
493 }
494 return nil, err
495 }
496 op.Steps[0] = domain.AppOperationStep{ID: "preflight", State: domain.AppStepSucceeded}
497 // A resumed claim can carry the service-step plan of an earlier attempt,
498 // including candidates it recorded. Converge those candidates before
499 // replacing the plan: an unreconciled leftover may still be running, and
500 // the replacement this execution creates must never overlap it.
501 if err := s.convergeResumedCandidates(ctx, app, op, log); err != nil {
502 return nil, err
503 }
504 // Replace the persisted plan instead of appending: the preflight step plus
505 // one step per pinned service, so runServiceStep's index contract matches a
506 // normalized layout and no earlier step is overwritten or left pending.
507 plan := make([]domain.AppOperationStep, 1, len(pinned)+1)
508 plan[0] = op.Steps[0]
509 for _, p := range pinned {
510 plan = append(plan, domain.AppOperationStep{
511 ID: "service." + p.name + ".replace",
512 State: domain.AppStepPending,
513 Service: p.name,
514 Digest: p.digest,
515 Image: p.runtimeImage,
516 })
517 }
518 op.Steps = plan
519 if err := s.deps.State.SaveOperation(ctx, *op); err != nil {
520 return nil, fmt.Errorf("deployment: persist pinned table: %w", err)
521 }
522 log.Info().Str("op", op.Op).Str("revision", rev.Revision).Int("services", len(pinned)).Msg("deployment: preflight passed")
523 return pinned, nil
524}
525
526// convergeResumedCandidates converges any candidate an earlier attempt of a
527// resumed claim recorded, so replacing its service-step plan cannot drop a
528// leftover that may still be running. A fresh claim has only its preflight
529// step and does no work here.
530func (s *Service) convergeResumedCandidates(ctx context.Context, app string, op *domain.AppOperation, log zerowrap.Logger) error {
531 needsActive := false
532 for _, step := range op.Steps {
533 if reconcileNeedsContainer(step, false) {
534 needsActive = true
535 break
536 }
537 }
538 if !needsActive {
539 return nil
540 }
541 active, _, err := s.deps.State.LoadActive(ctx, app)
542 if err != nil {
543 return fmt.Errorf("deployment: load active for resumed claim: %w", err)
544 }
545 if _, err := s.convergeInterruptedSteps(ctx, app, op, active, false, log); err != nil {
546 return err
547 }
548 return nil
549}
550
551// claimOperation is the single claim point before any mutation effect.
552// A keyed request is claimed atomically: the first claim persists the
553// in-flight journal and reports owned=true; a repeat returns the stored
554// journal and reports owned=false. A key that already answered a
555// different request fails with ErrAppStateConflict, and a key for a name
556// with no app identity fails with ErrAppNotFound without writing
557// anything. An unkeyed request (internal recovery paths) starts a fresh
558// journal under a generated id.
559func (s *Service) claimOperation(ctx context.Context, key string, op domain.AppOperation, steps []domain.AppOperationStep) (domain.AppOperation, bool, error) {
560 op.Steps = steps
561 // A journal is never opened while a different operation of this app is
562 // still unfinished: that predecessor must be reconciled first, or this
563 // claim would mask it and its leftover generation could stay untracked.
564 latest, found, err := s.deps.State.LoadLatestOperation(ctx, op.App)
565 if err != nil {
566 return domain.AppOperation{}, false, fmt.Errorf("deployment: load latest operation: %w", err)
567 }
568 if found && !latest.Terminal() && latest.Op != key {
569 return domain.AppOperation{}, false, fmt.Errorf(
570 "deployment: app %q has unfinished operation %s: %w", op.App, latest.Op, domain.ErrAppStateConflict)
571 }
572 if key == "" {
573 op.Op = newOpID()
574 if err := s.deps.State.SaveOperation(ctx, op); err != nil {
575 return domain.AppOperation{}, false, fmt.Errorf("deployment: persist journal before effects: %w", err)
576 }
577 return op, true, nil
578 }
579 op.Op = key
580 existing, claimed, err := s.deps.State.ClaimOperation(ctx, op)
581 if err != nil {
582 return domain.AppOperation{}, false, err
583 }
584 if !claimed {
585 return existing, false, nil
586 }
587 return op, true, nil
588}
589
590// replayError reports a replayed key whose journal never reached a
591// terminal outcome: the operation is still in flight or was interrupted,
592// so its effects must not run again.
593func replayError(op domain.AppOperation) error {
594 if !op.Terminal() {
595 return fmt.Errorf("deployment: operation %s has not reached a terminal outcome: %w", op.Op, domain.ErrAppStateConflict)
596 }
597 if op.Outcome != domain.AppOutcomeSuccess {
598 return fmt.Errorf("deployment: operation %s previously ended with outcome %s: %w", op.Op, op.Outcome, domain.ErrAppStateConflict)
599 }
600 return nil
601}
602
603// resolveRevision loads the captured revision (default: current desired).
604// A revision that cannot be resolved on a name with no app identity at
605// all reports ErrAppNotFound: the failure is the missing app, not the
606// missing revision.
607func (s *Service) resolveRevision(ctx context.Context, input DeployInput) (domain.AppDesiredRevision, error) {
608 if input.Revision != "" {
609 rev, err := s.deps.State.LoadRevision(ctx, input.App, input.Revision)
610 if err != nil && errors.Is(err, domain.ErrAppRevisionNotFound) {
611 if knownErr := s.requireKnownApp(ctx, input.App); knownErr != nil {
612 return domain.AppDesiredRevision{}, knownErr
613 }
614 }
615 return rev, err
616 }
617 rev, ok, err := s.deps.State.LoadDesired(ctx, input.App)
618 if err != nil {
619 return domain.AppDesiredRevision{}, err
620 }
621 if !ok {
622 if knownErr := s.requireKnownApp(ctx, input.App); knownErr != nil {
623 return domain.AppDesiredRevision{}, knownErr
624 }
625 return domain.AppDesiredRevision{}, fmt.Errorf("deployment: app %q has no desired state: %w", input.App, domain.ErrAppRevisionNotFound)
626 }
627 return rev, nil
628}
629
630// requireKnownApp refuses a mutation of a name with no live app identity.
631func (s *Service) requireKnownApp(ctx context.Context, app string) error {
632 exists, err := s.deps.State.AppExists(ctx, app)
633 if err != nil {
634 return fmt.Errorf("deployment: app existence: %w", err)
635 }
636 if !exists {
637 return fmt.Errorf("deployment: app %q does not exist: %w", app, domain.ErrAppNotFound)
638 }
639 return nil
640}
641
642// checkConverged permits a targeted deploy when every desired/effective
643// difference belongs to that service. App-wide and other-service changes
644// must be deployed together so ACTIVE never combines incompatible specs.
645func (s *Service) checkConverged(ctx context.Context, app, service string, rev domain.AppDesiredRevision) error {
646 active, ok, err := s.deps.State.LoadActive(ctx, app)
647 if err != nil {
648 return err
649 }
650 if !ok {
651 return fmt.Errorf("deployment: app %q was never deployed, targeted deploy refused: %w", app, domain.ErrAppStateConflict)
652 }
653 if active.Converged && active.ConvergedRevision == rev.Revision {
654 return nil
655 }
656 diff := domain.DiffAppSpec(rev.Spec, effectiveAppSpec(active))
657 prefix := "service/" + service + "/"
658 if len(diff.Added) > 0 {
659 return targetedDivergenceError(rev.Revision, diff.Added[0]+" (added)")
660 }
661 if len(diff.Removed) > 0 {
662 return targetedDivergenceError(rev.Revision, diff.Removed[0]+" (removed)")
663 }
664 for _, path := range diff.Changed {
665 if !strings.HasPrefix(path, prefix) {
666 return targetedDivergenceError(rev.Revision, path)
667 }
668 }
669 return nil
670}
671
672func effectiveAppSpec(active domain.AppActive) domain.AppSpec {
673 spec := domain.AppSpec{Name: active.App, Networks: append([]domain.AppSharedNetwork(nil), active.Networks...)}
674 for name, service := range active.Services {
675 effective := service.Spec
676 effective.Name = name
677 spec.Services = append(spec.Services, effective)
678 }
679 return spec
680}
681
682func targetedDivergenceError(revision, path string) error {
683 return fmt.Errorf("%w: service-targeted deploy refused, desired %s also changes %s", domain.ErrAppStateConflict, revision, path)
684}
685
686// selectPreflightServices copies and optionally narrows a revision's services.
687func selectPreflightServices(rev domain.AppDesiredRevision, onlyService string) ([]domain.AppService, error) {
688 services := append([]domain.AppService(nil), rev.Spec.Services...)
689 if onlyService == "" {
690 return services, nil
691 }
692 for _, svc := range services {
693 if svc.Name == onlyService {
694 return []domain.AppService{svc}, nil
695 }
696 }
697 return nil, fmt.Errorf("deployment: service %q not in revision %s: %w", onlyService, rev.Revision, domain.ErrAppStateConflict)
698}
699
700// preflightServices runs the preflight gates in order. No mutation.
701func (s *Service) preflightServices(ctx context.Context, app string, rev domain.AppDesiredRevision, onlyService string) ([]pinnedService, error) {
702 services, err := selectPreflightServices(rev, onlyService)
703 if err != nil {
704 return nil, err
705 }
706 sort.Slice(services, func(i, j int) bool { return services[i].Name < services[j].Name })
707
708 var pinned []pinnedService
709 ownership, err := s.deps.State.LoadOwnership(ctx, app)
710 if err != nil {
711 return nil, err
712 }
713 // Defensive re-check: stored revisions predate or bypass apply
714 // validation; an overlap must fail preflight before any mutation.
715 if err := rev.Spec.CheckEnvSecretCollisions(); err != nil {
716 return nil, err
717 }
718 appEnv := maps.Clone(rev.Spec.Env)
719 if appEnv == nil {
720 appEnv = map[string]string{}
721 }
722 for _, svc := range services {
723 digest, err := s.deps.Images.ResolveDigest(ctx, svc.Image)
724 if err != nil {
725 return nil, fmt.Errorf("deployment: image %q unresolvable: %w", svc.Image, domain.ErrAppImageUnresolvable)
726 }
727 if err := s.checkSecrets(ctx, app, ownership.ID, svc); err != nil {
728 return nil, err
729 }
730 runtimeImage, err := s.preflightImage(ctx, svc.Image, digest)
731 if err != nil {
732 return nil, err
733 }
734 if err := s.checkImageVolumes(ctx, svc, runtimeImage); err != nil {
735 return nil, err
736 }
737 // Bind resolution stays a preflight gate: an unresolvable bind
738 // must fail before any workload mutation. The successful values
739 // are discarded because createAndStart re-resolves against the
740 // current policy immediately before the runtime mutation.
741 if _, err := s.resolveServiceBinds(app, svc); err != nil {
742 return nil, err
743 }
744 if err := s.preflightServiceDevices(ctx, app, svc, pinned); err != nil {
745 return nil, err
746 }
747 pinned = append(pinned, pinnedService{
748 name: svc.Name, spec: svc, digest: digest, runtimeImage: runtimeImage, appEnv: appEnv,
749 appNetworks: append([]domain.AppSharedNetwork(nil), rev.Spec.Networks...),
750 sharedNetworks: domain.AppServiceSharedNetworks(rev.Spec, svc.Name),
751 })
752 }
753 if err := s.recheckReservations(ctx, app, rev); err != nil {
754 return nil, err
755 }
756 if err := s.checkResources(ctx, app, ownership, services); err != nil {
757 return nil, err
758 }
759 return pinned, nil
760}
761
762// preflightServiceDevices runs the device authorization and engine
763// capability gates for one service. Split from preflightServices to keep
764// its complexity within budget.
765func (s *Service) preflightServiceDevices(ctx context.Context, app string, svc domain.AppService, pinned []pinnedService) error {
766 if _, err := s.resolveServiceDevices(app, svc); err != nil {
767 return err
768 }
769 // Engine capability is a knowable-before-mutation failure: a
770 // device-bearing revision on an unsupported engine must fail here,
771 // before withdrawal retires the serving generation. The check runs
772 // once per revision, on the first device-bearing service;
773 // CreateContainer keeps the same gate as defense.
774 if len(svc.Devices) > 0 && !devicesEngineChecked(pinned) {
775 if s.deps.Runtime == nil {
776 return fmt.Errorf("deployment: runtime unavailable: %w", domain.ErrRuntimeUnsupported)
777 }
778 // Sanitize the adapter cause: version-probe failures may embed
779 // the daemon endpoint, which must not reach journals or API
780 // responses. Cancellation and deadlines are the exception: they
781 // stay recognizable so aborted deploys are not misread as
782 // incapable engines.
783 if err := s.deps.Runtime.SupportsCDIDevices(ctx); err != nil {
784 return sanitizedEngineProbeError(svc.Name, err)
785 }
786 }
787 return nil
788}
789
790// sanitizedEngineProbeError maps an engine device-capability probe failure
791// onto the caller-visible error. Cancellation and deadlines survive so
792// shutdown and timeout handling keep working; every other cause collapses
793// to ErrRuntimeUnsupported alone, dropping the adapter text that may embed
794// the daemon endpoint.
795func sanitizedEngineProbeError(service string, err error) error {
796 switch {
797 case errors.Is(err, context.Canceled):
798 return fmt.Errorf("deployment: engine device capability check for service %q: %w", service, context.Canceled)
799 case errors.Is(err, context.DeadlineExceeded):
800 return fmt.Errorf("deployment: engine device capability check for service %q: %w", service, context.DeadlineExceeded)
801 default:
802 return fmt.Errorf("deployment: engine device capability check for service %q: %w", service, domain.ErrRuntimeUnsupported)
803 }
804}
805
806// devicesEngineChecked reports whether an earlier pinned service already
807// triggered the engine capability probe for this revision.
808func devicesEngineChecked(pinned []pinnedService) bool {
809 for _, p := range pinned {
810 if len(p.spec.Devices) > 0 {
811 return true
812 }
813 }
814 return false
815}
816
817// checkSecrets reads every required secret path once. Values stay in
818// memory for container creation only; nothing is written anywhere.
819// Paths are UUID-keyed so a removed app's secrets are never adopted
820// by a new app reusing the name.
821func (s *Service) checkSecrets(ctx context.Context, app, appID string, svc domain.AppService) error {
822 if len(svc.SecretFiles) > 0 && s.deps.SecretFiles == nil {
823 return fmt.Errorf("deployment: service %q delivers secrets as files but no secret file store is configured", svc.Name)
824 }
825 if s.deps.Secrets == nil {
826 return fmt.Errorf("deployment: secret provider unavailable: %w", domain.ErrAppSecretMissing)
827 }
828 for envKey, name := range svc.Secrets {
829 path := domain.AppSecretPathForID(appID, app, svc.Name, name)
830 if _, err := s.deps.Secrets.GetSecret(ctx, path); err != nil {
831 return fmt.Errorf("deployment: secret %s (env %s) missing: %w", path, envKey, domain.ErrAppSecretMissing)
832 }
833 }
834 return nil
835}
836
837// appSecretID returns the stable internal UUID for secret paths.
838// Empty means legacy name-keyed paths (records predating UUIDs).
839// Used on the execution path where preflight's ownership snapshot is
840// not in scope; deploys are infrequent, one extra store read per
841// service is acceptable.
842func (s *Service) appSecretID(ctx context.Context, app string) (string, error) {
843 ownership, err := s.deps.State.LoadOwnership(ctx, app)
844 if err != nil {
845 return "", err
846 }
847 return ownership.ID, nil
848}
849
850func (s *Service) preflightImage(ctx context.Context, image, digest string) (string, error) {
851 if err := validation.ValidateImageDigest(digest); err != nil {
852 return "", fmt.Errorf("deployment: image %q resolved to invalid digest: %w", image, domain.ErrAppImageUnresolvable)
853 }
854 if err := s.validateImageSource(image, digest); err != nil {
855 return "", err
856 }
857 if s.deps.Registry.Domain == "" {
858 return image, nil
859 }
860 return s.pullImage(ctx, stripImageTag(image)+"@"+digest)
861}
862
863// validateImageSource enforces the installation image policy on a
864// reference before any pull. Both the manifest reference and the pinned
865// digest are checked, so a digest-pinned ref cannot bypass the hostname
866// and port allowlist on deploy or recovery.
867func (s *Service) validateImageSource(image, digest string) error {
868 ref := strings.TrimSpace(image)
869 if digest != "" && !strings.Contains(ref, "@") {
870 ref = stripImageTag(image) + "@" + digest
871 }
872 if err := s.deps.ImagePolicy.ValidateImageSource(ref); err != nil {
873 return fmt.Errorf("deployment: image %q: %w", image, err)
874 }
875 return nil
876}
877
878// checkImageVolumes rejects images with unmapped VOLUME declarations.
879func (s *Service) checkImageVolumes(ctx context.Context, svc domain.AppService, runtimeImage string) error {
880 declared, err := s.deps.Runtime.InspectImageVolumes(ctx, runtimeImage)
881 if err != nil {
882 return fmt.Errorf("deployment: inspect image volumes: %w", err)
883 }
884 if len(declared) == 0 {
885 return nil
886 }
887 mapped := map[string]struct{}{}
888 for _, vol := range svc.Volumes {
889 mapped[vol.Path] = struct{}{}
890 }
891 // Bind destinations also map image-declared volumes: a bind that
892 // mounts over an image VOLUME is an explicit operator mapping.
893 for _, bind := range svc.Binds {
894 mapped[bind.Path] = struct{}{}
895 }
896 for _, path := range declared {
897 if _, ok := mapped[path]; !ok {
898 return fmt.Errorf(
899 "deployment: image declares unmanaged volume %q, map it explicitly: %w",
900 path, domain.ErrAppUnmanagedImageVolume,
901 )
902 }
903 }
904 return nil
905}
906
907// recheckReservations re-validates against the live global table.
908func (s *Service) recheckReservations(ctx context.Context, app string, rev domain.AppDesiredRevision) error {
909 checkpoint, err := s.deps.State.LoadCheckpoint(ctx)
910 if err != nil {
911 return err
912 }
913 reservations := domain.ReservationsFor(rev.Spec)
914 if err := domain.CheckReservations(checkpoint.Reservations, reservations, app); err != nil {
915 return fmt.Errorf("deployment: %w", err)
916 }
917 return nil
918}
919
920// checkResources verifies volumes exist-or-creatable and ownership is consistent.
921// A generated runtime volume that already exists but is NOT recorded in
922// this app's ownership is refused fail-closed: mounting it would
923// implicitly adopt (and possibly modify) foreign data. Volumes recorded
924// in ownership (attached or retained) were created by this app's own
925// deploys and are safe to reuse.
926func (s *Service) checkResources(ctx context.Context, app string, ownership domain.AppOwnership, services []domain.AppService) error {
927 owned := map[string]string{}
928 ownedRuntime := map[string]struct{}{}
929 for _, vol := range ownership.Volumes {
930 owned[vol.Name] = vol.Service
931 ownedRuntime[vol.RuntimeName] = struct{}{}
932 }
933 for _, svc := range services {
934 for _, vol := range svc.Volumes {
935 if owner, ok := owned[vol.Name]; ok && owner != svc.Name {
936 return fmt.Errorf(
937 "deployment: volume %q owned by %q, not %q: %w",
938 vol.Name, owner, svc.Name, domain.ErrAppStateConflict,
939 )
940 }
941 runtimeName := domain.RuntimeVolumeName(app, svc.Name, vol.Name)
942 exists, err := s.deps.Runtime.VolumeExists(ctx, runtimeName)
943 if err != nil {
944 return fmt.Errorf("deployment: check volume %q: %w", runtimeName, err)
945 }
946 if exists {
947 if _, ok := ownedRuntime[runtimeName]; !ok {
948 return fmt.Errorf(
949 "deployment: runtime volume %q already exists but is not owned by app %q: refusing to adopt foreign data: %w",
950 runtimeName, app, domain.ErrAppStateConflict,
951 )
952 }
953 }
954 }
955 }
956 return nil
957}
958
959// ComputeOutcome derives the op outcome over terminal per-service results.
960func ComputeOutcome(results map[string]ServiceResult) string {
961 deployed := 0
962 failed := 0
963 for _, result := range results {
964 switch result.Result {
965 case "deployed", ServiceResultUnchanged, domain.AppServiceRemoved:
966 deployed++
967 case "failed":
968 failed++
969 }
970 }
971 switch {
972 case deployed > 0 && failed > 0:
973 return domain.AppOutcomePartial
974 case deployed > 0:
975 return domain.AppOutcomeSuccess
976 default:
977 return domain.AppOutcomeFailed
978 }
979}
980
981// itoa formats integers without extra imports.
982func itoa(n int) string {
983 return fmt.Sprintf("%d", n)
984}