Normalize JSON output for network and volume resources. (apple#1624)

jglogan · web-flow · commit e20aca820364 · 2026-06-01T21:42:10.000-07:00
Normalize JSON output for network and volume resources. (apple#1624) - Reworks both JSON output presets to use sorted keys, ISO timestamps. `compact` is used for `ls` output, and `pretty` is used for `inspect`. - Extracts non-DRY option configuration into presets. - Closes apple#1623.
diff --git a/Sources/APIServer/APIServer+Start.swift b/Sources/APIServer/APIServer+Start.swift
@@ -80,7 +80,7 @@ extension APIServer {
                 await containersService.setNetworksService(networkService)
                 initializeHealthCheckService(log: log, routes: &routes)
                 try initializeKernelService(log: log, routes: &routes)
-                let volumesService = try initializeVolumeService(containersService: containersService, log: log, routes: &routes)
+                let volumesService = try await initializeVolumeService(containersService: containersService, log: log, routes: &routes)
                 try initializeDiskUsageService(
                     containersService: containersService,
                     volumesService: volumesService,
@@ -359,11 +359,11 @@ extension APIServer {
             containersService: ContainersService,
             log: Logger,
             routes: inout [XPCRoute: XPCServer.RouteHandler]
-        ) throws -> VolumesService {
+        ) async throws -> VolumesService {
             log.info("initializing volume service")
 
             let resourceRoot = appRoot.appending(FilePath.Component("volumes"))
-            let service = try VolumesService(resourceRoot: resourceRoot, containersService: containersService, log: log)
+            let service = try await VolumesService(resourceRoot: resourceRoot, containersService: containersService, log: log)
             let harness = VolumesHarness(service: service, log: log)
 
             routes[XPCRoute.volumeCreate] = XPCServer.route(harness.create)
diff --git a/Sources/ContainerCommands/Container/ContainerInspect.swift b/Sources/ContainerCommands/Container/ContainerInspect.swift
@@ -50,7 +50,7 @@ extension Application {
                 )
             }
 
-            try Output.emit(Output.renderJSON(containers.map { PrintableContainer($0) }))
+            try Output.emit(Output.renderJSON(containers.map { PrintableContainer($0) }, options: .pretty))
         }
     }
 }
diff --git a/Sources/ContainerCommands/Image/ImageInspect.swift b/Sources/ContainerCommands/Image/ImageInspect.swift
@@ -63,11 +63,7 @@ extension Application {
                 printable.append(ImageResource(config: image.description, index: resolved.index, manifests: resolved.manifests))
             }
 
-            let options = JSONOptions(
-                outputFormatting: [.prettyPrinted, .sortedKeys],
-                dateEncodingStrategy: .iso8601
-            )
-            try Output.emit(Output.renderJSON(printable, options: options))
+            try Output.emit(Output.renderJSON(printable, options: .pretty))
         }
     }
 }
diff --git a/Sources/ContainerCommands/Image/ImageList.swift b/Sources/ContainerCommands/Image/ImageList.swift
@@ -99,8 +99,7 @@ extension Application {
         }
 
         private static func emitJSON(resources: [ImageResource]) throws {
-            let options = JSONOptions(dateEncodingStrategy: .iso8601)
-            try Output.emit(Output.renderJSON(resources, options: options))
+            try Output.emit(Output.renderJSON(resources, options: .compact))
         }
     }
 }
diff --git a/Sources/ContainerCommands/Network/NetworkInspect.swift b/Sources/ContainerCommands/Network/NetworkInspect.swift
@@ -47,7 +47,7 @@ extension Application {
                 )
             }
 
-            try Output.emit(Output.renderJSON(items))
+            try Output.emit(Output.renderJSON(items, options: .pretty))
         }
     }
 }
diff --git a/Sources/ContainerCommands/OutputRendering.swift b/Sources/ContainerCommands/OutputRendering.swift
@@ -23,8 +23,8 @@ public struct JSONOptions: Sendable {
     public var outputFormatting: JSONEncoder.OutputFormatting = []
     public var dateEncodingStrategy: JSONEncoder.DateEncodingStrategy = .deferredToDate
 
-    public static let compact = JSONOptions()
-    public static let prettySorted = JSONOptions(outputFormatting: [.prettyPrinted, .sortedKeys])
+    public static let compact = JSONOptions(outputFormatting: [.sortedKeys], dateEncodingStrategy: .iso8601)
+    public static let pretty = JSONOptions(outputFormatting: [.prettyPrinted, .sortedKeys], dateEncodingStrategy: .iso8601)
 
     public init(
         outputFormatting: JSONEncoder.OutputFormatting = [],
@@ -85,10 +85,10 @@ public enum Output {
     /// The JSON and display models may be the same type (e.g., `PrintableContainer`)
     /// or different types.
     public static func render<J: Encodable, D: ListDisplayable>(
-        json: J, display: [D], format: ListFormat, quiet: Bool
+        json: J, display: [D], format: ListFormat, quiet: Bool, jsonOptions: JSONOptions = .compact
     ) throws {
         switch format {
-        case .json: try emit(renderJSON(json))
+        case .json: try emit(renderJSON(json, options: jsonOptions))
         case .yaml: try emit(renderYAML(json))
         case .table: emit(renderList(display, quiet: quiet))
         case .toml: try emit(renderTOML(json))
diff --git a/Sources/ContainerCommands/System/SystemDF.swift b/Sources/ContainerCommands/System/SystemDF.swift
@@ -37,7 +37,7 @@ extension Application {
             let stats = try await ClientDiskUsage.get()
 
             if format == .json {
-                try Output.emit(Output.renderJSON(stats, options: .prettySorted))
+                try Output.emit(Output.renderJSON(stats, options: .pretty))
                 return
             }
 
diff --git a/Sources/ContainerCommands/Volume/VolumeInspect.swift b/Sources/ContainerCommands/Volume/VolumeInspect.swift
@@ -38,7 +38,7 @@ extension Application.VolumeCommand {
         public func run() async throws {
             let uniqueNames = Set(names)
             let volumes = try await ClientVolume.list().filter { uniqueNames.contains($0.id) }
-            let volumeResources = volumes.map { VolumeResource(config: $0) }
+            let volumeResources = volumes.map { VolumeResource(configuration: $0) }
 
             if volumes.count != uniqueNames.count {
                 let found = Set(volumes.map { $0.id })
@@ -49,11 +49,7 @@ extension Application.VolumeCommand {
                 )
             }
 
-            let options = JSONOptions(
-                outputFormatting: [.prettyPrinted, .sortedKeys],
-                dateEncodingStrategy: .iso8601
-            )
-            try Output.emit(Output.renderJSON(volumeResources, options: options))
+            try Output.emit(Output.renderJSON(volumeResources, options: .pretty))
         }
     }
 }
diff --git a/Sources/ContainerCommands/Volume/VolumeList.swift b/Sources/ContainerCommands/Volume/VolumeList.swift
@@ -41,14 +41,7 @@ extension Application.VolumeCommand {
 
         public func run() async throws {
             let volumes = try await ClientVolume.list()
-            let volumeResources = volumes.map { VolumeResource(config: $0) }
-
-            if format == .json {
-                let options = JSONOptions(dateEncodingStrategy: .iso8601)
-                try Output.emit(Output.renderJSON(volumeResources, options: options))
-                return
-            }
-
+            let volumeResources = volumes.map { VolumeResource(configuration: $0) }
             try Output.render(json: volumeResources, display: volumeResources, format: format, quiet: quiet)
         }
     }
diff --git a/Sources/ContainerCommands/Volume/VolumeResource+ListDisplayable.swift b/Sources/ContainerCommands/Volume/VolumeResource+ListDisplayable.swift
@@ -25,8 +25,8 @@ extension VolumeResource: ListDisplayable {
         [
             name,
             isAnonymous ? "anonymous" : "named",
-            config.driver,
-            config.options.isEmpty ? "" : config.options.sorted(by: { $0.key < $1.key }).map { "\($0.key)=\($0.value)" }.joined(separator: ","),
+            configuration.driver,
+            configuration.options.isEmpty ? "" : configuration.options.sorted(by: { $0.key < $1.key }).map { "\($0.key)=\($0.value)" }.joined(separator: ","),
         ]
     }
 
diff --git a/Sources/ContainerResource/Network/NetworkConfiguration.swift b/Sources/ContainerResource/Network/NetworkConfiguration.swift
@@ -101,8 +101,8 @@ public struct NetworkConfiguration: Codable, Sendable, Identifiable {
             self.plugin = plugin
             self.options = try container.decodeIfPresent([String: String].self, forKey: .options) ?? [:]
         } else if let legacy = try container.decodeIfPresent(_LegacyPluginInfo.self, forKey: .pluginInfo) {
-            // - Deprecated: As of 1.0.0. Use ``plugin`` and ``options`` instead.
-            // - Note: Will be removed in a later release.
+            // Deprecated: As of 1.0.0. Use ``plugin`` and ``options`` instead.
+            // Note: Will be removed in a later release.
             self.plugin = legacy.plugin
             var opts: [String: String] = [:]
             if let variant = legacy.variant { opts["variant"] = variant }
diff --git a/Sources/ContainerResource/Volume/VolumeConfiguration.swift b/Sources/ContainerResource/Volume/VolumeConfiguration.swift
@@ -17,7 +17,7 @@
 import Foundation
 
 /// A named or anonymous volume that can be mounted in containers.
-public struct VolumeConfiguration: Sendable, Codable, Equatable, Identifiable {
+public struct VolumeConfiguration: Sendable, Equatable, Identifiable {
     // id of the volume.
     public var id: String { name }
     // Name of the volume.
@@ -29,7 +29,7 @@ public struct VolumeConfiguration: Sendable, Codable, Equatable, Identifiable {
     // The mount point of the volume on the host.
     public var source: String
     // Timestamp when the volume was created.
-    public var createdAt: Date
+    public var creationDate: Date
     // User-defined key/value metadata.
     public var labels: [String: String]
     // Driver-specific options.
@@ -42,7 +42,7 @@ public struct VolumeConfiguration: Sendable, Codable, Equatable, Identifiable {
         driver: String = "local",
         format: String = "ext4",
         source: String,
-        createdAt: Date = Date(),
+        creationDate: Date = Date(),
         labels: [String: String] = [:],
         options: [String: String] = [:],
         sizeInBytes: UInt64? = nil
@@ -51,11 +51,49 @@ public struct VolumeConfiguration: Sendable, Codable, Equatable, Identifiable {
         self.driver = driver
         self.format = format
         self.source = source
-        self.createdAt = createdAt
+        self.creationDate = creationDate
         self.labels = labels
         self.options = options
         self.sizeInBytes = sizeInBytes
     }
+
+    enum CodingKeys: String, CodingKey {
+        case name, driver, format, source, labels, options, sizeInBytes
+        case creationDate
+        // TODO: retain for deserialization compatibility, remove in next major version
+        case createdAt
+    }
+}
+
+extension VolumeConfiguration: Codable {
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        name = try container.decode(String.self, forKey: .name)
+        driver = try container.decode(String.self, forKey: .driver)
+        format = try container.decode(String.self, forKey: .format)
+        source = try container.decode(String.self, forKey: .source)
+        // Deprecated: As of 1.0.0. Use ``creationDate`` instead of ``createdAt``.
+        // Note: Will be removed in a later release.
+        creationDate =
+            try container.decodeIfPresent(Date.self, forKey: .creationDate)
+            ?? container.decodeIfPresent(Date.self, forKey: .createdAt)
+            ?? Date(timeIntervalSince1970: 0)
+        labels = try container.decodeIfPresent([String: String].self, forKey: .labels) ?? [:]
+        options = try container.decodeIfPresent([String: String].self, forKey: .options) ?? [:]
+        sizeInBytes = try container.decodeIfPresent(UInt64.self, forKey: .sizeInBytes)
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(name, forKey: .name)
+        try container.encode(driver, forKey: .driver)
+        try container.encode(format, forKey: .format)
+        try container.encode(source, forKey: .source)
+        try container.encode(creationDate, forKey: .creationDate)
+        try container.encode(labels, forKey: .labels)
+        try container.encode(options, forKey: .options)
+        try container.encodeIfPresent(sizeInBytes, forKey: .sizeInBytes)
+    }
 }
 
 extension VolumeConfiguration {
diff --git a/Sources/ContainerResource/Volume/VolumeResource.swift b/Sources/ContainerResource/Volume/VolumeResource.swift
@@ -19,37 +19,37 @@ import Foundation
 /// A volume resource, representing a configured volume.
 public struct VolumeResource: ManagedResource {
     /// The volume's configuration — its persistent, intrinsic properties.
-    public let config: VolumeConfiguration
+    public let configuration: VolumeConfiguration
 
     // MARK: ManagedResource
 
     /// The unique identifier for this volume. Identical to ``VolumeConfiguration/name``.
-    public var id: String { config.name }
+    public var id: String { configuration.name }
 
     /// The user-assigned name for this volume. For volumes, name and ID are the same.
-    public var name: String { config.name }
+    public var name: String { configuration.name }
 
     /// The time at which this volume was created.
-    public var creationDate: Date { config.createdAt }
+    public var creationDate: Date { configuration.creationDate }
 
     /// Key-value labels for this volume. If the underlying
     /// ``VolumeConfiguration/labels`` dictionary contains values that fail
     /// ``ResourceLabels`` validation, this returns an empty label set.
     public var labels: ResourceLabels {
-        (try? ResourceLabels(config.labels)) ?? ResourceLabels()
+        (try? ResourceLabels(configuration.labels)) ?? ResourceLabels()
     }
 
     /// Whether this is an anonymous volume (detected via the configuration's labels).
-    public var isAnonymous: Bool { config.isAnonymous }
+    public var isAnonymous: Bool { configuration.isAnonymous }
 
     // MARK: Initialization
 
     /// Creates a volume resource.
     ///
     /// - Parameters:
-    ///   - config: The volume's intrinsic configuration.
-    public init(config: VolumeConfiguration) {
-        self.config = config
+    ///   - configuration: The volume's intrinsic configuration.
+    public init(configuration: VolumeConfiguration) {
+        self.configuration = configuration
     }
 }
 
@@ -74,17 +74,17 @@ extension VolumeResource {
 extension VolumeResource {
     enum CodingKeys: String, CodingKey {
         case id
-        case config
+        case configuration
     }
 
     public func encode(to encoder: Encoder) throws {
         var container = encoder.container(keyedBy: CodingKeys.self)
         try container.encode(id, forKey: .id)
-        try container.encode(config, forKey: .config)
+        try container.encode(configuration, forKey: .configuration)
     }
 
     public init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
-        self.config = try container.decode(VolumeConfiguration.self, forKey: .config)
+        self.configuration = try container.decode(VolumeConfiguration.self, forKey: .configuration)
     }
 }
diff --git a/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift b/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift
@@ -37,12 +37,29 @@ public actor VolumesService {
     private static let entityFile = "entity.json"
     private static let blockFile = "volume.img"
 
-    public init(resourceRoot: FilePath, containersService: ContainersService, log: Logger) throws {
+    public init(resourceRoot: FilePath, containersService: ContainersService, log: Logger) async throws {
         try FileManager.default.createDirectory(atPath: resourceRoot.string, withIntermediateDirectories: true)
         self.resourceRoot = resourceRoot
         self.store = try FilesystemEntityStore<VolumeConfiguration>(path: resourceRoot, type: "volumes", log: log)
         self.containersService = containersService
         self.log = log
+
+        // Migrate configs stored with the old `createdAt` key to `creationDate`.
+        // Deprecated: As of 1.0.0. Use ``creationDate`` instead of ``createdAt``.
+        // Note: Will be removed in a later release.
+        let configurations = try await store.list()
+        for configuration in configurations {
+            do {
+                try await store.update(configuration)
+            } catch {
+                log.error(
+                    "failed to migrate volume configuration",
+                    metadata: [
+                        "name": "\(configuration.name)",
+                        "error": "\(error)",
+                    ])
+            }
+        }
     }
 
     public func create(
diff --git a/Tests/CLITests/Subcommands/Networks/TestCLINetwork.swift b/Tests/CLITests/Subcommands/Networks/TestCLINetwork.swift
@@ -181,6 +181,7 @@ class TestCLINetwork: CLITest {
             }
 
             let decoder = JSONDecoder()
+            decoder.dateDecodingStrategy = .iso8601
             let networks = try decoder.decode([NetworkInspectOutput].self, from: jsonData)
             guard networks.count == 1 else {
                 throw CLIError.invalidOutput("expected exactly one network from inspect, got \(networks.count)")
diff --git a/Tests/CLITests/Subcommands/Volumes/TestCLIAnonymousVolumes.swift b/Tests/CLITests/Subcommands/Volumes/TestCLIAnonymousVolumes.swift
@@ -317,6 +317,9 @@ class TestCLIAnonymousVolumes: CLITest {
         let (_, output, error, status) = try run(arguments: ["volume", "list", "--format", "json"])
         #expect(status == 0, "volume list should succeed: \(error)")
 
+        #expect(output.contains("\"creationDate\""), "JSON output should use creationDate key")
+        #expect(!output.contains("\"createdAt\""), "JSON output must not use deprecated createdAt key")
+
         // Parse JSON to verify metadata
         let data = output.data(using: .utf8)!
         let decoder = JSONDecoder()
diff --git a/Tests/CLITests/Subcommands/Volumes/TestCLIVolumes.swift b/Tests/CLITests/Subcommands/Volumes/TestCLIVolumes.swift
@@ -248,6 +248,8 @@ class TestCLIVolumes: CLITest {
         }
 
         #expect(inspectOutput.contains(volumeName), "volume inspect should contain volume name")
+        #expect(inspectOutput.contains("\"creationDate\""), "inspect JSON should use creationDate key")
+        #expect(!inspectOutput.contains("\"createdAt\""), "inspect JSON must not use deprecated createdAt key")
 
         // Delete volume
         try doVolumeDelete(name: volumeName)
diff --git a/Tests/ContainerCommandsTests/ListFormattingTests.swift b/Tests/ContainerCommandsTests/ListFormattingTests.swift
diff --git a/Tests/ContainerResourceTests/VolumeConfigurationTests.swift b/Tests/ContainerResourceTests/VolumeConfigurationTests.swift

Original file line number	Diff line number	Diff line change
`@@ -50,7 +50,7 @@ extension Application {`
`50`	`50`	`)`
`51`	`51`	`}`
`52`	`52`
`53`		`- try Output.emit(Output.renderJSON(containers.map { PrintableContainer($0) }))`
	`53`	`+ try Output.emit(Output.renderJSON(containers.map { PrintableContainer($0) }, options: .pretty))`
`54`	`54`	`}`
`55`	`55`	`}`
`56`	`56`	`}`
Original file line number	Diff line number	Diff line change
`@@ -63,11 +63,7 @@ extension Application {`
`63`	`63`	`printable.append(ImageResource(config: image.description, index: resolved.index, manifests: resolved.manifests))`
`64`	`64`	`}`
`65`	`65`
`66`		`- let options = JSONOptions(`
`67`		`- outputFormatting: [.prettyPrinted, .sortedKeys],`
`68`		`- dateEncodingStrategy: .iso8601`
`69`		`- )`
`70`		`- try Output.emit(Output.renderJSON(printable, options: options))`
	`66`	`+ try Output.emit(Output.renderJSON(printable, options: .pretty))`
`71`	`67`	`}`
`72`	`68`	`}`
`73`	`69`	`}`
Original file line number	Diff line number	Diff line change
`@@ -99,8 +99,7 @@ extension Application {`
`99`	`99`	`}`
`100`	`100`
`101`	`101`	`private static func emitJSON(resources: [ImageResource]) throws {`
`102`		`- let options = JSONOptions(dateEncodingStrategy: .iso8601)`
`103`		`- try Output.emit(Output.renderJSON(resources, options: options))`
	`102`	`+ try Output.emit(Output.renderJSON(resources, options: .compact))`
`104`	`103`	`}`
`105`	`104`	`}`
`106`	`105`	`}`
Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,7 @@ extension Application {`
`47`	`47`	`)`
`48`	`48`	`}`
`49`	`49`
`50`		`- try Output.emit(Output.renderJSON(items))`
	`50`	`+ try Output.emit(Output.renderJSON(items, options: .pretty))`
`51`	`51`	`}`
`52`	`52`	`}`
`53`	`53`	`}`
Original file line number	Diff line number	Diff line change
`@@ -37,7 +37,7 @@ extension Application {`
`37`	`37`	`let stats = try await ClientDiskUsage.get()`
`38`	`38`
`39`	`39`	`if format == .json {`
`40`		`- try Output.emit(Output.renderJSON(stats, options: .prettySorted))`
	`40`	`+ try Output.emit(Output.renderJSON(stats, options: .pretty))`
`41`	`41`	`return`
`42`	`42`	`}`
`43`	`43`
Original file line number	Diff line number	Diff line change
`@@ -38,7 +38,7 @@ extension Application.VolumeCommand {`
`38`	`38`	`public func run() async throws {`
`39`	`39`	`let uniqueNames = Set(names)`
`40`	`40`	`let volumes = try await ClientVolume.list().filter { uniqueNames.contains($0.id) }`
`41`		`- let volumeResources = volumes.map { VolumeResource(config: $0) }`
	`41`	`+ let volumeResources = volumes.map { VolumeResource(configuration: $0) }`
`42`	`42`
`43`	`43`	`if volumes.count != uniqueNames.count {`
`44`	`44`	`let found = Set(volumes.map { $0.id })`
`@@ -49,11 +49,7 @@ extension Application.VolumeCommand {`
`49`	`49`	`)`
`50`	`50`	`}`
`51`	`51`
`52`		`- let options = JSONOptions(`
`53`		`- outputFormatting: [.prettyPrinted, .sortedKeys],`
`54`		`- dateEncodingStrategy: .iso8601`
`55`		`- )`
`56`		`- try Output.emit(Output.renderJSON(volumeResources, options: options))`
	`52`	`+ try Output.emit(Output.renderJSON(volumeResources, options: .pretty))`
`57`	`53`	`}`
`58`	`54`	`}`
`59`	`55`	`}`
Original file line number	Diff line number	Diff line change
`@@ -25,8 +25,8 @@ extension VolumeResource: ListDisplayable {`
`25`	`25`	`[`
`26`	`26`	`name,`
`27`	`27`	`isAnonymous ? "anonymous" : "named",`
`28`		`- config.driver,`
`29`		`- config.options.isEmpty ? "" : config.options.sorted(by: { $0.key < $1.key }).map { "\($0.key)=\($0.value)" }.joined(separator: ","),`
	`28`	`+ configuration.driver,`
	`29`	`+ configuration.options.isEmpty ? "" : configuration.options.sorted(by: { $0.key < $1.key }).map { "\($0.key)=\($0.value)" }.joined(separator: ","),`
`30`	`30`	`]`
`31`	`31`	`}`
`32`	`32`