docs: document race condition design choice in ListRoutesWithDetails

Explain the trade-off of copying container map under lock then making
external calls without lock, avoiding I/O while holding locks.

commit: 13bac4934fc84947cd8b969fa0aef9a310233251
author: brice · 9mo ago · 2026-01-17 11:42 UTC
parent: ba3e8b0
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

1 file · +3 -0

M internal/usecase/container/service.go +3 -0


@@ -317,6 +317,9 @@ func (s Service) List(_ context.Context) map[string]domain.Container {
317	317		}
318	318
319	319		// ListRoutesWithDetails returns routes with network and attachment info.
	320	+	// Note: Container map is copied under lock, then external calls are made without lock.
	321	+	// If containers are removed between copy and runtime calls, errors are handled gracefully
	322	+	// (network becomes empty string). This trade-off avoids holding locks during I/O.
320	323		func (s *Service) ListRoutesWithDetails(ctx context.Context) []domain.RouteInfo {
321	324		s.mu.RLock()
322	325		containers := make(map[string]*domain.Container, len(s.containers))


@@ -317,6 +317,9 @@ func (s Service) List(_ context.Context) map[string]domain.Container {
317	}	317		}
318		318
319	// ListRoutesWithDetails returns routes with network and attachment info.	319		// ListRoutesWithDetails returns routes with network and attachment info.
		320	+	// Note: Container map is copied under lock, then external calls are made without lock.
		321	+	// If containers are removed between copy and runtime calls, errors are handled gracefully
		322	+	// (network becomes empty string). This trade-off avoids holding locks during I/O.
320	func (s *Service) ListRoutesWithDetails(ctx context.Context) []domain.RouteInfo {	323		func (s *Service) ListRoutesWithDetails(ctx context.Context) []domain.RouteInfo {
321	s.mu.RLock()	324		s.mu.RLock()
322	containers := make(map[string]*domain.Container, len(s.containers))	325		containers := make(map[string]*domain.Container, len(s.containers))