Skip to content

Add exclusive UNIX endpoint ownership#29

Open
samuel-williams-shopify wants to merge 2 commits into
mainfrom
add-exclusive-unix-endpoints
Open

Add exclusive UNIX endpoint ownership#29
samuel-williams-shopify wants to merge 2 commits into
mainfrom
add-exclusive-unix-endpoints

Conversation

@samuel-williams-shopify

@samuel-williams-shopify samuel-williams-shopify commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add IO::Endpoint::ExclusiveUNIXEndpoint as a dedicated subclass for UNIX socket path ownership.
  • Add IO::Endpoint.exclusive_unix(path) as the explicit construction API; IO::Endpoint.unix(path) remains non-owning.
  • Add unique: for generating an immediately inspectable worker socket path within an existing directory using a prefix, PID, and random entropy.
  • Hold an adjacent flock for the socket lifetime so crashed workers release ownership automatically and later workers can recover stale sockets.
  • Close the bound socket before releasing ownership, while guaranteeing cleanup if socket closure raises.
  • Remove both the socket and lock paths on orderly close, with filesystem identity checks that preserve replacement entries.
  • Preserve ownership cleanup through delegating endpoint wrappers such as Async::HTTP::Endpoint.
  • Refuse to replace unrelated filesystem entries during stale socket recovery.

Validation

  • Full Sus suite: 75 passed, 164 assertions
  • RuboCop: 39 files, no offenses
  • Documentation coverage: 142/142 public definitions
  • Verified recovery after SIGKILL for stable and generated socket paths
  • Verified cleanup through Async::HTTP::Endpoint
  • Verified ownership release when socket closure raises

@samuel-williams-shopify
samuel-williams-shopify force-pushed the add-exclusive-unix-endpoints branch 2 times, most recently from 2a38c9e to 14bcbcb Compare July 23, 2026 04:08
Signed-off-by: Samuel Williams <samuel.williams@shopify.com>
@samuel-williams-shopify
samuel-williams-shopify force-pushed the add-exclusive-unix-endpoints branch from 14bcbcb to c9726ba Compare July 23, 2026 04:26
@samuel-williams-shopify

Copy link
Copy Markdown
Contributor Author

After working through the intended Falcon cluster use case, I do not think we should merge the exclusive endpoint in its current form.

Each worker can use a unique UNIX socket path, so there should be no meaningful ownership contention. xDS is the authoritative source of viable worker endpoints, and graceful shutdown can explicitly unlink the path. A crash may leave stale entries in the directory, but that is unavoidable in the general case and consumers already need to tolerate unavailable sockets or rely on xDS metadata.

ExclusiveUNIXEndpoint offers automatic orderly cleanup and stronger arbitration for stable paths, but the lock-file and ownership lifecycle add substantial complexity that this use case does not need. The existing UNIXEndpoint is probably sufficient.

The safety improvement that prevents stale-socket recovery from replacing an unrelated filesystem entry may still be worth extracting into a smaller separate PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant