Attachment and NetworkStatus lack backward-compatible decoding (unlike NetworkConfiguration)

[edsai]

Summary

The Attachment and NetworkStatus structs in ContainerResource do not handle backward-compatible JSON decoding when communicating with older versions of container-apiserver. This causes keyNotFound decoding errors when a client built against v0.9.0 of this package talks to the v0.7.0 container-apiserver that ships with macOS 26.

NetworkConfiguration already handles this correctly with fallback decoding — Attachment and NetworkStatus should do the same.

Background

Between v0.7.0 and v0.9.0, several JSON field names were renamed:

Struct	v0.7.0 field	v0.9.0 field
Attachment	address (String)	ipv4Address (CIDRv4)
Attachment	gateway (String)	ipv4Gateway (IPv4Address)
NetworkStatus	address (String)	ipv4Subnet (CIDRv4)
NetworkStatus	gateway (String)	ipv4Gateway (IPv4Address)
NetworkConfiguration	subnet (String?)	ipv4Subnet (CIDRv4?)

NetworkConfiguration already has a custom init(from decoder:) that tries ipv4Subnet first and falls back to subnet:

// NetworkConfiguration.swift (already correct)
let subnetText =
    try container.decodeIfPresent(String.self, forKey: .ipv4Subnet)
    ?? container.decodeIfPresent(String.self, forKey: .subnet)

Attachment and NetworkStatus use the default synthesized Codable conformance, which only accepts the new field names and fails with keyNotFound when it encounters the old ones.

Impact

Any downstream project (e.g., socktainer) that builds against apple/container v0.9.0 but runs on a stock macOS 26 system (which ships container-apiserver v0.7.0) will crash when decoding network data.

Error:

keyNotFound(CodingKeys(stringValue: "ipv4Address", intValue: nil),
  Swift.DecodingError.Context(codingPath: [..., "networks", ...],
  debugDescription: "No value associated with key \"ipv4Address\""))

Suggested Fix

Add custom init(from decoder:) to Attachment and NetworkStatus, matching the pattern already used in NetworkConfiguration.

For Attachment (Sources/ContainerResource/Network/Attachment.swift):

public init(from decoder: Decoder) throws {
    let container = try decoder.container(keyedBy: CodingKeys.self)
    self.network = try container.decode(String.self, forKey: .network)
    self.hostname = try container.decode(String.self, forKey: .hostname)

    if let addr = try? container.decode(CIDRv4.self, forKey: .ipv4Address) {
        self.ipv4Address = addr
    } else {
        self.ipv4Address = try container.decode(CIDRv4.self, forKey: .address)
    }

    if let gw = try? container.decode(IPv4Address.self, forKey: .ipv4Gateway) {
        self.ipv4Gateway = gw
    } else {
        self.ipv4Gateway = try container.decode(IPv4Address.self, forKey: .gateway)
    }

    self.ipv6Address = try container.decodeIfPresent(CIDRv6.self, forKey: .ipv6Address)
    self.macAddress = try container.decodeIfPresent(MACAddress.self, forKey: .macAddress)
}

private enum CodingKeys: String, CodingKey {
    case network, hostname, ipv4Address, ipv4Gateway, ipv6Address, macAddress
    case address, gateway // v0.7.0 field names
}

Same pattern for NetworkStatus (Sources/ContainerResource/Network/NetworkState.swift).

Related

• Socktainer v0.9.0 fails on stock macOS 26 (container-apiserver v0.7.0) socktainer/socktainer#181 — downstream breakage caused by this inconsistency

[jglogan]

@edsai Slammed this week but wanted to get back to you quickly on this as this is an interesting case.

To date, we've gleefully broken the world and focused solely on migrating at-rest data forward when container starts, and not bothered with incompatibility for in-flight data.

This has generally worked because the container client and services are tightly coupled in the application package, but as you point out, breaks on the first instance of an client app that exists in a separate package.

We want socktainer to work and definitely don't want users cursing you or us due to version incompatibility. We've been slowly evolving the client-server code towards something that could properly be called an SDK, and compatibility across versions is a requirement.

Thank you for doing the analysis from 0.7.0 to 0.9.0, and we'll look into making those short-term changes. Have you tested a patched version of main to determine that a client built on main will interoperate with the 0.7.0 container release?

[edsai]

Thank you for doing the analysis from 0.7.0 to 0.9.0, and we'll look into making those short-term changes. Have you tested a patched version of main to determine that a client built on main will interoperate with the 0.7.0 container release?

I'll try to get some time to test. Thanks for the quick reply

[saehejkang]

@edsai Take a look at #1216, if you can test socktainer using that feature branch

[edsai]

@saehejkang :

Test Results: PR #1216 Backward-Compatible Decoding Fix

Tested PR #1216 against a v0.7.0 container-apiserver with socktainer as the client. Bug confirmed and fix verified — both Attachment.swift and NetworkState.swift custom decoders are necessary.

Before merging, I'd appreciate a Co-authored-by trailer on the merge commit, since this PR implements the solution I proposed in #1196 (custom init(from decoder:) with try? fallback to old field names):

Co-authored-by: Ed Saipetch <ed@twentybelow.com>

Broken (v0.9.0 socktainer, unpatched, v0.7.0 apiserver)

Endpoint	Result	Error
GET /containers/json	FAIL	keyNotFound: "ipv4Address"
GET /containers/{id}/json	FAIL	keyNotFound: "ipv4Address"
GET /networks	FAIL	keyNotFound: "ipv4Subnet"
GET /version	PASS	(no container data involved)
Socktainer logs	FAIL	Decoding errors present

Error from socktainer logs:

[ WARNING ] internalError: "failed to list containers"
  (cause: "keyNotFound(CodingKeys(stringValue: "ipv4Address", intValue: nil), ...
  debugDescription: "No value associated with key ... \"ipv4Address\"")")

The /networks endpoint also fails with keyNotFound: "ipv4Subnet", confirming the NetworkState decoder fix is also needed.

Fixed (PR #1216 applied, v0.7.0 apiserver)

Endpoint	Result
GET /containers/json	PASS — Valid JSON with network data
GET /containers/{id}/json	PASS — Valid JSON with network info
GET /networks	PASS — Valid JSON with container mappings
GET /version	PASS
Socktainer logs	PASS — No decoding errors

Environment

• macOS 26.3, Apple M1 Max, Xcode 26.2
• container-apiserver v0.7.0 (1e19a4d)
• socktainer v0.9.0 built against container v0.9.0 (3e49dce) with PR [networks]: add decoder/encoder to Attachment and NetworkStatus #1216 files applied via local path dependency

[saehejkang]

Before merging, I'd appreciate a Co-authored-by trailer on the merge commit, since this PR implements the solution I proposed in #1196 (custom init(from decoder:) with try? fallback to old field names)

Apologies for not doing that initially. I will make sure you are co authored before it is merged 😁

EDIT: PR updated with co-author