Fix forwarded process signal encoding by vincent-peng · Pull Request #1778 · apple/container

vincent-peng · 2026-06-21T11:16:08Z

Summary

Fixes [Bug]: container hangs and cant terminate (^Cfailed to send signal: ["error": invalidArgument: "missing signal in xpc message", "signal": 2]) #1876
Fixes [Bug]: ClientProcess.kill always fails with "missing signal in xpc message" - client sends the signal as an integer, server reads it as a string #1941
Encode forwarded process signals as signal names instead of integer XPC values.
Preserve Darwin-to-Linux signal semantics for foreground signal forwarding.
Add coverage for the kill request payload and forwarded INT, TERM, WINCH, USR1, and USR2 mappings.

Root cause

Foreground non-tty signal forwarding sent .signal as an integer, but the API server reads that field as a string before forwarding it to the runtime. That made forwarded resize signals fail with missing signal in xpc message. A numeric-only fix would also risk mis-mapping Darwin USR1/USR2 values to Linux.

Validation

swift test --filter ContainerAPIClientTests.ClientProcessTests
swift test --filter ContainerAPIClientTests
swift build --target ContainerAPIClient

JeronimoColon · 2026-07-13T04:49:11Z

I hit this independently while building on ContainerAPIClient, in a form broader than the resize noise in #1747: ClientProcess.kill fails for every signal, so there is no working way to signal an exec'd process at all. A timeout built on createProcess can stop waiting for a command, but cannot terminate it. I filed #1941 with a standalone reproducer and the root-cause trace.

Two notes from checking this change against the server path:

The encoding checks out. The server-side parse (Signal.init(_:) in containerization) uppercases, trims an optional SIG prefix, and resolves the name against the Linux table, so the prefix-less names this PR sends parse correctly. That parser and its tables are unchanged from containerization 0.33.3 through current main, so a client carrying this fix also works against already-installed 1.0.0 and 1.1.0 API servers.
Consider adding a KILL case to the tests. Timeout and cancel implementations mostly send SIGKILL, so it is the value most callers will hit first. It passes the guard today (Signal.platformName(SIGKILL) resolves to "KILL", which is in the Linux table); a test would pin that.

Sending names instead of numbers also avoids the Darwin/Linux mismatch on USR1 and USR2, which a numeric fix would have gotten wrong. Nice work.

vincent-peng · 2026-07-13T23:27:51Z

Thanks, this was helpful. Added explicit SIGKILL coverage in b08d725 to pin the timeout/cancel path.

I also added a Darwin-only SIGINFO rejection case so the client-side guard keeps host-only signal names from reaching the runtime. Keeping the name-based encoding unchanged so USR1/USR2 continue mapping by signal name rather than Darwin numeric value.

jglogan · 2026-10-21T16:57:31Z

@vincent-peng We've been swamped with security issues and other backlog but your fix looks good if can rebase and add verified commit signatures (see https://github.com/apple/containerization/blob/0cb4d5bdd8e575e2bdbeb03278c0c07d7a80a989/CONTRIBUTING.md#pull-requests). Thank you for the contribution!

jglogan · 2026-10-21T16:58:50Z

@vincent-peng it looks like the original commits lack signatures but your last commit is good. When you rebase onto main, perhaps squash your changes into a single signed comment and we can do a CI run on that.

vincent-peng · 2026-10-21T21:20:23Z

@jglogan Done. rebased onto latest main and squashed into a single signed commit (de0063a). Should be good for a CI run whenever you're ready, thanks!

jglogan · 2026-10-22T01:29:38Z

Thanks for the quick turn! Building now.

github-actions · 2026-10-22T02:14:25Z

Code Coverage

Tier	Line Coverage
Unit	22.78%
Integration	69.39%
Combined	77.97%

jglogan

@vincent-peng Everything looks good. I've just added an API compatibility note for documentation, and some suggestions for future work here that don't need to gate this PR. Thanks again for your work and for your patience!

jglogan · 2026-10-22T15:44:45Z

-        request.set(key: .processIdentifier, value: id)
-        request.set(key: .signal, value: Int64(signal))
+        request.set(key: .processIdentifier, value: processId)
+        request.set(key: .signal, value: try forwardedSignalName(signal))


Note
This is a breaking change to the XPC "wire protocol", but it fixes a client-server incompatibility that has existed for all 1.x releases (#628 added the Int64 signal on the server side and #1589 changed it to String on the server and in ContainerClient but not ClientProcess).

From a compatibility perspective, if we consider all application releases since 1.0.0 to use "version 1" of the XPC API, all clients prior to the next (1.7.0) release will see #1876 on a version 1 container-apiserver, and all subsequent version 1 API clients will work against any version 1 server.

jglogan · 2026-10-22T15:50:17Z


-        try await xpcClient.send(request)
+    static func forwardedSignalName(_ signal: Int32) throws -> String {
+        guard let name = Signal.platformName(signal), Signal.linux[name] != nil else {


Follow-on for anyone who wants it: rework this check using the os value from the running container image's platform. The best solution may be to propose a change down in Containerization.Signal, as right now it's platform helper is based on the host platform, which doesn't make much sense for container signals.

jglogan · 2026-10-22T15:51:28Z

+    }

-        try await xpcClient.send(request)
+    static func forwardedSignalName(_ signal: Int32) throws -> String {


@chengboonrong Numeric fallback here now in #1997?

@dkovba

apple/container **1.6.1** is out (previously tracked: `1.2.0`). Upstream notes: https://github.com/apple/container/releases/tag/1.6.1 — mirrored in `docs/upstream/apple-container-1.6.1.md`. ## Review checklist - [ ] New or changed CLI flags Gantry should surface (`container run/create/machine/build`) - [ ] Changed `--format json` shapes the DockerKit apple transport decodes - [ ] Fixed upstream bugs Gantry currently works around - [ ] `ContainerTooling.recommendedVersion` / feature gates need moving to `1.6.1` - [ ] MCP tools and App Intents that expose the affected commands - [ ] README and CHANGELOG entries for whatever is adopted Merging records the version as reviewed. Implement the adopted parts on this branch, or merge as-is and open follow-ups. --- <details><summary>Upstream release notes</summary> ⌨️ denotes breaking CLI changes. 👩‍💻 denotes breaking API changes. - Core - [Fix signals not properly passed to container processes](apple/container#2276) - Kubernetes - [Fix problems when creating clusters concurrently](apple/container#2276) - [Rename to `container cluster`](apple/container#2427) ## What's Changed * Fix host port conflicts and leftover failed nodes during cluster creation by @dkovba in apple/container#2399 * Fix forwarded process signal encoding by @vincent-peng in apple/container#1778 * Remove SIGWINCH from signal kill set by @ArasanDev in apple/container#1854 * Infer platform and runtime from OCI image by @noah-thor in apple/container#2422 * rename to container cluster by @crosbymichael in apple/container#2427 ## New Contributors * @vincent-peng made their first contribution in apple/container#1778 * @ArasanDev made their first contribution in apple/container#1854 **Full Changelog**: apple/container@1.6.0...1.6.1 </details> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

) apple/container 1.6.1 pins containerization 0.53.0. No source changes are needed here. The release fixes ClientProcess.kill (apple/container#1778), which sent the signal as an integer while the API server reads it as a name, so every kill of an exec'd process failed with "missing signal in xpc message" (apple/container#1941). The health loop uses that kill to stop a probe that runs past its timeout, so a hung probe was never stopped: it stayed in the container, and ProbesInFlight failed every later probe without running it until the hung one exited by itself. With this bump the probe is killed at its deadline and the next probe runs. The fix is in the client library, so it needs this rebuild, and it works against a 1.6.0 API server as well: that server already reads the signal as a name. ProbesInFlight stays, since a probe can still outlive its kill by ignoring SIGTERM or when the kill times out. Its comment no longer cites the fixed issue. Signed-off-by: Wes Morgan <git@wesmorgan.me> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

vincent-peng marked this pull request as ready for review June 21, 2026 11:18

JeronimoColon mentioned this pull request Jul 13, 2026

[Bug]: ClientProcess.kill always fails with "missing signal in xpc message" - client sends the signal as an integer, server reads it as a string #1941

Closed

2 of 3 tasks

jglogan approved these changes Oct 21, 2026

View reviewed changes

vincent-peng closed this Oct 21, 2026

vincent-peng force-pushed the fix-forwarded-process-signals branch from c58fd89 to ca4884f Compare October 21, 2026 21:19

vincent-peng reopened this Oct 21, 2026

vincent-peng closed this Oct 22, 2026

vincent-peng force-pushed the fix-forwarded-process-signals branch from de0063a to b37ed58 Compare October 22, 2026 00:17

Fix forwarded process signal encoding

b32e5c4

vincent-peng reopened this Oct 22, 2026

vincent-peng requested a review from jglogan October 22, 2026 07:17

jglogan approved these changes Oct 22, 2026

View reviewed changes

jglogan merged commit 1ebb9d0 into apple:main Oct 22, 2026
3 checks passed

This was referenced Oct 22, 2026

Remove SIGWINCH from signal kill set #1854

Merged

Fix foreground process signal forwarding #1871

Open

Fall back to the numeric signal for unnamed signals in ClientProcess #1997

Open

vincent-peng deleted the fix-forwarded-process-signals branch October 24, 2026 00:18

henrywang mentioned this pull request Oct 24, 2026

chore(deps): bump apple/container to 1.6.1 / containerization to 0.53.0 henrywang/Berthly#192

Closed

6 tasks

This was referenced Oct 26, 2026

Bump apple/container to 1.6.1 andrew-waters/orchard#152

Closed

Support container 1.6.1: the cluster plugin rename, and build against and install 1.6.1 andrew-waters/orchard#153

Merged

github-actions Bot mentioned this pull request Oct 26, 2026

chore(upstream): adopt apple/container 1.6.1 getgantry/gantry#26

Merged

6 tasks

cap10morgan mentioned this pull request Oct 26, 2026

deps: bump apple/container to 1.6.1 and containerization to 0.53.0 socktainer/socktainer#485

Merged

5 of 6 tasks

synkathairo-homebrew-bump-bot Bot mentioned this pull request Oct 30, 2026

container 1.6.1 synkathairo/homebrew-repo#133

Merged

Navigation Menu

Repository navigation

Fix forwarded process signal encoding - #1778

Fix forwarded process signal encoding#1778
jglogan merged 1 commit into
apple:mainfrom
vincent-peng:fix-forwarded-process-signals

vincent-peng commented Jun 21, 2026 •

edited by jglogan

Loading

Uh oh!

JeronimoColon commented Jul 13, 2026

Uh oh!

vincent-peng commented Jul 13, 2026

Uh oh!

jglogan commented Oct 21, 2026

Uh oh!

jglogan commented Oct 21, 2026

Uh oh!

vincent-peng commented Oct 21, 2026 •

edited

Loading

Uh oh!

jglogan commented Oct 22, 2026

Uh oh!

github-actions Bot commented Oct 22, 2026

Uh oh!

jglogan left a comment

Uh oh!

jglogan Oct 22, 2026

Uh oh!

jglogan Oct 22, 2026

Uh oh!

jglogan Oct 22, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

vincent-peng commented Jun 21, 2026 • edited by jglogan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Root cause

Validation

Uh oh!

JeronimoColon commented Jul 13, 2026

Uh oh!

vincent-peng commented Jul 13, 2026

Uh oh!

jglogan commented Oct 21, 2026

Uh oh!

jglogan commented Oct 21, 2026

Uh oh!

vincent-peng commented Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jglogan commented Oct 22, 2026

Uh oh!

github-actions Bot commented Oct 22, 2026

Code Coverage

Uh oh!

jglogan left a comment

Choose a reason for hiding this comment

Uh oh!

jglogan Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

jglogan Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

jglogan Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vincent-peng commented Jun 21, 2026 •

edited by jglogan

Loading

vincent-peng commented Oct 21, 2026 •

edited

Loading