varlink / rust / 30166081117

56%

Build Type

push

github

Committed by web-flow

Commit Message

feat: add MethodCall::push_fd() for passing file descriptors (SCM_RIGHTS) (#149)

systemd's `sd-varlink` extends varlink with file-descriptor passing over
the
Unix socket via SCM_RIGHTS: fds are pushed before the call and
referenced from
the parameters by their push-order index. (This is not part of the core
varlink
protocol as specified on varlink.org — the push-order convention is the
de-facto
one used by systemd's services.) This crate had no client-side way to
attach
fds; this adds that, mirroring `sd_varlink_push_fd()`.

## API

```rust
let mut call = client.some_method(args);
let idx = call.push_fd(fd)?;   // -> 0, then 1, ... (push order == the index methods reference)
call.more()?;                  // or .call()/.oneway(); fds are delivered with the request
```

- `MethodCall::push_fd(fd) -> io::Result<usize>` (unix only). Dups the
fd with
`F_DUPFD_CLOEXEC` (caller keeps ownership of the original), queues it,
and
  returns its push-order index.
- On send, queued fds are delivered with the request via a single
`sendmsg()` + `SCM_RIGHTS` on the connection's socket; any bytes past
the first
  `sendmsg` are written normally through the existing writer.
- Only `AF_UNIX`-socket-backed connections support this — SCM_RIGHTS
does not
exist elsewhere. `push_fd` checks the socket family up front
(`getsockname`),
so a `tcp:` connection or a reader/writer-pair connection fails
immediately
  with `io::ErrorKind::Unsupported` rather than later at send time.

No opt-in gate (cf. systemd's
`SD_VARLINK_SERVER_ALLOW_FD_PASSING_OUTPUT`):
on the client side, calling `push_fd` is itself the explicit opt-in — no
ancillary data is ever attached unless the application pushed an fd for
that
specific call.

## Scope

Send-only. Receiving descriptors (server → client) is not implemented —
it would
require recvmsg-based reading throughout the input path, and nothing
needs it yet.
`cfg(unix)` only, matching the crate's existing platform split; `libc`
is already
a unix depe... (continued)

Coverage Stats

222 of 226 new or added lines in 2 files covered. (98.23%)

64 existing lines in 2 files now uncovered.

3045 of 5408 relevant lines covered (56.31%)

13.6 hits per line